From 6d8bdc65446a704d0750217efd05532fc641ea7d Mon Sep 17 00:00:00 2001 From: Jacob McDonnell Date: Sat, 25 Apr 2026 14:02:27 -0400 Subject: docs: OpenBSD Man Pages Added --- static/openbsd/man9/KASSERT.9 | 105 ++ static/openbsd/man9/Makefile | 188 ++++ static/openbsd/man9/RBT_INIT.9 | 563 ++++++++++ static/openbsd/man9/SMR_LIST_INIT.9 | 445 ++++++++ static/openbsd/man9/SMR_PTR_GET.9 | 73 ++ static/openbsd/man9/SRPL_EMPTY_LOCKED.9 | 155 +++ static/openbsd/man9/SipHash24.9 | 108 ++ static/openbsd/man9/VOP_LOOKUP.9 | 917 ++++++++++++++++ static/openbsd/man9/aml_evalnode.9 | 202 ++++ static/openbsd/man9/arc4random.9 | 64 ++ static/openbsd/man9/atomic_add_int.9 | 73 ++ static/openbsd/man9/atomic_cas_uint.9 | 76 ++ static/openbsd/man9/atomic_dec_int.9 | 72 ++ static/openbsd/man9/atomic_inc_int.9 | 72 ++ static/openbsd/man9/atomic_load_int.9 | 68 ++ static/openbsd/man9/atomic_setbits_int.9 | 71 ++ static/openbsd/man9/atomic_sub_int.9 | 71 ++ static/openbsd/man9/atomic_swap_uint.9 | 59 ++ static/openbsd/man9/audio.9 | 529 ++++++++++ static/openbsd/man9/autoconf.9 | 252 +++++ static/openbsd/man9/bemtoh32.9 | 143 +++ static/openbsd/man9/bintimeadd.9 | 185 ++++ static/openbsd/man9/bio_register.9 | 66 ++ static/openbsd/man9/boot.9 | 107 ++ static/openbsd/man9/bpf_mtap.9 | 306 ++++++ static/openbsd/man9/buffercache.9 | 395 +++++++ static/openbsd/man9/bufq_init.9 | 145 +++ static/openbsd/man9/bus_dma.9 | 891 ++++++++++++++++ static/openbsd/man9/bus_space.9 | 1520 +++++++++++++++++++++++++++ static/openbsd/man9/clockintr.9 | 333 ++++++ static/openbsd/man9/clockintr_bind.9 | 296 ++++++ static/openbsd/man9/cond_init.9 | 126 +++ static/openbsd/man9/config_attach.9 | 84 ++ static/openbsd/man9/config_defer.9 | 62 ++ static/openbsd/man9/copy.9 | 136 +++ static/openbsd/man9/counters_alloc.9 | 312 ++++++ static/openbsd/man9/cpu_xcall.9 | 114 ++ static/openbsd/man9/cpumem_get.9 | 239 +++++ static/openbsd/man9/crypto.9 | 518 +++++++++ static/openbsd/man9/delay.9 | 35 + static/openbsd/man9/disk.9 | 366 +++++++ static/openbsd/man9/disklabel.9 | 152 +++ static/openbsd/man9/dma_alloc.9 | 74 ++ static/openbsd/man9/dohooks.9 | 71 ++ static/openbsd/man9/dostartuphooks.9 | 61 ++ static/openbsd/man9/evcount.9 | 230 ++++ static/openbsd/man9/extent.9 | 425 ++++++++ static/openbsd/man9/fb_setup.9 | 238 +++++ static/openbsd/man9/ffs.9 | 68 ++ static/openbsd/man9/file.9 | 154 +++ static/openbsd/man9/fork1.9 | 167 +++ static/openbsd/man9/getdevvp.9 | 90 ++ static/openbsd/man9/getnewvnode.9 | 83 ++ static/openbsd/man9/getsn.9 | 48 + static/openbsd/man9/hardclock.9 | 77 ++ static/openbsd/man9/hashinit.9 | 91 ++ static/openbsd/man9/hook_establish.9 | 89 ++ static/openbsd/man9/hz.9 | 91 ++ static/openbsd/man9/idgen32.9 | 56 + static/openbsd/man9/ieee80211.9 | 285 +++++ static/openbsd/man9/ieee80211_crypto.9 | 101 ++ static/openbsd/man9/ieee80211_input.9 | 115 ++ static/openbsd/man9/ieee80211_ioctl.9 | 82 ++ static/openbsd/man9/ieee80211_node.9 | 267 +++++ static/openbsd/man9/ieee80211_output.9 | 154 +++ static/openbsd/man9/ieee80211_proto.9 | 77 ++ static/openbsd/man9/ieee80211_radiotap.9 | 259 +++++ static/openbsd/man9/if_addrhook_add.9 | 120 +++ static/openbsd/man9/if_get.9 | 80 ++ static/openbsd/man9/if_rxr_init.9 | 189 ++++ static/openbsd/man9/ifiq_input.9 | 66 ++ static/openbsd/man9/ifq_deq_begin.9 | 76 ++ static/openbsd/man9/ifq_enqueue.9 | 172 +++ static/openbsd/man9/iic.9 | 360 +++++++ static/openbsd/man9/imax.9 | 93 ++ static/openbsd/man9/inittodr.9 | 95 ++ static/openbsd/man9/intr_barrier.9 | 42 + static/openbsd/man9/intrmap_create.9 | 125 +++ static/openbsd/man9/intro.9 | 46 + static/openbsd/man9/kcov_remote_register.9 | 95 ++ static/openbsd/man9/km_alloc.9 | 181 ++++ static/openbsd/man9/knote.9 | 114 ++ static/openbsd/man9/kstat_create.9 | 268 +++++ static/openbsd/man9/kstat_kv_init.9 | 125 +++ static/openbsd/man9/kthread.9 | 97 ++ static/openbsd/man9/ktrace.9 | 157 +++ static/openbsd/man9/lim_cur.9 | 119 +++ static/openbsd/man9/loadfirmware.9 | 58 + static/openbsd/man9/log.9 | 75 ++ static/openbsd/man9/malloc.9 | 403 +++++++ static/openbsd/man9/mbuf.9 | 826 +++++++++++++++ static/openbsd/man9/mbuf_tags.9 | 265 +++++ static/openbsd/man9/md5.9 | 72 ++ static/openbsd/man9/membar_sync.9 | 124 +++ static/openbsd/man9/memcmp.9 | 95 ++ static/openbsd/man9/mi_switch.9 | 111 ++ static/openbsd/man9/microtime.9 | 219 ++++ static/openbsd/man9/ml_init.9 | 184 ++++ static/openbsd/man9/mq_init.9 | 251 +++++ static/openbsd/man9/mutex.9 | 186 ++++ static/openbsd/man9/namei.9 | 326 ++++++ static/openbsd/man9/panic.9 | 76 ++ static/openbsd/man9/pci_conf_read.9 | 121 +++ static/openbsd/man9/pci_intr_map.9 | 193 ++++ static/openbsd/man9/pci_mapreg_map.9 | 133 +++ static/openbsd/man9/physio.9 | 130 +++ static/openbsd/man9/pmap.9 | 424 ++++++++ static/openbsd/man9/pool.9 | 352 +++++++ static/openbsd/man9/pool_cache_init.9 | 198 ++++ static/openbsd/man9/ppsratecheck.9 | 89 ++ static/openbsd/man9/printf.9 | 255 +++++ static/openbsd/man9/psignal.9 | 125 +++ static/openbsd/man9/radio.9 | 118 +++ static/openbsd/man9/rasops.9 | 239 +++++ static/openbsd/man9/ratecheck.9 | 138 +++ static/openbsd/man9/refcnt_init.9 | 131 +++ static/openbsd/man9/resettodr.9 | 50 + static/openbsd/man9/route.9 | 103 ++ static/openbsd/man9/rssadapt.9 | 418 ++++++++ static/openbsd/man9/rt_ifa_add.9 | 121 +++ static/openbsd/man9/rt_timer_add.9 | 108 ++ static/openbsd/man9/rtable_add.9 | 92 ++ static/openbsd/man9/rtable_walk.9 | 74 ++ static/openbsd/man9/rtalloc.9 | 106 ++ static/openbsd/man9/rtlabel_id2name.9 | 75 ++ static/openbsd/man9/rtrequest.9 | 138 +++ static/openbsd/man9/rwlock.9 | 271 +++++ static/openbsd/man9/sensor_attach.9 | 157 +++ static/openbsd/man9/sigio_init.9 | 147 +++ static/openbsd/man9/smr_call.9 | 135 +++ static/openbsd/man9/socreate.9 | 312 ++++++ static/openbsd/man9/sosplice.9 | 279 +++++ static/openbsd/man9/spl.9 | 253 +++++ static/openbsd/man9/srp_enter.9 | 233 ++++ static/openbsd/man9/srpl_rc_init.9 | 182 ++++ static/openbsd/man9/startuphook_establish.9 | 85 ++ static/openbsd/man9/stoeplitz_to_key.9 | 136 +++ static/openbsd/man9/strcmp.9 | 86 ++ static/openbsd/man9/strnstr.9 | 90 ++ static/openbsd/man9/style.9 | 614 +++++++++++ static/openbsd/man9/syscall.9 | 244 +++++ static/openbsd/man9/sysctl_int.9 | 281 +++++ static/openbsd/man9/task_add.9 | 237 +++++ static/openbsd/man9/tc_init.9 | 141 +++ static/openbsd/man9/tfind.9 | 58 + static/openbsd/man9/thread_fork.9 | 105 ++ static/openbsd/man9/timeout.9 | 419 ++++++++ static/openbsd/man9/tsleep.9 | 287 +++++ static/openbsd/man9/tvtohz.9 | 63 ++ static/openbsd/man9/uiomove.9 | 137 +++ static/openbsd/man9/usb_add_task.9 | 122 +++ static/openbsd/man9/usbd_close_pipe.9 | 48 + static/openbsd/man9/usbd_open_pipe.9 | 132 +++ static/openbsd/man9/usbd_ref_wait.9 | 64 ++ static/openbsd/man9/usbd_transfer.9 | 117 +++ static/openbsd/man9/uvm_fault.9 | 55 + static/openbsd/man9/uvm_init.9 | 450 ++++++++ static/openbsd/man9/uvm_km_alloc.9 | 65 ++ static/openbsd/man9/uvm_map.9 | 331 ++++++ static/openbsd/man9/uvm_pagealloc.9 | 166 +++ static/openbsd/man9/uvm_vslock.9 | 73 ++ static/openbsd/man9/uvn_attach.9 | 99 ++ static/openbsd/man9/vaccess.9 | 98 ++ static/openbsd/man9/vclean.9 | 80 ++ static/openbsd/man9/vcount.9 | 61 ++ static/openbsd/man9/vdevgone.9 | 81 ++ static/openbsd/man9/vfinddev.9 | 60 ++ static/openbsd/man9/vflush.9 | 79 ++ static/openbsd/man9/vflushbuf.9 | 33 + static/openbsd/man9/vfs.9 | 57 + static/openbsd/man9/vfs_busy.9 | 85 ++ static/openbsd/man9/vfs_cache.9 | 179 ++++ static/openbsd/man9/vget.9 | 90 ++ static/openbsd/man9/vgone.9 | 72 ++ static/openbsd/man9/vhold.9 | 74 ++ static/openbsd/man9/vinvalbuf.9 | 132 +++ static/openbsd/man9/vnode.9 | 416 ++++++++ static/openbsd/man9/vnsubr.9 | 304 ++++++ static/openbsd/man9/vput.9 | 62 ++ static/openbsd/man9/vrecycle.9 | 67 ++ static/openbsd/man9/vref.9 | 66 ++ static/openbsd/man9/vrele.9 | 66 ++ static/openbsd/man9/vwaitforio.9 | 81 ++ static/openbsd/man9/vwakeup.9 | 48 + static/openbsd/man9/wdog_register.9 | 66 ++ static/openbsd/man9/wsfont_init.9 | 188 ++++ 186 files changed, 33188 insertions(+) create mode 100644 static/openbsd/man9/KASSERT.9 create mode 100644 static/openbsd/man9/Makefile create mode 100644 static/openbsd/man9/RBT_INIT.9 create mode 100644 static/openbsd/man9/SMR_LIST_INIT.9 create mode 100644 static/openbsd/man9/SMR_PTR_GET.9 create mode 100644 static/openbsd/man9/SRPL_EMPTY_LOCKED.9 create mode 100644 static/openbsd/man9/SipHash24.9 create mode 100644 static/openbsd/man9/VOP_LOOKUP.9 create mode 100644 static/openbsd/man9/aml_evalnode.9 create mode 100644 static/openbsd/man9/arc4random.9 create mode 100644 static/openbsd/man9/atomic_add_int.9 create mode 100644 static/openbsd/man9/atomic_cas_uint.9 create mode 100644 static/openbsd/man9/atomic_dec_int.9 create mode 100644 static/openbsd/man9/atomic_inc_int.9 create mode 100644 static/openbsd/man9/atomic_load_int.9 create mode 100644 static/openbsd/man9/atomic_setbits_int.9 create mode 100644 static/openbsd/man9/atomic_sub_int.9 create mode 100644 static/openbsd/man9/atomic_swap_uint.9 create mode 100644 static/openbsd/man9/audio.9 create mode 100644 static/openbsd/man9/autoconf.9 create mode 100644 static/openbsd/man9/bemtoh32.9 create mode 100644 static/openbsd/man9/bintimeadd.9 create mode 100644 static/openbsd/man9/bio_register.9 create mode 100644 static/openbsd/man9/boot.9 create mode 100644 static/openbsd/man9/bpf_mtap.9 create mode 100644 static/openbsd/man9/buffercache.9 create mode 100644 static/openbsd/man9/bufq_init.9 create mode 100644 static/openbsd/man9/bus_dma.9 create mode 100644 static/openbsd/man9/bus_space.9 create mode 100644 static/openbsd/man9/clockintr.9 create mode 100644 static/openbsd/man9/clockintr_bind.9 create mode 100644 static/openbsd/man9/cond_init.9 create mode 100644 static/openbsd/man9/config_attach.9 create mode 100644 static/openbsd/man9/config_defer.9 create mode 100644 static/openbsd/man9/copy.9 create mode 100644 static/openbsd/man9/counters_alloc.9 create mode 100644 static/openbsd/man9/cpu_xcall.9 create mode 100644 static/openbsd/man9/cpumem_get.9 create mode 100644 static/openbsd/man9/crypto.9 create mode 100644 static/openbsd/man9/delay.9 create mode 100644 static/openbsd/man9/disk.9 create mode 100644 static/openbsd/man9/disklabel.9 create mode 100644 static/openbsd/man9/dma_alloc.9 create mode 100644 static/openbsd/man9/dohooks.9 create mode 100644 static/openbsd/man9/dostartuphooks.9 create mode 100644 static/openbsd/man9/evcount.9 create mode 100644 static/openbsd/man9/extent.9 create mode 100644 static/openbsd/man9/fb_setup.9 create mode 100644 static/openbsd/man9/ffs.9 create mode 100644 static/openbsd/man9/file.9 create mode 100644 static/openbsd/man9/fork1.9 create mode 100644 static/openbsd/man9/getdevvp.9 create mode 100644 static/openbsd/man9/getnewvnode.9 create mode 100644 static/openbsd/man9/getsn.9 create mode 100644 static/openbsd/man9/hardclock.9 create mode 100644 static/openbsd/man9/hashinit.9 create mode 100644 static/openbsd/man9/hook_establish.9 create mode 100644 static/openbsd/man9/hz.9 create mode 100644 static/openbsd/man9/idgen32.9 create mode 100644 static/openbsd/man9/ieee80211.9 create mode 100644 static/openbsd/man9/ieee80211_crypto.9 create mode 100644 static/openbsd/man9/ieee80211_input.9 create mode 100644 static/openbsd/man9/ieee80211_ioctl.9 create mode 100644 static/openbsd/man9/ieee80211_node.9 create mode 100644 static/openbsd/man9/ieee80211_output.9 create mode 100644 static/openbsd/man9/ieee80211_proto.9 create mode 100644 static/openbsd/man9/ieee80211_radiotap.9 create mode 100644 static/openbsd/man9/if_addrhook_add.9 create mode 100644 static/openbsd/man9/if_get.9 create mode 100644 static/openbsd/man9/if_rxr_init.9 create mode 100644 static/openbsd/man9/ifiq_input.9 create mode 100644 static/openbsd/man9/ifq_deq_begin.9 create mode 100644 static/openbsd/man9/ifq_enqueue.9 create mode 100644 static/openbsd/man9/iic.9 create mode 100644 static/openbsd/man9/imax.9 create mode 100644 static/openbsd/man9/inittodr.9 create mode 100644 static/openbsd/man9/intr_barrier.9 create mode 100644 static/openbsd/man9/intrmap_create.9 create mode 100644 static/openbsd/man9/intro.9 create mode 100644 static/openbsd/man9/kcov_remote_register.9 create mode 100644 static/openbsd/man9/km_alloc.9 create mode 100644 static/openbsd/man9/knote.9 create mode 100644 static/openbsd/man9/kstat_create.9 create mode 100644 static/openbsd/man9/kstat_kv_init.9 create mode 100644 static/openbsd/man9/kthread.9 create mode 100644 static/openbsd/man9/ktrace.9 create mode 100644 static/openbsd/man9/lim_cur.9 create mode 100644 static/openbsd/man9/loadfirmware.9 create mode 100644 static/openbsd/man9/log.9 create mode 100644 static/openbsd/man9/malloc.9 create mode 100644 static/openbsd/man9/mbuf.9 create mode 100644 static/openbsd/man9/mbuf_tags.9 create mode 100644 static/openbsd/man9/md5.9 create mode 100644 static/openbsd/man9/membar_sync.9 create mode 100644 static/openbsd/man9/memcmp.9 create mode 100644 static/openbsd/man9/mi_switch.9 create mode 100644 static/openbsd/man9/microtime.9 create mode 100644 static/openbsd/man9/ml_init.9 create mode 100644 static/openbsd/man9/mq_init.9 create mode 100644 static/openbsd/man9/mutex.9 create mode 100644 static/openbsd/man9/namei.9 create mode 100644 static/openbsd/man9/panic.9 create mode 100644 static/openbsd/man9/pci_conf_read.9 create mode 100644 static/openbsd/man9/pci_intr_map.9 create mode 100644 static/openbsd/man9/pci_mapreg_map.9 create mode 100644 static/openbsd/man9/physio.9 create mode 100644 static/openbsd/man9/pmap.9 create mode 100644 static/openbsd/man9/pool.9 create mode 100644 static/openbsd/man9/pool_cache_init.9 create mode 100644 static/openbsd/man9/ppsratecheck.9 create mode 100644 static/openbsd/man9/printf.9 create mode 100644 static/openbsd/man9/psignal.9 create mode 100644 static/openbsd/man9/radio.9 create mode 100644 static/openbsd/man9/rasops.9 create mode 100644 static/openbsd/man9/ratecheck.9 create mode 100644 static/openbsd/man9/refcnt_init.9 create mode 100644 static/openbsd/man9/resettodr.9 create mode 100644 static/openbsd/man9/route.9 create mode 100644 static/openbsd/man9/rssadapt.9 create mode 100644 static/openbsd/man9/rt_ifa_add.9 create mode 100644 static/openbsd/man9/rt_timer_add.9 create mode 100644 static/openbsd/man9/rtable_add.9 create mode 100644 static/openbsd/man9/rtable_walk.9 create mode 100644 static/openbsd/man9/rtalloc.9 create mode 100644 static/openbsd/man9/rtlabel_id2name.9 create mode 100644 static/openbsd/man9/rtrequest.9 create mode 100644 static/openbsd/man9/rwlock.9 create mode 100644 static/openbsd/man9/sensor_attach.9 create mode 100644 static/openbsd/man9/sigio_init.9 create mode 100644 static/openbsd/man9/smr_call.9 create mode 100644 static/openbsd/man9/socreate.9 create mode 100644 static/openbsd/man9/sosplice.9 create mode 100644 static/openbsd/man9/spl.9 create mode 100644 static/openbsd/man9/srp_enter.9 create mode 100644 static/openbsd/man9/srpl_rc_init.9 create mode 100644 static/openbsd/man9/startuphook_establish.9 create mode 100644 static/openbsd/man9/stoeplitz_to_key.9 create mode 100644 static/openbsd/man9/strcmp.9 create mode 100644 static/openbsd/man9/strnstr.9 create mode 100644 static/openbsd/man9/style.9 create mode 100644 static/openbsd/man9/syscall.9 create mode 100644 static/openbsd/man9/sysctl_int.9 create mode 100644 static/openbsd/man9/task_add.9 create mode 100644 static/openbsd/man9/tc_init.9 create mode 100644 static/openbsd/man9/tfind.9 create mode 100644 static/openbsd/man9/thread_fork.9 create mode 100644 static/openbsd/man9/timeout.9 create mode 100644 static/openbsd/man9/tsleep.9 create mode 100644 static/openbsd/man9/tvtohz.9 create mode 100644 static/openbsd/man9/uiomove.9 create mode 100644 static/openbsd/man9/usb_add_task.9 create mode 100644 static/openbsd/man9/usbd_close_pipe.9 create mode 100644 static/openbsd/man9/usbd_open_pipe.9 create mode 100644 static/openbsd/man9/usbd_ref_wait.9 create mode 100644 static/openbsd/man9/usbd_transfer.9 create mode 100644 static/openbsd/man9/uvm_fault.9 create mode 100644 static/openbsd/man9/uvm_init.9 create mode 100644 static/openbsd/man9/uvm_km_alloc.9 create mode 100644 static/openbsd/man9/uvm_map.9 create mode 100644 static/openbsd/man9/uvm_pagealloc.9 create mode 100644 static/openbsd/man9/uvm_vslock.9 create mode 100644 static/openbsd/man9/uvn_attach.9 create mode 100644 static/openbsd/man9/vaccess.9 create mode 100644 static/openbsd/man9/vclean.9 create mode 100644 static/openbsd/man9/vcount.9 create mode 100644 static/openbsd/man9/vdevgone.9 create mode 100644 static/openbsd/man9/vfinddev.9 create mode 100644 static/openbsd/man9/vflush.9 create mode 100644 static/openbsd/man9/vflushbuf.9 create mode 100644 static/openbsd/man9/vfs.9 create mode 100644 static/openbsd/man9/vfs_busy.9 create mode 100644 static/openbsd/man9/vfs_cache.9 create mode 100644 static/openbsd/man9/vget.9 create mode 100644 static/openbsd/man9/vgone.9 create mode 100644 static/openbsd/man9/vhold.9 create mode 100644 static/openbsd/man9/vinvalbuf.9 create mode 100644 static/openbsd/man9/vnode.9 create mode 100644 static/openbsd/man9/vnsubr.9 create mode 100644 static/openbsd/man9/vput.9 create mode 100644 static/openbsd/man9/vrecycle.9 create mode 100644 static/openbsd/man9/vref.9 create mode 100644 static/openbsd/man9/vrele.9 create mode 100644 static/openbsd/man9/vwaitforio.9 create mode 100644 static/openbsd/man9/vwakeup.9 create mode 100644 static/openbsd/man9/wdog_register.9 create mode 100644 static/openbsd/man9/wsfont_init.9 (limited to 'static/openbsd/man9') diff --git a/static/openbsd/man9/KASSERT.9 b/static/openbsd/man9/KASSERT.9 new file mode 100644 index 00000000..9f88a687 --- /dev/null +++ b/static/openbsd/man9/KASSERT.9 @@ -0,0 +1,105 @@ +.\" $OpenBSD: KASSERT.9,v 1.3 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 2002, 2003 CubeSoft Communications, 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, 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 $Mdocdate: June 13 2025 $ +.Dt KASSERT 9 +.Os +.Sh NAME +.Nm assert , +.Nm KASSERT , +.Nm KDASSERT , +.Nm KASSERTMSG , +.Nm KDASSERTMSG , +.Nm CTASSERT +.Nd kernel assert library routines +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn assert "CONDITION" +.Ft void +.Fn KASSERT "CONDITION" +.Ft void +.Fn KDASSERT "CONDITION" +.Ft void +.Fn KASSERTMSG "CONDITION" "fmt" "..." +.Ft void +.Fn KDASSERTMSG "CONDITION" "fmt" "..." +.Ft void +.Fn CTASSERT "CONDITION" +.Sh DESCRIPTION +The +kernel +library implements a set of useful functions and macros implementing +expression verification. +.Pp +These macros cause kernel +.Xr panic 9 +if the given condition evaluates to false. +.Fn assert +tests are always compiled in. +.Fn KASSERT +and +.Fn KASSERTMSG +tests are only included if the kernel has +.Dv DIAGNOSTIC +enabled. +.Fn KDASSERT +and +.Fn KDASSERTMSG +tests are only included if the kernel has +.Dv DEBUG +enabled. +The +.Fn KASSERTMSG +and +.Fn KDASSERTMSG +macros append +to the +.Xr panic 9 +format string the message specified by +.Fa format +and its subsequent arguments, similar to +.Xr printf 9 +functions. +.Pp +.Fn CTASSERT +causes a compile time error if the given condition evaluates to +false. +Its main purpose is to verify assertions about type and struct sizes that +would otherwise make the code fail at run time. +.Fn CTASSERT +can be used in global scope or at the start of blocks, where variable +declarations are allowed. +.Sh SEE ALSO +.Xr assert 3 , +.Xr panic 9 +.Sh HISTORY +The +.Fn KASSERTMSG +and +.Fn KDASSERTMSG +macros are taken from +.Nx . diff --git a/static/openbsd/man9/Makefile b/static/openbsd/man9/Makefile new file mode 100644 index 00000000..d0a9cd95 --- /dev/null +++ b/static/openbsd/man9/Makefile @@ -0,0 +1,188 @@ +MAN = aml_evalnode.9 \ + arc4random.9 \ + atomic_add_int.9 \ + atomic_cas_uint.9 \ + atomic_dec_int.9 \ + atomic_inc_int.9 \ + atomic_load_int.9 \ + atomic_setbits_int.9 \ + atomic_sub_int.9 \ + atomic_swap_uint.9 \ + audio.9 \ + autoconf.9 \ + bemtoh32.9 \ + bintimeadd.9 \ + bio_register.9 \ + boot.9 \ + bpf_mtap.9 \ + buffercache.9 \ + bufq_init.9 \ + bus_dma.9 \ + bus_space.9 \ + clockintr_bind.9 \ + clockintr.9 \ + cond_init.9 \ + config_attach.9 \ + config_defer.9 \ + copy.9 \ + counters_alloc.9 \ + cpu_xcall.9 \ + cpumem_get.9 \ + crypto.9 \ + delay.9 \ + disk.9 \ + disklabel.9 \ + dma_alloc.9 \ + dohooks.9 \ + dostartuphooks.9 \ + evcount.9 \ + extent.9 \ + fb_setup.9 \ + ffs.9 \ + file.9 \ + fork1.9 \ + getdevvp.9 \ + getnewvnode.9 \ + getsn.9 \ + hardclock.9 \ + hashinit.9 \ + hook_establish.9 \ + hz.9 \ + idgen32.9 \ + ieee80211_crypto.9 \ + ieee80211_input.9 \ + ieee80211_ioctl.9 \ + ieee80211_node.9 \ + ieee80211_output.9 \ + ieee80211_proto.9 \ + ieee80211_radiotap.9 \ + ieee80211.9 \ + if_addrhook_add.9 \ + if_get.9 \ + if_rxr_init.9 \ + ifiq_input.9 \ + ifq_deq_begin.9 \ + ifq_enqueue.9 \ + iic.9 \ + imax.9 \ + inittodr.9 \ + intr_barrier.9 \ + intrmap_create.9 \ + intro.9 \ + KASSERT.9 \ + kcov_remote_register.9 \ + km_alloc.9 \ + knote.9 \ + kstat_create.9 \ + kstat_kv_init.9 \ + kthread.9 \ + ktrace.9 \ + lim_cur.9 \ + loadfirmware.9 \ + log.9 \ + malloc.9 \ + mbuf_tags.9 \ + mbuf.9 \ + md5.9 \ + membar_sync.9 \ + memcmp.9 \ + mi_switch.9 \ + microtime.9 \ + ml_init.9 \ + mq_init.9 \ + mutex.9 \ + namei.9 \ + panic.9 \ + pci_conf_read.9 \ + pci_intr_map.9 \ + pci_mapreg_map.9 \ + physio.9 \ + pmap.9 \ + pool_cache_init.9 \ + pool.9 \ + ppsratecheck.9 \ + printf.9 \ + psignal.9 \ + radio.9 \ + rasops.9 \ + ratecheck.9 \ + RBT_INIT.9 \ + refcnt_init.9 \ + resettodr.9 \ + route.9 \ + rssadapt.9 \ + rt_ifa_add.9 \ + rt_timer_add.9 \ + rtable_add.9 \ + rtable_walk.9 \ + rtalloc.9 \ + rtlabel_id2name.9 \ + rtrequest.9 \ + rwlock.9 \ + sensor_attach.9 \ + sigio_init.9 \ + SipHash24.9 \ + smr_call.9 \ + SMR_LIST_INIT.9 \ + SMR_PTR_GET.9 \ + socreate.9 \ + sosplice.9 \ + spl.9 \ + srp_enter.9 \ + SRPL_EMPTY_LOCKED.9 \ + srpl_rc_init.9 \ + startuphook_establish.9 \ + stoeplitz_to_key.9 \ + strcmp.9 \ + strnstr.9 \ + style.9 \ + syscall.9 \ + sysctl_int.9 \ + task_add.9 \ + tc_init.9 \ + tfind.9 \ + thread_fork.9 \ + timeout.9 \ + tsleep.9 \ + tvtohz.9 \ + uiomove.9 \ + usb_add_task.9 \ + usbd_close_pipe.9 \ + usbd_open_pipe.9 \ + usbd_ref_wait.9 \ + usbd_transfer.9 \ + uvm_fault.9 \ + uvm_init.9 \ + uvm_km_alloc.9 \ + uvm_map.9 \ + uvm_pagealloc.9 \ + uvm_vslock.9 \ + uvn_attach.9 \ + vaccess.9 \ + vclean.9 \ + vcount.9 \ + vdevgone.9 \ + vfinddev.9 \ + vflush.9 \ + vflushbuf.9 \ + vfs_busy.9 \ + vfs_cache.9 \ + vfs.9 \ + vget.9 \ + vgone.9 \ + vhold.9 \ + vinvalbuf.9 \ + vnode.9 \ + vnsubr.9 \ + VOP_LOOKUP.9 \ + vput.9 \ + vrecycle.9 \ + vref.9 \ + vrele.9 \ + vwaitforio.9 \ + vwakeup.9 \ + wdog_register.9 \ + wsfont_init.9 + +include ../../mandoc.mk + diff --git a/static/openbsd/man9/RBT_INIT.9 b/static/openbsd/man9/RBT_INIT.9 new file mode 100644 index 00000000..9a59c6cd --- /dev/null +++ b/static/openbsd/man9/RBT_INIT.9 @@ -0,0 +1,563 @@ +.\" $OpenBSD: RBT_INIT.9,v 1.6 2017/06/08 03:12:53 dlg 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. +.\" * +.\" * 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. +.\" */ +.\" +.\" Copyright (c) 2016 David Gwynne +.\" +.\" 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: June 8 2017 $ +.Dt RBT_INIT 9 +.Os +.Sh NAME +.Nm RBT_HEAD , +.Nm RBT_ENTRY , +.Nm RBT_PROTOTYPE , +.Nm RBT_GENERATE , +.Nm RBT_INITIALIZER , +.Nm RBT_INIT , +.Nm RBT_INSERT , +.Nm RBT_REMOVE , +.Nm RBT_FIND , +.Nm RBT_NFIND , +.Nm RBT_EMPTY , +.Nm RBT_ROOT , +.Nm RBT_MIN , +.Nm RBT_MAX , +.Nm RBT_NEXT , +.Nm RBT_PREV , +.Nm RBT_LEFT , +.Nm RBT_RIGHT , +.Nm RBT_PARENT , +.Nm RBT_SET_LEFT , +.Nm RBT_SET_RIGHT , +.Nm RBT_SET_PARENT , +.Nm RBT_FOREACH , +.Nm RBT_FOREACH_SAFE , +.Nm RBT_FOREACH_REVERSE , +.Nm RBT_FOREACH_REVERSE_SAFE , +.Nm RBT_POISON , +.Nm RBT_CHECK +.Nd Kernel red-black trees +.Sh SYNOPSIS +.In sys/tree.h +.Fn RBT_HEAD "NAME" "TYPE" +.Fn RBT_ENTRY "TYPE" +.Fo RBT_PROTOTYPE +.Fa "NAME" +.Fa "TYPE" +.Fa "ENTRY" +.Fa "int (*compare)(const struct TYPE *, const struct TYPE *)" +.Fc +.Fo RBT_GENERATE +.Fa "NAME" +.Fa "TYPE" +.Fa "ENTRY" +.Fa "int (*compare)(const struct TYPE *, const struct TYPE *)" +.Fc +.Ft struct NAME +.Fn RBT_INITIALIZER "struct NAME *self" +.Ft void +.Fn RBT_INIT "NAME" "struct NAME *rbt" +.Ft struct TYPE * +.Fn RBT_INSERT "NAME" "struct NAME *rbt" "struct TYPE *elm" +.Ft struct TYPE * +.Fn RBT_REMOVE "NAME" "struct NAME *rbt" "struct TYPE *elm" +.Ft struct TYPE * +.Fn RBT_FIND "NAME" "struct NAME *rbt" "const struct TYPE *key" +.Ft struct TYPE * +.Fn RBT_NFIND "NAME" "struct NAME *rbt" "const struct TYPE *key" +.Ft int +.Fn RBT_EMPTY "NAME" "struct NAME *rbt" +.Ft struct TYPE * +.Fn RBT_ROOT "NAME" "struct NAME *rbt" +.Ft struct TYPE * +.Fn RBT_MIN "NAME" "struct NAME *rbt" +.Ft struct TYPE * +.Fn RBT_MAX "NAME" "struct NAME *rbt" +.Ft struct TYPE * +.Fn RBT_NEXT "NAME" "struct TYPE *elm" +.Ft struct TYPE * +.Fn RBT_PREV "NAME" "struct TYPE *elm" +.Ft struct TYPE * +.Fn RBT_LEFT "NAME" "struct TYPE *elm" +.Ft struct TYPE * +.Fn RBT_RIGHT "NAME" "struct TYPE *elm" +.Ft struct TYPE * +.Fn RBT_PARENT "NAME" "struct TYPE *elm" +.Ft void +.Fn RBT_SET_LEFT "NAME" "struct TYPE *elm" "struct TYPE *left" +.Ft void +.Fn RBT_SET_RIGHT "NAME" "struct TYPE *elm" "struct TYPE *right" +.Ft void +.Fn RBT_SET_PARENT "NAME" "struct TYPE *elm" "struct TYPE *parent" +.Fo RBT_FOREACH +.Fa "VARNAME" +.Fa "NAME" +.Fa "struct NAME *rbt" +.Fc +.Fo RBT_FOREACH_REVERSE +.Fa "VARNAME" +.Fa "NAME" +.Fa "struct NAME *rbt" +.Fc +.Fo RBT_FOREACH_SAFE +.Fa "VARNAME" +.Fa "NAME" +.Fa "struct NAME *rbt" +.Fa "NEXTVARNAME" +.Fc +.Fo RBT_FOREACH_REVERSE_SAFE +.Fa "VARNAME" +.Fa "NAME" +.Fa "struct NAME *rbt" +.Fa "NEXTVARNAME" +.Fc +.Ft void +.Fn RBT_POISON "NAME" "struct TYPE *elm" "unsigned long poison" +.Ft int +.Fn RBT_CHECK "NAME" "struct TYPE *elm" "unsigned long poison" +.Sh DESCRIPTION +The red-black tree API provides data structures and operations for +storing structures in red-black trees. +.Pp +A red-black tree is a binary search tree with the node color as an +extra attribute. +It fulfills a set of conditions: +.Pp +.Bl -enum -compact -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 O(lg n). +The maximum height of a red-black tree is 2lg (n+1). +.Pp +This API is implemented as a set of functions that operate on generic +pointers, but users of the API generate wrappers and macros that provide +type safety when calling the functions. +.Pp +In the macro definitions, +.Fa TYPE +is the name of a structure that will be stored in a red-black tree. +The +.Fa TYPE +structure must contain an +.Fn RBT_ENTRY +field +that allows the element to be connected to a tree. +The argument +.Fa NAME +is the name of a red-black tree type that can store a particular +.Fa TYPE +element. +.Ss Creating a Red-Black Tree Type +The +.Fn RBT_HEAD +macro creates a red-black tree type to store +.Fa TYPE +structures as elements in the tree. +The argument +.Fa NAME +must uniquely identify every type of tree that is defined. +.Pp +.Fn RBT_PROTOTYPE +produces the wrappers for a red-black tree type identified by +.Fa NAME +to operate on elements of type +.Fa TYPE . +.Fa ENTRY +specifies which field in the +.Fa TYPE +structure is used to connect elements to +.Fa NAME +red-black trees. +Elements in the red-black tree are ordered according to the result of comparing +them with the +.Fa compare +function. +If the first argument to +.Fa compare +is to be ordered lower than the second, +the function returns a value smaller than zero. +If the first argument is to be ordered higher than the second, +the function returns a value greater than zero. +If they are equal, the function returns zero. +.Pp +.Fn RBT_GENERATE +produces the internal data structures used by the red-black tree +type identified by +.Fa NAME +to operate on elements of type +.Fa TYPE . +The +.Fa ENTRY +and +.Fa compare +arguments are the same as the +.Fn RBT_PROTOTYPE +arguments of the same names. +.Ss Initialising a Red-Black Tree +.Fn RBT_INIT +initialises the red-black tree +.Fa rbt +of type +.Fa NAME +to an empty state. +.Pp +.Fn RBT_INITIALIZER +can be used to initialise a declaration of the red-black tree +.Fa self +of type +.Fa NAME +to an empty state. +.Ss Red-Black Tree Operations +.Fn RBT_INSERT +inserts the element +.Fa elm +into the red-black tree +.Fa rbt +of type +.Fa NAME . +Upon success, +.Dv NULL +is returned. +If a matching element already exists in the tree, the insertion is +aborted and a pointer to the existing element is returned. +.Pp +.Fn RBT_REMOVE +removes the element +.Fa elm +from the red-black tree +.Fa rbt +of type +.Fa NAME . +.Fa elm +must exist in the tree +.Fa rbt +before it is removed. +.Pp +.Fn RBT_FIND +performs a binary search for an exact match of +.Fa key +in the red-black tree +.Fa rbt +of type +.Fa NAME . +.Pp +.Fn RBT_NFIND +performs a binary search for the first node that is greater than or equal to +.Fa key +in the red-black tree +.Fa rbt +of type +.Fa NAME . +.Pp +.Fn RBT_EMPTY +returns if the red-black tree +.Fa rbt +of type +.Fa NAME +is empty. +.Pp +.Fn RBT_ROOT +returns the root element in the red-black tree +.Fa rbt +of type +.Fa NAME . +.Pp +.Fn RBT_MIN +returns the lowest ordered element in the red-black tree +.Fa rbt +of type +.Fa NAME . +.Pp +.Fn RBT_MAX +returns the highest ordered element in the red-black tree +.Fa rbt +of type +.Fa NAME . +.Ss Red-Black Tree Element Operations +.Fn RBT_NEXT +returns a pointer to the next ordered element after +.Fa elm +in a red-black tree of type +.Fa NAME . +.Pp +.Fn RBT_PREV +returns a pointer to the previous ordered element before +.Fa elm +in a red-black tree of type +.Fa NAME . +.Pp +.Fn RBT_LEFT +returns a pointer to the left child element of +.Fa elm +in a red-black tree of type +.Fa NAME . +.Pp +.Fn RBT_RIGHT +returns a pointer to the right child element of +.Fa elm +in a red-black tree of type +.Fa NAME . +.Pp +.Fn RBT_PARENT +returns a pointer to the parent element of +.Fa elm +in a red-black tree of type +.Fa NAME . +.Pp +.Fn RBT_SET_LEFT +sets the left child pointer of element +.Fa elm +to +.Fa left +in a red-black tree of type +.Fa NAME . +.Pp +.Fn RBT_SET_RIGHT +sets the right child pointer of element +.Fa elm +to +.Fa right +in a red-black tree of type +.Fa NAME . +.Pp +.Fn RBT_SET_PARENT +sets the parent pointer of element +.Fa elm +to +.Fa parent +in a red-black tree of type +.Fa NAME . +.Ss Red-Black Tree Iterators +The +.Fn RBT_FOREACH +macro iterates over the red-black tree +.Fa rbt +of type +.Fa NAME +from the lowest ordered element to the highest ordered element, +setting +.Fa VARNAME +to each element in turn. +.Pp +The +.Fn RBT_FOREACH_REVERSE +macro iterates over the red-black tree +.Fa rbt +of type +.Fa NAME +from the highest ordered element to the lowest ordered element, +setting +.Fa VARNAME +to each element in turn. +.Pp +The +.Fn RBT_FOREACH_SAFE +macro iterates over the red-black tree +.Fa rbt +of type +.Fa NAME +from the lowest ordered element to the highest ordered element, +setting +.Fa VARNAME +to each element in turn. +.Fa VARNAME +may be removed from the tree during iteration because a reference to the next +element is held in +.Fa NEXTVARNAME . +.Pp +The +.Fn RBT_FOREACH_REVERSE_SAFE +macro iterates over the red-black tree +.Fa rbt +of type +.Fa NAME +from the highest ordered element to the lowest ordered element, +setting +.Fa VARNAME +to each element in turn. +.Fa VARNAME +may be removed from the tree during iteration because a reference to the next +element is held in +.Fa NEXTVARNAME . +.Ss Red-Black Tree Element Poisoning +.Fn RBT_POISON +is used to poison the pointers in the RBT_ENTRY structure inside +.Fa elm +which has been removed from a red-black tree of type +.Fa NAME +with the +.Fa poison +value. +.Pp +.Fn RBT_CHECK +is used to verify that the pointers in the RBT_ENTRY structure inside +.Fa elm +are set to the +.Fa poison +value. +.Sh CONTEXT +.Fn RBT_INIT , +.Fn RBT_INSERT , +.Fn RBT_REMOVE , +.Fn RBT_FIND , +.Fn RBT_NFIND , +.Fn RBT_EMPTY , +.Fn RBT_ROOT , +.Fn RBT_MIN , +.Fn RBT_MAX , +.Fn RBT_NEXT , +.Fn RBT_PREV , +.Fn RBT_LEFT , +.Fn RBT_RIGHT , +.Fn RBT_PARENT , +.Fn RBT_SET_LEFT , +.Fn RBT_SET_RIGHT , +.Fn RBT_SET_PARENT , +.Fn RBT_FOREACH , +.Fn RBT_FOREACH_REVERSE , +.Fn RBT_FOREACH_SAFE , +.Fn RBT_FOREACH_SAFE_REVERSE , +.Fn RBT_POISON , +and +.Fn RBT_CHECK +can be called during autoconf, from process context, or from interrupt +context. +.Pp +It is up to the caller to provide appropriate locking around calls to +these functions to prevent concurrent access to the relevant data structures. +.Sh RETURN VALUES +.Fn RBT_INSERT +will return +.Dv NULL +on successful insertion of +.Fa elm +into the tree, otherwise it will return a reference to an existing +element with the same key. +.Pp +.Fn RBT_FIND +will return a reference to an element that compares as equal to +.Fa key , +or +.Dv NULL +if no such element could be found. +.Pp +.Fn RBT_NFIND +will return a reference to the nearest element that compares as equal or +greater to +.Fa key , +or +.Dv NULL +if no such element could be found. +.Pp +.Fn RBT_EMPTY +returns non-zero if the red-black tree +.Fa rbt +is empty, otherwise 0. +.Pp +.Fn RBT_ROOT +returns a reference to the root node in the red-black tree +.Fa rbt , +or +.Dv NULL +if it is empty. +.Pp +.Fn RBT_MIN +returns a reference to the lowest ordered element in the red-black tree +.Fa rbt , +or +.Dv NULL +if it is empty. +.Pp +.Fn RBT_MAX +returns a reference to the lowest ordered element in the red-black tree +.Fa rbt , +or +.Dv NULL +if it is empty. +.Pp +.Fn RBT_NEXT +returns a reference to the next ordered element in the red-black tree after +.Fa elm , +or +.Dv NULL +if it is the greatest element in the tree. +.Pp +.Fn RBT_PREV +returns a reference to the previous ordered element in the red-black tree before +.Fa elm , +or +.Dv NULL +if it is the lowest element in the tree. +.Pp +.Fn RBT_LEFT +returns a reference to the left child element of +.Fa elm , +or +.Dv NULL +if it is a leaf in the tree. +.Pp +.Fn RBT_RIGHT +returns a reference to the right child element of +.Fa elm , +or +.Dv NULL +if it is a leaf in the tree. +.Pp +.Fn RBT_PARENT +returns a reference to the parent element of +.Fa elm , +or +.Dv NULL +if it is the root of the tree. +.Pp +.Fn RBT_CHECK +returns non-zero if the RBT_ENTRY in the red-black tree element contains the +.Fa poison +value, +otherwise 0. +.Sh SEE ALSO +.Xr RB_INIT 3 +.Sh HISTORY +The red-black tree kernel API first appeared in +.Ox 6.1 . diff --git a/static/openbsd/man9/SMR_LIST_INIT.9 b/static/openbsd/man9/SMR_LIST_INIT.9 new file mode 100644 index 00000000..de917172 --- /dev/null +++ b/static/openbsd/man9/SMR_LIST_INIT.9 @@ -0,0 +1,445 @@ +.\" $OpenBSD: SMR_LIST_INIT.9,v 1.8 2022/01/16 05:38:58 jsg Exp $ +.\" +.\" Copyright (c) 2019 Visa Hankala +.\" +.\" 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 16 2022 $ +.Dt SMR_LIST_INIT 9 +.Os +.Sh NAME +.Nm SMR_SLIST_ENTRY , +.Nm SMR_SLIST_HEAD , +.Nm SMR_SLIST_HEAD_INITIALIZER , +.Nm SMR_SLIST_INIT , +.Nm SMR_SLIST_FIRST , +.Nm SMR_SLIST_NEXT , +.Nm SMR_SLIST_FOREACH , +.Nm SMR_SLIST_FIRST_LOCKED , +.Nm SMR_SLIST_NEXT_LOCKED , +.Nm SMR_SLIST_EMPTY_LOCKED , +.Nm SMR_SLIST_FOREACH_LOCKED , +.Nm SMR_SLIST_FOREACH_SAFE_LOCKED , +.Nm SMR_SLIST_INSERT_HEAD_LOCKED , +.Nm SMR_SLIST_INSERT_AFTER_LOCKED , +.Nm SMR_SLIST_REMOVE_HEAD_LOCKED , +.Nm SMR_SLIST_REMOVE_AFTER_LOCKED , +.Nm SMR_SLIST_REMOVE_LOCKED , +.Nm SMR_LIST_ENTRY , +.Nm SMR_LIST_HEAD , +.Nm SMR_LIST_HEAD_INITIALIZER , +.Nm SMR_LIST_INIT , +.Nm SMR_LIST_FIRST , +.Nm SMR_LIST_NEXT , +.Nm SMR_LIST_FOREACH , +.Nm SMR_LIST_FIRST_LOCKED , +.Nm SMR_LIST_NEXT_LOCKED , +.Nm SMR_LIST_EMPTY_LOCKED , +.Nm SMR_LIST_FOREACH_LOCKED , +.Nm SMR_LIST_FOREACH_SAFE_LOCKED , +.Nm SMR_LIST_INSERT_HEAD_LOCKED , +.Nm SMR_LIST_INSERT_AFTER_LOCKED , +.Nm SMR_LIST_INSERT_BEFORE_LOCKED , +.Nm SMR_LIST_REMOVE_LOCKED , +.Nm SMR_TAILQ_ENTRY , +.Nm SMR_TAILQ_HEAD , +.Nm SMR_TAILQ_HEAD_INITIALIZER , +.Nm SMR_TAILQ_INIT , +.Nm SMR_TAILQ_FIRST , +.Nm SMR_TAILQ_NEXT , +.Nm SMR_TAILQ_FOREACH , +.Nm SMR_TAILQ_FIRST_LOCKED , +.Nm SMR_TAILQ_NEXT_LOCKED , +.Nm SMR_TAILQ_LAST_LOCKED , +.Nm SMR_TAILQ_EMPTY_LOCKED , +.Nm SMR_TAILQ_FOREACH_LOCKED , +.Nm SMR_TAILQ_FOREACH_SAFE_LOCKED , +.Nm SMR_TAILQ_INSERT_HEAD_LOCKED , +.Nm SMR_TAILQ_INSERT_TAIL_LOCKED , +.Nm SMR_TAILQ_INSERT_AFTER_LOCKED , +.Nm SMR_TAILQ_INSERT_BEFORE_LOCKED , +.Nm SMR_TAILQ_REMOVE_LOCKED +.Nd SMR list macros +.Sh SYNOPSIS +.In sys/smr.h +.Fn SMR_SLIST_ENTRY "TYPE" +.Ft void +.Fn SMR_SLIST_INIT "SMR_SLIST_HEAD *head" +.Ft TYPE * +.Fn SMR_SLIST_FIRST "SMR_SLIST_HEAD *head" +.Ft TYPE * +.Fn SMR_SLIST_NEXT "TYPE *elm" "FIELDNAME" +.Fn SMR_SLIST_FOREACH "VARNAME" "SMR_SLIST_HEAD *head" "FIELDNAME" +.Ft TYPE * +.Fn SMR_SLIST_FIRST_LOCKED "SMR_SLIST_HEAD *head" +.Ft TYPE * +.Fn SMR_SLIST_NEXT_LOCKED "TYPE *elm" "FIELDNAME" +.Ft int +.Fn SMR_SLIST_EMPTY_LOCKED "SMR_SLIST_HEAD *head" +.Fn SMR_SLIST_FOREACH_LOCKED "VARNAME" "SMR_SLIST_HEAD *head" "FIELDNAME" +.Fn SMR_SLIST_FOREACH_SAFE_LOCKED "VARNAME" "SMR_LIST_HEAD *head" "FIELDNAME" "TEMP_VARNAME" +.Ft void +.Fn SMR_SLIST_INSERT_HEAD_LOCKED "SMR_SLIST_HEAD *head" "struct TYPE *elm" "FIELDNAME" +.Ft void +.Fn SMR_SLIST_INSERT_AFTER_LOCKED "struct TYPE *listelm" "struct TYPE *elm" "FIELDNAME" +.Ft void +.Fn SMR_SLIST_REMOVE_HEAD_LOCKED "SMR_SLIST_HEAD *head" "FIELDNAME" +.Ft void +.Fn SMR_SLIST_REMOVE_AFTER_LOCKED "struct TYPE *elm" "FIELDNAME" +.Ft void +.Fn SMR_SLIST_REMOVE_LOCKED "SMR_SLIST_HEAD *head" "struct TYPE *elm" "TYPE" "FIELDNAME" +.Fn SMR_LIST_ENTRY "TYPE" +.Ft void +.Fn SMR_LIST_INIT "SMR_LIST_HEAD *head" +.Ft TYPE * +.Fn SMR_LIST_FIRST "SMR_LIST_HEAD *head" +.Ft TYPE * +.Fn SMR_LIST_NEXT "TYPE *elm" "FIELDNAME" +.Ft TYPE * +.Fn SMR_LIST_FIRST_LOCKED "SMR_LIST_HEAD *head" +.Ft TYPE * +.Fn SMR_LIST_NEXT_LOCKED "TYPE *elm" "FIELDNAME" +.Ft int +.Fn SMR_LIST_EMPTY_LOCKED "SMR_LIST_HEAD *head" +.Fn SMR_LIST_FOREACH "VARNAME" "SMR_LIST_HEAD *head" "FIELDNAME" +.Fn SMR_LIST_FOREACH_LOCKED "VARNAME" "SMR_LIST_HEAD *head" "FIELDNAME" +.Fn SMR_LIST_FOREACH_SAFE_LOCKED "VARNAME" "SMR_LIST_HEAD *head" "FIELDNAME" "TEMP_VARNAME" +.Ft void +.Fn SMR_LIST_INSERT_HEAD_LOCKED "SMR_LIST_HEAD *head" "struct TYPE *elm" "FIELDNAME" +.Ft void +.Fn SMR_LIST_INSERT_AFTER_LOCKED "struct TYPE *listelm" "struct TYPE *elm" "FIELDNAME" +.Ft void +.Fn SMR_LIST_INSERT_BEFORE_LOCKED "struct TYPE *listelm" "struct TYPE *elm" "FIELDNAME" +.Ft void +.Fn SMR_LIST_REMOVE_LOCKED "struct TYPE *elm" "FIELDNAME" +.Fn SMR_TAILQ_ENTRY "TYPE" +.Ft void +.Fn SMR_TAILQ_INIT "SMR_TAILQ_HEAD *head" +.Ft TYPE * +.Fn SMR_TAILQ_FIRST "SMR_TAILQ_HEAD *head" +.Ft TYPE * +.Fn SMR_TAILQ_NEXT "TYPE *elm" "FIELDNAME" +.Ft TYPE * +.Fn SMR_TAILQ_FIRST_LOCKED "SMR_TAILQ_HEAD *head" +.Ft TYPE * +.Fn SMR_TAILQ_NEXT_LOCKED "TYPE *elm" "FIELDNAME" +.Ft TYPE * +.Fn SMR_TAILQ_LAST_LOCKED "SMR_TAILQ_HEAD *head" +.Fn SMR_TAILQ_FOREACH "VARNAME" "SMR_TAILQ_HEAD *head" "FIELDNAME" +.Fn SMR_TAILQ_FOREACH_LOCKED "VARNAME" "SMR_TAILQ_HEAD *head" "FIELDNAME" +.Fn SMR_TAILQ_FOREACH_SAFE_LOCKED "VARNAME" "SMR_TAILQ_HEAD *head" "FIELDNAME" "TEMP_VARNAME" +.Ft void +.Fn SMR_TAILQ_INSERT_HEAD_LOCKED "SMR_TAILQ_HEAD *head" "struct TYPE *elm" "FIELDNAME" +.Ft void +.Fn SMR_TAILQ_INSERT_TAIL_LOCKED "SMR_TAILQ_HEAD *head" "struct TYPE *elm" "FIELDNAME" +.Ft void +.Fn SMR_TAILQ_INSERT_AFTER_LOCKED "struct TYPE *listelm" "struct TYPE *elm" "FIELDNAME" +.Ft void +.Fn SMR_TAILQ_INSERT_BEFORE_LOCKED "struct TYPE *listelm" "struct TYPE *elm" "FIELDNAME" +.Ft void +.Fn SMR_TAILQ_REMOVE_LOCKED "struct TYPE *elm" "FIELDNAME" +.Sh DESCRIPTION +The SMR list macros define and operate on singly-linked lists, +lists and tail queues +that can be used with the safe memory reclamation mechanism. +A data structure built with these macros can be accessed concurrently +by multiple readers and a single writer. +.Pp +Readers have to access the data structure inside SMR read-side critical +section. +The critical section is entered using +.Xr smr_read_enter 9 , +and left using +.Xr smr_read_leave 9 . +.Pp +Writers must ensure exclusive write access. +That can be done using a lock, such as +.Xr mutex 9 +or +.Xr rwlock 9 . +The mutual exclusion of writers does not need to apply to readers. +.Pp +When an element has been removed from the data structure, the element +must not be deleted or re-inserted before all reader references to it have +disappeared. +The writer has to use either +.Xr smr_barrier 9 +or +.Xr smr_call 9 +to ensure that the element can no longer be accessed by readers. +.Ss Singly-Linked Lists +The +.Fn SMR_SLIST_ENTRY +macro declares a structure that connects the elements in the list. +.Pp +.Fn SMR_SLIST_INIT +initializes the list +.Fa head +to an empty state. +.Pp +.Fn SMR_SLIST_FIRST +and +.Fn SMR_SLIST_FIRST_LOCKED +return the first element on the list +.Fa head , +or NULL if the list is empty. +.Pp +.Fn SMR_SLIST_NEXT +and +.Fn SMR_SLIST_NEXT_LOCKED +return the successor of the element +.Fa elm , +or NULL if there are no more elements on the list. +.Pp +.Fn SMR_SLIST_EMPTY_LOCKED +returns true if the list +.Fa head +is empty. +.Pp +.Fn SMR_SLIST_FOREACH +and +.Fn SMR_SLIST_FOREACH_LOCKED +traverse the list +.Fa head +in forward direction. +.Pp +.Fn SMR_SLIST_FOREACH_SAFE_LOCKED +traverses the list +.Fa head +in forward direction. +It is permitted to remove the element referenced by variable +.Fa VARNAME +from the list and defer its freeing using +.Xr smr_call 9 . +.Pp +.Fn SMR_SLIST_INSERT_HEAD_LOCKED +inserts the new element +.Fa elm +at the head of the list. +.Pp +.Fn SMR_SLIST_INSERT_AFTER_LOCKED +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +.Fn SMR_SLIST_REMOVE_HEAD_LOCKED +removes the first element of the list +.Fa head . +.Pp +.Fn SMR_SLIST_REMOVE_AFTER_LOCKED +removes the list element immediately following +.Fa elm . +.Pp +.Fn SMR_SLIST_REMOVE_LOCKED +removes the list element +.Fa elm +from the list +.Fa head . +.Ss Linked Lists +The +.Fn SMR_LIST_ENTRY +macro declares a structure that connects the elements in the list. +.Pp +.Fn SMR_LIST_INIT +initializes the list +.Fa head +to an empty state. +.Pp +.Fn SMR_LIST_FIRST +and +.Fn SMR_LIST_FIRST_LOCKED +return the first element on the list +.Fa head , +or NULL if the list is empty. +.Pp +.Fn SMR_LIST_NEXT +and +.Fn SMR_LIST_NEXT_LOCKED +return the successor of the element +.Fa elm , +or NULL if there are no more elements on the list. +.Pp +.Fn SMR_LIST_EMPTY_LOCKED +returns true if the list +.Fa head +is empty. +.Pp +.Fn SMR_LIST_FOREACH +and +.Fn SMR_LIST_FOREACH_LOCKED +traverse the list +.Fa head +in forward direction. +.Pp +.Fn SMR_LIST_FOREACH_SAFE_LOCKED +traverses the list +.Fa head +in forward direction. +It is permitted to remove the element referenced by variable +.Fa VARNAME +from the list and defer its freeing using +.Xr smr_call 9 . +.Pp +.Fn SMR_LIST_INSERT_HEAD_LOCKED +inserts the new element +.Fa elm +at the head of the list. +.Pp +.Fn SMR_LIST_INSERT_AFTER_LOCKED +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +.Fn SMR_LIST_INSERT_BEFORE_LOCKED +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +.Fn SMR_LIST_REMOVE_LOCKED +removes the element +.Fa elm +from the list +.Fa head . +.Ss Tail Queues +The +.Fn SMR_TAILQ_ENTRY +macro declares a structure that connects the elements in +the tail queue. +.Pp +.Fn SMR_TAILQ_INIT +initializes the tail queue +.Fa head +to an empty state. +.Pp +.Fn SMR_TAILQ_FIRST +and +.Fn SMR_TAILQ_FIRST_LOCKED +return the first element in the queue +.Fa head , +or NULL if the queue is empty. +.Pp +.Fn SMR_TAILQ_NEXT +and +.Fn SMR_TAILQ_NEXT_LOCKED +return the successor of the element +.Fa elm , +or NULL if there are no more elements in the queue. +.Pp +.Fn SMR_TAILQ_EMPTY_LOCKED +returns true if the queue +.Fa head +is empty. +.Pp +.Fn SMR_TAILQ_FOREACH +and +.Fn SMR_TAILQ_FOREACH_LOCKED +traverse the queue +.Fa head +in forward direction. +.Pp +.Fn SMR_TAILQ_FOREACH_SAFE_LOCKED +traverses the queue +.Fa head +in forward direction. +It is permitted to remove the element referenced by variable +.Fa VARNAME +from the queue and defer its freeing using +.Xr smr_call 9 . +.Pp +.Fn SMR_TAILQ_INSERT_HEAD_LOCKED +inserts the new element +.Fa elm +at the head of the queue. +.Pp +.Fn SMR_TAILQ_INSERT_TAIL_LOCKED +inserts the new element +.Fa elm +at the tail of the queue. +.Pp +.Fn SMR_TAILQ_INSERT_AFTER_LOCKED +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +.Fn SMR_TAILQ_INSERT_BEFORE_LOCKED +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +.Fn SMR_TAILQ_REMOVE_LOCKED +removes the element +.Fa elm +from the queue +.Fa head . +.Sh CONTEXT +All SMR list macros can be used during autoconf, from process context, +or from interrupt context. +.Pp +.Nm SMR_SLIST_FIRST , +.Nm SMR_SLIST_NEXT , +.Nm SMR_SLIST_FOREACH , +.Nm SMR_LIST_FIRST , +.Nm SMR_LIST_NEXT , +.Nm SMR_LIST_FOREACH , +.Nm SMR_TAILQ_FIRST , +.Nm SMR_TAILQ_NEXT +and +.Nm SMR_TAILQ_FOREACH +can be used from SMR read-side critical section. +.Pp +.Nm SMR_SLIST_INIT , +.Nm SMR_SLIST_FIRST_LOCKED , +.Nm SMR_SLIST_NEXT_LOCKED , +.Nm SMR_SLIST_EMPTY_LOCKED , +.Nm SMR_SLIST_FOREACH_LOCKED , +.Nm SMR_SLIST_FOREACH_SAFE_LOCKED , +.Nm SMR_SLIST_INSERT_HEAD_LOCKED , +.Nm SMR_SLIST_INSERT_AFTER_LOCKED , +.Nm SMR_SLIST_REMOVE_HEAD_LOCKED , +.Nm SMR_SLIST_REMOVE_AFTER_LOCKED , +.Nm SMR_SLIST_REMOVE_LOCKED , +.Nm SMR_LIST_INIT , +.Nm SMR_LIST_FIRST_LOCKED , +.Nm SMR_LIST_NEXT_LOCKED , +.Nm SMR_LIST_EMPTY_LOCKED , +.Nm SMR_LIST_FOREACH_LOCKED , +.Nm SMR_LIST_FOREACH_SAFE_LOCKED , +.Nm SMR_LIST_INSERT_HEAD_LOCKED , +.Nm SMR_LIST_INSERT_AFTER_LOCKED , +.Nm SMR_LIST_INSERT_BEFORE_LOCKED , +.Nm SMR_LIST_REMOVE_LOCKED , +.Nm SMR_TAILQ_INIT , +.Nm SMR_TAILQ_FIRST_LOCKED , +.Nm SMR_TAILQ_NEXT_LOCKED , +.Nm SMR_TAILQ_EMPTY_LOCKED , +.Nm SMR_TAILQ_FOREACH_LOCKED , +.Nm SMR_TAILQ_FOREACH_SAFE_LOCKED , +.Nm SMR_TAILQ_INSERT_HEAD_LOCKED , +.Nm SMR_TAILQ_INSERT_TAIL_LOCKED , +.Nm SMR_TAILQ_INSERT_AFTER_LOCKED , +.Nm SMR_TAILQ_INSERT_BEFORE_LOCKED , +and +.Nm SMR_TAILQ_REMOVE_LOCKED +can be used from writer context. +.Sh SEE ALSO +.Xr queue 3 , +.Xr smr_call 9 , +.Xr SMR_PTR_GET 9 +.Sh HISTORY +The SMR list macros first appeared in +.Ox 6.5 . diff --git a/static/openbsd/man9/SMR_PTR_GET.9 b/static/openbsd/man9/SMR_PTR_GET.9 new file mode 100644 index 00000000..af4ddb0c --- /dev/null +++ b/static/openbsd/man9/SMR_PTR_GET.9 @@ -0,0 +1,73 @@ +.\" $OpenBSD: SMR_PTR_GET.9,v 1.3 2019/07/05 04:46:26 dlg Exp $ +.\" +.\" Copyright (c) 2019 Visa Hankala +.\" +.\" 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: July 5 2019 $ +.Dt SMR_PTR_GET 9 +.Os +.Sh NAME +.Nm SMR_PTR_GET , +.Nm SMR_PTR_GET_LOCKED , +.Nm SMR_PTR_SET_LOCKED +.Nd safe memory reclamation pointer API +.Sh SYNOPSIS +.Ft TYPE +.Fn SMR_PTR_GET "TYPE *pptr" +.Ft TYPE +.Fn SMR_PTR_GET_LOCKED "TYPE *pptr" +.Ft void +.Fn SMR_PTR_SET_LOCKED "TYPE *pptr" "TYPE v" +.Sh DESCRIPTION +The SMR_PTR macros are used for accessing SMR-protected pointers. +.Pp +The macro +.Fn SMR_PTR_GET +reads the pointer referenced by +.Fa pptr +for dereferencing inside SMR read-side critical section. +.Pp +.Fn SMR_PTR_GET_LOCKED +reads the pointer referenced by +.Fa pptr +for dereferencing inside writer context. +.Pp +.Fn SMR_PTR_SET_LOCKED +writes value +.Fa v +to the pointer referenced by +.Fa pptr . +The operation issues a write-write memory barrier with +.Xr membar_producer 9 +before the pointer write. +.Sh CONTEXT +.Fn SMR_PTR_GET , +.Fn SMR_PTR_GET_LOCKED +and +.Fn SMR_PTR_SET_LOCKED +can be called during autoconf, from process context, or from interrupt context. +.Pp +.Fn SMR_PTR_GET +can be used from SMR read-side critical section. +.Fn SMR_PTR_GET_LOCKED +and +.Fn SMR_PTR_SET_LOCKED +can be used from writer context. +.Sh SEE ALSO +.Xr membar_producer 9 , +.Xr SMR_LIST_INIT 9 , +.Xr smr_read_enter 9 +.Sh HISTORY +The SMR_PTR macros first appeared in +.Ox 6.5 . diff --git a/static/openbsd/man9/SRPL_EMPTY_LOCKED.9 b/static/openbsd/man9/SRPL_EMPTY_LOCKED.9 new file mode 100644 index 00000000..49403832 --- /dev/null +++ b/static/openbsd/man9/SRPL_EMPTY_LOCKED.9 @@ -0,0 +1,155 @@ +.\" $OpenBSD: SRPL_EMPTY_LOCKED.9,v 1.3 2016/11/21 07:11:13 dlg Exp $ +.\" +.\" Copyright (c) 2015 David Gwynne +.\" +.\" 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: November 21 2016 $ +.Dt SRPL_EMPTY_LOCKED 9 +.Os +.Sh NAME +.Nm SRPL_EMPTY_LOCKED , +.Nm SRPL_FIRST_LOCKED , +.Nm SRPL_NEXT_LOCKED , +.Nm SRPL_FOREACH_LOCKED , +.Nm SRPL_FOREACH_SAFE_LOCKED , +.Nm SRPL_INSERT_HEAD_LOCKED , +.Nm SRPL_INSERT_AFTER_LOCKED , +.Nm SRPL_REMOVE_LOCKED +.Nd serialised singly-linked shared reference pointer list operations +.Sh SYNOPSIS +.In sys/srp.h +.Ft int +.Fn "SRPL_EMPTY_LOCKED" "SRPL_HEAD *sl" +.Ft void * +.Fn "SRPL_FIRST_LOCKED" "SRPL_HEAD *sl" +.Ft void * +.Fn "SRPL_NEXT_LOCKED" "struct TYPE *listelm" "FIELDNAME" +.Fn "SRPL_FOREACH_LOCKED" "VARNAME" "SRPL_HEAD *sl" "FIELDNAME" +.Fo "SRPL_FOREACH_SAFE_LOCKED" +.Fa "VARNAME" +.Fa "SRPL_HEAD *sl" +.Fa "FIELDNAME" +.Fa "TEMP_VARNAME" +.Fc +.Ft void +.Fo "SRPL_INSERT_HEAD_LOCKED" +.Fa "struct srpl_rc *rc" +.Fa "SRPL_HEAD *sl" +.Fa "struct TYPE *elm" +.Fa "FIELDNAME" +.Fc +.Ft void +.Fo "SRPL_INSERT_AFTER_LOCKED" +.Fa "struct srpl_rc *rc" +.Fa "struct TYPE *listelm" +.Fa "struct TYPE *elm" +.Fa "FIELDNAME" +.Fc +.Ft void +.Fo "SRPL_REMOVE_LOCKED" +.Fa "struct srpl_rc *rc" +.Fa "SRPL_HEAD *sl" +.Fa "struct TYPE *listelm" +.Fa "TYPE" +.Fa "FIELDNAME" +.Fc +.Sh DESCRIPTION +The SRP list +macros build a linked list on top of shared reference pointers. +These macros allow manipulation and traversal of the linked list while +access to the list is serialised by the caller. +.Pp +.Fn SRPL_EMPTY_LOCKED +tests whether the SRP list +.Fa sl +is empty. +.Pp +.Fn SRPL_FIRST_LOCKED +accesses the first element in the SRP list +.Fa sl . +.Pp +.Fn SRPL_NEXT_LOCKED +accesses the next element in the SRP list after +.Fa listelm . +.Pp +.Fn SRPL_FOREACH_LOCKED +creates a loop for traversing the elements in the SRP list +.Fa sl . +.Pp +.Fn SRPL_FOREACH_SAFE_LOCKED +creates a loop for traversing the elements in the SRP list +.Fa sl , +permitting it to remove +.Fa VARNAME +as well as freeing it from within the loop safely without interfering with the +traversal. +.Pp +.Fn SRPL_INSERT_HEAD_LOCKED +inserts +.Fa elm +into the SRP list +.Fa sl . +Reference counts are adjusted on the list items using the functions +specified by +.Fa rc . +.Pp +.Fn SRPL_INSERT_AFTER_LOCKED +inserts +.Fa elm +into an SRP list after the element +.Fa listelm . +Reference counts are adjusted on the list items using the functions +specified by +.Fa rc . +.Pp +.Fn SRPL_REMOVE_LOCKED +iterates over the SRP list +.Fa sl +until it finds +.Fa listelm +and then removes it. +Reference counts are adjusted on the list items using the functions +specified by +.Fa rc . +.Sh CONTEXT +.Fn SRPL_EMPTY_LOCKED , +.Fn SRPL_FIRST_LOCKED , +.Fn SRPL_NEXT_LOCKED , +.Fn SRPL_FOREACH_LOCKED , +.Fn SRPL_INSERT_HEAD_LOCKED , +.Fn SRPL_INSERT_AFTER_LOCKED , +and +.Fn SRPL_REMOVE_LOCKED +may be called during autoconf or from process context. +An appropriate lock must be held that prevents concurrent modifications +to the list. +.Sh RETURN VALUES +.Fn SRPL_FIRST_LOCKED , +and +.Fn SRPL_NEXT_LOCKED +return a pointer to elements in the SRP list, or +.Dv NULL +if there are no more elements. +.Pp +.Fn SRPL_EMPTY_LOCKED +returns non-zero when the list is empty, otherwise 0. +.Sh SEE ALSO +.Xr SRPL_FIRST 9 +.Sh HISTORY +The srp API was originally written by +.An Jonathan Matthew Aq Mt jmatthew@openbsd.org +and +.An David Gwynne Aq Mt dlg@openbsd.org . +The SRP list API first appeared in +.Ox 5.9 . diff --git a/static/openbsd/man9/SipHash24.9 b/static/openbsd/man9/SipHash24.9 new file mode 100644 index 00000000..d596e40c --- /dev/null +++ b/static/openbsd/man9/SipHash24.9 @@ -0,0 +1,108 @@ +.\" $OpenBSD: SipHash24.9,v 1.6 2015/09/14 15:14:55 schwarze Exp $ +.\" +.\" Copyright (c) 2014 David Gwynne +.\" +.\" 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: September 14 2015 $ +.Dt SIPHASH24 9 +.Os +.Sh NAME +.Nm SipHash24_Init , +.Nm SipHash24_Update , +.Nm SipHash24_End , +.Nm SipHash24_Final , +.Nm SipHash24 +.Nd calculate SipHash24 hashes +.Sh SYNOPSIS +.In crypto/siphash.h +.Ft void +.Fn SipHash24_Init "SIPHASH_CTX *ctx" "const SIPHASH_KEY *key" +.Ft void +.Fn SipHash24_Update "SIPHASH_CTX *ctx" "const void *data" "size_t len" +.Ft uint64_t +.Fn SipHash24_End "SIPHASH_CTX *ctx" +.Ft void +.Fn SipHash24_Final "void *digest" "SIPHASH_CTX *ctx" +.Ft uint64_t +.Fn SipHash24 "const SIPHASH_KEY *key" "const void *data" "size_t len" +.Sh DESCRIPTION +The SipHash algorithm is a keyed hash algorithm optimised for short +inputs which produces a 64-bit digest of data. +The SipHash24 functions implement the algorithm with 2 compression +rounds and 4 finalisation rounds. +.Pp +.Fn SipHash24_Init +initialises a +.Vt SIPHASH_CTX +context +.Fa ctx +with the secret +.Fa key . +.Pp +.Fn SipHash24_Update +adds +.Fa data +of length +.Fa len +to the context +.Fa ctx . +.Pp +.Fn SipHash24_End +is called after all data has been added to +.Fa ctx +via +.Fn SipHash24_Update +and returns a message digest in the host's native endian. +.Pp +.Fn SipHash24_Final +is called after all data has been added to +.Fa ctx +via +.Fn SipHash24_Update +and stores the message digest at the address specified by the +.Fa digest +parameter. +The buffer at +.Fa digest +must be +.Dv SIPHASH_DIGEST_LENGTH +bytes long. +.Pp +.Fn SipHash24 +calculates the digest of +.Fa data +of length +.Fa len +with the secret +.Fa key . +.Pp +It is recommended that the +.Vt SIPHASH_KEY +key be generated with +.Xr arc4random_buf 9 . +.Sh CONTEXT +.Fn SipHash24_Init , +.Fn SipHash24_Update , +.Fn SipHash24_End , +.Fn SipHash24_Final +and +.Fn SipHash24 +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn SipHash24_End +and +.Fn SipHash24 +return the 64-bit message digest in the host's native endian representation. +.Sh SEE ALSO +.Xr arc4random_buf 9 diff --git a/static/openbsd/man9/VOP_LOOKUP.9 b/static/openbsd/man9/VOP_LOOKUP.9 new file mode 100644 index 00000000..e6f17c7c --- /dev/null +++ b/static/openbsd/man9/VOP_LOOKUP.9 @@ -0,0 +1,917 @@ +.\" $OpenBSD: VOP_LOOKUP.9,v 1.46 2022/06/26 05:20:42 visa Exp $ +.\" +.\" Copyright (c) 2003 Ted Unangst +.\" Copyright (c) 2000, 2001 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 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 $Mdocdate: June 26 2022 $ +.Dt VOP_LOOKUP 9 +.Os +.Sh NAME +.Nm VOP_LOOKUP , +.Nm VOP_ABORTOP , +.Nm VOP_ACCESS , +.Nm VOP_ADVLOCK , +.Nm VOP_BMAP , +.Nm VOP_BWRITE , +.Nm VOP_CLOSE , +.Nm VOP_CREATE , +.Nm VOP_FSYNC , +.Nm VOP_GETATTR , +.Nm VOP_INACTIVE , +.Nm VOP_IOCTL , +.Nm VOP_ISLOCKED , +.Nm VOP_KQFILTER , +.Nm VOP_LINK , +.Nm VOP_LOCK , +.Nm VOP_MKDIR , +.Nm VOP_MKNOD , +.Nm VOP_OPEN , +.Nm VOP_PATHCONF , +.Nm VOP_PRINT , +.Nm VOP_READ , +.Nm VOP_READDIR , +.Nm VOP_READLINK , +.Nm VOP_RECLAIM , +.Nm VOP_REMOVE , +.Nm VOP_RENAME , +.Nm VOP_REVOKE , +.Nm VOP_RMDIR , +.Nm VOP_SETATTR , +.Nm VOP_STRATEGY , +.Nm VOP_SYMLINK , +.Nm VOP_UNLOCK , +.Nm VOP_WRITE +.Nd vnode operations +.Sh SYNOPSIS +.In sys/vnode.h +.Ft int +.Fo VOP_ABORTOP +.Fa "struct vnode *dvp" +.Fa "struct componentname *cnp" +.Fc +.Ft int +.Fo VOP_ACCESS +.Fa "struct vnode *vp" +.Fa "int mode" +.Fa "struct ucred *cred" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_ADVLOCK +.Fa "struct vnode *vp" +.Fa "void *id" +.Fa "int op" +.Fa "struct flock *fl" +.Fa "int flags" +.Fc +.Ft int +.Fo VOP_BMAP +.Fa "struct vnode *vp" +.Fa "daddr_t bn" +.Fa "struct vnode **vpp" +.Fa "daddr_t *bnp" +.Fa "int *runp" +.Fc +.Ft int +.Fo VOP_BWRITE +.Fa "struct buf *bp" +.Fc +.Ft int +.Fo VOP_CLOSE +.Fa "struct vnode *vp" +.Fa "int fflag" +.Fa "struct ucred *cred" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_CREATE +.Fa "struct vnode *dvp" +.Fa "struct vnode **vpp" +.Fa "struct componentname *cnp" +.Fa "struct vattr *vap" +.Fc +.Ft int +.Fo VOP_FSYNC +.Fa "struct vnode *vp" +.Fa "struct ucred *cred" +.Fa "int waitfor" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_GETATTR +.Fa "struct vnode *vp" +.Fa "struct vattr *vap" +.Fa "struct ucred *cred" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_INACTIVE +.Fa "struct vnode *vp" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_IOCTL +.Fa "struct vnode *vp" +.Fa "u_long command" +.Fa "void *data" +.Fa "int fflag" +.Fa "struct ucred *cred" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_ISLOCKED +.Fa "struct vnode *vp" +.Fc +.Ft int +.Fo VOP_KQFILTER +.Fa "struct vnode *vp" +.Fa "struct knote *kn" +.Fc +.Ft int +.Fo VOP_LINK +.Fa "struct vnode *dvp" +.Fa "struct vnode *vp" +.Fa "struct componentname *cnp" +.Fc +.Ft int +.Fo VOP_LOCK +.Fa "struct vnode *vp" +.Fa "int flags" +.Fc +.Ft int +.Fo VOP_LOOKUP +.Fa "struct vnode *dvp" +.Fa "struct vnode **vpp" +.Fa "struct componentname *cnp" +.Fc +.Ft int +.Fo VOP_MKDIR +.Fa "struct vnode *dvp" +.Fa "struct vnode **vpp" +.Fa "struct componentname *cnp" +.Fa "struct vattr *vap" +.Fc +.Ft int +.Fo VOP_MKNOD +.Fa "struct vnode *dvp" +.Fa "struct vnode **vpp" +.Fa "struct componentname *cnp" +.Fa "struct vattr *vap" +.Fc +.Ft int +.Fo VOP_OPEN +.Fa "struct vnode *vp" +.Fa "int mode" +.Fa "struct ucred *cred" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_PATHCONF +.Fa "struct vnode *vp" +.Fa "int name" +.Fa "register_t *retval" +.Fc +.Ft int +.Fo VOP_PRINT +.Fa "struct vnode *vp" +.Fc +.Ft int +.Fo VOP_READ +.Fa "struct vnode *vp" +.Fa "struct uio *uio" +.Fa "int ioflag" +.Fa "struct ucred *cred" +.Fc +.Ft int +.Fo VOP_READDIR +.Fa "struct vnode *vp" +.Fa "struct uio *uio" +.Fa "struct ucred *cred" +.Fa "int *eofflag" +.Fc +.Ft int +.Fo VOP_READLINK +.Fa "struct vnode *vp" +.Fa "struct uio *uio" +.Fa "struct ucred *cred" +.Fc +.Ft int +.Fo VOP_RECLAIM +.Fa "struct vnode *vp" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_REMOVE +.Fa "struct vnode *dvp" +.Fa "struct vnode *vp" +.Fa "struct componentname *cnp" +.Fc +.Ft int +.Fo VOP_RENAME +.Fa "struct vnode *fdvp" +.Fa "struct vnode *fvp" +.Fa "struct componentname *fcnp" +.Fa "struct vnode *tdvp" +.Fa "struct vnode *tvp" +.Fa "struct componentname *tcnp" +.Fc +.Ft int +.Fo VOP_REVOKE +.Fa "struct vnode *vp" +.Fa "int flags" +.Fc +.Ft int +.Fo VOP_RMDIR +.Fa "struct vnode *dvp" +.Fa "struct vnode *vp" +.Fa "struct componentname *cnp" +.Fc +.Ft int +.Fo VOP_SETATTR +.Fa "struct vnode *vp" +.Fa "struct vattr *vap" +.Fa "struct ucred *cred" +.Fa "struct proc *p" +.Fc +.Ft int +.Fo VOP_STRATEGY +.Fa "struct vnode *vp" +.Fa "struct buf *bp" +.Fc +.Ft int +.Fo VOP_SYMLINK +.Fa "struct vnode *dvp" +.Fa "struct vnode **vpp" +.Fa "struct componentname *cnp" +.Fa "struct vattr *vap" +.Fa "char *target" +.Fc +.Ft int +.Fo VOP_UNLOCK +.Fa "struct vnode *vp" +.Fc +.Ft int +.Fo VOP_WRITE +.Fa "struct vnode *vp" +.Fa "struct uio *uio" +.Fa "int ioflag" +.Fa "struct ucred *cred" +.Fc +.Sh DESCRIPTION +The +.Nm VOP +functions implement a generic way to perform operations on vnodes. +The VOP function called passes the arguments to the correct file system +specific function. +Not all file systems implement all operations, in which case a generic +method will be used. +These functions exist to provide an abstract method to invoke vnode +operations without needing to know anything about the underlying file system. +Many system calls map directly to a specific VOP function. +.Pp +The arguments for each VOP +function consist of one or more vnode pointers along with other data +needed to perform the operation. +Care must be taken to obey the vnode locking discipline when using +VOP functions. +Many VOP calls take a +.Vt struct proc *p +argument. +This should be the current process. +VOP calls are not safe to call in an interrupt context. +.Pp +The +.Vt vattr +structure used by +.Fn VOP_CREATE , +.Fn VOP_GETATTR , +.Fn VOP_MKDIR , +.Fn VOP_MKNOD , +.Fn VOP_SETATTR , +and +.Fn VOP_SYMLINK +is: +.Bd -literal +struct vattr { + enum vtype va_type; /* vnode type */ + mode_t va_mode; /* files access mode and type */ + nlink_t va_nlink; /* number of references */ + uid_t va_uid; /* owner user id */ + gid_t va_gid; /* owner group id */ + long va_fsid; /* file system id */ + u_quad_t va_fileid; /* file id */ + u_quad_t va_size; /* file size in bytes */ + long va_blocksize; /* blocksize preferred for i/o */ + struct timespec va_atime; /* time of last access */ + struct timespec va_mtime; /* time of last modification */ + struct timespec va_ctime; /* time file changed */ + u_long va_gen; /* generation number of file */ + u_long va_flags; /* flags defined for file */ + dev_t va_rdev; /* device the vnode represents */ + u_quad_t va_bytes; /* bytes of held disk space */ + u_quad_t va_filerev; /* file modification number */ + u_int va_vaflags; /* operations flags */ + long va_spare; /* remain quad aligned */ +}; +.Ed +.Pp +The following sections comment on the VOP functions from the consumer's +perspective. +.Pp +.Bl -tag -width Ds -compact +.It Fn VOP_ABORTOP dvp cnp +Abort any asynchronous operations pending on the vnode +.Fa dvp +associated with the path name +.Fa cnp . +This is mostly used by internal VFS code and should not be needed by +file system implementors. +.Pp +.It Fn VOP_ACCESS vp mode cred p +Determine if the locked vnode +.Fa vp +can be accessed by the calling process +.Fa p +with credentials +.Fa cred +for the given access +.Fa mode . +.Pp +.Fa mode +may contain any of the following values: +.Pp +.Bl -tag -width Ds -compact -offset indent +.It Dv VWRITE +check writeability +.It Dv VREAD +check readability +.It Dv VEXEC +check executability +.El +.Pp +If the access check succeeds, zero is returned; otherwise, an +appropriate error code is returned. +.Pp +.It Fn VOP_ADVLOCK vp id op fl flags +Perform advisory locking on the vnode +.Fa vp +according to the operation +.Fa op +and lock specification +.Fa fl . +.Fa id +identifies the resource holding the lock +(typically a pointer to the holding process). +.Pp +.Fa op +may be one of the following operations: +.Pp +.Bl -tag -width F_GETLK -compact -offset indent +.It Dv F_GETLK +Get the first lock that would block a lock request. +.It Dv F_SETLK +Set a lock. +.It Dv F_UNLCK +Release a lock. +.El +.Pp +.Fa flags +may contain the following flags: +.Pp +.Bl -tag -width F_POSIX -compact -offset indent +.It Dv F_WAIT +If required, block waiting to obtain an exclusive lock. +.It Dv F_POSIX +Follow POSIX locking semantics; see +.Xr fcntl 2 . +.It Dv F_FLOCK +Follow +.Xr flock 2 +locking semantics. +.El +.Pp +Upon success, zero is returned; otherwise, an appropriate error code is +returned. +.Pp +.It Fn VOP_BMAP vp bn vpp bnp runp +Convert the logical block number +.Fa bn +of the file the locked vnode +.Fa vp +is associated with its physical number on-disk. +The physical block number is stored in +.Fa *bnp +on return. +.Fa vpp , +if +.No non- Ns Dv NULL , +will be updated to point to the vnode of the block device of which +.Fa vp +is associated. +.Fa runp , +if +.No non- Ns Dv NULL , +will be updated to the number of contiguous disk blocks following +.Fa *bnp . +Upon success, zero is returned; otherwise, an appropriate error code is +returned. +.Pp +.It Fn VOP_BWRITE bp +Write a file system buffer to disk. +Upon success, zero is returned; otherwise, an appropriate error code is +returned. +.Pp +.It Fn VOP_CLOSE vp fflag cred p +Close the file associated with the locked vnode +.Fa vp +with file flags +.Fa fflag +by the calling process +.Fa p +with credentials +.Fa cred . +This operation should be performed only when the file is no longer being +used. +Upon success, zero is returned; otherwise, an appropriate error code is +returned. +.Pp +.It Fn VOP_CREATE dvp vpp cnp vap +Create a new directory entry for a regular file in the directory +.Fa dvp +and return a locked, referenced vnode in +.Fa vpp . +The file name is in +.Fa cnp +and its permissions will be +.Fa vap . +.Fa dvp +must be locked. +.Pp +.It Fn VOP_FSYNC vp cred waitfor p +Flush any dirty buffers associated with +.Fa vp +to disk. +The vnode is locked on entry and exit. +.Fa waitfor +can be set to +.Dv MNT_WAIT +to indicate that +.Fn VOP_FSYNC +should not return until all data is written. +.Pp +.It Fn VOP_GETATTR vp vap cred p +.It Fn VOP_SETATTR vp vap cred p +Access the vnode attributes +.Fa vap +of the vnode +.Fa vp +by the calling process +.Fa p +with credentials +.Fa cred . +.Fn VOP_SETATTR +requires that +.Fa vp +be locked. +A field value for any member of +.Fa vap +of +.Dv VNOVAL +represents that the information could not be obtained by +.Fn VOP_GETATTR +or should not be changed by +.Fn VOP_SETATTR . +Upon success of obtaining or changing the attributes, zero is returned; +otherwise, an appropriate error code is returned. +All attributes are held in the +.Vt vattr +structure shown above. +.Pp +.It Fn VOP_INACTIVE vp p +Notify the underlying file system that the locked vnode +.Fa vp +is no longer in use. +The vnode will be unlocked upon return. +.Fa p +specifies the calling process. +This may happen when the vnode reference count reaches zero or +when the underlying file system has disappeared or has been forcibly +unmounted. +.Pp +Typically, the underlying file system will write any buffers associated +with +.Fa vp +to disk or delete the file entry, if need be. +The underlying file system may not necessarily release any buffers +associated with +.Fa vp +so that it can be immediately reactivated in case the file is used again. +Upon success, zero is returned; otherwise, an appropriate error code is +returned. +.Pp +.It Fn VOP_IOCTL vp command data fflag cred p +Perform the control operation +.Fa command +with additional information +.Fa data +on the vnode +.Fa vp , +normally associated with a device, +with file flags +.Fa fflag +by the calling process +.Fa p +with credentials +.Fa cred . +Upon success, zero is returned; otherwise, an appropriate error code is +returned. +.Pp +.It Fn VOP_ISLOCKED vp +.It Fn VOP_LOCK vp flags +.It Fn VOP_UNLOCK vp +.Fn VOP_LOCK +is used internally by +.Xr vn_lock 9 +to lock a vnode. +It should not be used by other file system code. +.Fn VOP_UNLOCK +unlocks a vnode. +Note the asymmetry between +.Xr vn_lock 9 +and +.Fn VOP_UNLOCK . +.Pp +.Fa flags +may contain the following flags: +.Pp +.Bl -tag -width LK_RECURSEFAIL -compact -offset indent +.It Dv LK_EXCLUSIVE +Acquire an exclusive lock. +.It Dv LK_SHARED +Acquire a shared lock. +.It Dv LK_NOWAIT +Don't wait if the vnode lock is held by someone else +(may still wait on reclamation lock). +.It Dv LK_RECURSEFAIL +Attempt at recursive lock fails. +.It Dv LK_DRAIN +Used to mean something else, but is now used abused as a flag to avoid a lock +inversion deadlock in deadfs. +Do not use this, it must die. +.El +.Pp +.Fn VOP_ISLOCKED +returns one of the following values: +.Pp +.Bl -tag -width LK_EXCLUSIVE -compact -offset indent +.It Dv LK_EXCLUSIVE +.Fa vp +is locked for exclusive access by the calling thread. +.It Dv LK_EXCLOTHER +.Fa vp +is locked for exclusive access by a different thread. +.It Dv LK_SHARED +.Fa vp +is locked for shared access. +The current thread may be one of the threads that have it locked. +.It 0 +.Fa vp +is not locked. +.El +.Pp +.Fn VOP_ISLOCKED +should be used cautiously, as not all file systems implement locks +effectively. +.Pp +.It Fn VOP_KQFILTER vp kn +Register the +.Xr knote 9 +filtering information +.Fa kn +for the vnode +.Fa vp . +Only filters for +.Dv EVFILT_READ , +.Dv EVFILT_WRITE , +and +.Dv EVFILT_VNODE +will invoke this operation. +Upon success, zero is returned; otherwise, a non-zero value is returned. +.Pp +.It Fn VOP_LINK dvp vp cnp +Increase the link count for the vnode +.Fa vp . +A new entry with name +.Fa cnp +should be added to the directory +.Fa dvp . +.Fa dvp +is locked on entry and unlocked on exit. +.Pp +.It Fn VOP_LOOKUP dvp vpp cnp +Find the file corresponding to the name +.Fa cnp +in the directory +.Fa dvp +and return a vnode in +.Fa vpp . +.Fa dvp +must be locked and referenced on entry with +.Xr vget 9 . +On a successful return, +.Fa vpp +will be returned locked and referenced, and +.Fa dvp +will return with the same reference count, but may be returned locked +or unlocked depending on the specific flags used in +.Fa cnp->cn_flags . +On error +.Fa vpp +will be +.Dv NULL +and +.Fa cnp->cn_flags +will be set to +.Dv PDIRUNLOCK +if +.Fa dvp +has been unlocked. +.Pp +.It Fn VOP_MKDIR dvp vpp cnp vap +Create a new directory named by +.Fa cnp +with permissions +.Fa vattr +in the directory +.Fa dvp . +On success, the new vnode is returned locked in +.Fa vpp . +.Fa dvp +must be locked on entry and is unlocked on exit. +.Pp +.It Fn VOP_MKNOD dvp vpp cnp vap +Create a device special file with name +.Fa cnp +and attributes +.Fa vap +in the directory associated with the locked vnode +.Fa dvp . +A pointer to the new, locked vnode will be returned in +.Fa *vpp +if +.Fa vpp +is not +.Dv NULL . +Upon success, zero is returned; otherwise, an appropriate error code is +returned. +.Pp +.It Fn VOP_OPEN vp mode cred p +Open the file associated with the vnode +.Fa vp +with the access modes +.Fa mode +by the calling process +.Fa p +with credentials +.Fa cred . +.Fa mode +takes the flags described in +.Xr open 2 . +.Pp +For some underlying file systems, access permissions for the file by the +process are checked; for others, this is a no-op. +In any case, this must be called before a process can access the file. +Upon success, zero is returned; otherwise, an appropriate error code is +returned. +.Pp +.It Fn VOP_PATHCONF vp name retval +Obtain the value of the applicable POSIX configurable pathname variable (see +.Xr pathconf 2 ) +specified by +.Fa name +from the locked vnode +.Fa vp . +The result is placed in +.Fa *retval . +Upon success, zero is returned; otherwise, an appropriate error code is +returned. +.Pp +.It Fn VOP_PRINT vp +Print information about the vnode to the kernel message buffer. +It is not used normally, but exists only for debugging purposes. +.Pp +.It Fn VOP_READ vp uio ioflag cred +Copy data from the locked vnode +.Fa vp +to the buffers specified by +.Fa uio +with calling process credentials +.Fa cred . +.Pp +.Fa ioflag +may contain the following flags: +.Pp +.Bl -tag -width IO_APPEND -offset indent -compact +.It Dv IO_NDELAY +Non-blocking I/O. +.It Dv IO_UNIT +Do I/O as an atomic unit. +.El +.Pp +Upon success, zero is returned; otherwise, an appropriate error code is +returned. +.Pp +.It Fn VOP_READDIR vp uio cred eofflag +Read the contents of the directory associated with the locked vnode +.Fa vp , +usually via +.Fn VOP_READ , +and convert its file-system-specific format to that expected by the +.Xr getdents 2 +system call, storing the result into the buffers specified by +.Fa uio . +.Fa cred +specifies the credentials of the calling process. +.Fa *eofflag +is set to a non-zero value on return once successful end-of-file for the +directory contents has been reached. +.Pp +Upon success, zero is returned; otherwise, an appropriate error code is +returned. +.Pp +.It Fn VOP_READLINK vp uio cred +Read a symbolic link and return the target's name in +.Fa uio . +.Fa vp +is locked on entry and exit and must be a symlink. +.Pp +.It Fn VOP_RECLAIM vp p +Used by +.Xr vclean 9 +so that the file system has an opportunity to free memory +and perform any other cleanup activity related to +.Fa vp . +.Fa vp +is unlocked on entry and exit. +.Fn VOP_RECLAIM +should not be used by generic code. +.Pp +.It Fn VOP_REMOVE dvp vp cnp +Remove the link named +.Fa cnp +from the directory +.Fa dvp . +This file corresponds to the vnode +.Fa vp . +Both +.Fa dvp +and +.Fa vp +are locked on entry and unlocked on exit, and +each has its reference count decremented by one. +.Fn VOP_REMOVE +does not delete the file from disk unless its link count +becomes zero (for file systems which support multiple links). +.Pp +.It Fn VOP_RENAME fdvp fvp fcnp tdvp tvp tcnp +Remove the link to the file with associated vnode +.Fa fvp +and name +.Fa fcnp +in the directory with associated vnode +.Fa fdvp , +and create a new link to the file with name +.Fa tcnp +(and associated locked vnode +.Fa tvp , +if the file already exists) residing in the directory with the +associated locked vnode +.Fa tdvp . +.Fa fdvp , +.Fa fvp , +and +.Fa tvp +(if not +.Dv NULL ) +will be released (see +.Xr vrele 9 ) +and +.Fa tdvp +will have its reference count decremented (see +.Xr vput 9 ) +on return. +If not +.Dv NULL , +.Fa tvp +will be unlocked on return (see +.Xr vput 9 ) . +Upon success, zero is returned; otherwise, an appropriate error code is +returned. +.Pp +.It Fn VOP_REVOKE vp flags +Used by the +.Xr revoke 2 +system call to prevent any further access to a vnode. +The vnode ops will be changed to those of deadfs, which returns only +errors. +.Ar vp +must be unlocked. +.Pp +.It Fn VOP_RMDIR dvp vp cnp +Remove the directory +.Fa vp +from the directory +.Fa dvp . +Both are locked on entry and unlocked on exit. +The name of the directory for removal is additionally contained in +.Fa cnp . +.Pp +.It Fn VOP_STRATEGY vp bp +Call the appropriate strategy function for the device vnode +.Fa vp +to read or write the buffer +.Fa bp . +.Pp +.It Fn VOP_SYMLINK dvp vpp cnp vap target +Create a symbolic link with name +.Fa cnp +in the directory +.Fa dvp +with mode +.Fa vap . +The link will point to +.Fa target +and a vnode for it is returned in +.Fa vpp . +The directory vnode is locked on entry and unlocked on exit. +Note that unlike most VOP calls returning a vnode, +.Fn VOP_SYMLINK +does not lock or reference +.Fa vpp . +.Pp +.It Fn VOP_WRITE vp uio ioflag cred +Copy data from the buffers specified by +.Fa uio +to the locked vnode +.Fa vp +with calling process credentials +.Fa cred . +.Pp +.Fa ioflag +may contain the following flags: +.Pp +.Bl -tag -width IO_APPEND -offset indent -compact +.It Dv IO_APPEND +Perform write at the end of file. +.It Dv IO_NDELAY +Non-blocking I/O. +.It Dv IO_SYNC +Wait for I/O to complete. +.It Dv IO_UNIT +Do I/O as an atomic unit. +.El +.Pp +Upon success, zero is returned; otherwise, an appropriate error code is +returned. +.El +.Sh RETURN VALUES +The +.Nm VOP +functions return 0 to indicate success and a non-zero error code +to indicate failure. +.Sh SEE ALSO +.Xr errno 2 , +.Xr uiomove 9 , +.Xr vfs 9 , +.Xr vn_lock 9 , +.Xr vnode 9 +.Sh AUTHORS +This man page was written by +.An Ted Unangst +for +.Ox . +.Sh BUGS +The locking discipline is too complex. +Refer to +.Xr vn_lock 9 . diff --git a/static/openbsd/man9/aml_evalnode.9 b/static/openbsd/man9/aml_evalnode.9 new file mode 100644 index 00000000..22b0b66e --- /dev/null +++ b/static/openbsd/man9/aml_evalnode.9 @@ -0,0 +1,202 @@ +.\" $OpenBSD: aml_evalnode.9,v 1.11 2015/09/14 15:14:55 schwarze Exp $ +.\" +.\" Copyright (c) 2007 Michael Knudsen +.\" +.\" 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: September 14 2015 $ +.Dt AML_EVALNODE 9 +.Os +.Sh NAME +.Nm aml_evalnode , +.Nm aml_evalname , +.Nm aml_find_node , +.Nm aml_freevalue , +.Nm aml_val2int +.Nd AML API +.Sh SYNOPSIS +.In dev/acpi/acpireg.h +.In dev/acpi/acpivar.h +.In dev/acpi/acpidev.h +.In dev/acpi/amltypes.h +.In dev/acpi/dsdt.h +.Ft int +.Fn aml_evalnode "struct acpi_softc *sc" "struct aml_node *node" \ +"int argc" "struct aml_value *argv" "struct aml_value *res" +.Ft int +.Fn aml_evalname "struct acpi_softc *sc" "struct aml_node *parent" \ +"const char *name" "int argc" "struct aml_value *argv" \ +"struct aml_value *res" +.Ft int +.Fn aml_find_node "struct aml_node *node" "const char *name" \ +"int (*cbproc)(struct aml_node *, void *arg)" "void *arg" +.Ft void +.Fn aml_freevalue "struct aml_value *val" +.Ft int64_t +.Fn aml_val2int "struct aml_value *rval" +.Sh DESCRIPTION +The AML API handles decoding and evaluation of the AML +code embedded in a machine's ACPI tables. +This code is used to implement configuration and control mechanisms for +machines. +.Pp +.Fn aml_evalnode +evaluates the AML node +.Fa node +located in the ACPI table specified by +.Fa sc . +Parameters may be passed using the +.Fa argv +parameters with the parameter +.Fa argc +specifying the number of parameters passed. +If there are no arguments, +a value of 0 is used for +.Fa argc +and +.Fa argv +should be +.Dv NULL . +If evaluating the node produces any result, for example a string with a device +name reference, this result is stored in the +.Fa res +parameter unless it is +.Dv NULL . +.Fa res +is cleared before storing the result. +If +.Fa node +does not exist, +.Fn aml_evalnode +returns +.Dv ACPI_E_BADVALUE , +otherwise it returns 0. +.Pp +.Fn aml_evalname +is similar to +.Fn aml_evalnode +but differs in that it searches for a subnode of +.Fa parent +with the name +.Fa name . +If such a node is found, it is evaluated using +.Fn aml_evalnode , +passing whatever parameters were passed to itself. +.Fn aml_evalname +returns the return value of +.Fn aml_evalnode . +.Pp +.Fn aml_find_node +is used to find all subnodes of +.Fa parent +with a name of +.Fa name . +For each node found, the function specified as the +.Fa cbproc +parameter is called with the node and +.Fa arg +as the first and second parameters, respectively. +The function specified as the +.Fa cbproc +parameter returns a value that specifies if the tree walk +should be terminated (!0) or continued (0) with the children. +.Fn aml_find_node +always returns 0. +.Pp +.Fn aml_freevalue +is used to free up the result returned from +.Fn aml_evalnode +or the other AML evaluation functions. +Note that no attempt is made to free the +.Vt struct aml_value +itself so it is safe to allocate this on the stack. +Also, calling +.Fn aml_freevalue +with a parameter of +.Dv NULL +is not an error. +.Pp +.Fn aml_val2int +is used to convert the +.Vt struct aml_value +pointed to by the +.Fa rval +parameter to a signed 64-bit integer value. +Multiple types exist for +.Vt struct aml_value , +and the conversion value depends on the type +of the value object as follows. +For objects of type +.Dv AML_OBJTYPE_INTEGER +and +.Dv AML_OBJTYPE_STATICINT , +the return value is simply the integer value stored in the object. +For objects of type +.Dv AML_OBJTYPE_BUFFER , +the return value is the integer interpretation of the buffer contents. +For objects of type +.Dv AML_OBJTYPE_STRING , +the return value is the integer value represented as a string in base 10 +or, if prefixed by +.Dq 0x , +in base 16. +If +.Fa rval +is +.Dv NULL +or not of one of the types mentioned above, +.Fn aml_val2int +returns 0. +.Sh EXAMPLES +Using +.Fn aml_evalname +to invoke the +.Dq _STA +method on a node +.Fa node +should be done like the following: +.Bd -literal -offset indent +struct acpi_softc *sc +struct aml_node *node; +struct aml_value res; + +if (aml_evalname(sc->sc_acpi, node, "_STA", 0, NULL, &res) != 0) { + dnprintf(10, "%s: no _STA\en", DEVNAME(sc)); + return; +} +.Ed +.Pp +Using the +.Vt struct aml_value +obtained from the +.Dq _STA +call to determine if the device is a battery is done as follows: +.Bd -literal -offset indent +if ((aml_val2int(&res) & STA_BATTERY) == 0) { + dnprintf(10, %s: no battery present\en", DEVNAME(sc)); + return; +.Ed +.Pp +Finally, when the result stored in +.Fa res +is no longer needed, free it using +.Fn aml_freevalue : +.Bd -literal -offset indent +aml_freevalue(&res); +.Ed +.Sh SEE ALSO +.Xr acpi 4 , +.Xr acpidump 8 +.Sh HISTORY +The AML API was written by +.An Jordan Hargrave Aq Mt jordan@openbsd.org . diff --git a/static/openbsd/man9/arc4random.9 b/static/openbsd/man9/arc4random.9 new file mode 100644 index 00000000..6dc6ab2c --- /dev/null +++ b/static/openbsd/man9/arc4random.9 @@ -0,0 +1,64 @@ +.\" $OpenBSD: arc4random.9,v 1.15 2020/05/29 03:19:43 deraadt Exp $ +.\" +.\" Copyright (c) 1996,2000 Michael Shalayeff +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 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 $Mdocdate: May 29 2020 $ +.Dt ARC4RANDOM 9 +.Os +.Sh NAME +.Nm arc4random , +.Nm arc4random_buf , +.Nm arc4random_uniform , +.Nm enqueue_randomness +.Nd kernel random subsystem +.Sh SYNOPSIS +.In sys/systm.h +.Ft u_int32_t +.Fn arc4random "void" +.Ft void +.Fn arc4random_buf "void *buf" "size_t nbytes" +.Ft u_int32_t +.Fn arc4random_uniform "u_int32_t upper_bound" +.Ft void +.Fn enqueue_randomness "int" +.Sh DESCRIPTION +.Fn arc4random +and +.Fn arc4random_buf +provide random numbers and are intended to be called in any +circumstance where random numbers are required. +.Pp +.Fn arc4random_uniform +will return a uniformly distributed random number less than +.Fa upper_bound , +avoiding "modulo bias" when the upper bound is not a power of two. +In the worst case, this function may consume multiple iterations +to ensure uniformity; see the source code to understand the problem +and solution. +.Pp +.Fn enqueue_randomness +causes the supplied data argument to be added to the entropy pool. +.Sh SEE ALSO +.Xr arc4random 3 , +.Xr random 4 diff --git a/static/openbsd/man9/atomic_add_int.9 b/static/openbsd/man9/atomic_add_int.9 new file mode 100644 index 00000000..3ca701a4 --- /dev/null +++ b/static/openbsd/man9/atomic_add_int.9 @@ -0,0 +1,73 @@ +.\" $OpenBSD: atomic_add_int.9,v 1.6 2014/02/13 12:05:05 dlg Exp $ +.\" +.\" Copyright (c) 2014 David Gwynne +.\" 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 $Mdocdate: February 13 2014 $ +.Dt ATOMIC_ADD_INT 9 +.Os +.Sh NAME +.Nm atomic_add_int , +.Nm atomic_add_int_nv , +.Nm atomic_add_long , +.Nm atomic_add_long_nv +.Nd atomic addition operations +.Sh SYNOPSIS +.In sys/atomic.h +.Ft void +.Fn atomic_add_int "volatile unsigned int *p" "unsigned int v" +.Ft unsigned int +.Fn atomic_add_int_nv "volatile unsigned int *p" "unsigned int v" +.Ft void +.Fn atomic_add_long "volatile unsigned long *p" "unsigned long v" +.Ft unsigned long +.Fn atomic_add_long_nv "volatile unsigned long *p" "unsigned long v" +.Sh DESCRIPTION +The atomic_add set of functions provide an interface for atomically +performing add and add-and-fetch operations with respect to interrupts +and multiple processors in the system. +.Pp +The value referenced by the pointer +.Fa p +is incremented by the value +.Fa v . +.Sh CONTEXT +.Fn atomic_add_int , +.Fn atomic_add_int_nv , +.Fn atomic_add_long , +and +.Fn atomic_add_long_nv +can all be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Nm atomic_add_int +and +.Nm atomic_add_long +perform the addition without returning any knowledge of the value at +.Fa p . +.Pp +.Nm atomic_add_int_nv +and +.Nm atomic_add_long_nv +return the value at +.Fa p +after the addition was performed. +.Sh SEE ALSO +.Xr atomic_inc_int 9 , +.Xr atomic_sub_int 9 +.Sh HISTORY +The atomic_add functions first appeared in +.Nx 5.0 +and +.Ox 5.5 . diff --git a/static/openbsd/man9/atomic_cas_uint.9 b/static/openbsd/man9/atomic_cas_uint.9 new file mode 100644 index 00000000..ab691ac3 --- /dev/null +++ b/static/openbsd/man9/atomic_cas_uint.9 @@ -0,0 +1,76 @@ +.\" $OpenBSD: atomic_cas_uint.9,v 1.7 2019/02/06 01:35:07 dlg Exp $ +.\" +.\" Copyright (c) 2014 David Gwynne +.\" 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 $Mdocdate: February 6 2019 $ +.Dt ATOMIC_CAS_UINT 9 +.Os +.Sh NAME +.Nm atomic_cas_uint , +.Nm atomic_cas_ulong , +.Nm atomic_cas_ptr +.Nd atomic compare-and-swap operations +.Sh SYNOPSIS +.In sys/atomic.h +.Ft unsigned int +.Fo atomic_cas_uint +.Fa "volatile unsigned int *p" +.Fa "unsigned int expected" +.Fa "unsigned int new" +.Fc +.Ft unsigned long +.Fo atomic_cas_ulong +.Fa "volatile unsigned long *p" +.Fa "unsigned long expected" +.Fa "unsigned long new" +.Fc +.Ft void * +.Fo atomic_cas_ptr +.Fa "volatile void *p" +.Fa "void *expected" +.Fa "void *new" +.Fc +.Sh DESCRIPTION +The atomic_cas set of functions provide an interface for atomically +performing compare-and-swap operations with respect to interrupts +and multiple processors in the system. +.Pp +The value referenced by the pointer +.Fa p +is compared against +.Fa expected . +If these values are equal then +.Fa new +replaces the value stored at +.Fa p . +.Sh CONTEXT +.Fn atomic_cas_uint , +.Fn atomic_cas_ulong , +and +.Fn atomic_cas_ptr +can all be called during autoconf, from process context, or from +interrupt context. +.Sh RETURN VALUES +These functions return the value at +.Fa p +as it was before the attempt to swap it. +.Sh SEE ALSO +.Xr atomic_swap_uint 9 +.Sh HISTORY +The atomic_cas functions first appeared in +.Nx 5.0 +and +.Ox 5.5 . diff --git a/static/openbsd/man9/atomic_dec_int.9 b/static/openbsd/man9/atomic_dec_int.9 new file mode 100644 index 00000000..b2923b7a --- /dev/null +++ b/static/openbsd/man9/atomic_dec_int.9 @@ -0,0 +1,72 @@ +.\" $OpenBSD: atomic_dec_int.9,v 1.6 2014/02/13 12:05:05 dlg Exp $ +.\" +.\" Copyright (c) 2014 David Gwynne +.\" 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 $Mdocdate: February 13 2014 $ +.Dt ATOMIC_DEC_INT 9 +.Os +.Sh NAME +.Nm atomic_dec_int , +.Nm atomic_dec_int_nv , +.Nm atomic_dec_long , +.Nm atomic_dec_long_nv +.Nd atomic decrement operations +.Sh SYNOPSIS +.In sys/atomic.h +.Ft void +.Fn atomic_dec_int "volatile unsigned int *p" +.Ft unsigned int +.Fn atomic_dec_int_nv "volatile unsigned int *p" +.Ft void +.Fn atomic_dec_long "volatile unsigned long *p " +.Ft unsigned long +.Fn atomic_dec_long_nv "volatile unsigned long *p" +.Sh DESCRIPTION +The atomic_dec set of functions provide an interface for atomically +performing decrement and decrement-and-fetch operations with respect +to interrupts and multiple processors in the system. +.Pp +The value referenced by the pointer +.Fa p +is decremented by 1. +.Sh CONTEXT +.Fn atomic_dec_int , +.Fn atomic_dec_int_nv , +.Fn atomic_dec_long , +and +.Fn atomic_dec_long_nv +can all be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Nm atomic_dec_int +and +.Nm atomic_dec_long +perform the decrement without returning any knowledge of the value at +.Fa p . +.Pp +.Nm atomic_dec_int_nv +and +.Nm atomic_dec_long_nv +return the value at +.Fa p +after the decrement was performed. +.Sh SEE ALSO +.Xr atomic_add_int 9 , +.Xr atomic_inc_int 9 +.Sh HISTORY +The atomic_add functions first appeared in +.Nx 5.0 +and +.Ox 5.5 . diff --git a/static/openbsd/man9/atomic_inc_int.9 b/static/openbsd/man9/atomic_inc_int.9 new file mode 100644 index 00000000..0d21dc51 --- /dev/null +++ b/static/openbsd/man9/atomic_inc_int.9 @@ -0,0 +1,72 @@ +.\" $OpenBSD: atomic_inc_int.9,v 1.6 2014/02/13 12:05:05 dlg Exp $ +.\" +.\" Copyright (c) 2014 David Gwynne +.\" 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 $Mdocdate: February 13 2014 $ +.Dt ATOMIC_INC_INT 9 +.Os +.Sh NAME +.Nm atomic_inc_int , +.Nm atomic_inc_int_nv , +.Nm atomic_inc_long , +.Nm atomic_inc_long_nv +.Nd atomic increment operations +.Sh SYNOPSIS +.In sys/atomic.h +.Ft void +.Fn atomic_inc_int "volatile unsigned int *p" +.Ft unsigned int +.Fn atomic_inc_int_nv "volatile unsigned int *p" +.Ft void +.Fn atomic_inc_long "volatile unsigned long *p " +.Ft unsigned long +.Fn atomic_inc_long_nv "volatile unsigned long *p" +.Sh DESCRIPTION +The atomic_inc set of functions provide an interface for atomically +performing increment and increment-and-fetch operations with respect +to interrupts and multiple processors in the system. +.Pp +The value referenced by the pointer +.Fa p +is incremented by 1. +.Sh CONTEXT +.Fn atomic_inc_int , +.Fn atomic_inc_int_nv , +.Fn atomic_inc_long , +and +.Fn atomic_inc_long_nv +can all be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Nm atomic_inc_int +and +.Nm atomic_inc_long +perform the increment without returning any knowledge of the value at +.Fa p . +.Pp +.Nm atomic_inc_int_nv +and +.Nm atomic_inc_long_nv +return the value at +.Fa p +after the increment was performed. +.Sh SEE ALSO +.Xr atomic_add_int 9 , +.Xr atomic_dec_int 9 +.Sh HISTORY +The atomic_inc functions first appeared in +.Nx 5.0 +and +.Ox 5.5 . diff --git a/static/openbsd/man9/atomic_load_int.9 b/static/openbsd/man9/atomic_load_int.9 new file mode 100644 index 00000000..c3e578ab --- /dev/null +++ b/static/openbsd/man9/atomic_load_int.9 @@ -0,0 +1,68 @@ +.\" $OpenBSD: atomic_load_int.9,v 1.2 2025/07/14 08:43:35 dlg Exp $ +.\" +.\" Copyright (c) 2014 David Gwynne +.\" Copyright (c) 2022 Alexander Bluhm +.\" 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 $Mdocdate: July 14 2025 $ +.Dt ATOMIC_LOAD_INT 9 +.Os +.Sh NAME +.Nm atomic_load_int , +.Nm atomic_load_long , +.Nm atomic_store_long , +.Nm atomic_store_int +.Nd atomic read and write memory operations +.Sh SYNOPSIS +.In sys/atomic.h +.Ft unsigned int +.Fn atomic_load_int "volatile const unsigned int *p" +.Ft unsigned long +.Fn atomic_load_long "volatile const unsigned long *p" +.Ft void +.Fn atomic_store_int "volatile unsigned int *p" "unsigned int v" +.Ft void +.Fn atomic_store_long "volatile unsigned long *p" "unsigned long v" +.Sh DESCRIPTION +The atomic_load and atomic_store set of functions provide an interface +for atomically performing read or write memory operations with +respect to interrupts and multiple processors in the system. +.Pp +The atomic_store functions change the value referenced by the pointer +.Fa p +to the value +.Fa v . +.Sh CONTEXT +.Fn atomic_load_int , +.Fn atomic_load_long , +.Fn atomic_store_int , +and +.Fn atomic_store_long +can all be called during autoconf, from process context, or from +interrupt context. +.Sh RETURN VALUES +.Nm atomic_load_int +and +.Nm atomic_load_long +return the value at +.Fa p . +.Sh SEE ALSO +.Xr atomic_add_int 9 , +.Xr atomic_add_long 9 , +.Xr atomic_sub_int 9 , +.Xr atomic_sub_long 9 +.Sh HISTORY +The atomic_load and atomic_store functions first appeared in +.Ox 7.1 . diff --git a/static/openbsd/man9/atomic_setbits_int.9 b/static/openbsd/man9/atomic_setbits_int.9 new file mode 100644 index 00000000..26183344 --- /dev/null +++ b/static/openbsd/man9/atomic_setbits_int.9 @@ -0,0 +1,71 @@ +.\" $OpenBSD: atomic_setbits_int.9,v 1.3 2014/02/13 14:25:21 jmc Exp $ +.\" +.\" Copyright (c) 2007 Artur Grabowski +.\" 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 $Mdocdate: February 13 2014 $ +.Dt ATOMIC_SETBITS_INT 9 +.Os +.Sh NAME +.Nm atomic_setbits_int , +.Nm atomic_clearbits_int +.Nd interface to perform atomic operations on data +.Sh SYNOPSIS +.In sys/atomic.h +.Ft void +.Fn atomic_setbits_int "unsigned int *p" "unsigned int b" +.Ft void +.Fn atomic_clearbits_int "unsigned int *p" "unsigned int b" +.Sh DESCRIPTION +The atomic bits set of functions provide an interface for changing data atomically with respect to interrupts and multiple processors in the system. +.Pp +The +.Fn atomic_setbits_int +function sets the bits in +.Fa b +in the integer pointed to by +.Fa p . +It is equivalent to +.Bd -literal -offset indent +*p |= b; +.Ed +.Pp +The +.Fn atomic_clearbits_int +function clears the bits in +.Fa b +in the integer pointed to by +.Fa p . +It is equivalent to +.Bd -literal -offset indent +*p &= ~b; +.Ed +.Sh CONTEXT +.Fn atomic_setbits_int , +and +.Fn atomic_clearbits_int +can be called during autoconf, from process context, or from interrupt context. +.Sh SEE ALSO +.Xr atomic_add_int 9 , +.Xr atomic_cas_uint 9 , +.Xr atomic_dec_int 9 , +.Xr atomic_inc_int 9 , +.Xr atomic_sub_int 9 , +.Xr atomic_swap_uint 9 +.Sh HISTORY +The +.Nm +functions first appeared in +.Ox 4.1 . diff --git a/static/openbsd/man9/atomic_sub_int.9 b/static/openbsd/man9/atomic_sub_int.9 new file mode 100644 index 00000000..2ae116cd --- /dev/null +++ b/static/openbsd/man9/atomic_sub_int.9 @@ -0,0 +1,71 @@ +.\" $OpenBSD: atomic_sub_int.9,v 1.6 2014/07/23 08:07:35 guenther Exp $ +.\" +.\" Copyright (c) 2014 David Gwynne +.\" 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 $Mdocdate: July 23 2014 $ +.Dt ATOMIC_SUB_INT 9 +.Os +.Sh NAME +.Nm atomic_sub_int , +.Nm atomic_sub_int_nv , +.Nm atomic_sub_long , +.Nm atomic_sub_long_nv +.Nd atomic subtraction operations +.Sh SYNOPSIS +.In sys/atomic.h +.Ft void +.Fn atomic_sub_int "volatile unsigned int *p" "unsigned int v" +.Ft unsigned int +.Fn atomic_sub_int_nv "volatile unsigned int *p" "unsigned int v" +.Ft void +.Fn atomic_sub_long "volatile unsigned long *p" "unsigned long v" +.Ft unsigned long +.Fn atomic_sub_long_nv "volatile unsigned long *p" "unsigned long v" +.Sh DESCRIPTION +The atomic_sub set of functions provide an interface for atomically +performing sub and sub-and-fetch operations with respect to interrupts +and multiple processors in the system. +.Pp +The value referenced by the pointer +.Fa p +is decremented by the value +.Fa v . +.Sh CONTEXT +.Fn atomic_sub_int , +.Fn atomic_sub_int_nv , +.Fn atomic_sub_long , +and +.Fn atomic_sub_long_nv +can all be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Nm atomic_sub_int +and +.Nm atomic_sub_long +perform the subtraction without returning any knowledge of the value at +.Fa p . +.Pp +.Nm atomic_sub_int_nv +and +.Nm atomic_sub_long_nv +return the value at +.Fa p +after the subtraction was performed. +.Sh SEE ALSO +.Xr atomic_add_int 9 , +.Xr atomic_dec_int 9 +.Sh HISTORY +The atomic_sub functions first appeared in +.Ox 5.5 . diff --git a/static/openbsd/man9/atomic_swap_uint.9 b/static/openbsd/man9/atomic_swap_uint.9 new file mode 100644 index 00000000..64c6b9e6 --- /dev/null +++ b/static/openbsd/man9/atomic_swap_uint.9 @@ -0,0 +1,59 @@ +.\" $OpenBSD: atomic_swap_uint.9,v 1.6 2014/07/18 10:40:14 dlg Exp $ +.\" +.\" Copyright (c) 2014 David Gwynne +.\" 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 $Mdocdate: July 18 2014 $ +.Dt ATOMIC_SWAP_UINT 9 +.Os +.Sh NAME +.Nm atomic_swap_uint , +.Nm atomic_swap_ulong , +.Nm atomic_swap_ptr +.Nd atomic swap operations +.Sh SYNOPSIS +.In sys/atomic.h +.Ft unsigned int +.Fn atomic_swap_uint "volatile unsigned int *p" "unsigned int new" +.Ft unsigned long +.Fn atomic_swap_ulong "volatile unsigned long *p" "unsigned long new" +.Ft void * +.Fn atomic_swap_ptr "volatile void *p" "void *new" +.Sh DESCRIPTION +The atomic_swap set of functions provide an interface for atomically +performing swap operations with respect to interrupts and multiple +processors in the system. +.Pp +The value referenced by the pointer +.Fa p +is replaced by the value +.Fa new . +.Sh CONTEXT +.Fn atomic_swap_uint , +.Fn atomic_swap_ulong , +and +.Fn atomic_swap_ptr +can all be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +These functions return the value at +.Fa p +as it was before the swap operation. +.Sh SEE ALSO +.Xr atomic_cas_uint 9 +.Sh HISTORY +The atomic_swap functions first appeared in +.Nx 5.0 +and +.Ox 5.5 . diff --git a/static/openbsd/man9/audio.9 b/static/openbsd/man9/audio.9 new file mode 100644 index 00000000..8b977a02 --- /dev/null +++ b/static/openbsd/man9/audio.9 @@ -0,0 +1,529 @@ +.\" $OpenBSD: audio.9,v 1.36 2025/11/02 14:33:06 ratchov Exp $ +.\" $NetBSD: audio.9,v 1.14 2000/02/11 22:56:15 kleink Exp $ +.\" +.\" Copyright (c) 1999, 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 $Mdocdate: November 2 2025 $ +.Dt AUDIO 9 +.Os +.Sh NAME +.Nm audio +.Nd interface between low and high level audio drivers +.Sh DESCRIPTION +The audio device driver is divided into a high level, +hardware independent layer, and a low level, hardware +dependent layer. +The interface between these is the +.Va audio_hw_if +structure. +.Bd -literal +struct audio_hw_if { + int (*open)(void *, int); + void (*close)(void *); + int (*set_params)(void *, int, int, + struct audio_params *, struct audio_params *); + int (*round_blocksize)(void *, int); + + int (*commit_settings)(void *); + + int (*init_output)(void *, void *, int); + int (*init_input)(void *, void *, int); + int (*start_output)(void *, void *, int, + void (*)(void *), void *); + int (*start_input)(void *, void *, int, + void (*)(void *), void *); + int (*halt_output)(void *); + int (*halt_input)(void *); + + int (*set_port)(void *, struct mixer_ctrl *); + int (*get_port)(void *, struct mixer_ctrl *); + + int (*query_devinfo)(void *, struct mixer_devinfo *); + + void *(*allocm)(void *, int, size_t, int, int); + void (*freem)(void *, void *, int); + size_t (*round_buffersize)(void *, int, size_t); + + int (*trigger_output)(void *, void *, void *, int, + void (*)(void *), void *, struct audio_params *); + int (*trigger_input)(void *, void *, void *, int, + void (*)(void *), void *, struct audio_params *); + void (*copy_output)(void *hdl, size_t bytes); + void (*underrun)(void *hdl); + int (*set_blksz)(void *, int, + struct audio_params *, struct audio_params *, int); + int (*set_nblks)(void *, int, int, + struct audio_params *, int); + size_t (*display_name)(void *, char *, size_t); +}; + +struct audio_params { + u_long sample_rate; /* sample rate */ + u_int encoding; /* mu-law, linear, etc */ + u_int precision; /* bits/sample */ + u_int bps; /* bytes/sample */ + u_int msb; /* data alignment */ + u_int channels; /* mono(1), stereo(2) */ +}; +.Ed +.Pp +The high level audio driver attaches to the low level driver +when the latter calls +.Fn audio_attach_mi . +This call is: +.Bd -literal -offset indent +struct device * +audio_attach_mi(const struct audio_hw_if *ahwp, void *hdl, + struct device *dev); +.Ed +.Pp +The +.Va audio_hw_if +struct is as shown above. +The +.Fa hdl +argument is a handle to some low level data structure. +It is sent as the first argument to all the functions in +.Fa ahwp +when the high level driver calls them. +.Fa dev +is the device struct for the hardware device. +.Pp +The upper layer of the audio driver allocates one buffer for playing +and one for recording. +It handles the buffering of data from the user processes in these. +The data is presented to the lower level in smaller chunks, called blocks. +During playback, if there is no data available from the user process +when the hardware requests another block, a block of silence will be +used instead. +Similarly, if the user process does not read data quickly enough during +recording, data will be thrown away. +.Pp +The fields of +.Va audio_hw_if +are described in some more detail below. +Some fields are optional and can be set to +.Dv NULL +if not needed. +.Bl -tag -width indent +.It Ft int Fn (*open) "void *hdl" "int flags" +This function is called when the audio device is opened, with +.Fa flags +the kernel representation of flags passed to the +.Xr open 2 +system call +.Po +see +.Dv OFLAGS +and +.Dv FFLAGS +in +.In sys/fcntl.h +.Pc . +It initializes the hardware for I/O. +Every successful call to +.Fn open +is matched by a call to +.Fn close . +This function returns 0 on success, otherwise an error code. +.It Ft void Fn (*close) "void *hdl" +This function is called when the audio device is closed. +.It Ft int Fn (*set_params) "void *hdl" "int setmode" "int usemode" \ +"struct audio_params *play" "struct audio_params *rec" +This function is called to set the audio encoding mode. +.Fa setmode +is a combination of the +.Dv AUMODE_RECORD +and +.Dv AUMODE_PLAY +flags to indicate which mode(s) are to be set. +.Fa usemode +is also a combination of these flags, but indicates the current +mode of the device (i.e., the value corresponding to the +.Va flags +argument to the +.Fn open +function). +The +.Fa play +and +.Fa rec +structures contain the encoding parameters that will be set. +The values of the structures must also be modified if the hardware +cannot be set to exactly the requested mode (e.g., if the requested +sampling rate is not supported, but one close enough is). +Except the channel count, the same value is passed in both +.Fa play +and +.Fa rec . +.Pp +The machine independent audio driver does some preliminary parameter checking; +it verifies that the precision is compatible with the encoding, +and it translates +.Dv AUDIO_ENCODING_[US]LINEAR +to +.Dv AUDIO_ENCODING_[US]LINEAR_{LE,BE} . +.Pp +This function returns 0 on success, otherwise an error code. +.It Ft int Fn (*round_blocksize) "void *hdl" "int bs" +This function is optional. +If supplied, it is called with the block size, +.Fa bs , +which has been computed by the upper layer. +It returns a block size, possibly changed according to the needs of the +hardware driver. +.It Ft int Fn (*commit_settings) "void *hdl" +This function is optional. +If supplied, it is called after all calls to +.Fn set_params +and +.Fn set_port +are done. +A hardware driver that needs to get the hardware in +and out of command mode for each change can save all the changes +during previous calls and do them all here. +This function returns 0 on success, otherwise an error code. +.It Ft int Fn (*init_output) "void *hdl" "void *buffer" "int size" +This function is optional. +If supplied, it is called before any output starts, but only after the total +.Fa size +of the output +.Fa buffer +has been determined. +It can be used to initialize looping DMA for hardware that needs it. +This function returns 0 on success, otherwise an error code. +.It Ft int Fn (*init_input) "void *hdl" "void *buffer" "int size" +This function is optional. +If supplied, it is called before any input starts, but only after the total +.Fa size +of the input +.Fa buffer +has been determined. +It can be used to initialize looping DMA for hardware that needs it. +This function returns 0 on success, otherwise an error code. +.It Ft int Fn (*start_output) "void *hdl" "void *block" "int bsize" \ +"void (*intr)(void *)" "void *intrarg" +This function is deprecated. +Use +.Fn trigger_output +instead. +This function is called to start the transfer of +.Fa bsize +bytes from +.Fa block +to the audio hardware. +The call returns when the data transfer +has been initiated (normally with DMA). +When the hardware is ready to accept more samples, the function +.Fa intr +will be called with the argument +.Fa intrarg . +Calling +.Fa intr +will normally initiate another call to +.Fn start_output . +This function returns 0 on success, otherwise an error code. +.It Ft int Fn (*start_input) "void *hdl" "void *block" "int bsize" \ +"void (*intr)(void *)" "void *intrarg" +This function is deprecated. +Use +.Fn trigger_input +instead. +This function is called to start the transfer of +.Fa bsize +bytes to +.Fa block +from the audio hardware. +The call returns when the data transfer +has been initiated (normally with DMA). +When the hardware is ready to deliver more samples, the function +.Fa intr +will be called with the argument +.Fa intrarg . +Calling +.Fa intr +will normally initiate another call to +.Fn start_input . +This function returns 0 on success, otherwise an error code. +.It Ft int Fn (*halt_output) "void *hdl" +This function is called to abort the output transfer (started by +.Fn trigger_output ) +in progress. +This function returns 0 on success, otherwise an error code. +.It Ft int Fn (*halt_input) "void *hdl" +This function is called to abort the input transfer (started by +.Fn trigger_input ) +in progress. +This function returns 0 on success, otherwise an error code. +.It Ft int Fn (*set_port) "void *hdl" "struct mixer_ctrl *mc" +This function is called when the +.Dv AUDIO_MIXER_WRITE +.Xr ioctl 2 +is used. +It takes data from +.Fa mc +and sets the corresponding mixer values. +This function returns 0 on success, otherwise an error code. +.It Ft int Fn (*get_port) "void *hdl" "struct mixer_ctrl *mc" +This function is called when the +.Dv AUDIO_MIXER_READ +.Xr ioctl 2 +is used. +It fills +.Fa mc +and returns 0 on success, or it returns an error code on failure. +.It Ft int Fn (*query_devinfo) "void *hdl" "struct mixer_devinfo *di" +This function is called when the +.Dv AUDIO_MIXER_DEVINFO +.Xr ioctl 2 +is used. +It fills +.Fa di +and returns 0 on success, or it returns an error code on failure. +.It Ft void * Fn (*allocm) "void *hdl" "int direction" "size_t size" "int type" \ +"int flags" +This function is optional. +If supplied, it is called to allocate the device buffers. +If not supplied, +.Xr malloc 9 +is used instead (with the same arguments but the first two). +The reason for using a device dependent routine instead of +.Xr malloc 9 +is that some buses need special allocation to do DMA. +.Fa direction +is +.Dv AUMODE_PLAY +or +.Dv AUMODE_RECORD . +This function returns the address of the buffer on success, or 0 on failure. +.It Ft void Fn (*freem) "void *hdl" "void *addr" "int type" +This function is optional. +If supplied, it is called to free memory allocated by +.Fn allocm . +If not supplied, +.Xr free 9 +is used instead. +.\" XXX: code passes int instead of size_t, but decl is size_t +.It Ft size_t Fn (*round_buffersize) "void *hdl" "int direction" \ +"size_t bufsize" +This function is optional. +If supplied, it is called at startup to determine the audio buffer size. +The upper layer supplies the suggested size in +.Fa bufsize , +which the hardware driver can then change if needed. +E.g., DMA on the ISA bus cannot exceed 65536 bytes. +Note that the buffer size is always a multiple of the block size, so +.Fn round_blocksize +and +.Fn round_buffersize +must be consistent. +.It Ft int Fn (*trigger_output) "void *hdl" "void *start" "void *end" "int blksize" \ +"void (*intr)(void *)" "void *intrarg" "struct audio_params *param" +This function is called to start the transfer of data from the circular +buffer delimited by +.Fa start +and +.Fa end +to the audio hardware, parameterized as in +.Fa param . +The call returns when the data transfer +has been initiated (normally with DMA). +When the hardware is finished transferring each +.Fa blksize +sized block, the function +.Fa intr +will be called with the argument +.Fa intrarg +(typically from the audio hardware interrupt service routine). +Once started, the transfer may be stopped using +.Fn halt_output . +This function returns 0 on success, otherwise an error code. +.It Ft int Fn (*trigger_input) "void *hdl" "void *start" "void *end" "int blksize" \ +"void (*intr)(void *)" "void *intrarg" "struct audio_params *param" +This function is called to start the transfer of data from the audio +hardware, parameterized as in +.Fa param , +to the circular buffer delimited by +.Fa start +and +.Fa end . +The call returns when the data transfer +has been initiated (normally with DMA). +When the hardware is finished transferring each +.Fa blksize +sized block, the function +.Fa intr +will be called with the argument +.Fa intrarg +(typically from the audio hardware interrupt service routine). +Once started, the transfer may be stopped using +.Fn halt_input . +This function returns 0 on success, otherwise an error code. +.It Ft void Fn (*copy_output) "void *hdl" "size_t bytes" +This function is called whenever the given amount of bytes was +appended to the play ring buffer, typically during a +.Xr write 2 +system call. +Drivers using bounce buffers for transfers between the audio +ring buffer and the device could implement this function +to copy the given amount of bytes into their bounce buffers. +There's no analogue function for recording as data is +produced by the device and could simply be copied upon +transfer completion. +.It Ft void Fn (*underrun) "void *hdl" +This function is called at interrupt context whenever a +play block was skipped by the +.Xr audio 4 +driver. +Drivers using bounce buffers for transfers between the audio +ring buffer and the device must implement this method to skip +one block from the audio ring buffer and transfer the +corresponding amount of silence to the device. +.It Ft int Fn (*set_blksz) "void *hdl" "int mode" \ +"struct audio_params *play" "struct audio_params *rec" "int blksz" +This function is called to set the audio block size. +.Fa mode +is a combination of the +.Dv AUMODE_RECORD +and +.Dv AUMODE_PLAY +flags indicating the current mode set with the +.Fn open +function. +The +.Fa play +and +.Fa rec +structures contain the current encoding set with the +.Fn set_params +function. +.Fa blksz +is the desired block size in frames. +It may be adjusted to match hardware constraints. +This function returns the adjusted block size. +.It Ft int Fn (*set_nblks) "void *hdl" "int dir" "int blksz" \ +"struct audio_params *params" "int nblks" +This function is called to set the number of audio blocks in +the ring buffer. +.Fa dir +is either the +.Dv AUMODE_RECORD +or the +.Dv AUMODE_PLAY +flag, indicating which ring buffer size is set. +The +.Fa params +structure contains the encoding parameters set by the +.Fn set_params +method. +.Fa blksz +is the current block size in frames set with the +.Fa set_params +function. +The +.Fa params +structure is the current encoding parameters, set with the +.Fn set_params +function. +.Fa nblks +is the desired number of blocks in the ring buffer. +It may be lowered to at least two, to match hardware constraints. +This function returns the adjusted number of blocks. +.It Ft size_t Fn (*display_name) "void *hdl" "char *buf" "size_t size" +This function produces a string suitable for user interfaces and +intended to help the user to identify the hardware. +Like +.Xr snprintf 3 , +this function returns the total length of the string it tried to create +(excluding the final +.Ql \e0 ) . +Unless +.Fa size +is 0, it writes at most +.Fa size Ns \-1 +characters followed by a terminating +.Ql \e0 +at the location pointed by +.Fa buf . +.El +.Pp +If the audio hardware is capable of input from more +than one source, it should define +.Dv AudioNsource +in class +.Dv AudioCrecord . +This mixer control should be of type +.Dv AUDIO_MIXER_ENUM +or +.Dv AUDIO_MIXER_SET +and enumerate the possible input sources. +For each of the named sources there should be +a control in the +.Dv AudioCinputs +class of type +.Dv AUDIO_MIXER_VALUE +if recording level of the source can be set. +If the overall recording level can be changed (i.e., regardless +of the input source) then this control should be named +.Dv AudioNrecord +and be of class +.Dv AudioCinputs . +.Pp +If the audio hardware is capable of output to more than +one destination, it should define +.Dv AudioNoutput +in class +.Dv AudioCmonitor . +This mixer control should be of type +.Dv AUDIO_MIXER_ENUM +or +.Dv AUDIO_MIXER_SET +and enumerate the possible destinations. +For each of the named destinations there should be +a control in the +.Dv AudioCoutputs +class of type +.Dv AUDIO_MIXER_VALUE +if output level of the destination can be set. +If the overall output level can be changed (i.e., regardless +of the destination) then this control should be named +.Dv AudioNmaster +and be of class +.Dv AudioCoutputs . +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr open 2 , +.Xr sio_open 3 , +.Xr audio 4 , +.Xr free 9 , +.Xr malloc 9 +.Sh HISTORY +This +.Nm +interface first appeared in +.Ox 1.2 . diff --git a/static/openbsd/man9/autoconf.9 b/static/openbsd/man9/autoconf.9 new file mode 100644 index 00000000..a2c4d54c --- /dev/null +++ b/static/openbsd/man9/autoconf.9 @@ -0,0 +1,252 @@ +.\" $OpenBSD: autoconf.9,v 1.18 2025/06/13 18:34:00 schwarze Exp $ +.\" $NetBSD: autoconf.9,v 1.9 2002/02/13 08:18:35 ross Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 $Mdocdate: June 13 2025 $ +.Dt CONFIG_SEARCH 9 +.Os +.Sh NAME +.Nm config_search , +.Nm config_rootsearch , +.Nm config_found_sm , +.Nm config_found , +.Nm config_rootfound +.Nd autoconfiguration framework +.Sh SYNOPSIS +.In sys/param.h +.In sys/device.h +.Ft void * +.Fn config_search "cfmatch_t func" "struct device *parent" "void *aux" +.Ft void * +.Fn config_rootsearch "cfmatch_t func" "char *rootname" "void *aux" +.Ft struct device * +.Fo config_found_sm +.Fa "struct device *parent" +.Fa "void *aux" +.Fa "cfprint_t print" +.Fa "cfmatch_t submatch" +.Fc +.Ft struct device * +.Fn config_found "struct device *parent" "void *aux" "cfprint_t print" +.Ft struct device * +.Fn config_rootfound "char *rootname" "void *aux" +.Sh DESCRIPTION +Autoconfiguration is the process of matching hardware devices with an +appropriate device driver. +In its most basic form, autoconfiguration consists of the recursive +process of finding and attaching all devices on a bus, including other buses. +.Pp +The autoconfiguration framework supports +.Em direct configuration +where the bus driver can determine the devices present. +.Pp +The autoconfiguration framework also supports +.Em indirect configuration +where the drivers must probe the bus looking for the presence of a device. +Direct configuration is preferred since it can find hardware regardless of +the presence of proper drivers. +.Pp +The autoconfiguration process occurs at system bootstrap and is driven by a +table generated from a +.Do +machine description +.Dc +file by +.Xr config 8 . +For a description of the +.Xr config 8 +.Do +device definition +.Dc +language, see +.Xr files.conf 5 . +.Pp +Each device must have a name consisting of an alphanumeric string that +ends with a unit number. +The unit number identifies an instance of the driver. +Device data structures are allocated dynamically during autoconfiguration, +giving a unique address for each instance. +.Ss Indirect Configuration +The +.Fn config_search +function performs indirect configuration of physical devices by iterating +over all potential children, calling the given function +.Fa func +for each one. +.Pp +The +.Fn config_rootsearch +function finds the root device identified by the string +.Fa rootname , +in a manner similar to +.Fn config_search , +except that there is no parent device. +If +.Fa func +is +.Dv NULL , +.Fn config_search +applies each child's match function instead. +The argument +.Fa parent +is the pointer to the parent's device structure. +The given +.Fa aux +argument describes the device that has been found and is simply passed +on through +.Fa func +to the child. +.Fn config_search +returns a pointer to the best-matched child or +.Dv NULL +otherwise. +.Pp +The role of +.Fa func +is to call +the match function for each device and call +.Fn config_attach +for any positive matches. +.Bd -literal +typedef int (*cfmatch_t)(struct device *parent, void *child, void *aux); +.Ed +.Pp +If +.Fa func +is +.Dv NULL , +then the parent should record the return value from +.Fn config_search +and call +.Fn config_attach +itself. +.Pp +Note that this function is designed so that it can be used to apply an +arbitrary function to all potential children. +In this case callers may choose to ignore the return value. +.Ss Direct Configuration +The +.Fn config_found_sm +function performs direct configuration on a physical device. +.Fn config_found_sm +is called by the parent and in turn calls the +.Fa submatch +function to call the match function as determined by the configuration table. +If +.Fa submatch +is +.Dv NULL , +the driver match functions are called directly. +The argument +.Fa parent +is the pointer to the parent's device structure. +The given +.Fa aux +argument describes the device that has been found. +The +.Em softc +structure for the matched device will be allocated, and the appropriate +driver attach function will be called. +.Pp +If the device is matched, the system prints the name of the child and +parent devices, and then calls the +.Fa print +function to produce additional information if desired. +If no driver takes a match, the same +.Fa print +function is called to complain. +The print function is called with the +.Fa aux +argument and, if the matches failed, the full name (including unit +number) of the parent device, otherwise +.Dv NULL . +.Bd -literal +typedef int (*cfprint_t)(void *aux, const char *parentname); +#define QUIET 0 /* print nothing */ +#define UNCONF 1 /* print " not configured" */ +#define UNSUPP 2 /* print " not supported" */ +.Ed +.Pp +Two special strings, +.Do +not configured +.Dc +and +.Do +unsupported +.Dc +will be appended automatically to non-driver reports if the return +value is +.Dv UNCONF +or +.Dv UNSUPP +respectively, otherwise the function should return the value +.Dv QUIET . +.Pp +The +.Fn config_found_sm +function returns a pointer to the attached device's +.Em softc +structure if the device is attached, +.Dv NULL +otherwise. +Most callers can ignore this value, since the system will already have +printed a diagnostic. +.Pp +The +.Fn config_found +macro expands to +.Fn config_found_sm "parent" "aux" "print" "submatch" +with +.Fa submatch +set to +.Dv NULL +and is provided for compatibility with older drivers. +.Pp +The +.Fn config_rootfound +function performs the same operation on the root device identified +by the +.Fa rootname +string. +.Sh CODE REFERENCES +The autoconfiguration framework itself is implemented within the file +.Pa sys/kern/subr_autoconf.c . +Data structures and function prototypes for the framework are located in +.Pa sys/sys/device.h . +.Sh SEE ALSO +.Xr autoconf 4 , +.Xr files.conf 5 , +.Xr config 8 , +.Xr config_attach 9 +.Sh HISTORY +Autoconfiguration first appeared in +.Bx 4.1 . +The autoconfiguration framework was completely revised in +.Bx 4.4 . diff --git a/static/openbsd/man9/bemtoh32.9 b/static/openbsd/man9/bemtoh32.9 new file mode 100644 index 00000000..7550ce61 --- /dev/null +++ b/static/openbsd/man9/bemtoh32.9 @@ -0,0 +1,143 @@ +.\" $OpenBSD: bemtoh32.9,v 1.8 2022/03/31 17:27:23 naddy Exp $ +.\" +.\" Copyright (c) 2014 David Gwynne +.\" 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 $Mdocdate: March 31 2022 $ +.Dt BEMTOH32 9 +.Os +.Sh NAME +.Nm bemtoh16 , +.Nm bemtoh32 , +.Nm bemtoh64 , +.Nm lemtoh16 , +.Nm lemtoh32 , +.Nm lemtoh64 , +.Nm htobem16 , +.Nm htobem32 , +.Nm htobem64 , +.Nm htolem16 , +.Nm htolem32 , +.Nm htolem64 +.Nd byte swapping memory load and store operations +.Sh SYNOPSIS +.In sys/types.h +.Ft uint16_t +.Fn bemtoh16 "volatile const uint16_t *m" +.Ft uint32_t +.Fn bemtoh32 "volatile const uint32_t *m" +.Ft uint64_t +.Fn bemtoh64 "volatile const uint64_t *m" +.Ft uint16_t +.Fn lemtoh16 "volatile const uint16_t *m" +.Ft uint32_t +.Fn lemtoh32 "volatile const uint32_t *m" +.Ft uint64_t +.Fn lemtoh64 "volatile const uint64_t *m" +.Ft void +.Fn htobem16 "volatile uint16_t *m" "uint16_t v" +.Ft void +.Fn htobem32 "volatile uint32_t *m" "uint32_t v" +.Ft void +.Fn htobem64 "volatile uint64_t *m" "uint64_t v" +.Ft void +.Fn htolem16 "volatile uint16_t *m" "uint16_t v" +.Ft void +.Fn htolem32 "volatile uint32_t *m" "uint32_t v" +.Ft void +.Fn htolem64 "volatile uint64_t *m" "uint64_t v" +.Sh DESCRIPTION +This API provides a way to take advantage of an architecture's ability +to load and store words in memory of different endians. +If an architecture has no specialised support for these operations, +they will be implemented as a wrapper around the +.Xr htobe64 3 +API. +.Pp +These operations are subject to the same alignment restrictions as +the host's normal memory loads and stores. +.Pp +.Fn bemtoh16 , +.Fn bemtoh32 , +and +.Fn bemtoh64 +read a big endian value from the memory located at +.Fa m +into the host's native byte order. +.Fn lemtoh16 , +.Fn lemtoh32 , +and +.Fn lemtoh64 +read a little endian value from the memory located at +.Fa m +into the host's native byte order. +.Pp +.Fn htobem16 , +.Fn htobem32 , +and +.Fn htobem64 +store the host's native byte ordered value of +.Fa v +as a big endian value in the memory located at +.Fa m . +.Fn htolem16 , +.Fn htolem32 , +and +.Fn htolem64 +store the host's native byte ordered value of +.Fa v +as a little endian value in the memory located at +.Fa m . +.Sh CONTEXT +.Fn bemtoh16 , +.Fn bemtoh32 , +.Fn bemtoh64 , +.Fn lemtoh16 , +.Fn lemtoh32 , +.Fn lemtoh64 , +.Fn htobem16 , +.Fn htobem32 , +.Fn htobem64 , +.Fn htolem16 , +.Fn htolem32 , +and +.Fn htolem64 +can be called during autoconf, from process context, or from interrupt +context. +.Sh RETURN VALUES +.Fn bemtoh16 , +.Fn bemtoh32 , +.Fn bemtoh64 , +.Fn lemtoh16 , +.Fn lemtoh32 , +and +.Fn lemtoh64 +return the host's native byte ordered value of the memory at +.Fa m +after the appropriate byteswapping has occurred. +.Pp +.Fn htobem16 , +.Fn htobem32 , +.Fn htobem64 , +.Fn htolem16 , +.Fn htolem32 , +and +.Fn htolem64 +do not return a value. +.Sh SEE ALSO +.Xr htobe64 3 +.Sh HISTORY +These functions first appeared in +.Ox 5.6 . diff --git a/static/openbsd/man9/bintimeadd.9 b/static/openbsd/man9/bintimeadd.9 new file mode 100644 index 00000000..ce6f6c94 --- /dev/null +++ b/static/openbsd/man9/bintimeadd.9 @@ -0,0 +1,185 @@ +.\" $OpenBSD: bintimeadd.9,v 1.1 2019/06/03 01:27:30 cheloha Exp $ +.\" $NetBSD: getitimer.2,v 1.6 1995/10/12 15:40:54 jtc 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. +.\" +.\" @(#)getitimer.2 8.2 (Berkeley) 12/11/93 +.\" +.Dd $Mdocdate: June 3 2019 $ +.Dt BINTIMEADD 9 +.Os +.Sh NAME +.Nm bintimecmp , +.Nm bintimesub , +.Nm bintimeadd , +.Nm bintimeaddfrac , +.Nm BINTIME_TO_TIMEVAL , +.Nm BINTIME_TO_TIMESPEC , +.Nm TIMEVAL_TO_BINTIME , +.Nm TIMESPEC_TO_BINTIME +.Nd manipulate kernel time structures +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fo bintimecmp +.Fa "struct bintime *a" +.Fa "struct bintime *b" +.Fa operator +.Fc +.Ft void +.Fo bintimesub +.Fa "const struct bintime *a" +.Fa "const struct bintime *b" +.Fa "struct bintime *c" +.Fc +.Ft void +.Fo bintimeadd +.Fa "const struct bintime *a" +.Fa "const struct bintime *b" +.Fa "struct bintime *c" +.Fc +.Ft void +.Fo bintimeaddfrac +.Fa "const struct bintime *a" +.Fa "uint64_t fraction" +.Fa "struct bintime *b" +.Fc +.Ft void +.Fo BINTIME_TO_TIMEVAL +.Fa "const struct bintime *bt" +.Fa "struct timeval *tv" +.Fc +.Ft void +.Fo BINTIME_TO_TIMESPEC +.Fa "const struct bintime *bt" +.Fa "struct timespec *ts" +.Fc +.Ft void +.Fo TIMEVAL_TO_BINTIME +.Fa "const struct timeval *tv" +.Fa "struct bintime *bt" +.Fc +.Ft void +.Fo TIMESPEC_TO_BINTIME +.Fa "const struct timespec *ts" +.Fa "struct bintime *bt" +.Fc +.Sh DESCRIPTION +These functions simplify the use of +.Vt bintime +structures and the conversion to and from other time representations. +.Pp +The following functions are available: +.Bl -tag -width Ds +.It Fn bintimecmp a b operator +Test if the expression +.Fa a operator b +is true, +where +.Fa operator +is one of +.Cm < , +.Cm <= , +.Cm == , +.Cm != , +.Cm >= , +or +.Cm > . +.It Fn bintimesub a b c +Subtract +.Fa b +from +.Fa a +and store the result in +.Fa c . +.It Fn bintimeadd a b c +Add +.Fa b +to +.Fa a +and store the result in +.Fa c . +.It Fn bintimeaddfrac a fraction b +Add +.Fa fraction +fractional seconds to +.Fa a +and store the result in +.Fa b . +A fractional second is equal to 1 / (2^64) seconds. +.It Fn BINTIME_TO_TIMEVAL bt tv +Convert +.Fa bt +to a +.Vt struct timeval +and store the result in +.Fa tv . +.It Fn BINTIME_TO_TIMESPEC bt ts +Convert +.Fa bt +to a +.Vt struct timespec +and store the result in +.Fa ts . +.It Fn TIMEVAL_TO_BINTIME tv bt +Convert +.Fa tv +to a +.Vt struct bintime +and store the result in +.Fa bt . +.It Fn TIMESPEC_TO_BINTIME ts bt +Convert +.Fa ts +to a +.Vt struct bintime +and store the result in +.Fa bt . +.El +.Sh RETURN VALUES +.Fn bintimecmp +returns 1 if the tested condition holds or 0 otherwise. +.Sh CODE REFERENCES +These functions are implemented in the file +.Pa sys/sys/time.h . +.Sh SEE ALSO +.Xr timeradd 3 , +.Xr microtime 9 , +.Xr tc_init 9 , +.Xr timeout 9 +.Sh HISTORY +Predecessors to these functions first appeared in +.Fx 5.0 +and were ported to +.Ox 3.6 . +They were modified to more closely resemble the +.Xr timeradd 3 +macros for +.Ox 6.6 . +.Sh AUTHORS +.An Poul-Henning Kamp Aq Mt phk@freebsd.org diff --git a/static/openbsd/man9/bio_register.9 b/static/openbsd/man9/bio_register.9 new file mode 100644 index 00000000..e823b036 --- /dev/null +++ b/static/openbsd/man9/bio_register.9 @@ -0,0 +1,66 @@ +.\" $OpenBSD: bio_register.9,v 1.6 2015/09/14 12:05:33 schwarze Exp $ +.\" +.\" Copyright (c) 2006 David Gwynne +.\" +.\" 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: September 14 2015 $ +.Dt BIO_REGISTER 9 +.Os +.Sh NAME +.Nm bio_register , +.Nm bio_unregister +.Nd block I/O ioctl tunnelling interface +.Sh SYNOPSIS +.In dev/biovar.h +.Ft int +.Fn bio_register "struct device *dev" "int (*bioctl)(struct device *, u_long, caddr_t)" +.Ft void +.Fn bio_unregister "struct device *dev" +.Sh DESCRIPTION +The block I/O ioctl tunnelling interface is used by drivers to register and +unregister ioctl handlers to be accessed via the +.Xr bio 4 +device. +.Pp +.Fn bio_register +is called by the driver represented by +.Fa dev +to register the +.Fa bioctl +argument as the ioctl handler for itself. +.Pp +.Fn bio_unregister +is called to remove the ioctl handler previously registered with +.Fn bio_register +for the device represented by +.Fa dev . +.Pp +.Fn bio_register +and +.Fn bio_unregister +can be called during +.Xr autoconf 9 +or from process context. +The +.Fa bioctl +callback is called from process context. +.Sh SEE ALSO +.Xr bio 4 , +.Xr autoconf 9 +.Sh HISTORY +The block I/O ioctl tunnelling interface first appeared in +.Ox 3.2 . +.Sh AUTHORS +The block I/O ioctl tunnelling interface was written by +.An Niklas Hallqvist Aq Mt niklas@openbsd.org . diff --git a/static/openbsd/man9/boot.9 b/static/openbsd/man9/boot.9 new file mode 100644 index 00000000..c8cb8d5b --- /dev/null +++ b/static/openbsd/man9/boot.9 @@ -0,0 +1,107 @@ +.\" $OpenBSD: boot.9,v 1.10 2014/12/10 15:29:52 mikeb Exp $ +.\" $NetBSD: boot.9,v 1.1 1995/11/25 21:24:48 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 $Mdocdate: December 10 2014 $ +.Dt BOOT 9 +.Os +.Sh NAME +.Nm boot +.Nd halt or reboot the system +.Sh SYNOPSIS +.In sys/reboot.h +.Ft void +.Fn boot "int howto" +.Sh DESCRIPTION +The +.Fn boot +function handles final system shutdown, and either halts or reboots +the system. +The exact action to be taken is determined by the flags passed in +.Fa howto +and by whether or not the system has finished autoconfiguration. +.Pp +If the system has finished autoconfiguration, +.Fn boot +does the following: +.Bl -enum -offset indent +.It +Sets the +.Va boothowto +system variable from the +.Fa howto +argument. +.It +If this is the first invocation of +.Fn boot +and the +.Dv RB_NOSYNC +flag is not set in +.Fa howto , +syncs and unmounts the system disks by calling +.Fn vfs_shutdown +and sets the time of day clock by calling +.Xr resettodr 9 . +.It +Disables interrupts. +.It +If rebooting after a crash (i.e., if +.Dv RB_DUMP +is set in +.Fa howto , +but +.Dv RB_HALT +is not), saves a system crash dump. +.It +Prints a message indicating that the system is about to be halted +or rebooted. +.It +If +.Dv RB_HALT +is set in +.Fa howto , +halts the system. +Otherwise, reboots the system. +.El +.Pp +If the system has not finished autoconfiguration, +.Fn boot +prints a message, and halts the system +(unless +.Dv RB_USERREQ +is specified, in which case the system will be halted if +.Dv RB_HALT +is given, and rebooted otherwise; see +.Xr reboot 2 +for more details). +.Sh SEE ALSO +.Xr reboot 2 , +.Xr resettodr 9 diff --git a/static/openbsd/man9/bpf_mtap.9 b/static/openbsd/man9/bpf_mtap.9 new file mode 100644 index 00000000..1e40f51b --- /dev/null +++ b/static/openbsd/man9/bpf_mtap.9 @@ -0,0 +1,306 @@ +.\" $OpenBSD: bpf_mtap.9,v 1.19 2025/03/04 01:33:42 dlg Exp $ +.\" +.\" Copyright (c) 2016 David Gwynne +.\" +.\" 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: March 4 2025 $ +.Dt BPF_MTAP 9 +.Os +.Sh NAME +.Nm bpfattach , +.Nm bpfxattach , +.Nm bpfdetach , +.Nm bpfsattach , +.Nm bpfsdetach , +.Nm bpf_filter , +.Nm bpf_mfilter , +.Nm bpf_validate , +.Nm bpf_mtap , +.Nm bpf_mtap_hdr , +.Nm bpf_mtap_af , +.Nm bpf_mtap_ether , +.Nm bpf_tap_hdr +.Nd BPF kernel API +.Sh SYNOPSIS +.In net/bpf.h +.Ft void +.Fo bpfattach +.Fa "caddr_t *bpfp" +.Fa "struct ifnet *ifp" +.Fa "u_int dlt" +.Fa "u_int hdrlen" +.Fc +.Ft void * +.Fo bpfxattach +.Fa "caddr_t *bpfp" +.Fa "const char *name" +.Fa "struct ifnet *ifp" +.Fa "u_int dlt" +.Fa "u_int hdrlen" +.Fc +.Ft void +.Fn bpfdetach "struct ifnet *ifp" +.Ft void * +.Fn bpfsattach "caddr_t *bpfp" "const char *name" "u_int dlt" "u_int hdrlen" +.Ft void +.Fn bpfsdetach "void *bpfif" +.Ft u_int +.Fo bpf_filter +.Fa "const struct bpf_insn *pc" +.Fa "const u_char *pkt" +.Fa "u_int wirelen" +.Fa "u_int pktlen" +.Fc +.Ft u_int +.Fo bpf_mfilter +.Fa "const struct bpf_insn *pc" +.Fa "const struct mbuf *m" +.Fa "u_int wirelen" +.Fc +.Ft int +.Fn bpf_validate "struct bpf_insn *pc" "int len" +.Ft int +.Fn bpf_mtap "caddr_t bpf" "const struct mbuf *m" "u_int direction" +.Ft int +.Fo bpf_mtap_hdr +.Fa "caddr_t bpf" +.Fa "const void *hdr" +.Fa "u_int hdrlen" +.Fa "const struct mbuf *m" +.Fa "u_int direction" +.Fc +.Ft int +.Fo bpf_mtap_af +.Fa "caddr_t bpf" +.Fa "u_int32_t af" +.Fa "const struct mbuf *m" +.Fa "u_int direction" +.Fc +.Ft int +.Fn bpf_mtap_ether "caddr_t bpf" "const struct mbuf *m" "u_int direction" +.Ft int +.Fo bpf_tap_hdr +.Fa "caddr_t bpf" +.Fa "const void *hdr" +.Fa "u_int hdrlen" +.Fa "const void *buf" +.Fa "u_int buflen" +.Fa "u_int direction" +.Fc +.Sh DESCRIPTION +The BPF kernel API provides functions for evaluating BPF instructions +against packets, and incoming linkage from device drivers. +A packet is parsed by the filters associated with each interface +and, if accepted, stashed into the corresponding buffer. +.Pp +.Fn bpfattach +allocates and configures a BPF interface for use with the network interface +.Fa ifp . +.Fa bpfp +is the location of BPF interface pointer that the network interface passes to +the filter functions. +The BPF interface pointer will be clear until a filter is registered and +packets can be filtered on it. +The +.Fa dlt +argument identifies the data link-layer type that the network +interface provides for this BPF interface. +.Fn bpfattach +may be called multiple times against the same network interface to +provide different data link-layer types for filtering. +.Fa hdrlen +indicates the length of the link header for the data link-layer type. +.Pp +.Fn bpfxattach +allocates and configures a BPF interface for use with the network interface +.Fa ifp , +but with a BPF interface name provided by the +.Fa name +argument instead of the name of the network interface. +The +.Fa bpfp , +.Fa dlt , +.Fa hdrlen +arguments work like those in +.Fn bpfattach . +.Pp +.Fn bpfdetach +removes and frees all the BPF interfaces that were configured for +the network interface +.Fa ifp . +.Pp +.Fn bpfsattach +allocates and configures a BPF interface for use by the subsystem +identified by +.Fa name . +The +.Fa bpfp , +.Fa dlt , +.Fa hdrlen +arguments work like those in +.Fn bpfattach . +.Pp +.Fn bpfsdetach +removes and frees the BPF interface referenced by +.Fa bpfif . +.Pp +.Fn bpf_filter +executes the BPF program referenced by +.Fa pc +against the packet buffer starting at +.Fa pkt +of +.Fa pktlen +bytes in length. +.Fa wirelen +is the length of the original packet on the wire. +.Pp +.Fn bpf_mfilter +executes the BPF program referenced by +.Fa pc +against the packet in the mbuf +.Fa m . +.Fa wirelen +is the length of the original packet on the wire. +.Pp +.Fn bpf_validate +tests if the BPF program referenced by +.Fa pc +is valid. +.Fa len +specifies the number of instructions in +.Fa pc . +.Pp +.Fn bpf_tap +runs the filters on the BPF interface referenced by +.Fa bpf +in the direction +.Fa direction +against the packet in the +.Fa pkt +buffer. +.Pp +.Fn bpf_mtap +runs the filters on the BPF interface referenced by +.Fa bpf +in the direction +.Fa direction +against the packet in mbuf chain +.Fa m . +.Pp +.Fn bpf_mtap_hdr +runs the filters on the BPF interface referenced by +.Fa bpf +in the direction +.Fa direction +against the packet in mbuf chain +.Fa m . +The header referenced by +.Fa hdr +will be prefixed to the packet during filter evaluation. +.Pp +.Fn bpf_mtap_af +runs the filters on the BPF interface referenced by +.Fa bpf +in the direction +.Fa direction +against the packet in mbuf chain +.Fa m . +The address family specified by +.Fa af +will be prepended to the packet before matching occurs. +.Pp +.Fn bpf_mtap_ether +runs the filters on the BPF interface referenced by +.Fa bpf +in the direction +.Fa direction +against an Ethernet packet in the mbuf +.Fa m . +If the mbuf is flagged with +.Dv M_VLANTAG , +an Ethernet VLAN header is constructed using +m->m_pkthdr.ether_vtag +and +m->m_pkthdr.pf.prio +before matching occurs. +.Pp +.Fn bpf_tap_hdr +runs the filters on the BPF interface referenced by +.Fa bpf +in the direction +.Fa direction +against the buffer +.Fa buf +of length +.Fa buflen . +The header +.Fa hdr +of length +.Fa hdrlen +will be prefixed to the buffer for filter evaluation. +.Sh CONTEXT +.Fn bpfattach , +.Fn bpfxattach , +.Fn bpfdetach , +.Fn bpfsattach , +and +.Fn bpfsdetach +can be called from process context. +.Pp +.Fn bpf_filter , +.Fn bpf_mfilter , +and +.Fn bpf_validate +can be called from process context, or from an interrupt context. +.Pp +.Fn bpf_mtap , +.Fn bpf_mtap_hdr , +.Fn bpf_mtap_af , +.Fn bpf_mtap_ether , +and +.Fn bpf_tap_hdr +can be called from process context, or from an interrupt context at or below +.Dv IPL_NET . +.Sh RETURN VALUES +.Fn bpfsattach +and +.Fn bpfxattach +return a reference to the BPF interface they allocate. +.Pp +.Fn bpf_filter +and +.Fn bpf_mfilter +return -1 (cast to an unsigned integer) if the filter program is +.Dv NULL , +or the result of the filter program. +Filter programs should return the maximum number of bytes of the +packet to capture, or 0 if the packet does not match the filter +program. +.Pp +.Fn bpf_validate +returns a non-zero value if the BPF program is valid, +otherwise 0. +.Pp +.Fn bpf_mtap , +.Fn bpf_mtap_hdr , +.Fn bpf_mtap_af , +.Fn bpf_mtap_ether , +and +.Fn bpf_tap_hdr +return 1 if the packet or buffer matched a filter that indicates it +should be dropped, otherwise 0. +.Sh SEE ALSO +.Xr mbuf 9 , +.Xr spl 9 diff --git a/static/openbsd/man9/buffercache.9 b/static/openbsd/man9/buffercache.9 new file mode 100644 index 00000000..1d31154b --- /dev/null +++ b/static/openbsd/man9/buffercache.9 @@ -0,0 +1,395 @@ +.\" $OpenBSD: buffercache.9,v 1.13 2019/07/19 00:24:31 cheloha Exp $ +.\" $NetBSD: buffercache.9,v 1.13 2004/06/25 15:31:37 wiz Exp $ +.\" +.\" Copyright (c)2003 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. +.\" +.\" +.\" following copyright notices are from sys/kern/vfs_bio.c. +.\" they are here because i took some comments from it. yamt@NetBSD.org +.\" +.\" +.\"/*- +.\" * Copyright (c) 1982, 1986, 1989, 1993 +.\" * The Regents of the University of California. All rights reserved. +.\" * (c) UNIX System Laboratories, Inc. +.\" * All or some portions of this file are derived from material licensed +.\" * to the University of California by American Telephone and Telegraph +.\" * Co. or Unix System Laboratories, Inc. and are reproduced herein with +.\" * the permission of UNIX System Laboratories, 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. +.\" * +.\" * @(#)vfs_bio.c 8.6 (Berkeley) 1/11/94 +.\" */ +.\" +.\"/*- +.\" * Copyright (c) 1994 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. +.\" * 3. All advertising materials mentioning features or use of this software +.\" * must display the following acknowledgement: +.\" * This product includes software developed by the University of +.\" * California, Berkeley and its contributors. +.\" * 4. 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. +.\" * +.\" * @(#)vfs_bio.c 8.6 (Berkeley) 1/11/94 +.\" */ +.\" +.\" +.\" ------------------------------------------------------------ +.Dd $Mdocdate: July 19 2019 $ +.Dt BUFFERCACHE 9 +.Os +.Sh NAME +.Nm buffercache , +.Nm bread , +.Nm bread_cluster , +.Nm breadn , +.Nm bwrite , +.Nm bawrite , +.Nm bdwrite , +.Nm getblk , +.Nm geteblk , +.Nm incore , +.Nm brelse , +.Nm biodone , +.Nm biowait +.Nd buffer cache interfaces +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/buf.h +.Ft int +.Fn bread "struct vnode *vp" "daddr_t blkno" "int size" \ +"struct buf **bpp" +.Ft int +.Fn bread_cluster "struct vnode *vp" "daddr_t blkno" "int size" \ +"struct buf **bpp" +.Ft int +.Fn breadn "struct vnode *vp" "daddr_t blkno" "int size" \ +"daddr_t rablks[]" "int rasizes[]" "int nrablks" \ +"struct buf **bpp" +.Ft int +.Fn bwrite "struct buf *bp" +.Ft void +.Fn bawrite "struct buf *bp" +.Ft void +.Fn bdwrite "struct buf *bp" +.Ft struct buf * +.Fn getblk "struct vnode *vp" "daddr_t blkno" "int size" \ +"int slpflag" "uint64_t slptimeo" +.Ft struct buf * +.Fn geteblk "size_t size" +.Ft struct buf * +.Fn incore "struct vnode *vp" "daddr_t blkno" +.Ft void +.Fn brelse "struct buf *bp" +.Ft void +.Fn biodone "struct buf *bp" +.Ft int +.Fn biowait "struct buf *bp" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Nm +interface is used by each filesystem to improve I/O performance using +in-core caches of filesystem blocks. +.Pp +The kernel memory used to cache a block is called a buffer and +described by a +.Em buf +structure. +In addition to describing a cached block, a +.Em buf +structure is also used to describe an I/O request as a part of +the disk driver interface. +.Pp +The block size used for logical block numbers depends on the type of the +given vnode. +For file vnodes, this is f_iosize of the underlying filesystem. +For block device vnodes, this will usually be DEV_BSIZE. +.\" XXX struct buf, B_ flags, MP locks, etc. +.\" XXX free list, hash queue, etc. +.\" ------------------------------------------------------------ +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn bread "vp" "blkno" "size" "bpp" +Read a block corresponding to +.Fa vp +and +.Fa blkno . +The buffer is returned via +.Fa bpp . +.Pp +If the buffer is not found (i.e. the block is not cached in memory), +.Fn bread +calls +.Fn getblk +to allocate a buffer with enough pages for +.Fa size +and reads the specified disk block into it. +.Pp +.Fn bread +always returns a buffer, even if it returns an error due to an I/O +error. +.Pp +The buffer returned by +.Fn bread +is marked as busy. +(The +.Dv B_BUSY +flag is set.) +After manipulation of the buffer returned from +.Fn bread , +the caller should unbusy it so that another thread can get it. +If the buffer contents are modified and should be written back to disk, +it should be unbusied using one of the variants of +.Fn bwrite . +Otherwise, it should be unbusied using +.Fn brelse . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Xo +.Fo breadn +.Fa "vp" +.Fa "blkno" +.Fa "size" +.Fa "rablks" +.Fa "rasizes" +.Fa "nrablks" +.Fa "bpp" +.Fc +.Xc +Get a buffer as +.Fn bread . +In addition, +.Fn breadn +will start read-ahead of blocks specified by +.Fa rablks , +.Fa rasizes , +and +.Fa nrablks . +The read-ahead blocks aren't returned, but are available in cache for +future accesses. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Xo +.Fo bread_cluster +.Fa "vp" +.Fa "blkno" +.Fa "size" +.Fa "bpp" +.Fc +.Xc +Read a block of size +.Fa "size" +corresponding to +.Fa vp +and +.Fa blkno , +with readahead. +If neither the first block nor a part of the next MAXBSIZE bytes is already +in the buffer cache, +.Fn bread_cluster +will perform a read-ahead of MAXBSIZE bytes in a single I/O operation. +This is currently more efficient than +.Fn breadn . +The read-ahead data isn't returned, but is available in cache for +future access. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn bwrite "bp" +Write a block. +Start I/O for write using +.Fn VOP_STRATEGY . +Then, unless the +.Dv B_ASYNC +flag is set in +.Fa bp , +.Fn bwrite +waits for the I/O to complete. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn bawrite "bp" +Write a block asynchronously. +Set the +.Dv B_ASYNC +flag in +.Fa bp +and simply call +.Fn VOP_BWRITE , +which results in +.Fn bwrite +for most filesystems. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn bdwrite "bp" +Delayed write. +Unlike +.Fn bawrite , +.Fn bdwrite +won't start any I/O. +It only marks the buffer as dirty +.Pq Dv B_DELWRI +and unbusies it. +This routine should be used when the buffer is expected +to be modified again soon, typically a small write that +partially fills a buffer. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn getblk "vp" "blkno" "size" "slpflag" "slptimeo" +Get a block of requested size +.Fa size +that is associated with a given vnode and block +offset, specified by +.Fa vp +and +.Fa blkno . +If it is found in the block cache, mark it as having been found, +make it busy and return it. +Otherwise, return an empty block of the correct size. +It is up to the caller to ensure that the cached blocks +are of the correct size. +.Pp +If +.Fn getblk +needs to sleep, +.Fa slpflag +and +.Fa slptimeo +are used as arguments for +.Xr tsleep_nsec 9 . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn geteblk "size" +Allocate an empty, disassociated block of a given size +.Fa size . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn incore "vp" "blkno" +Determine if a block associated with a given vnode and block offset +is in the cache. +If it is there, return a pointer to it. +Note that +.Fn incore +doesn't mark the buffer as busy unlike +.Fn getblk . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn brelse "bp" +Unlock a buffer by clearing the +.Dv B_AGE , +.Dv B_ASYNC , +.Dv B_BUSY , +.Dv B_NOCACHE , +and +.Dv B_DEFERRED +flags and release it to the free lists. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn biodone "bp" +Mark I/O complete on a buffer. +If a callback has been requested by +.Dv B_CALL , +do so. +Otherwise, wake up the waiting processes. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn biowait "bp" +Wait for operations on the buffer to complete. +When they do, extract and return the I/O's error value. +If the operation on the buffer is being done via a direct call to a +.Fn strategy +type function, then the buffer must be previously initialized with the +.Dv B_RAW +flag. +.El +.\" ------------------------------------------------------------ +.Sh CODE REFERENCES +This section describes places within the +.Ox +source tree where actual code implementing the buffer cache subsystem +can be found. +All pathnames are relative to +.Pa /usr/src . +.Pp +The buffer cache subsystem is implemented within the file +.Pa sys/kern/vfs_bio.c . +.Sh SEE ALSO +.Xr intro 9 , +.Xr vnode 9 , +.Xr VOP_STRATEGY 9 +.Rs +.%A Maurice J. Bach +.%B "The Design of the UNIX Operating System" +.%I "Prentice Hall" +.%D 1986 +.Re +.Rs +.%A Marshall Kirk McKusick +.%A Keith Bostic +.%A Michael J. Karels +.%A John S. Quarterman +.%B "The Design and Implementation of the 4.4BSD Operating System" +.%I "Addison Wesley" +.%D 1996 +.Re +.Rs +.%A Leffler, et. al. +.%B "The Design and Implementation of the 4.3 BSD Unix Operating System" +.%I Addison Wesley +.%D 1989 +.Re diff --git a/static/openbsd/man9/bufq_init.9 b/static/openbsd/man9/bufq_init.9 new file mode 100644 index 00000000..e30150b7 --- /dev/null +++ b/static/openbsd/man9/bufq_init.9 @@ -0,0 +1,145 @@ +.\" $OpenBSD: bufq_init.9,v 1.7 2025/05/17 10:13:40 jsg Exp $ +.\" +.\" Copyright (c) 2013 David Gwynne +.\" +.\" 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: May 17 2025 $ +.Dt BUFQ_INIT 9 +.Os +.Sh NAME +.Nm bufq_init , +.Nm bufq_destroy , +.Nm bufq_queue , +.Nm bufq_dequeue , +.Nm bufq_peek , +.Nm bufq_drain +.\" .Nm bufq_wait , +.\" .Nm bufq_done , +.\" .Nm bufq_quiesce , +.\" .Nm bufq_restart +.Nd buf queues +.Sh SYNOPSIS +.In sys/buf.h +.Ft int +.Fn bufq_init "struct bufq *bufq" "int type" +.Ft void +.Fn bufq_destroy "struct bufq *bufq" +.Ft void +.Fn bufq_queue "struct bufq *bufq" "struct buf *bp" +.Ft struct buf * +.Fn bufq_dequeue "struct bufq *bufq" +.Ft int +.Fn bufq_peek "struct bufq *bufq" +.Ft void +.Fn bufq_drain "struct bufq *bufq" +.Sh DESCRIPTION +The bufq API implements queueing and scheduling of I/O operations on disk +devices. +It provides multiple scheduling algorithms within the API. +.Pp +It is the responsibility of the disk device driver to provide +pre-allocated bufq structures. +.Pp +.Fn bufq_init +initialises the +.Fa bufq +structure and allocates any state required by the scheduling algorithm +by the +.Fa type +argument. +.Pp +The +.Fa type +argument to +.Fn bufq_init +can be one of the following scheduling algorithms: +.Pp +.Bl -tag -offset indent -width BUFQ_DEFAULT -compact +.It Dv BUFQ_FIFO +A simple First-In First-Out queue. +.It Dv BUFQ_NSCAN +Takes batches of "N" bufs from the queue and sorts them for optimal +head movement. +.It Dv BUFQ_DEFAULT +This currently aliases +.Dv BUFQ_NSCAN . +.El +.Pp +.Fn bufq_destroy +frees any state that was used by the scheduler. +.Pp +.Fn bufq_queue +is used to add the buf specified by +.Fa bp +to the +.Fa bufq +queue. +.Pp +.Fn bufq_dequeue +is used to get the next buf the +.Fa bufq +has scheduled to be serviced by a disk. +The buf will be removed from the queue. +.Pp +.Fn bufq_peek +allows the caller to determine if there are more bufs queued on +.Fa bufq +without modifying the list of bufs. +.Pp +.Fn bufq_drain +is a convenience function for devices that have detached. +It removes all the bufs currently queued on +.Fa bufq , +marks them as failed with an +.Er ENXIO +error, and returns them to the block layer via +.Xr biodone 9 . +.Sh CONTEXT +.Fn bufq_init +and +.Fn bufq_destroy +can be called during autoconf, or from process context. +.Pp +.Nm bufq_queue , +.Nm bufq_dequeue , +.Nm bufq_peek , +and +.Nm bufq_drain +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn bufq_init +will return 0 on success, or an error code as per +.Xr errno 2 . +.Pp +.Fn bufq_dequeue +returns the next buf that is scheduled to be serviced by the disk. +.Dv NULL +is returned if there are no bufs available on the queue. +.Pp +.Fn bufq_peek +returns 1 if there are bufs available to be scheduled on the disk, otherwise 0. +.Sh SEE ALSO +.Xr errno 2 , +.Xr autoconf 9 , +.Xr biodone 9 , +.Xr disk 9 +.Sh HISTORY +The bufq API was written by +.An Thordur I. Bjornsson +and +.An David Gwynne Aq Mt dlg@openbsd.org . +The bufq API first appeared in +.Ox 4.8 +and finally succeeded in fully replacing disksort in +.Ox 5.5 . diff --git a/static/openbsd/man9/bus_dma.9 b/static/openbsd/man9/bus_dma.9 new file mode 100644 index 00000000..c8ccd7cf --- /dev/null +++ b/static/openbsd/man9/bus_dma.9 @@ -0,0 +1,891 @@ +.\" $OpenBSD: bus_dma.9,v 1.37 2022/02/20 23:14:36 jsg Exp $ +.\" $NetBSD: bus_dma.9,v 1.14 2000/06/14 06:49:19 cgd Exp $ +.\" +.\" Copyright (c) 1996, 1997, 1998 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. +.\" +.Dd $Mdocdate: February 20 2022 $ +.Dt BUS_DMAMAP_CREATE 9 +.Os +.Sh NAME +.Nm bus_dmamap_create , +.Nm bus_dmamap_destroy , +.Nm bus_dmamap_load , +.Nm bus_dmamap_load_mbuf , +.Nm bus_dmamap_load_uio , +.Nm bus_dmamap_load_raw , +.Nm bus_dmamap_unload , +.Nm bus_dmamap_sync , +.Nm bus_dmamem_alloc , +.Nm bus_dmamem_alloc_range , +.Nm bus_dmamem_free , +.Nm bus_dmamem_map , +.Nm bus_dmamem_unmap , +.Nm bus_dmamem_mmap +.Nd bus and machine independent DMA mapping interface +.Sh SYNOPSIS +.In machine/bus.h +.Sh DESCRIPTION +The +.Nm +interface provides a bus and machine independent mechanism +for managing DMA data transfers to and from devices. +.Pp +The basic abstraction is +.Fa bus_dmamap_t , +a pointer to a structure describing an individual DMA mapping. +The structure contains an array of segments +.Pq Fa dm_segs , +and a count of segments +.Pq Fa dm_nsegs . +.Pp +Each segment in +.Fa dm_segs +describes a single physical area of memory suitable for DMA, with a starting +address +.Pq Fa ds_addr +and a length +.Pq Fa ds_len . +These are the values that must be communicated to the DMA device. +Taken together the segments exactly and completely describe the buffer +being used to transfer data. +.Pp +.Fa bus_dma_tag_t +is an opaque type. +.Fa bus_dma_tag_t +values are received from higher software layers and are never created, +changed, deleted or even examined in this interface. +.Pp +The basic cycle to transfer data to/from a DMA device is: +.Bd -literal +bus_dmamap_create(); /* get a dmamap to load/unload */ + +for each DMA xfer { + bus_dmamem_alloc(); /* allocate some DMA'able memory */ + bus_dmamem_map(); /* map it into the kernel address space */ + + /* + * Fill the allocated DMA'able memory with whatever data + * is to be sent out, using the pointer obtained with + * bus_dmamem_map(). + */ + + bus_dmamap_load(); /* initialize the segments of dmamap */ + bus_dmamap_sync(); /* synchronize/flush any DMA cache */ + + for (i = 0; i < dm_nsegs; i++) { + /* + * Tell the DMA device the physical address + * (dmamap->dm_segs[i].ds_addr) and the length + * (dmamap->dm_segs[i].ds_len) of the memory to xfer. + * + * Start the DMA, wait until it's done + */ + } + + bus_dmamap_sync(); /* synchronize/flush any DMA cache */ + bus_dmamap_unload(); /* prepare dmamap for reuse */ + + /* + * Copy any data desired from the DMA'able memory using the + * pointer created by bus_dmamem_map(). + */ + + bus_dmamem_unmap(); /* free kernel virtual address space */ + bus_dmamem_free(); /* free DMA'able memory */ +} + +bus_dmamap_destroy(); /* release any resources used by dmamap */ +.Ed +.Sh DATA TYPES +Individual implementations may name these structures whatever they wish, +providing that the external representations are: +.Bl -tag -width "bus_dma_segment_t" +.It Fa bus_addr_t +A device bus address to be used for CPU access or DMA. +.It Fa bus_size_t +The size of a bus address range. +.It Fa bus_dma_tag_t +A machine-dependent opaque type describing the implementation of DMA for +a given host/bus. +Machine-dependent code is responsible for passing these structures to a +bus's autoconfiguration machinery, which in turn passes it down to the device +drivers. +.It Fa bus_dma_segment_t +A structure describing an individual DMA segment. +The structure may have machine-dependent members and arbitrary layout, but +has at least the following members: +.Bd -literal + bus_addr_t ds_addr; + bus_size_t ds_len; +.Ed +.Pp +The values in +.Fa ds_addr +and +.Fa ds_len +are suitable for programming into a DMA controller's address and length +registers. +.It Fa bus_dmamap_t +A pointer to a structure describing an individual DMA mapping. +The structure may have machine-dependent members and arbitrary layout, but +has at least the following members: +.Bd -literal + int dm_nsegs; + bus_dma_segment_t *dm_segs; +.Ed +.Pp +The +.Fa dm_segs +member may be an array of segments or a pointer to an array of segments. +The +.Fa dm_nsegs +member indicates the number of segments in +.Fa dm_segs . +.El +.Sh DMA MAPS +.nr nS 1 +.Ft int +.Fn bus_dmamap_create "bus_dma_tag_t tag" "bus_size_t size" "int nsegments" \ + "bus_size_t maxsegsz" "bus_size_t boundary" "int flags" \ + "bus_dmamap_t *dmamp" +.Ft void +.Fn bus_dmamap_destroy "bus_dma_tag_t tag" "bus_dmamap_t dmam" +.nr nS 0 +.Pp +The +.Fn bus_dmamap_create +function allocates a DMA handle and initializes it according to the parameters +provided. +This function returns 0 on success, an error code otherwise. +.Pp +The +.Fn bus_dmamap_create +arguments are as follows: +.Bl -tag -width nsegments -compact +.It Fa tag +The +.Fa bus_dma_tag_t +passed down from the parent driver via +.Fa _attach_args . +.It Fa size +The maximum DMA transfer that can be mapped by the handle. +.It Fa nsegments +Number of segments the device can support in a single DMA transaction. +This may be the number of scatter-gather descriptors supported by the +device. +.It Fa maxsegsz +The maximum number of bytes that may be transferred by any given DMA +segment. +.It Fa boundary +Some DMA controllers are not able to transfer data that crosses a +particular boundary. +This argument allows this boundary to be specified. +The boundary lines begin at 0, and occur every +.Fa boundary +bytes. +Mappings may begin on a boundary line but may not end on or cross a +boundary line. +If no boundary condition needs to be observed, a +.Fa boundary +argument of 0 should be used. +.It Fa flags +Flags are defined as follows: +.Bl -tag -width BUS_DMA_ALLOCNOW -compact +.It Dv BUS_DMA_WAITOK +It is safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_NOWAIT +It is not safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_ALLOCNOW +Perform any resource allocation this handle may need now. +If this is not specified, the allocation may be deferred to +.Fn bus_dmamap_load . +If this flag is specified, +.Fn bus_dmamap_load +will not block on resource allocation. +.It Dv BUS_DMA_BUS[1-4] +These flags are placeholders, and may be used by buses to provide +bus-dependent functionality. +.El +.It Fa dmamp +A +.Fa bus_dmamap_t +pointer. +A DMA map will be allocated and pointed to by +.Fa dmamp +upon successful completion of this routine. +.El +.Pp +The +.Fn bus_dmamap_destroy +function frees all resources associated with a given DMA handle. +This function always succeeds if given valid arguments. +.Pp +The +.Fn bus_dmamap_destroy +arguments are as follows: +.Bl -tag -width dmam -compact +.It Fa tag +The +.Fa bus_dma_tag_t +passed down from the parent driver via +.Fa _attach_args . +.It Fa dmam +The DMA handle to destroy. +.El +.Pp +In the event that the DMA handle contains a valid mapping, the mapping +will be unloaded via the same mechanism used by +.Fn bus_dmamap_unload . +.Sh DMA MAP SEGMENTS +.nr nS 1 +.Ft int +.Fn bus_dmamap_load "bus_dma_tag_t tag" "bus_dmamap_t dmam" "void *buf" \ + "bus_size_t buflen" "struct proc *p" "int flags" +.Ft int +.Fn bus_dmamap_load_mbuf "bus_dma_tag_t tag" "bus_dmamap_t dmam" \ + "struct mbuf *chain" "int flags" +.Ft int +.Fn bus_dmamap_load_uio "bus_dma_tag_t tag" "bus_dmamap_t dmam" \ + "struct uio *uio" "int flags" +.Ft int +.Fn bus_dmamap_load_raw "bus_dma_tag_t tag" "bus_dmamap_t dmam" \ + "bus_dma_segment_t *segs" "int nsegs" \ + "bus_size_t size" "int flags" +.Ft void +.Fn bus_dmamap_unload "bus_dma_tag_t tag" "bus_dmamap_t dmam" +.nr nS 0 +.Pp +The +.Fn bus_dmamap_load +function loads a DMA handle with mappings for a DMA transfer. +It assumes that all pages involved in a DMA transfer are wired. +This function returns 0 on success, an error code otherwise. +.Pp +The +.Fn bus_dmamap_load +arguments are as follows: +.Bl -tag -width buflen -compact +.It Fa tag +The +.Fa bus_dma_tag_t +passed down from the parent driver via +.Fa _attach_args . +.It Fa dmam +The DMA handle with which to map the transfer. +.It Fa buf +The buffer to be used for the DMA transfer. +.It Fa buflen +The size of the buffer. +.It Fa p +Used to indicate the address space in which the buffer is located. +If +.Dv NULL , +the buffer is assumed to be in kernel space. +Otherwise, the buffer is assumed to be in process +.Fa p Ns 's +address space. +.It Fa flags +Flags are defined as follows: +.Bl -tag -width BUS_DMA_STREAMING -compact +.It Dv BUS_DMA_WAITOK +It is safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_NOWAIT +It is not safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_BUS[1-4] +These flags are placeholders, and may be used by buses to provide +bus-dependent functionality. +.It Dv BUS_DMA_STREAMING +By default, the +.Nm +API assumes that there is coherency between memory and the device +performing the DMA transaction. +Some platforms, however, have special hardware, such as an +.Dq I/O cache , +which may improve performance +of some types of DMA transactions, but which break the assumption +that there is coherency between memory and the device performing +the DMA transaction. +This flag allows the use of this special hardware, provided that +the device is doing sequential, unidirectional transfers which +conform to certain alignment and size constraints defined by the +platform. +If the platform does not support the feature, or if +the buffer being loaded into the DMA map does not conform to the +constraints required for use of the feature, then this flag will +be silently ignored. +Also refer to the use of this flag with the +.Fn bus_dmamem_alloc +function. +.It Dv BUS_DMA_READ +This is a hint to the machine-dependent back-end that indicates the +mapping will be used only for a +.Em "device -\*[Gt] memory" +transaction. +The back-end may perform optimizations based on this information. +.It Dv BUS_DMA_WRITE +This is a hint to the machine-dependent back-end that indicates the +mapping will be used only for a +.Em "memory -\*[Gt] device" +transaction. +The back-end may perform optimizations based on this information. +.El +.El +.Pp +As noted above, if a DMA handle is created with +.Dv BUS_DMA_ALLOCNOW , +.Fn bus_dmamap_load +will never block. +.Pp +If a call to +.Fn bus_dmamap_load +fails, the mapping in the DMA handle will be invalid. +It is the responsibility of the caller to clean up any inconsistent +device state resulting from incomplete iteration through the uio. +.Pp +The +.Fn bus_dmamap_load_mbuf +function is a variation of +.Fn bus_dmamap_load +which maps mbuf chains for DMA transfers. +Mbuf chains are assumed to be in kernel virtual address space. +.Pp +The +.Fn bus_dmamap_load_uio +function is a variation of +.Fn bus_dmamap_load +which maps buffers pointed to by +.Fa uio +for DMA transfers. +The value of +.Fa "uio->uio_segflg" +will determine if the buffers are in user or kernel virtual address +space. +If the buffers are in user address space, the buffers are assumed to be +in +.Fa "uio->uio_procp" Ns 's +address space. +.Pp +The +.Fn bus_dmamap_load_raw +function is a variation of +.Fn bus_dmamap_load +which maps buffers allocated by +.Fn bus_dmamem_alloc +(see below). +The +.Fa segs +argument is a +.Fa bus_dma_segment_t +array filled in by +.Fn bus_dmamem_alloc . +The +.Fa nsegs +argument is the number of segments in the array. +The +.Fa size +argument is the size of the DMA transfer. +.Pp +The +.Fn bus_dmamap_unload +function deletes the mappings for a given DMA handle. +This function always succeeds if given valid arguments. +Attempting to unload a map that is already unloaded is +not valid. +.Pp +The +.Fn bus_dmamap_unload +arguments are as follows: +.Bl -tag -width dmam -compact +.It Fa tag +The +.Fa bus_dma_tag_t +passed down from the parent driver via +.Fa _attach_args . +.It Fa dmam +The DMA handle containing the mappings which are to be deleted. +.El +.Pp +If the DMA handle was created with +.Dv BUS_DMA_ALLOCNOW , +.Fn bus_dmamap_unload +will not free the corresponding resources which were allocated by +.Fn bus_dmamap_create . +This is to ensure that +.Fn bus_dmamap_load +will never block on resources if the handle was created with +.Dv BUS_DMA_ALLOCNOW . +.Sh SYNCHRONIZATION +.nr nS 1 +.Ft void +.Fn bus_dmamap_sync "bus_dma_tag_t tag" "bus_dmamap_t dmam" \ + "bus_addr_t offset" "bus_size_t size" \ + "int ops" +.nr nS 0 +.Pp +The +.Fn bus_dmamap_sync +function performs pre- and post-DMA operation cache and/or buffer +synchronization. +This function always succeeds if given valid arguments. +.Pp +The +.Fn bus_dmamap_sync +arguments are as follows: +.Bl -tag -width "offset" -compact +.It Fa tag +The +.Fa bus_dma_tag_t +passed down from the parent driver via +.Fa _attach_args . +.It Fa dmam +The DMA mapping to be synchronized. +.It Fa offset +Offset in the DMA mapping to be synchronized. +.It Fa size +The size of the region to be synchronized. +.It Fa ops +One or more synchronization operations to perform. +The following DMA synchronization operations are defined: +.Bl -tag -width BUS_DMASYNC_POSTWRITE -compact +.It Dv BUS_DMASYNC_PREREAD +Perform any pre-read DMA cache and/or bounce operations. +.It Dv BUS_DMASYNC_POSTREAD +Perform any post-read DMA cache and/or bounce operations. +.It Dv BUS_DMASYNC_PREWRITE +Perform any pre-write DMA cache and/or bounce operations. +.It Dv BUS_DMASYNC_POSTWRITE +Perform any post-write DMA cache and/or bounce operations. +.El +.Pp +More than one operation may be performed in a given synchronization call. +Mixing of +.Em PRE +and +.Em POST +operations is not allowed, and behavior is undefined if this is attempted. +.El +.Pp +Synchronization operations are expressed from the perspective of the +host RAM, e.g., a +.Em "device -> memory" +operation is a +.Em READ +and a +.Em "memory -> device" +operation is a +.Em WRITE . +.Pp +.Fn bus_dmamap_sync +may consult state kept within the DMA map to determine if the memory is +mapped in a DMA coherent fashion. +If so, +.Fn bus_dmamap_sync +may elect to skip certain expensive operations, such as flushing of the +data cache. +See +.Fn bus_dmamem_map +for more information on this subject. +.Pp +On platforms which implement reordered stores, +.Fn bus_dmamap_sync +will always cause the store buffer to be flushed. +.Pp +This function exists so that multiple read and write transfers can be +performed with the same buffer, and so that drivers can explicitly +inform the +.Nm +code when their data is +.Dq ready +in its DMA buffer. +.Pp +An example of multiple read-write use of a single mapping +might look like: +.Bd -literal +bus_dmamap_load(...); + +while (not done) { + /* invalidate soon-to-be-stale cache blocks */ + bus_dmamap_sync(..., BUS_DMASYNC_PREREAD); + + [ do read DMA ] + + /* copy from bounce */ + bus_dmamap_sync(..., BUS_DMASYNC_POSTREAD); + + /* read data now in driver-provided buffer */ + + [ computation ] + + /* data to be written now in driver-provided buffer */ + + /* flush write buffers and writeback, copy to bounce */ + bus_dmamap_sync(..., BUS_DMASYNC_PREWRITE); + + [ do write DMA ] + + /* probably a no-op, but provided for consistency */ + bus_dmamap_sync(..., BUS_DMASYNC_POSTWRITE); +} + +bus_dmamap_unload(...); +.Ed +.Pp +If DMA read and write operations are not preceded and followed by the +appropriate synchronization operations, behavior is undefined. +.Sh DMA-SAFE MEMORY +.nr nS 1 +.Ft int +.Fn bus_dmamem_alloc "bus_dma_tag_t tag" "bus_size_t size" \ + "bus_size_t alignment" "bus_size_t boundary" \ + "bus_dma_segment_t *segs" "int nsegs" "int *rsegs" \ + "int flags" +.Ft int +.Fn bus_dmamem_alloc_range "bus_dma_tag_t tag" "bus_size_t size" \ + "bus_size_t alignment" "bus_size_t boundary" \ + "bus_dma_segment_t *segs" "int nsegs" "int *rsegs" \ + "int flags" "bus_addr_t low" "bus_addr_t high" +.Ft void +.Fn bus_dmamem_free "bus_dma_tag_t tag" "bus_dma_segment_t *segs" "int nsegs" +.nr nS 0 +.Pp +The +.Fn bus_dmamem_alloc +function allocates memory that is "DMA safe" for the bus corresponding to the +given tag. +This function returns 0 on success, or an error code indicating mode of +failure. +.Pp +The mapping of this memory is machine-dependent (or "opaque"); +machine-independent code should not assume that the addresses returned +are valid in kernel virtual address space, or that the addresses +returned are system physical addresses. +The address value returned as part of +.Fa segs +can thus not be used to program DMA controller address registers. +Only the values in the +.Fa dm_segs +array of a successfully loaded DMA map (using +.Fn bus_dmamap_load ) +can be used for this purpose. +.Pp +Allocations will always be rounded to the hardware page size. +Callers may wish to take advantage of this, and cluster allocation of +small data structures. +.Pp +The +.Fn bus_dmamem_alloc +arguments are as follows: +.Bl -tag -width alignment -compact +.It Fa tag +The +.Fa bus_dma_tag_t +passed down from the parent driver via +.Fa _attach_args . +.It Fa size +The amount of memory to allocate. +.It Fa alignment +Each segment in the allocated memory will be aligned to this value. +If the alignment is less than a hardware page size, it will be rounded +up to the hardware page size. +This value must be a power of two. +.It Fa boundary +Each segment in the allocated memory must not cross this boundary +(relative to zero). +This value must be a power of two. +A boundary value less than the size of the allocation is invalid. +.It Fa segs +The +.Fa bus_dma_segment_t +array, filled in as memory is allocated, +representing the opaque addresses of the memory chunks. +.It Fa nsegs +The number of segments available in +.Fa segs . +Used to specify the maximum number of segments that the allocated memory may +be divided into. +.It Fa rsegs +The number of segments used in +.Fa segs . +Used to return the actual number of segments the memory was divided into. +.It Fa flags +Flags are defined as follows: +.Bl -tag -width BUS_DMA_STREAMING -compact +.It Dv BUS_DMA_WAITOK +It is safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_NOWAIT +It is not safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_ZERO +The memory allocated should be zeroed. +.It Dv BUS_DMA_STREAMING +Adjusts, if necessary, the size, alignment, and boundary constraints +to conform to the platform-dependent requirements for the use of the +.Dv BUS_DMA_STREAMING +flag with the +.Fn bus_dmamap_load +function. +If the platform does not support the +.Dv BUS_DMA_STREAMING +feature, or if the size, alignment, and boundary constraints +would already satisfy the platform's requirements, this flag +is silently ignored. +The +.Dv BUS_DMA_STREAMING +flag will never relax the constraints specified in the call. +.It Dv BUS_DMA_BUS[1-4] +These flags are placeholders, and may be used by buses to provide +bus-dependent functionality. +.El +.El +.Pp +The +.Fn bus_dmamem_alloc_range +function is a variation of +.Fn bus_dmamem_alloc +that allows specification of the "DMA safe" bus address range +supported by the device. +The additional +.Fa low +and +.Fa high +arguments specify the lowest and highest bus address that the device +can use for DMA transfers. +This function should only be used if that address range differs from +the default address range for the bus. +.Pp +All pages allocated by +.Fn bus_dmamem_alloc +and +.Fn bus_dmamem_alloc_range +will be wired down until they are freed by +.Fn bus_dmamem_free . +.Pp +The +.Fn bus_dmamem_free +function frees memory previously allocated by +.Fn bus_dmamem_alloc +or +.Fn bus_dmamem_alloc_range , +invalidating any mapping. +This function always succeeds if given valid arguments. +.Pp +The +.Fn bus_dmamem_free +arguments are as follows: +.Bl -tag -width nsegs -compact +.It Fa tag +The +.Fa bus_dma_tag_t +passed down from the parent driver via +.Fa _attach_args . +.It Fa segs +The +.Fa bus_dma_segment_t +array filled in by +.Fn bus_dmamem_alloc . +.It Fa nsegs +The number of segments in +.Fa segs . +.El +.Sh MAPPING DMA-SAFE MEMORY +.nr nS 1 +.Ft int +.Fn bus_dmamem_map "bus_dma_tag_t tag" "bus_dma_segment_t *segs" "int nsegs" \ + "size_t size" "caddr_t *kvap" "int flags" +.Ft void +.Fn bus_dmamem_unmap "bus_dma_tag_t tag" "caddr_t kva" "size_t size" +.Ft paddr_t +.Fn bus_dmamem_mmap "bus_dma_tag_t tag" "bus_dma_segment_t *segs" \ + "int nsegs" "off_t off" "int prot" "int flags" +.nr nS 0 +.Pp +The +.Fn bus_dmamem_map +function maps memory allocated with +.Fn bus_dmamem_alloc +or +.Fn bus_dmamem_alloc_range +into kernel virtual address space. +This function returns 0 on success, an error code otherwise, and must not be +called from an interrupt context. +.Pp +The +.Fn bus_dmamem_map +arguments are as follows: +.Bl -tag -width flags -compact +.It Fa tag +The +.Fa bus_dma_tag_t +passed down from the parent driver via +.Fa _attach_args . +.It Fa segs +The +.Fa bus_dma_segment_t +array filled in by +.Fn bus_dmamem_alloc , +representing the memory regions to map. +.It Fa nsegs +The number of segments in +.Fa segs . +.It Fa size +The size of the mapping. +.It Fa kvap +Filled in to specify the kernel virtual address where the memory is +mapped. +.It Fa flags +Flags are defined as follows: +.Bl -tag -width BUS_DMA_COHERENT -compact +.It Dv BUS_DMA_WAITOK +It is safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_NOWAIT +It is not safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_BUS[1-4] +These flags are placeholders, and may be used by buses to provide +bus-dependent functionality. +.It Dv BUS_DMA_COHERENT +This flag is a +.Em hint +to machine-dependent code. +If possible, map the memory in such a way as it will be DMA coherent. +This may include mapping the pages into uncached address space or +setting the cache-inhibit bits in page table entries. +If implementation of DMA coherent mappings is impossible, this is +ignored. +.Pp +Later, when this memory is loaded into a DMA map, machine-dependent code +will take whatever steps are necessary to determine if the memory was +mapped in a DMA coherent fashion. +This may include checking if the kernel virtual address lies within +uncached address space or if the cache-inhibit bits are set in page +table entries. +If it is determined that the mapping is DMA coherent, state may be +placed into the DMA map for use by later calls to +.Fn bus_dmamap_sync . +.It Dv BUS_DMA_NOCACHE +This flag is a +.Em hint +to machine-dependent code. +If possible, map the memory uncached. +.El +.El +.Pp +The +.Fn bus_dmamem_unmap +function unmaps memory previously mapped with +.Fn bus_dmamem_map , +freeing the kernel virtual address space used by the mapping. +This function always succeeds if given valid arguments, but must not be +called from an interrupt context. +.Pp +.Fn bus_dmamem_unmap +arguments are as follows: +.Bl -tag -width size -compact +.It Fa tag +The +.Fa bus_dma_tag_t +passed down from the parent driver via +.Fa _attach_args . +.It Fa kva +The kernel virtual address of the mapped memory. +.It Fa size +The size of the mapping. +.El +.Pp +The +.Fn bus_dmamem_mmap +function provides support for user +.Xr mmap 2 Ns 'ing +of DMA-safe memory. +.Fn bus_dmamem_mmap +is to be called by a device driver's +.Fn (*d_mmap) +entry point, which is called by the device pager for each page to be mapped. +This function returns a physical address to be passed to +.Fn pmap_enter +by the device pager, or -1 on failure. +.Fn bus_dmamem_mmap +arguments are +as follows: +.Bl -tag -width nsegs -compact +.It Fa tag +The +.Fa bus_dma_tag_t +passed down from the parent driver via +.Fa _attach_args . +.It Fa segs +The +.Fa bus_dma_segment_t +array filled in by +.Fn bus_dmamem_alloc , +representing the memory to be +.Xr mmap 2 Ns 'ed . +.It Fa nsegs +The number of elements in the +.Fa segs +array. +.It Fa off +The offset of the page in DMA memory which is to be mapped. +.It Fa prot +The protection codes for the mapping. +.It Fa flags +Flags are defined as follows: +.Bl -tag -width BUS_DMA_COHERENT -compact +.It Dv BUS_DMA_WAITOK +It is safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_NOWAIT +It is not safe to wait (sleep) for resources during this call. +.It Dv BUS_DMA_BUS[1-4] +These flags are placeholders, and may be used by buses to provide +bus-dependent functionality. +.It Dv BUS_DMA_COHERENT +See +.Fn bus_dmamem_map +above for a description of this flag. +.It Dv BUS_DMA_NOCACHE +See +.Fn bus_dmamem_map +above for a description of this flag. +.El +.El +.Sh SEE ALSO +.Xr bus_space 9 +.Sh HISTORY +The +.Nm +interface appeared in +.Nx 1.3 . +.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 Chris Demetriou, Charles Hannum, Ross Harvey, +Matthew Jacob, Jonathan Stone, and Matt Thomas. diff --git a/static/openbsd/man9/bus_space.9 b/static/openbsd/man9/bus_space.9 new file mode 100644 index 00000000..58acb832 --- /dev/null +++ b/static/openbsd/man9/bus_space.9 @@ -0,0 +1,1520 @@ +.\" $OpenBSD: bus_space.9,v 1.32 2022/02/06 00:29:03 jsg Exp $ +.\" $NetBSD: bus_space.9,v 1.15 2000/08/09 03:11:00 tv Exp $ +.\" +.\" 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 $Mdocdate: February 6 2022 $ +.Dt BUS_SPACE 9 +.Os +.Sh NAME +.Nm bus_space , +.Nm bus_space_alloc , +.Nm bus_space_barrier , +.Nm bus_space_copy_1 , +.Nm bus_space_copy_2 , +.Nm bus_space_copy_4 , +.Nm bus_space_copy_8 , +.Nm bus_space_free , +.Nm bus_space_map , +.Nm bus_space_mmap , +.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_raw_multi_1 , +.Nm bus_space_read_raw_multi_2 , +.Nm bus_space_read_raw_multi_4 , +.Nm bus_space_read_raw_multi_8 , +.Nm bus_space_read_raw_2 , +.Nm bus_space_read_raw_4 , +.Nm bus_space_read_raw_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_raw_region_1 , +.Nm bus_space_read_raw_region_2 , +.Nm bus_space_read_raw_region_4 , +.Nm bus_space_read_raw_region_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_region_1 , +.Nm bus_space_set_region_2 , +.Nm bus_space_set_region_4 , +.Nm bus_space_set_region_8 , +.Nm bus_space_subregion , +.Nm bus_space_unmap , +.Nm bus_space_vaddr , +.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_raw_multi_1 , +.Nm bus_space_write_raw_2 , +.Nm bus_space_write_raw_4 , +.Nm bus_space_write_raw_8 , +.Nm bus_space_write_raw_multi_2 , +.Nm bus_space_write_raw_multi_4 , +.Nm bus_space_write_raw_multi_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_raw_region_1 , +.Nm bus_space_write_raw_region_2 , +.Nm bus_space_write_raw_region_4 , +.Nm bus_space_write_raw_region_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 +.Fn bus_space_map "bus_space_tag_t space" "bus_addr_t address" \ +"bus_size_t size" "int flags" "bus_space_handle_t *handlep" +.Ft void +.Fn bus_space_unmap "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t size" +.Ft int +.Fn bus_space_subregion "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "bus_size_t size" "bus_space_handle_t *nhandlep" +.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 +.Fn bus_space_free "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t size" +.Ft void * +.Fn bus_space_vaddr "bus_space_tag_t space" "bus_space_handle_t handle" +.Ft paddr_t +.Fn bus_space_mmap "bus_space_tag_t space" "bus_addr_t addr" "off_t off" \ +"int prot" "int flags" +.Ft u_int8_t +.Fn bus_space_read_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" +.Ft u_int16_t +.Fn bus_space_read_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" +.Ft u_int32_t +.Fn bus_space_read_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" +.Ft u_int64_t +.Fn bus_space_read_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" +.Ft u_int16_t +.Fn bus_space_read_raw_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" +.Ft u_int32_t +.Fn bus_space_read_raw_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" +.Ft u_int64_t +.Fn bus_space_read_raw_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" +.Ft void +.Fn bus_space_write_1 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "u_int8_t value" +.Ft void +.Fn bus_space_write_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "u_int16_t value" +.Ft void +.Fn bus_space_write_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "u_int32_t value" +.Ft void +.Fn bus_space_write_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "u_int64_t value" +.Ft void +.Fn bus_space_write_raw_2 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "u_int16_t value" +.Ft void +.Fn bus_space_write_raw_4 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "u_int32_t value" +.Ft void +.Fn bus_space_write_raw_8 "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "u_int64_t value" +.Ft void +.Fn bus_space_barrier "bus_space_tag_t space" "bus_space_handle_t handle" \ +"bus_size_t offset" "bus_size_t length" "int flags" +.Ft void +.Fn bus_space_read_region_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_region_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_region_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_region_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap" \ +"bus_size_t count" +.\".Ft void +.\".Fn bus_space_read_raw_region_1 "bus_space_tag_t space" \ +.\""bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" \ +.\""bus_size_t count" +.Ft void +.Fn bus_space_read_raw_region_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_raw_region_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_raw_region_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_region_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_region_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int16_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_region_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int32_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_region_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int64_t *datap" \ +"bus_size_t count" +.\".Ft void +.\".Fn bus_space_write_raw_region_1 "bus_space_tag_t space" \ +.\""bus_space_handle_t handle" "bus_size_t offset" "const u_int8_t *datap" \ +.\""bus_size_t count" +.Ft void +.Fn bus_space_write_raw_region_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_raw_region_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_write_raw_region_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_copy_1 "bus_space_tag_t space" \ +"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ +"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Ft void +.Fn bus_space_copy_2 "bus_space_tag_t space" \ +"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ +"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Ft void +.Fn bus_space_copy_4 "bus_space_tag_t space" \ +"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ +"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Ft void +.Fn bus_space_copy_8 "bus_space_tag_t space" \ +"bus_space_handle_t srchandle" "bus_size_t srcoffset" \ +"bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Ft void +.Fn bus_space_set_multi_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int8_t value" \ +"bus_size_t count" +.Ft void +.Fn bus_space_set_multi_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int16_t value" \ +"bus_size_t count" +.Ft void +.Fn bus_space_set_multi_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int32_t value" \ +"bus_size_t count" +.Ft void +.Fn bus_space_set_multi_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int64_t value" \ +"bus_size_t count" +.Ft void +.Fn bus_space_set_region_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int8_t value" \ +"bus_size_t count" +.Ft void +.Fn bus_space_set_region_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int16_t value" \ +"bus_size_t count" +.Ft void +.Fn bus_space_set_region_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int32_t value" \ +"bus_size_t count" +.Ft void +.Fn bus_space_set_region_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int64_t value" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_multi_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_multi_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int16_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_multi_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int32_t *datap" \ +"bus_size_t count" +.Ft void +.Fn bus_space_read_multi_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int64_t *datap" \ +"bus_size_t count" +.\".Ft void +.\".Fn bus_space_read_raw_multi_1 "bus_space_tag_t space" \ +.\""bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" \ +.\""bus_size_t size" +.Ft void +.Fn bus_space_read_raw_multi_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" \ +"bus_size_t size" +.Ft void +.Fn bus_space_read_raw_multi_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" \ +"bus_size_t size" +.Ft void +.Fn bus_space_read_raw_multi_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "u_int8_t *datap" \ +"bus_size_t size" +.Ft void +.Fn bus_space_write_multi_1 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int8_t *datap" \ +"bus_size_t size" +.Ft void +.Fn bus_space_write_multi_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int16_t *datap" \ +"bus_size_t size" +.Ft void +.Fn bus_space_write_multi_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int32_t *datap" \ +"bus_size_t size" +.Ft void +.Fn bus_space_write_multi_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int64_t *datap" \ +"bus_size_t size" +.\".Ft void +.\".Fn bus_space_write_raw_multi_1 "bus_space_tag_t space" \ +.\""bus_space_handle_t handle" "bus_size_t offset" "const u_int8_t *datap" \ +.\""bus_size_t size" +.Ft void +.Fn bus_space_write_raw_multi_2 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int8_t *datap" \ +"bus_size_t size" +.Ft void +.Fn bus_space_write_raw_multi_4 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int8_t *datap" \ +"bus_size_t size" +.Ft void +.Fn bus_space_write_raw_multi_8 "bus_space_tag_t space" \ +"bus_space_handle_t handle" "bus_size_t offset" "const u_int8_t *datap" \ +"bus_size_t size" +.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 or by some other +means) or may cause improper operation which is not immediately fatal. +Functions which return void or which return data read from bus space +(i.e. functions which don't 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. +.Pp +.Bl -ohang -compact +.It Fa bus_addr_t +.Pp +The +.Fa 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. +.Pp +.It Fa bus_size_t +.Pp +The +.Fa 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. +.Pp +.It Fa bus_space_tag_t +.Pp +The +.Fa 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're operating. +.Pp +.It Fa bus_space_handle_t +.Pp +The +.Fa 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. +.El +.Sh MAPPING AND UNMAPPING BUS SPACE +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. +.Pp +.Bl -ohang -compact +.It Fn bus_space_map "space" "address" "size" "flags" "handlep" +.Pp +The +.Fn bus_space_map +function maps the region of bus space named by the +.Fa space , +.Fa 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 BUS_SPACE_MAP_CACHEABLE -offset indent +.It Dv BUS_SPACE_MAP_CACHEABLE +Try to map the space so that access can be cached by the system cache. +If this flag is not specified, the implementation should map the space +so that it will not be cached. +This mapping method will only be useful in very rare occasions. +.Pp +This flag must have a value of 1 on all implementations for backward +compatibility. +.It Dv BUS_SPACE_MAP_PREFETCHABLE +Try to map the space so that accesses can be prefetched by the system, +and writes can be buffered. +This means, accesses should be side effect free (idempotent). +The +.Fn bus_space_barrier +methods will flush the write buffer or force actual read accesses. +If this flag is not specified, the +implementation should map the space so that it will not be prefetched +or delayed. +.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). +The +.Fn bus_space_vaddr +method can be used to obtain the kernel virtual address of the mapped range. +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. +Use of this mapping method is not encouraged for normal device access; +where linear access is not essential, use of the +.Fn bus_space_read/write +methods is strongly recommended. +.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_PREFETCHABLE +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' "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-prefetchable mapping when the system can only provide a prefetchable 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 VME, and for spaces which coexist with +those spaces (e.g. EISA and PCI memory and I/O spaces coexisting 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. +.Pp +.It Fn bus_space_unmap "space" "handle" "size" +.Pp +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. +.Pp +.It Fn bus_space_subregion "space" "handle" "offset" "size" "nhandlep" +.Pp +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. +.Pp +.It Fn bus_space_vaddr "tag" "handle" +.Pp +This method returns the kernel virtual address of a mapped bus space if and +only if it was mapped with the +.Dv BUS_SPACE_MAP_LINEAR +flag. +The range can be accessed by normal (volatile) pointer dereferences. +If mapped with the +.Dv BUS_SPACE_MAP_PREFETCHABLE +flag, the +.Fn bus_space_barrier +method must be used to force a particular access order. +.Pp +.It Fn bus_space_mmap "tag" "addr" "off" "prot" "flags" +.Pp +This method is used to provide support for memory mapping bus space +into user applications. +If an address space is addressable via volatile pointer dereferences, +.Fn bus_space_mmap +will return the physical address (possibly encoded as a machine-dependent +cookie) of the bus space indicated by +.Fa addr +and +.Fa off . +.Fa addr +is the base address of the device or device region, and +.Fa off +is the offset into that region that is being requested. +If the region cannot be mapped (either the address does not exist, +or the constraints cannot be met), +.Fn bus_space_mmap +returns \-1 to indicate failure. +.Pp +Note that it is not necessary that the region being requested by a +.Fn bus_space_mmap +call be mapped into a +.Fa bus_space_handle_t . +.Pp +.Fn bus_space_mmap +is called once per +.Dv PAGE_SIZE +page in the range. +The +.Fa prot +argument indicates the memory protection requested by the user application +for the range. +.El +.Sh ALLOCATING AND FREEING BUS SPACE +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. +.Pp +.Bl -ohang -compact +.It Xo +.Fo bus_space_alloc +.Fa "space" "reg_start" "reg_end" "size" +.Fa "alignment" "boundary" "flags" "addrp" "handlep" +.Fc +.Xc +.Pp +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 , +.Fa reg_end , +.Fa 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 +.Po +for example, +.Fa size +greater than +.Fa boundary +.Pc . +.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 . +.Pp +.It Fn bus_space_free "space" "handle" "size" +.Pp +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. +.El +.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. +.Pp +.Bl -ohang -compact +.It Fn bus_space_read_1 "space" "handle" "offset" +.It Fn bus_space_read_2 "space" "handle" "offset" +.It Fn bus_space_read_4 "space" "handle" "offset" +.It Fn bus_space_read_8 "space" "handle" "offset" +.Pp +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. +.Pp +.It Fn bus_space_write_1 "space" "handle" "offset" "value" +.It Fn bus_space_write_2 "space" "handle" "offset" "value" +.It Fn bus_space_write_4 "space" "handle" "offset" "value" +.It Fn bus_space_write_8 "space" "handle" "offset" "value" +.Pp +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. +.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. +.Pp +.Bl -ohang -compact +.It Fn bus_space_barrier "space" "handle" "offset" "length" "flags" +.Pp +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 BUS_SPACE_BARRIER_WRITE -offset indent +.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. +.El +.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_N +family of functions and the +.Fn bus_space_set_region_N +family of functions allow drivers to perform these operations. +.Pp +.Bl -ohang -compact +.It Fn bus_space_read_region_1 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_region_2 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_region_4 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_region_8 "space" "handle" "offset" "datap" "count" +.Pp +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. +.Pp +.It Fn bus_space_write_region_1 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_region_2 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_region_4 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_region_8 "space" "handle" "offset" "datap" "count" +.Pp +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. +.Pp +.It Fn bus_space_copy_1 "space" "srchandle" "srcoffset" "dsthandle" \ +"dstoffset" "count" +.It Fn bus_space_copy_2 "space" "srchandle" "srcoffset" "dsthandle" \ +"dstoffset" "count" +.It Fn bus_space_copy_4 "space" "srchandle" "srcoffset" "dsthandle" \ +"dstoffset" "count" +.It Fn bus_space_copy_8 "space" "srchandle" "srcoffset" "dsthandle" \ +"dstoffset" "count" +.Pp +The +.Fn bus_space_copy_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 +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_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_N +functions. +.Pp +Overlapping copies between different subregions of a single region of +bus space are handled correctly by the +.Fn bus_space_copy_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. +.Pp +.It Fn bus_space_set_region_1 "space" "handle" "offset" "value" "count" +.It Fn bus_space_set_region_2 "space" "handle" "offset" "value" "count" +.It Fn bus_space_set_region_4 "space" "handle" "offset" "value" "count" +.It Fn bus_space_set_region_8 "space" "handle" "offset" "value" "count" +.Pp +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. +.El +.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_write_multi_N , +and +.Fn bus_space_set_multi_N +families of functions are provided. +.Pp +.Bl -ohang -compact +.It Fn bus_space_read_multi_1 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_multi_2 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_multi_4 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_read_multi_8 "space" "handle" "offset" "datap" "count" +.Pp +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. +.Pp +.It Fn bus_space_write_multi_1 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_multi_2 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_multi_4 "space" "handle" "offset" "datap" "count" +.It Fn bus_space_write_multi_8 "space" "handle" "offset" "datap" "count" +.Pp +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. +.Pp +.It Fn bus_space_set_multi_1 "space" "handle" "offset" "value" "count" +.It Fn bus_space_set_multi_2 "space" "handle" "offset" "value" "count" +.It Fn bus_space_set_multi_4 "space" "handle" "offset" "value" "count" +.It Fn bus_space_set_multi_8 "space" "handle" "offset" "value" "count" +.Pp +The +.Fn bus_space_set_multi_N +family of functions writes the 1, 2, 4, or 8 byte value +.Fa value +into bus space +.Fa count +times at byte offset +.Fa offset +in 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 address specified by +.Fa handle +plus the offset should be a multiple of the size of the data value being +written. +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. +.El +.Sh RAW 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 untranslated access. +Access to these types of memory regions should be with the following functions. +.Pp +.Bl -ohang -compact +.It Fn bus_space_read_raw_2 "space" "handle" "offset" +.It Fn bus_space_read_raw_4 "space" "handle" "offset" +.It Fn bus_space_read_raw_8 "space" "handle" "offset" +.It Fn bus_space_write_raw_2 "space" "handle" "offset" "value" +.It Fn bus_space_write_raw_4 "space" "handle" "offset" "value" +.It Fn bus_space_write_raw_8 "space" "handle" "offset" "value" +.El +.Pp +The +.Fn bus_space_{read,write}_raw_N +functions take the same arguments and return the same types as their +non-raw counterparts, but do not do any translation of the values. +.Pp +.Bl -ohang -compact +.\".It Fn bus_space_read_stream_1 "space" "handle" "offset" +.\".It Fn bus_space_read_stream_2 "space" "handle" "offset" +.\".It Fn bus_space_read_stream_4 "space" "handle" "offset" +.\".It Fn bus_space_read_stream_8 "space" "handle" "offset" +.\".It Fn bus_space_read_raw_multi_1 "space" "handle" "offset" "datap" "size" +.It Fn bus_space_read_raw_multi_2 "space" "handle" "offset" "datap" "size" +.It Fn bus_space_read_raw_multi_4 "space" "handle" "offset" "datap" "size" +.It Fn bus_space_read_raw_multi_8 "space" "handle" "offset" "datap" "size" +.\".It Fn bus_space_read_raw_region_1 "space" "handle" "offset" "datap" "size" +.It Fn bus_space_read_raw_region_2 "space" "handle" "offset" "datap" "size" +.It Fn bus_space_read_raw_region_4 "space" "handle" "offset" "datap" "size" +.It Fn bus_space_read_raw_region_8 "space" "handle" "offset" "datap" "size" +.\".It Fn bus_space_write_stream_1 "space" "handle" "offset" "value" +.\".It Fn bus_space_write_stream_2 "space" "handle" "offset" "value" +.\".It Fn bus_space_write_stream_4 "space" "handle" "offset" "value" +.\".It Fn bus_space_write_stream_8 "space" "handle" "offset" "value" +.\".It Fn bus_space_write_raw_multi_1 "space" "handle" "offset" "datap" "size" +.It Fn bus_space_write_raw_multi_2 "space" "handle" "offset" "datap" "size" +.It Fn bus_space_write_raw_multi_4 "space" "handle" "offset" "datap" "size" +.It Fn bus_space_write_raw_multi_8 "space" "handle" "offset" "datap" "size" +.\".It Fn bus_space_write_raw_region_1 "space" "handle" "offset" "datap" "size" +.It Fn bus_space_write_raw_region_2 "space" "handle" "offset" "datap" "size" +.It Fn bus_space_write_raw_region_4 "space" "handle" "offset" "datap" "size" +.It Fn bus_space_write_raw_region_8 "space" "handle" "offset" "datap" "size" +.El +.Pp +These functions, unlike their non-raw counterparts, all take a +u_int8_t pointer for the +.Fa datap +argument and a byte count for the +.Fa size +argument regardless of the access width being requested. +.Pp +.Fa datap +must reference a buffer that is correctly aligned for the +access width being requested or the results are undefined. +.Pp +.Fa size +must be a multiple of the access width or the results are undefined. +.Pp +In all other respects these functions are the same as their non-raw +counterparts. +Consult the documentation for those functions for further +information. +.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 +.Ox +development team added the *_raw_* API, and discarded the *_stream_* +API. +.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 Chris Demetriou +wrote this manual page. +.Pp +.An Niklas Hallqvist +did the *_raw_* API for +.Ox . diff --git a/static/openbsd/man9/clockintr.9 b/static/openbsd/man9/clockintr.9 new file mode 100644 index 00000000..a2486aa6 --- /dev/null +++ b/static/openbsd/man9/clockintr.9 @@ -0,0 +1,333 @@ +.\" $OpenBSD: clockintr.9,v 1.3 2022/11/10 23:57:31 jsg Exp $ +.\" +.\" Copyright (c) 2020-2022 Scott Cheloha +.\" +.\" 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: November 10 2022 $ +.Dt CLOCKINTR 9 +.Os +.Sh NAME +.Nm clockintr_init , +.Nm clockintr_cpu_init , +.Nm clockintr_dispatch , +.Nm clockintr_setstatclockrate , +.Nm clockintr_trigger +.Nd clock interrupt scheduler +.Sh SYNOPSIS +.In sys/clockintr.h +.Ft void +.Fo clockintr_init +.Fa "u_int flags" +.Fc +.Ft void +.Fo clockintr_cpu_init +.Fa "struct intrclock *ic" +.Fc +.Ft int +.Fo clockintr_dispatch +.Fa "void *frame" +.Fc +.Ft void +.Fo clockintr_setstatclockrate +.Fa "int freq" +.Fc +.Ft void +.Fo clockintr_trigger +.Fa "void" +.Fc +.In sys/kernel.h +.Vt extern int hz; +.Vt extern int stathz; +.Vt extern int profhz; +.In sys/sched.h +.Vt extern int schedhz; +.Sh DESCRIPTION +The +.Nm +subsystem maintains a schedule of events, +dispatches expired events, +and rearms the local interrupt clock for each CPU in the system. +.Pp +The +.Fn clockintr_init +function initializes the subsystem as follows: +.Bl -dash +.It +.Xr hardclock 9 +is configured to run +.Xr hz 9 +times per second on each CPU. +It is an error if +.Vt hz +is less than one or greater than one billion. +.It +.Fn statclock +is configured to run +.Vt stathz +times per second on each CPU. +It is an error if +.Vt stathz +is less than one or greater than one billion. +.It +When appropriate, +.Fn statclock +will be reconfigured to run +.Vt profhz +times per second on each CPU. +.Vt profhz +must be a non-zero integer multiple of +.Vt stathz . +It is an error if +.Vt profhz +is less than +.Vt stathz +or greater than one billion. +.It +If +.Vt schedhz +is non-zero, +.Fn schedclock +is configured to run +.Vt schedhz +times per second on each CPU. +It is an error if +.Vt schedhz +is less than zero or greater than one billion. +.El +.Pp +The event schedule has a resolution of one nanosecond and event periods are +computed using integer division. +If +.Vt hz , +.Vt stathz , +.Vt profhz , +or +.Vt schedhz +do not divide evenly into one billion, +the corresponding event will not be dispatched at the specified frequency. +.Pp +The +.Fn clockintr_init +function accepts the bitwise OR of zero or more of the following +.Fa flags : +.Bl -tag -width CL_RNDSTAT +.It Dv CL_RNDSTAT +Randomize the +.Fn statclock . +Instead of using a fixed period, +the subsystem will select pseudorandom intervals in a range such that +the average +.Fn statclock +period is equal to the inverse of +.Vt stathz . +.El +.Pp +The +.Fn clockintr_init +function must be called exactly once and only by the primary CPU. +It should be called after all timecounters are installed with +.Xr tc_init 9 . +.Pp +The +.Fn clockintr_cpu_init +function prepares the calling CPU for +.Fn clockintr_dispatch . +The first time it is called on a given CPU, +if +.Fa ic +is not +.Dv NULL , +the caller is configured to use the given +.Fa intrclock +during +.Fn clockintr_dispatch ; +otherwise the caller is responsible for rearming its own interrupt +clock after each +.Fn clockintr_dispatch . +Subsequent calls ignore +.Fa ic : +instead, +the caller's event schedule is advanced past any expired events +without dispatching those events. +It is an error to call this function before the subsystem is initialized with +.Fn clockintr_init . +All CPUs should call +.Fn clockintr_cpu_init +during each system resume after the system time is updated with +.Xr inittodr 9 , +otherwise they will needlessly dispatch every event that expired while +the system was suspended. +.Pp +The +.Fn clockintr_dispatch +function executes all expired events on the caller's event schedule and, +if configured, +rearms the caller's interrupt clock to fire when the next event is scheduled +to expire. +The +.Fa frame +argument must point to the caller's +.Dv clockframe +struct. +The +.Fn clockintr_dispatch +function should only be called from a clock interrupt handler at +.Dv IPL_CLOCK +.Pq see Xr spl 9 . +It is an error to call this function on a given CPU before +.Fn clockintr_cpu_init . +.Pp +The +.Fn clockintr_setstatclockrate +function changes the effective dispatch frequency for +.Fn statclock +to +.Fa freq . +It should be called from the machine-dependent +.Fn setstatclockrate +function after performing any needed hardware reconfiguration. +It is an error if +.Fa freq +is not equal to +.Vt stathz +or +.Vt profhz . +It is an error to call this function before the subsystem is initialized with +.Fn clockintr_init . +.Pp +The +.Fn clockintr_trigger +function causes the +.Fn clockintr_dispatch +function to run in the appropriate context as soon as possible if +the caller was configured with an +.Fa intrclock +when +.Fn clockintr_cpu_init +was first called. +If the caller was not configured with an +.Fa intrclock , +the function does nothing. +It is an error to call this function on a given CPU before +.Fn clockintr_cpu_init . +.Pp +The +.Fa ic +argument to +.Fn clockintr_cpu_init +points to an +.Fa intrclock +structure: +.Bd -literal -offset indent +struct intrclock { + void *ic_cookie; + void (*ic_rearm)(void *cookie, uint64_t nsecs); + void (*ic_trigger)(void *cookie); +}; +.Ed +.Pp +The +.Fa intrclock +structure provides the +.Nm +subsystem with a uniform interface for manipulating an interrupt clock. +It has the following members: +.Bl -tag -width XXXXXXXXXX +.It Fa ic_cookie +May point to any resources needed during +.Fa ic_rearm +or +.Fa ic_trigger +to arm the underlying interrupt clock +.Pq see below . +.It Fa ic_rearm +Should cause +.Fn clockintr_dispatch +to run on the calling CPU in the appropriate context after at least +.Fa nsecs +nanoseconds have elapsed. +The first argument, +.Fa cookie , +is the +.Fa ic_cookie +member of the parent structure. +The second argument, +.Fa nsecs , +is a non-zero count of nanoseconds. +.It Fa ic_trigger +Should cause +.Fn clockintr_dispatch +to run on the calling CPU in the appropriate context as soon as possible. +The first argument, +.Fa cookie , +is the +.Fa ic_cookie +member of the parent structure. +.El +.Sh CONTEXT +The +.Fn clockintr_init , +.Fn clockintr_cpu_init , +and +.Fn clockintr_trigger +functions may be called during autoconf. +.Pp +The +.Fn clockintr_dispatch +function may be called from interrupt context at +.Dv IPL_CLOCK . +.Pp +The +.Fn clockintr_setstatclockrate +function may be called during autoconf, +from process context, +or from interrupt context. +.Sh RETURN VALUES +The +.Fn clockintr_dispatch +function returns non-zero if at least one event was dispatched, +otherwise it returns zero. +.Sh CODE REFERENCES +.Pa sys/kern/kern_clockintr.c +.Sh SEE ALSO +.Xr hardclock 9 , +.Xr hz 9 , +.Xr inittodr 9 , +.Xr nanouptime 9 , +.Xr spl 9 , +.Xr tc_init 9 , +.Xr timeout 9 +.Rs +.%A Steven McCanne +.%A Chris Torek +.%T A Randomized Sampling Clock for CPU Utilization Estimation and Code Profiling +.%B \&In Proc. Winter 1993 USENIX Conference +.%D 1993 +.%P pp. 387\(en394 +.%I USENIX Association +.Re +.Rs +.%A Richard McDougall +.%A Jim Mauro +.%B Solaris Internals: Solaris 10 and OpenSolaris Kernel Architecture +.%I Prentice Hall +.%I Sun Microsystems Press +.%D 2nd Edition, 2007 +.%P pp. 912\(en925 +.Re +.Sh HISTORY +The +.Nm +subsystem first appeared in +.Ox 7.3 . diff --git a/static/openbsd/man9/clockintr_bind.9 b/static/openbsd/man9/clockintr_bind.9 new file mode 100644 index 00000000..38b89fbd --- /dev/null +++ b/static/openbsd/man9/clockintr_bind.9 @@ -0,0 +1,296 @@ +.\" $OpenBSD: clockintr_bind.9,v 1.1 2024/02/24 16:21:32 cheloha Exp $ +.\" +.\" Copyright (c) 2023-2024 Scott Cheloha +.\" +.\" 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: February 24 2024 $ +.Dt CLOCKINTR_BIND 9 +.Os +.Sh NAME +.Nm clockintr_bind , +.Nm clockintr_schedule , +.Nm clockintr_advance , +.Nm clockintr_cancel , +.Nm clockintr_unbind , +.Nm clockintr_stagger , +.Nm clockrequest_advance +.Nd execute a function in a clock interrupt context +.Sh SYNOPSIS +.In sys/clockintr.h +.Ft void +.Fo clockintr_bind +.Fa "struct clockintr *cl" +.Fa "struct cpu_info *cpu" +.Fa "void (*callback)(struct clockrequest *cr, void *cf, void *arg)" +.Fa "void *arg" +.Fc +.Ft void +.Fo clockintr_schedule +.Fa "struct clockintr *cl" +.Fa "uint64_t abs" +.Fc +.Ft uint64_t +.Fo clockintr_advance +.Fa "struct clockintr *cl" +.Fa "uint64_t interval" +.Fc +.Ft void +.Fo clockintr_cancel +.Fa "struct clockintr *cl" +.Fc +.Ft void +.Fo clockintr_unbind +.Fa "struct clockintr *cl" +.Fa "uint32_t flags" +.Fc +.Ft void +.Fo clockintr_stagger +.Fa "struct clockintr *cl" +.Fa "uint64_t interval" +.Fa "uint32_t numer" +.Fa "uint32_t denom" +.Fc +.Ft uint64_t +.Fo clockrequest_advance +.Fa "struct clockrequest *cr" +.Fa "uint64_t interval" +.Fc +.\" .Fn clockrequest_advance_random is intentionally undocumented. +.\" It may be removed in the future. New code should not use it. +.Sh DESCRIPTION +The clock interrupt subsystem schedules functions for asynchronous execution +from the clock interrupt context on a particular CPU. +.Pp +Clock interrupts are well-suited for timekeeping, +scheduling, +and statistical profiling. +Applications with more relaxed latency requirements should use timeouts +to schedule asynchronous execution; +see +.Xr timeout_add 9 +for details. +.Pp +The +.Fn clockintr_bind +function initializes the clock interrupt object +.Fa cl . +When +.Fa cl +expires, +its +.Fa callback +function is executed from the +.Dv IPL_CLOCK +context on its host +.Fa cpu +without any locks or mutexes. +The callback function must not block. +Its parameters are as follows: +.Bl -tag -width indent +.It Fa cr +A private +.Vt clockrequest +object. +May be used to request rescheduling; +see +.Fn clockrequest_advance +below. +.It Fa cf +The +.Fa cpu Ns 's +current machine-dependent clockframe. +.It Fa arg +The +.Fa arg +given to +.Fn clockintr_bind . +.El +.Pp +The memory pointed to by +.Fa cl +must be zeroed before it is first bound. +It is an error to use +.Fa cl +as argument to any other function in the +.Vt clockintr +API before it is bound. +It is an error to rebind +.Fa cl +without first unbinding it; +see +.Fn clockintr_unbind +below. +.Pp +The +.Fn clockintr_schedule +function schedules +.Fa cl +to expire at the absolute time +.Fa abs +on the system uptime clock. +The subsystem will never execute +.Fa cl Ns 's +callback function before this expiration time, +though its execution may be delayed by other activity on the system. +.Pp +The +.Fn clockintr_advance +function schedules +.Fa cl +to expire at the next terminus of the given +.Fa interval , +a non-zero count of nanoseconds, +relative to +.Fa cl Ns 's +current expiration time. +Periodic clock interrupts should be scheduled with +.Fn clockintr_advance +to keep the execution period from drifting. +.Pp +The +.Fn clockintr_cancel +function cancels any pending expiration of +.Fa cl . +.Pp +The +.Fn clockintr_unbind +function cancels any pending expiration of +.Fa cl +and severs the binding between +.Fa cl +and its host +.Fa cpu . +Upon return, +.Fa cl +may be rebound with +.Fn clockintr_bind . +The call may be configured with zero or more of the following +.Fa flags : +.Bl -tag -width CL_BARRIER +.It Dv CL_BARRIER +If +.Fa cl Ns 's +callback function is executing, +block until it returns. +By default, +the caller does not block. +Useful when +.Fa arg +is a shared reference. +.El +.Pp +The +.Fn clockintr_stagger +function resets +.Fa cl Ns 's +expiration time to a fraction of the given +.Fa interval , +a count of nanoseconds. +Specifically, +.Fa cl Ns 's +expiration time is reset to +.Pq Fa interval Ms / Fa denom Ms * Fa numer . +Periodic clock interrupts bound to multiple CPUs may be staggered +to reduce the likelihood that their callback functions will execute +simultaneously and compete for a shared resource. +It is an error if +.Fa numer +is greater than or equal to +.Fa denom . +It is an error if +.Fa cl +is already scheduled to expire. +.Pp +The +.Fn clockrequest_advance +function is similar to +.Fn clockintr_advance , +except that +(a) it may only be called during the execution of a +.Fa callback +function, +(b) it accepts a +.Vt clockrequest +pointer as argument, +and (c) scheduling requests submitted with the interface are not fulfilled +until the callback function returns. +When the callback function returns, +scheduling requests are only committed to the underlying clock interrupt +object if that object was not manipulated during the execution of the +callback function. +Otherwise, +outstanding requests are discarded. +.Sh CONTEXT +The +.Fn clockintr_bind +function may only be called from process context. +.Pp +The +.Fn clockintr_advance , +.Fn clockintr_cancel , +.Fn clockintr_schedule , +and +.Fn clockintr_stagger +functions may be called from process context or from interrupt context. +.Pp +The +.Fn clockintr_unbind +function may normally be called from process context or from interrupt context. +However, +if the +.Dv CL_BARRIER +flag is set in +.Fa flags , +the function may only be called from process context. +.Pp +The +.Fn clockrequest_advance +function may only be called during execution of a +.Fa callback +function. +.Sh RETURN VALUES +The +.Fn clockintr_advance +and +.Fn clockrequest_advance +functions return the number of +.Fa interval Ns s +that have elapsed since +.Fa cl +was scheduled to expire, +or zero if +.Fa cl +has not yet expired. +.Sh CODE REFERENCES +.Pa sys/kern/kern_clockintr.c +.Sh SEE ALSO +.Xr microtime 9 , +.Xr spl 9 , +.Xr timeout 9 +.Rs +.%A Richard McDougall +.%A Jim Mauro +.%B Solaris Internals: Solaris 10 and OpenSolaris Kernel Architecture +.%I Prentice Hall +.%I Sun Microsystems Press +.%D 2nd Edition, 2007 +.%P pp. 912\(en925 +.Re +.Sh HISTORY +The +.Vt clockintr +and +.Vt clockrequest +APIs first appeared in +.Ox 7.5 . diff --git a/static/openbsd/man9/cond_init.9 b/static/openbsd/man9/cond_init.9 new file mode 100644 index 00000000..4157cfdb --- /dev/null +++ b/static/openbsd/man9/cond_init.9 @@ -0,0 +1,126 @@ +.\" $OpenBSD: cond_init.9,v 1.5 2025/07/28 13:33:17 schwarze Exp $ */ +.\" +.\" Copyright (c) 2017 David Gwynne +.\" +.\" 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: July 28 2025 $ +.Dt COND_INIT 9 +.Os +.Sh NAME +.Nm cond_init , +.Nm cond_wait , +.Nm cond_signal , +.Nm COND_INITIALIZER +.Nd wait condition API +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn "cond_init" "struct cond *c" +.Ft void +.Fn "cond_wait" "struct cond *c" "const char *wmesg" +.Ft void +.Fn "cond_signal" "struct cond *c" +.Ft void +.Fn "cond_signal_handler" "void *c" +.Fn "COND_INITIALIZER" +.Sh DESCRIPTION +The wait condition API allows a thread to sleep while it waits for +a notification, aka signal, that pending work has completed. +.Pp +.Fn cond_init +initialises the wait condition +.Fa c +for use. +.Pp +.Fn cond_wait +is used to sleep on the wait condition +.Fa c +until whatever the thread is waiting on calls +.Fn cond_signal +or +.Fn cond_signal_handler . +.Fa wmesg +is a pointer to a character string indicating the reason the thread +is sleeping. +.Pp +.Fn cond_signal +and +.Fn cond_signal_handler +notify the thread waiting on +.Fa c +that the work has finished and it may proceed. +.Fn cond_signal +and +.Fn cond_signal_handler +operate identically, the only difference is the type of argument they take. +.Fn cond_signal_handler +takes a +.Ft void * +argument, allowing it to be used directly with APIs such as +.Xr task_set 9 +and +.Xr timeout_set 9 . +.Pp +.Fn COND_INITIALIZER +initialises a declaration of a cond for use. +.Sh CONTEXT +.Fn cond_init , +.Fn cond_signal , +and +.Fn cond_signal_handler +can be called during autoconf, from process context, or from interrupt +context. +.Pp +.Fn cond_wait +can be called from process context. +.Sh EXAMPLES +.Xr taskq_barrier 9 +is implemented using the wait condition API. +The following is a commented copy of the implementation: +.Bd -literal +static void taskq_barrier_task(void *); + +void +taskq_barrier(struct taskq *tq) +{ + struct cond c; + struct task t; + + /* + * any currently running work has to have finished + * before this new task can be run. + */ + + cond_init(&c); + task_init(&t, taskq_barrier_task, &c); + + task_add(tq, &t); + + /* wait until the task runs and signals completion */ + cond_wait(&c, "tqbar"); +} + +static void +taskq_barrier_task(void *p) +{ + struct cond *c = p; + + /* + * all previous tasks have run, signal the thread waiting + * in taskq_barrier + */ + + cond_signal(c); +} +.Ed diff --git a/static/openbsd/man9/config_attach.9 b/static/openbsd/man9/config_attach.9 new file mode 100644 index 00000000..d485dcf5 --- /dev/null +++ b/static/openbsd/man9/config_attach.9 @@ -0,0 +1,84 @@ +.\" $OpenBSD: config_attach.9,v 1.4 2025/06/13 18:34:00 schwarze Exp $ +.\" $NetBSD: autoconf.9,v 1.9 2002/02/13 08:18:35 ross Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 $Mdocdate: June 13 2025 $ +.Dt CONFIG_ATTACH 9 +.Os +.Sh NAME +.Nm config_attach , +.Nm config_detach , +.Nm config_detach_children +.Nd attach and detach devices +.Sh SYNOPSIS +.In sys/param.h +.In sys/device.h +.Ft struct device * +.Fn config_attach "struct device *parent" "void *cf" "void *aux" \ + "cfprint_t print" +.Ft int +.Fn config_detach "struct device *dev" "int flags" +.Ft int +.Fn config_detach_children "struct device *parent" "int flags" +.Sh DESCRIPTION +The +.Fn config_attach +function attaches a found device. +Memory is allocated for the +.Em softc +structure and the driver's attach function is called according to the +configuration table. +If successful, +.Fn config_attach +returns the +.Em softc . +If unsuccessful, it returns +.Dv NULL . +.Pp +The +.Fn config_detach +function is called by the parent to detach the child device. +The second argument +.Fa flags +contains detachment flags: +.Bd -literal +#define DETACH_FORCE 0x01 /* Force detachment; hardware gone */ +#define DETACH_QUIET 0x02 /* Don't print a notice */ +.Ed +.Sh CONTEXT +.Fn config_detach +is always called from process context, allowing +.Xr tsleep 9 +to be called while the device detaches itself (to deal with processes +which have a device open). +.Sh RETURN VALUES +.Fn config_detach +returns zero if successful and an error code otherwise. +.Sh SEE ALSO +.Xr config_found 9 diff --git a/static/openbsd/man9/config_defer.9 b/static/openbsd/man9/config_defer.9 new file mode 100644 index 00000000..a078977b --- /dev/null +++ b/static/openbsd/man9/config_defer.9 @@ -0,0 +1,62 @@ +.\" $OpenBSD: config_defer.9,v 1.3 2025/06/13 18:34:00 schwarze Exp $ +.\" $NetBSD: autoconf.9,v 1.9 2002/02/13 08:18:35 ross Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 $Mdocdate: June 13 2025 $ +.Dt CONFIG_DEFER 9 +.Os +.Sh NAME +.Nm config_defer , +.Nm config_mountroot +.Nd deferred device configuration +.Sh SYNOPSIS +.In sys/param.h +.In sys/device.h +.Ft void +.Fn config_defer "struct device *dev" "void (*func)(struct device *)" +.Ft void +.Fn config_mountroot "struct device *dev" "void (*func)(struct device *)" +.Sh DESCRIPTION +The +.Fn config_defer +function is called by the child to defer the remainder of its configuration +until all its parent devices have been attached. +At this point, the function +.Fa func +is called with the argument +.Fa dev . +.Pp +The +.Fn config_mountroot +function is called by a device driver to defer the remainder of its +configuration until after the root file system is mounted. +At this point, the function +.Fa func +is called with the argument +.Fa dev . diff --git a/static/openbsd/man9/copy.9 b/static/openbsd/man9/copy.9 new file mode 100644 index 00000000..ff7c8c0e --- /dev/null +++ b/static/openbsd/man9/copy.9 @@ -0,0 +1,136 @@ +.\" $OpenBSD: copy.9,v 1.18 2023/01/06 19:10:18 miod Exp $ +.\" $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 $Mdocdate: January 6 2023 $ +.Dt COPYIN 9 +.Os +.Sh NAME +.Nm copyin , +.Nm copyout , +.Nm copyinstr , +.Nm copyoutstr , +.Nm kcopy +.Nd kernel 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 copyout "const void *kaddr" "void *uaddr" "size_t len" +.Ft int +.Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done" +.Ft int +.Fn copyoutstr "const void *kaddr" "void *uaddr" "size_t len" "size_t *done" +.Ft int +.Fn kcopy "const void *kfaddr" "void *kdaddr" "size_t len" +.Sh DESCRIPTION +The +.Nm +functions are designed to copy contiguous data from one address to another. +All but +.Fn kcopy +copy data from user-space to kernel-space or vice-versa. +.Pp +The +.Nm +routines provide the following functionality: +.Bl -tag -width "copyoutstr()" +.It Fn copyin +Copies +.Fa len +bytes of data from the user-space address +.Fa uaddr +to the kernel-space address +.Fa kaddr . +.It Fn copyout +Copies +.Fa len +bytes of data from the kernel-space address +.Fa kaddr +to the user-space address +.Fa uaddr . +.It Fn copyinstr +Copies a null-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 null, +is returned in +.Fa *done , +if +.Fa done +is not +.Dv NULL . +.It Fn copyoutstr +Copies a null-terminated string, at most +.Fa len +bytes long, from kernel-space address +.Fa kaddr +to user-space address +.Fa uaddr . +The number of bytes actually copied, including the terminating null, +is returned in +.Fa *done , +if +.Fa done +is not +.Dv NULL . +.It Fn kcopy +Copies +.Fa len +bytes of data from the kernel-space address +.Fa kfaddr +to the kernel-space address +.Fa kdaddr . +.El +.Sh RETURN VALUES +The +.Nm +functions return 0 on success or +.Er EFAULT +if a bad address is encountered. +In addition, the +.Fn copyinstr +and +.Fn copyoutstr +functions return +.Er ENAMETOOLONG +if the string is longer than +.Fa len +bytes. +.\" .Sh SEE ALSO diff --git a/static/openbsd/man9/counters_alloc.9 b/static/openbsd/man9/counters_alloc.9 new file mode 100644 index 00000000..01d343d3 --- /dev/null +++ b/static/openbsd/man9/counters_alloc.9 @@ -0,0 +1,312 @@ +.\" $OpenBSD: counters_alloc.9,v 1.13 2023/09/16 09:33:28 mpi Exp $ +.\" +.\" Copyright (c) 2016 David Gwynne +.\" +.\" 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: September 16 2023 $ +.Dt COUNTERS_ALLOC 9 +.Os +.Sh NAME +.Nm counters_alloc , +.Nm counters_free , +.Nm COUNTERS_BOOT_MEMORY , +.Nm COUNTERS_BOOT_INITIALIZER , +.Nm counters_alloc_ncpus , +.Nm counters_enter , +.Nm counters_leave , +.Nm counters_inc , +.Nm counters_add , +.Nm counters_pkt , +.Nm counters_read , +.Nm counters_zero +.Nd per CPU counters +.Sh SYNOPSIS +.In sys/percpu.h +.Ft struct cpumem * +.Fn counters_alloc "unsigned int ncounters" +.Ft void +.Fn counters_free "struct cpumem *cm" "unsigned int ncounters" +.Fn COUNTERS_BOOT_MEMORY "NAME" "unsigned int ncounters" +.Fn COUNTERS_BOOT_INITIALIZER "NAME" +.Ft struct cpumemt * +.Fo counters_alloc_ncpus +.Fa "struct cpumem *cm" +.Fa "unsigned int ncounters" +.Fc +.Ft uint64_t * +.Fn counters_enter "struct counters_ref *ref" "struct cpumem *cm" +.Ft void +.Fn counters_leave "struct counters_ref *ref" "struct cpumem *cm" +.Ft void +.Fn counters_inc "struct cpumem *cm" "unsigned int counter" +.Ft void +.Fn counters_add "struct cpumem *cm" "unsigned int counter" "uint64_t v" +.Ft void +.Fo counters_pkt +.Fa "struct cpumem *cm" +.Fa "unsigned int pcounter" +.Fa "unsigned int bcounter" +.Fa "uint64_t bytes" +.Fc +.Ft void +.Fo counters_read +.Fa "struct cpumem *cm" +.Fa "uint64_t *counters" +.Fa "unsigned int ncounters" +.Fa "uint64_t *scratch" +.Fc +.Ft void +.Fn counters_zero "struct cpumem *cm" "unsigned int ncounters" +.Sh DESCRIPTION +The per CPU counter API builds on the per CPU memory API and provides +access to a series of uint64_t counter values on each CPU. +.Pp +The API provides versioning of counter updates without using +interlocked CPU instructions so they can all be read in a consistent +state. +Updates to counters should be limited to addition or subtraction +of uint64_t values. +.Pp +An alternate implementation of the API is provided on uni-processor +systems +(i.e. when the kernel is not built with +.Dv MULTIPROCESSOR +defined) +that provides no overhead compared to direct access to a +data structure. +This allows the API to be used without affecting the performance +of uni-processor systems. +.Pp +.Fn counters_alloc +allocates memory for a series of uint64_t values on each CPU. +.Fa ncounters +specifies the number of counters to be allocated. +The counters will be zeroed on allocation. +.Pp +.Fn counters_free +deallocates each CPU's counters. +The same +.Fa ncounters +argument originally provided to +.Fn counters_alloc +must be passed to +.Fn counters_free . +.Pp +.Fn counters_alloc +may only be used after all the CPUs in the system have been attached. +If a set of CPU counters needs to be available during early boot, +a cpumem pointer and counters for the boot CPU may be statically +allocated. +.Pp +.Fn COUNTERS_BOOT_MEMORY +statically allocates a set of counter for use on the boot CPU +before the other CPUs in the system have been attached. +The allocation is identified by +.Fa NAME +and provides memory for the number of counters specified by +.Fa ncounters . +The counters will be initialised to zero. +.Pp +.Fn COUNTERS_BOOT_INITIALIZER +is used to initialise a cpumem pointer with the memory that was previously +allocated using +.Fn COUNTERS_BOOT_MEMORY +and identified by +.Fa NAME . +.Pp +.Fn counters_alloc_ncpus +allocates additional sets of counters for the CPUs that were attached +during boot. +The cpumem structure +.Fa cm +must have been initialised with +.Fn COUNTERS_BOOT_INITIALIZER . +The same number of counters originally passed to +.Fa COUNTERS_BOOT_MEMORY +must be specified by +.Fa ncounters . +The counters on the boot CPU will be preserved, while the counters +for the additional CPUs will be zeroed on allocation. +.Pp +Counters that have been allocated with +.Fn COUNTERS_BOOT_MEMORY +and +.Fn counters_alloc_ncpus +cannot be deallocated with +.Fa counters_free . +.Pp +.Fn counters_enter +provides access to the current CPU's set of counters referenced by +.Fa cm . +The caller's reference to the counters is held by +.Fa ref . +.Pp +.Fn counters_leave +indicates the end of access to the current CPU's set of counters referenced by +.Fa cm . +The reference held by +.Fa ref +is released by this call. +.Pp +.Fn counters_inc +increments the counter at the index specified by +.Fa counter +in the array of counters referenced by +.Fa cm . +.Pp +.Fn counters_add +adds the value of +.Fa v +to the counter at the index specified by +.Fa counter +in the array of counters referenced by +.Fa cm . +.Pp +.Fn counters_pkt +increments the value at the index specified by +.Fa pcounter +and adds the value of +.Fa bytes +to the counter at the index specified by +.Fa bcounter +in the array of counters referenced by +.Fa cm . +.Pp +.Fn counters_read +iterates over each CPU's set of counters referenced by +.Fa cm , +takes a consistent snapshot of the counters, and then sums them together. +The sum of the counters is written to the +.Fa counters +array. +The number of counters is specified with +.Fa ncounters . +.Fa scratch +may point to a buffer used to temporarily hold +.Fa counters . +If +.Dv NULL , +one will be dynamically allocated and freed. +.Pp +.Fn counters_zero +iterates over each CPU's set of counters referenced by +.Fa cm +and zeroes them. +The number of counters is specified with +.Fa ncounters . +.Fn counters_zero +itself does not prevent concurrent updates of the counters; it is +up to the caller to serialise this call with other actions. +.Sh CONTEXT +.Fn counters_alloc , +.Fn counters_free , +.Fn counters_alloc_ncpus , +and +.Fn counters_read +may be called during autoconf, or from process context. +.Pp +.Fn counters_enter , +.Fn counters_leave , +.Fn counters_inc , +.Fn counters_add , +.Fn counters_pkt , +and +.Fn counters_zero +may be called during autoconf, from process context, or from interrupt +context. +The per CPU counters API does not provide any locking or serialisation +of access to each CPU's set of counters beyond isolating each CPU's +update. +It is up to the caller to provide appropriate locking or serialisation +around calls to these functions to prevent concurrent access to the +relevant data structures. +.Sh RETURN VALUES +.Fn counters_alloc +and +.Fn counters_alloc_ncpus +will return an opaque cpumem pointer that references each CPU's +set of counters. +.Pp +.Fn counters_enter +returns a reference to the current CPU's set of counters. +.Sh EXAMPLES +The following is an example of providing per CPU counters at boot +time based on the +.Xr mbuf 9 +statistics code in +.Pa sys/kern/uipc_mbuf.c . +.Bd -literal +/* mbuf stats */ +COUNTERS_BOOT_MEMORY(mbstat_boot, MBSTAT_COUNT); +struct cpumem *mbstat = COUNTERS_BOOT_INITIALIZER(mbstat_boot); + +/* + * this function is called from init_main.c after devices + * (including additional CPUs) have been attached + */ +void +mbcpuinit() +{ + mbstat = counters_alloc_ncpus(mbstat, MBSTAT_COUNT); +} + +struct mbuf * +m_get(int nowait, int type) +{ + ... + + struct counters_ref cr; + uint64_t *counters; + int s; + + ... + + s = splnet(); + counters = counters_enter(&cr, mbstat); + counters[type]++; + counters_leave(&cr, mbstat); + splx(s); + + ... +} + +struct mbuf * +m_free(struct mbuf *m) +{ + ... + + struct counters_ref cr; + uint64_t *counters; + int s; + + ... + + s = splnet(); + counters = counters_enter(&cr, mbstat); + counters[m->m_type]--; + counters_leave(&cr, mbstat); + splx(s); + + ... +} +.Ed +.Sh SEE ALSO +.Xr cpumem_get 9 , +.Xr malloc 9 +.Sh HISTORY +The per CPU counter API first appeared in +.Ox 6.1 . +.Sh AUTHORS +The per CPU counter API was written by +.An David Gwynne Aq Mt dlg@openbsd.org . diff --git a/static/openbsd/man9/cpu_xcall.9 b/static/openbsd/man9/cpu_xcall.9 new file mode 100644 index 00000000..629c4d9e --- /dev/null +++ b/static/openbsd/man9/cpu_xcall.9 @@ -0,0 +1,114 @@ +.\" $OpenBSD: cpu_xcall.9,v 1.2 2025/07/13 19:36:42 schwarze Exp $ +.\" +.\" Copyright (c) 2025 David Gwynne +.\" 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 $Mdocdate: July 13 2025 $ +.Dt CPU_XCALL 9 +.Os +.Sh NAME +.Nm cpu_xcall_set , +.Nm cpu_xcall , +.Nm cpu_xcall_sync , +.Nm XCALL_INITIALIZER +.Nd CPU crosscall API +.Sh SYNOPSIS +.In sys/xcall.h +.Ft void +.Fn cpu_xcall_set "struct xcall *xc" "void (*func)(void *)" "void *arg" +.Ft void +.Fn cpu_xcall "struct cpu_info *ci" "struct xcall *xc" +.Ft void +.Fo cpu_xcall_sync +.Fa "struct cpu_info *ci" +.Fa "void (*func)(void *)" +.Fa "void *arg" +.Fa "const char *wmesg" +.Fc +.Fn XCALL_INITIALIZER "void (*func)(void *)" "void *arg" +.Sh DESCRIPTION +The +CPU crosscall API +supports the dispatch of function execution to a specific CPU +in the kernel. +The functions are run in a software interrupt context at +.Dv IPL_SOFTCLOCK . +.Pp +The +.Fn cpu_xcall_set +function prepares the xcall structure +.Fa xc +to call the function +.Fa func +with argument +.Fa arg +via future calls to +.Fn cpu_xcall . +.Pp +.Fn cpu_xcall +dispatches a call to a function with an argument represented by +.Fa xc +on the CPU specified by the +.Fa ci +cpu_info structure. +The same +.Fa xc +may be scheduled for execution on multiple CPUs concurrently. +.Pp +.Fn cpu_xcall_sync +dispatches a call to the function +.Fa func +with argument +.Fa arg +on the CPU specified by the +.Fa ci +cpu_info structure, and waits for that function to complete. +.Fn cpu_xcall_sync +may sleep waiting for the call to +.Fa func +to complete with +.Fa wmesg +as the wait message. +.Pp +.Fn XCALL_INITIALIZER +initialises a +.Vt xcall +structure to call the function +.Fa func +with argument +.Fa arg +via future calls to +.Fn cpu_xcall . +.Sh CONTEXT +.Fn cpu_xcall_set +and +.Fn cpu_xcall +can be called from process context or from interrupt context. +.Pp +.Fn cpu_xcall_sync +can be called from process context. +.Sh SEE ALSO +.Xr spl 9 , +.Xr tsleep 9 +.Sh HISTORY +The +.Nm +functions first appeared in +.Ox 7.8 . +.Sh AUTHORS +The +.Nm +functions were written by +.An David Gwynne Aq Mt dlg@openbsd.org . diff --git a/static/openbsd/man9/cpumem_get.9 b/static/openbsd/man9/cpumem_get.9 new file mode 100644 index 00000000..4be510ad --- /dev/null +++ b/static/openbsd/man9/cpumem_get.9 @@ -0,0 +1,239 @@ +.\" $OpenBSD: cpumem_get.9,v 1.11 2020/08/27 09:29:16 fcambus Exp $ +.\" +.\" Copyright (c) 2016 David Gwynne +.\" +.\" 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: August 27 2020 $ +.Dt CPUMEM_GET 9 +.Os +.Sh NAME +.Nm cpumem_get , +.Nm cpumem_put , +.Nm cpumem_malloc , +.Nm cpumem_malloc_ncpus , +.Nm cpumem_free , +.Nm CPUMEM_BOOT_MEMORY , +.Nm CPUMEM_BOOT_INITIALIZER , +.Nm cpumem_enter , +.Nm cpumem_leave , +.Nm cpumem_first , +.Nm cpumem_next , +.Nm CPUMEM_FOREACH +.Nd per CPU memory allocations +.Sh SYNOPSIS +.In sys/percpu.h +.Ft struct cpumem * +.Fn cpumem_get "struct pool *pp" +.Ft void +.Fn cpumem_put "struct pool *pp" "struct cpumem *cm" +.Ft struct cpumem * +.Fn cpumem_malloc "size_t sz" "int type" +.Ft struct cpumem * +.Fn cpumem_malloc_ncpus "struct cpumem *cm" "size_t sz" "int type" +.Ft void +.Fn cpumem_free "struct cpumem *cm" "int type" "size_t sz" +.Fn CPUMEM_BOOT_MEMORY "NAME" "size_t sz" +.Fn CPUMEM_BOOT_INITIALIZER "NAME" +.Ft void * +.Fn cpumem_enter "struct cpumem *cm" +.Ft void +.Fn cpumem_leave "struct cpumem *cm" "void *m" +.Ft void * +.Fn cpumem_first "struct cpumem_iter *ci" "struct cpumem *cm" +.Ft void * +.Fn cpumem_next "struct cpumem_iter *ci" "struct cpumem *cm" +.Fn CPUMEM_FOREACH "VARNAME" "struct cpumem_iter *ci" "struct cpumem *cm" +.Sh DESCRIPTION +The per CPU memory API provides wrappers around the allocation of +and access to per CPU memory. +.Pp +An alternate implementation of the API is provided on uni-processor +(i.e. when the kernel is not built with +.Dv MULTIPROCESSOR +defined) +systems that provides no overhead compared to direct access to a +data structure. +This allows the API to be used without affecting the performance +on uni-processor systems. +.Ss Per CPU Memory Allocation and Deallocation +.Fn cpumem_get +allocates memory for each CPU from the +.Fa pp +pool. +The memory will be zeroed on allocation. +.Pp +.Fn cpumem_put +returns each CPUs memory allocation referenced by +.Fa cm +to the +.Fa pp +pool. +.Pp +.Fn cpumem_malloc +allocates +.Fa sz +bytes of +.Fa type +memory for each CPU using +.Xr malloc 9 . +The memory will be zeroed on allocation. +.Pp +.Fn cpumem_free +returns each CPU's memory allocation referenced by +.Fa cm +to the system using +.Xr free 9 . +The same object size and type originally provided to +.Fn cpumem_malloc +must be specified by +.Fa sz +and +.Fa type +respectively. +.Pp +.Fn cpumem_get +and +.Fn cpumem_malloc +may only be used after all the CPUs in the system have been attached. +If per CPU memory needs to be available during early boot, +a cpumem pointer and memory for the boot CPU may be statically +allocated. +.Pp +.Fn CPUMEM_BOOT_MEMORY +statically allocates memory for use on the boot CPU +before the other CPUs in the system have been attached. +The allocation is identified by +.Fa NAME , +and provides the number of bytes specified by the +.Fa sz +argument. +The memory will be initialised to zeros. +.Pp +.Fn CPUMEM_BOOT_INITIALIZER +is used to initialise a cpumem pointer with the memory that was previously +allocated using +.Fn CPUMEM_BOOT_MEMORY +and identified by +.Fa NAME . +.Pp +.Fn cpumem_malloc_ncpus +allocates additional memory for the CPUs that were attached during boot. +The cpumem structure +.Fa cm +must have been initialised with +.Fn CPUMEM_BOOT_INITIALIZER . +The same number of bytes originally passed to +.Fa COUNTERS_BOOT_MEMORY +must be specified by +.Fa sz . +The +.Fa type +argument specifies the type of memory that the counters will be +allocated as via +.Xr malloc 9 . +The contents of the memory on the boot CPU will be preserved, while +the allocations for the additional CPU's will be zeroed on allocation. +.Pp +Per CPU memory that has been allocated with +.Fn CPUMEM_BOOT_MEMORY +and +.Fn cpumem_malloc_ncpus +cannot be deallocated with +.Fa cpumem_free . +Any attempt to do so will lead to undefined behaviour. +.Ss Per CPU Memory Access +.Fn cpumem_enter +provides access to the current CPU's memory allocation referenced by +.Fa cm . +.Pp +.Fn cpumem_leave +indicates the end of access to the current CPU's memory allocation referenced by +.Fa cm . +.Ss Per CPU Memory Iterators +.Fn cpumem_first +provides access to the first CPU's memory allocation referenced by +.Fa cm . +The iterator +.Fa ci +may be used in subsequent calls to +.Fn cpumem_next . +.Pp +.Fn cpumem_next +provides access to the next CPU's memory allocation referenced by +.Fa cm +and +.Fa ci . +.Pp +The +.Fn CPUMEM_FOREACH +macro iterates over each CPU's memory allocation referenced by +.Fa cm +using the iterator +.Fa ci , +setting +.Fa VARNAME +to each CPU's allocation in turn. +.Sh CONTEXT +.Fn cpumem_get , +.Fn cpumem_put , +.Fn cpumem_malloc , +.Fn cpumem_free , +and +.Fn cpumem_malloc_ncpus +may be called during autoconf, or from process context. +.Pp +.Fn cpumem_enter , +.Fn cpumem_leave , +.Fn cpumem_first , +.Fn cpumem_next , +and +.Fn CPUMEM_FOREACH +may be called during autoconf, from process context, or from interrupt +context. +The per CPU memory API does not provide any locking or serialisation +of access to each CPU's memory allocation. +It is up to the caller to provide appropriate locking or serialisation +around calls to these functions to prevent concurrent access to the +relevant data structures. +.Sh RETURN VALUES +.Fn cpumem_get , +.Fn cpumem_malloc , +and +.Fn cpumem_malloc_ncpus +will return an opaque cpumem pointer that references each CPU's +memory allocation. +.Pp +.Fn cpumem_enter +returns a reference to the current CPU's memory allocation. +.Pp +.Fn cpumem_first +returns a reference to the first CPU's memory allocation. +.Pp +.Fn cpumem_next +returns a reference to the next CPU's memory allocation according to the +iterator +.Fa ci , +or +.Dv NULL +if the iterator has run out of CPUs. +.Sh SEE ALSO +.Xr counters_alloc 9 , +.Xr malloc 9 , +.Xr pool_get 9 +.Sh HISTORY +The per CPU memory API first appeared in +.Ox 6.1 . +.Sh AUTHORS +The per CPU memory API was written by +.An David Gwynne Aq Mt dlg@openbsd.org . diff --git a/static/openbsd/man9/crypto.9 b/static/openbsd/man9/crypto.9 new file mode 100644 index 00000000..11f289c8 --- /dev/null +++ b/static/openbsd/man9/crypto.9 @@ -0,0 +1,518 @@ +.\" $OpenBSD: crypto.9,v 1.43 2020/03/28 13:16:09 krw Exp $ +.\" +.\" The author of this man 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 $Mdocdate: March 28 2020 $ +.Dt CRYPTO_GET_DRIVERID 9 +.Os +.Sh NAME +.Nm crypto_get_driverid , +.Nm crypto_register , +.Nm crypto_unregister , +.Nm crypto_done , +.Nm crypto_newsession , +.Nm crypto_freesession , +.Nm crypto_dispatch , +.Nm crypto_getreq , +.Nm crypto_freereq +.Nd API for cryptographic services in the kernel +.Sh SYNOPSIS +.In crypto/cryptodev.h +.Ft int32_t +.Fn crypto_get_driverid "u_int8_t" +.Ft int +.Fn crypto_register "u_int32_t" "int *" "int (*)(u_int32_t *, struct cryptoini *)" "int (*)(u_int64_t)" "int (*)(struct cryptop *)" +.Ft int +.Fn crypto_unregister "u_int32_t" "int" +.Ft void +.Fn crypto_done "struct cryptop *" +.Ft int +.Fn crypto_newsession "u_int64_t *" "struct cryptoini *" "int" +.Ft int +.Fn crypto_freesession "u_int64_t" +.Ft int +.Fn crypto_dispatch "struct cryptop *" +.Ft struct cryptop * +.Fn crypto_getreq "int" +.Ft void +.Fn crypto_freereq "struct cryptop *" +.Bd -literal + +#define EALG_MAX_BLOCK_LEN 16 + +struct cryptoini { + int cri_alg; + int cri_klen; + int cri_rnd; + caddr_t cri_key; + u_int8_t cri_iv[EALG_MAX_BLOCK_LEN]; + struct cryptoini *cri_next; +}; + +struct cryptodesc { + int crd_skip; + int crd_len; + int crd_inject; + int crd_flags; + struct cryptoini CRD_INI; + struct cryptodesc *crd_next; +}; + +struct cryptop { + u_int64_t crp_sid; + int crp_ilen; + int crp_olen; + int crp_alloctype; + int crp_etype; + int crp_flags; + void *crp_buf; + void *crp_opaque; + struct cryptodesc *crp_desc; + int (*crp_callback)(struct cryptop *); + struct cryptop *crp_next; + caddr_t crp_mac; +}; +.Ed +.Sh DESCRIPTION +.Nm +is a framework for drivers of cryptographic hardware to register with +the kernel so +.Dq consumers +(other kernel subsystems, and eventually +users through an appropriate device) are able to make use of it. +Drivers register with the framework the algorithms they support, +and provide entry points (functions) the framework may call to +establish, use, and tear down sessions. +Sessions are used to cache cryptographic information in a particular driver +(or associated hardware), so initialization is not needed with every request. +Consumers of cryptographic services pass a set of +descriptors that instruct the framework (and the drivers registered +with it) of the operations that should be applied on the data (more +than one cryptographic operation can be requested). +.Pp +Since the consumers may not be associated with a process, drivers may +not use +.Xr tsleep 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. +An error indication is provided in the latter case. +A specific error code, +.Er EAGAIN , +is used to indicate that a session number has changed and that the +request may be re-submitted immediately with the new session number. +Errors are only returned to the invoking function if not +enough information to call the callback is available (meaning, there +was a fatal error in verifying the arguments). +For session initialization and teardown there is no callback mechanism used. +.Pp +The +.Fn crypto_newsession +routine is called by consumers of cryptographic services (such as the +.Xr ipsec 4 +stack) that wish to establish a new session with the framework. +On success, the first argument will contain the Session Identifier (SID). +The second argument contains all the necessary information for +the driver to establish the session. +The third argument indicates whether a +hardware driver should be used (1) or not (0). +The various fields in the +.Fa cryptoini +structure are: +.Bl -tag -width foobarmoocow +.It Fa cri_alg +Contains an algorithm identifier. +Currently supported encryption algorithms are: +.Bd -literal +CRYPTO_3DES_CBC +CRYPTO_BLF_CBC +CRYPTO_CAST_CBC +CRYPTO_AES_CBC +CRYPTO_AES_CTR +CRYPTO_AES_XTS +.Ed +.Pp +Authentication algorithms are: +.Bd -literal +CRYPTO_MD5_HMAC +CRYPTO_SHA1_HMAC +CRYPTO_RIPEMD160_HMAC +CRYPTO_SHA2_256_HMAC +CRYPTO_SHA2_384_HMAC +CRYPTO_SHA2_512_HMAC +.Ed +.Pp +Algorithms performing authenticated encryption are: +.Bd -literal +CRYPTO_AES_GCM_16 +CRYPTO_AES_GMAC +CRYPTO_CHACHA20_POLY1305 +.Ed +.It Fa cri_klen +Specifies the length of the key in bits, for variable-size key +algorithms. +.It Fa cri_rnd +Specifies the number of rounds to be used with the algorithm, for +variable-round algorithms. +.It Fa cri_key +Contains the key to be used with the algorithm. +.It Fa cri_iv +Contains an explicit initialization vector (IV), if it does not prefix +the data. +This field is ignored during initialization. +If no IV is explicitly passed (see below on details), a random IV is used +by the device driver processing the request. +.Pp +In the case of the CRYPTO_AES_XTS transform, the IV should be provided +as a 64-bit block number in host byte order. +.It Fa cri_next +Contains a pointer to another +.Fa cryptoini +structure. +Multiple such structures may be linked to establish multi-algorithm sessions +.Pf ( Xr ipsec 4 +is an example consumer of such a feature). +.El +.Pp +The +.Fa cryptoini +structure and its contents will not be modified by the framework (or +the drivers used). +Subsequent requests for processing that use the +SID returned will avoid the cost of re-initializing the hardware (in +essence, SID acts as an index in the session cache of the driver). +.Pp +.Fn crypto_freesession +is called with the SID returned by +.Fn crypto_newsession +to disestablish the session. +.Pp +.Fn crypto_dispatch +is called to process a request. +The various fields in the +.Fa cryptop +structure are: +.Bl -tag -width crp_alloctype +.It Fa crp_sid +Contains the SID. +.It Fa crp_ilen +Indicates the total length in bytes of the buffer to be processed. +.It Fa crp_olen +On return, contains the length of the result, not including +.Fa crd_skip . +For symmetric crypto operations, this will be the same as the input length. +.It Fa crp_alloctype +Indicates the type of buffer, as used in the kernel +.Xr malloc 9 +routine. +This will be used if the framework needs to allocate a new +buffer for the result (or for re-formatting the input). +.It Fa crp_callback +This routine is invoked upon completion of the request, whether +successful or not. +It is invoked through the +.Fn crypto_done +routine. +If the request was not successful, an error code is set in the +.Fa crp_etype +field. +It is the responsibility of the callback routine to set the appropriate +.Xr spl 9 +level. +.It Fa crp_etype +Contains the error type, if any errors were encountered, or zero if +the request was successfully processed. +If the +.Er EAGAIN +error code is returned, the SID has changed (and has been recorded in the +.Fa crp_sid +field). +The consumer should record the new SID and use it in all subsequent requests. +In this case, the request may be re-submitted immediately. +This mechanism is used by the framework to perform +session migration (move a session from one driver to another, because +of availability, performance, or other considerations). +.Pp +Note that this field only makes sense when examined by +the callback routine specified in +.Fa crp_callback . +Errors are returned to the invoker of +.Fn crypto_process +only when enough information is not present to call the callback +routine (i.e., if the pointer passed is +.Dv NULL +or if no callback routine was specified). +.It Fa crp_flags +Is a bitmask of flags associated with this request. +Currently defined flags are: +.Bl -tag -width CRYPTO_F_IMBUF +.It Dv CRYPTO_F_IMBUF +The buffer pointed to by +.Fa crp_buf +is an mbuf chain. +.El +.It Fa crp_buf +Points to the input buffer. +On return (when the callback is invoked), +it contains the result of the request. +The input buffer may be an mbuf +chain or a struct uio depending on +.Fa crp_flags . +.It Fa crp_opaque +This is passed through the crypto framework untouched and is +intended for the invoking application's use. +.It Fa crp_desc +This is a linked list of descriptors. +Each descriptor provides +information about what type of cryptographic operation should be done +on the input buffer. +The various fields are: +.Bl -tag -width "crd_inject" +.It Fa crd_skip +The offset in the input buffer where processing should start. +.It Fa crd_len +How many bytes, after +.Fa crd_skip , +should be processed. +.It Fa crd_inject +Offset from the beginning of the buffer to insert any results. +For encryption algorithms, this is where the initialization vector +(IV) will be inserted when encrypting or where it can be found when +decrypting (subject to +.Fa crd_flags ) . +For MAC algorithms, this is where the result of the keyed hash will be +inserted. +.It Fa crd_flags +The following flags are defined: +.Bl -tag -width CRD_F_IV_EXPLICIT +.It Dv CRD_F_ENCRYPT +For encryption algorithms, this bit is set when encryption is required +(when not set, decryption is performed). +.It Dv CRD_F_IV_PRESENT +For encryption algorithms, this bit is set when the IV already +precedes the data, so the +.Fa crd_inject +value will be ignored and no IV will be written in the buffer. +Otherwise, the IV used to encrypt the packet will be written +at the location pointed to by +.Fa crd_inject . +The IV length is assumed to be equal to the blocksize of the +encryption algorithm. +Some applications that do special +.Dq IV cooking , +such as the half-IV mode in +.Xr ipsec 4 , +can use this flag to indicate that the IV should not be written on the packet. +This flag is typically used in conjunction with the +.Dv CRD_F_IV_EXPLICIT +flag. +.It Dv CRD_F_IV_EXPLICIT +For encryption algorithms, this bit is set when the IV is explicitly +provided by the consumer in the +.Fa crd_iv +fields. +Otherwise, for encryption operations the IV is provided for by +the driver used to perform the operation, whereas for decryption +operations it is pointed to by the +.Fa crd_inject +field. +This flag is typically used when the IV is calculated +.Dq on the fly +by the consumer, and does not precede the data (some +.Xr ipsec 4 +configurations, and the encrypted swap are two such examples). +.It Dv CRD_F_COMP +For compression algorithms, this bit is set when compression is required (when +not set, decompression is performed). +.El +.It Fa CRD_INI +This +.Fa cryptoini +structure will not be modified by the framework or the device drivers. +Since this information accompanies every cryptographic +operation request, drivers may re-initialize state on-demand +(typically an expensive operation). +Furthermore, the cryptographic +framework may re-route requests as a result of full queues or hardware +failure, as described above. +.It Fa crd_next +Point to the next descriptor. +Linked operations are useful in protocols such as +.Xr ipsec 4 , +where multiple cryptographic transforms may be applied on the same +block of data. +.El +.El +.Pp +.Fn crypto_getreq +allocates a +.Fa cryptop +structure with a linked list of as many +.Fa cryptodesc +structures as were specified in the argument passed to it. +.Pp +.Fn crypto_freereq +deallocates a structure +.Fa cryptop +and any +.Fa cryptodesc +structures linked to it. +Note that it is the responsibility of the +callback routine to do the necessary cleanups associated with the +opaque field in the +.Fa cryptop +structure. +.Sh DRIVER-SIDE API +The +.Fn crypto_get_driverid , +.Fn crypto_register , +.Fn crypto_unregister , +and +.Fn crypto_done +routines are used by drivers that provide support for cryptographic +primitives to register and unregister with the kernel crypto services +framework. +Drivers must first use the +.Fn crypto_get_driverid +function to acquire a driver identifier, specifying the +.Fa cc_flags +as an argument (normally 0, but software-only drivers should specify +.Dv CRYPTOCAP_F_SOFTWARE ) . +For each algorithm the driver supports, it must then call +.Fn crypto_register . +The first argument is the driver identifier. +The second argument is an array of +.Dv CRYPTO_ALGORITHM_MAX + 1 +elements, indicating which algorithms are supported. +The last three arguments are pointers to three +driver-provided functions that the framework may call to establish new +cryptographic context with the driver, free already established +context, and ask for a request to be processed (encrypt, decrypt, etc.\&) +.Fn crypto_unregister +is called by drivers that wish to withdraw support for an algorithm. +The two arguments are the driver and algorithm identifiers, respectively. +Typically, drivers for +.Xr pcmcia 4 +crypto cards that are being ejected will invoke this routine for all +algorithms supported by the card. +If called with +.Dv CRYPTO_ALGORITHM_MAX + 1 , +all algorithms registered for a driver will be unregistered in one go +and the driver will be disabled (no new sessions will be allocated on +that driver, and any existing sessions will be migrated to other +drivers). +The same will be done if all algorithms associated with a driver are +unregistered one by one. +.Pp +The calling convention for the three driver-supplied routines is: +.Bd -literal +int (*newsession) (u_int32_t *, struct cryptoini *); +int (*freesession) (u_int64_t); +int (*process) (struct cryptop *); +.Ed +.Pp +On invocation, the first argument to +.Fn newsession +contains the driver identifier obtained via +.Fn crypto_get_driverid . +On successfully returning, it should contain a driver-specific session +identifier. +The second argument is identical to that of +.Fn crypto_newsession . +.Pp +The +.Fn freesession +routine takes as argument the SID (which is the concatenation of the +driver identifier and the driver-specific session identifier). +It should clear any context associated with the session (clear hardware +registers, memory, etc.). +.Pp +The +.Fn process +routine is invoked with a request to perform crypto processing. +This routine must not block, but should queue the request and return +immediately. +Upon processing the request, the callback routine should be invoked. +In case of error, the error indication must be placed in the +.Fa crp_etype +field of the +.Fa cryptop +structure. +When the request is completed, or an error is detected, the +.Fn process +routine should invoke +.Fn crypto_done . +Session migration may be performed, as mentioned previously. +.Sh RETURN VALUES +.Fn crypto_register , +.Fn crypto_unregister , +.Fn crypto_newsession , +and +.Fn crypto_freesession +return 0 on success, or an error code on failure. +.Fn crypto_get_driverid +returns a non-negative value on error, and \-1 on failure. +.Fn crypto_getreq +returns a pointer to a +.Fa cryptop +structure and +.Dv NULL +on failure. +.Fn crypto_dispatch +returns +.Er EINVAL +if its argument or the callback function was +.Dv NULL , +and 0 otherwise. +The callback is provided with an error code in case of failure, in the +.Fa crp_etype +field. +.Sh FILES +.Bl -tag -width sys/crypto/crypto.c +.It Pa sys/crypto/crypto.c +most of the framework code +.El +.Sh SEE ALSO +.Xr ipsec 4 , +.Xr pcmcia 4 , +.Xr malloc 9 , +.Xr tsleep 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 currently assumes that all the algorithms in a +.Fn crypto_newsession +operation must be available by the same driver. +If that's not the case, session initialization will fail. +.Pp +The framework also 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. +.Pp +Multiple instances of the same algorithm in the same session are not +supported. +.Pp +A queue for completed operations should be implemented and processed +at some software +.Xr spl 9 +level, to avoid overall system latency issues, and potential kernel +stack exhaustion while processing a callback. diff --git a/static/openbsd/man9/delay.9 b/static/openbsd/man9/delay.9 new file mode 100644 index 00000000..b54f33f1 --- /dev/null +++ b/static/openbsd/man9/delay.9 @@ -0,0 +1,35 @@ +.\" $OpenBSD: delay.9,v 1.5 2019/06/27 18:11:53 cheloha Exp $ +.\" +.\" Copyright (c) 2006 David Gwynne +.\" +.\" 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: June 27 2019 $ +.Dt DELAY 9 +.Os +.Sh NAME +.Nm delay +.Nd busy-wait for an interval +.Sh SYNOPSIS +.In sys/param.h +.Ft void +.Fn delay "int interval" +.Sh DESCRIPTION +The +.Fn delay +function busy-waits for at least +.Fa interval +microseconds. +.Sh SEE ALSO +.Xr timeout 9 , +.Xr tsleep 9 diff --git a/static/openbsd/man9/disk.9 b/static/openbsd/man9/disk.9 new file mode 100644 index 00000000..bc443660 --- /dev/null +++ b/static/openbsd/man9/disk.9 @@ -0,0 +1,366 @@ +.\" $OpenBSD: disk.9,v 1.35 2022/09/07 05:36:59 jsg Exp $ +.\" $NetBSD: disk.9,v 1.2 1996/04/08 20:41:25 jtc Exp $ +.\" +.\" Copyright (c) 1995, 1996 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 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 $Mdocdate: September 7 2022 $ +.Dt DISK_INIT 9 +.Os +.Sh NAME +.Nm disk_init , +.Nm disk_attach , +.Nm disk_detach , +.Nm disk_busy , +.Nm disk_unbusy +.Nd generic disk framework +.Sh SYNOPSIS +.In sys/types.h +.In sys/disklabel.h +.In sys/disk.h +.Ft void +.Fn disk_init "void" +.Ft void +.Fn disk_attach "struct disk *" +.Ft void +.Fn disk_detach "struct disk *" +.Ft void +.Fn disk_busy "struct disk *" +.Ft void +.Fn disk_unbusy "struct disk *" "long bcount" "int read" +.Sh DESCRIPTION +The +.Ox +generic disk framework is designed to provide flexible, +scalable, and consistent handling of disk state and metrics information. +The fundamental component of this framework is the +.Nm +structure, which is defined as follows: +.Bd -literal +struct disk { + TAILQ_ENTRY(disk) dk_link; /* link in global disklist */ + struct rwlock dk_lock; /* disk lock */ + struct mutex dk_mtx; /* busy/unbusy mtx */ + char *dk_name; /* disk name */ + struct device *dk_device; /* disk device structure. */ + dev_t dk_devno; /* disk device number. */ + int dk_flags; /* disk flags */ +#define DKF_CONSTRUCTED 0x0001 +#define DKF_OPENED 0x0002 +#define DKF_NOLABELREAD 0x0004 + + /* + * Metrics data; note that some metrics may have no meaning + * on certain types of disks. + */ + int dk_busy; /* busy counter */ + u_int64_t dk_rxfer; /* total number of read transfers */ + u_int64_t dk_wxfer; /* total number of write transfers */ + u_int64_t dk_seek; /* total independent seek operations */ + u_int64_t dk_rbytes; /* total bytes read */ + u_int64_t dk_wbytes; /* total bytes written */ + struct timeval dk_attachtime; /* time disk was attached */ + struct timeval dk_timestamp; /*time of first busy or any unbusy*/ + struct timeval dk_time; /* total time spent busy */ + + int dk_bopenmask; /* block devices open */ + int dk_copenmask; /* character devices open */ + int dk_openmask; /* composite (bopen|copen) */ + int dk_state; /* label state ### */ + int dk_blkshift; /*shift to convert DEV_BSIZE to blks*/ + int dk_byteshift; /* shift to convert bytes to blks */ + + /* + * Disk label information. Storage for the in-core disk label + * must be dynamically allocated, otherwise the size of this + * structure becomes machine-dependent. + */ + struct disklabel *dk_label; +}; +.Ed +.Pp +The system maintains a global linked-list of all disks attached to the +system. +This list, called +.Nm disklist , +may grow or shrink over time as disks are dynamically added and removed +from the system. +An example of a driver which currently makes use of the detachment +capability of the framework is the +.Xr vnd 4 +pseudo-device driver. +.Pp +The following is a brief description of each function in the framework: +.Bl -tag -width "disk_unbusy()" +.It Fn disk_init +Initialize the disklist and other data structures used by the framework. +Called by +.Fn main +before autoconfiguration. +.It Fn disk_attach +Attach a disk; allocate storage for the disklabel, set the +.Dq attached time +timestamp, insert the disk into the disklist, and increment the +system disk count. +.It Fn disk_detach +Detach a disk; free storage for the disklabel, remove the disk +from the disklist, and decrement the system disk count. +If the count drops below zero, panic. +.It Fn disk_busy +Increment the disk's +.Dq busy counter . +If this counter goes from 0 to 1, set the timestamp corresponding to +this transfer. +.It Fn disk_unbusy +Decrement a disk's busy counter. +If the count drops below zero, print a warning message. +Get the current time, subtract it from the disk's timestamp, and add +the difference to the disk's running total. +Set the disk's timestamp to the current time. +If the provided byte count is greater than 0, +add it to the disk's running total and increment the number of transfers +performed by the disk. +The third argument +.Ar read +specifies the direction of I/O; +if non-zero it means reading from the disk, +otherwise it means writing to the disk. +.El +.Pp +The functions typically called by device drivers are +.Fn disk_attach , +.Fn disk_detach , +.Fn disk_busy +and +.Fn disk_unbusy . +.Sh USING THE FRAMEWORK +This section includes a description on basic use of the framework +and example usage of its functions. +Actual implementation of +a device driver which utilizes the framework may vary. +.Pp +A special routine, +.Fn disk_init , +is provided to perform basic initialization of data structures used by +the framework. +It is called exactly once by the system, in +.Fn main , +before device autoconfiguration. +.Pp +Each device in the system uses a +.Dq softc +structure which contains autoconfiguration and state information for that +device. +In the case of disks, the softc should also contain one instance +of the disk structure, e.g.: +.Bd -literal +struct foo_softc { + struct device *sc_dev; /* generic device information */ + struct disk *sc_dk; /* generic disk information */ + [ . . . more . . . ] +}; +.Ed +.Pp +In order for the system to gather metrics data about a disk, the disk must +be registered with the system. +The +.Fn disk_attach +routine performs all of the functions currently required to register a disk +with the system including allocation of disklabel storage space, +recording of the time since boot that the disk was attached, and insertion +into the disklist. +Note that since this function allocates storage space +for the disklabel, it must be called before the disklabel is read from the +media or used in any other way. +Before +.Fn disk_attach +is called, a portion of the disk structure must be initialized with +data specific to that disk. +For example, in the +.Dq foo +disk driver, the following would be performed in the autoconfiguration +.Dq attach +routine: +.Bd -literal +void +fooattach(struct device *parent, struct device *self, void *aux) +{ + struct foo_softc *sc = (struct foo_softc *)self; + [ . . . ] + + /* Initialize and attach the disk structure. */ + sc->sc_dk.dk_driver = &foodkdriver; + sc->sc_dk.dk_name = sc->sc_dev.dv_xname; + disk_attach(&sc->sc_dk); + + /* Read geometry and fill in pertinent parts of disklabel. */ + [ . . . ] +} +.Ed +.Pp +The +.Nm foodkdriver +above is the disk's +.Dq driver +switch. +This switch currently includes a pointer to the disk's +.Dq strategy +routine. +This switch needs to have global scope and should be initialized as follows: +.Bd -literal +void foostrategy(struct buf *); +struct dkdriver foodkdriver = { foostrategy }; +.Ed +.Pp +Once the disk is attached, metrics may be gathered on that disk. +In order to gather metrics data, the driver must tell the framework +when the disk starts and stops operations. +This functionality is provided by the +.Fn disk_busy +and +.Fn disk_unbusy +routines. +The +.Fn disk_busy +routine should be called immediately before a command to the disk is +sent, e.g.: +.Bd -literal +void +foostart(struct foo_softc *sc) +{ + [ . . . ] + + /* Get buffer from drive's transfer queue. */ + [ . . . ] + + /* Build command to send to drive. */ + [ . . . ] + + /* Tell the disk framework we're going busy. */ + disk_busy(&sc->sc_dk); + + /* Send command to the drive. */ + [ . . . ] +} +.Ed +.Pp +When +.Fn disk_busy +is called, a timestamp is taken if the disk's busy counter moves from +0 to 1, indicating the disk has gone from an idle to non-idle state. +Note that +.Fn disk_busy +must be called at +.Fn splbio . +At the end of a transaction, the +.Fn disk_unbusy +routine should be called. +This routine performs some consistency checks, +such as ensuring that the calls to +.Fn disk_busy +and +.Fn disk_unbusy +are balanced. +This routine also performs the actual metrics calculation. +A timestamp is taken, and the difference from the timestamp taken in +.Fn disk_busy +is added to the disk's total running time. +The disk's timestamp is then +updated in case there is more than one pending transfer on the disk. +A byte count is also added to the disk's running total, and if greater than +zero, the number of transfers the disk has performed is incremented. +.Bd -literal +void +foodone(struct foo_xfer *xfer) +{ + struct foo_softc = (struct foo_softc *)xfer->xf_softc; + struct buf *bp = xfer->xf_buf; + long nbytes; + [ . . . ] + + /* + * Get number of bytes transferred. If there is no buf + * associated with the xfer, we are being called at the + * end of a non-I/O command. + */ + if (bp == NULL) + nbytes = 0; + else + nbytes = bp->b_bcount - bp->b_resid; + + [ . . . ] + + /* Notify the disk framework that we've completed the transfer. */ + disk_unbusy(&sc->sc_dk, nbytes); + + [ . . . ] +} +.Ed +.Pp +Like +.Fn disk_busy , +.Fn disk_unbusy +must be called at +.Fn splbio . +.Sh CODE REFERENCES +The disk framework itself is implemented within the file +.Pa sys/kern/subr_disk.c . +Data structures and function prototypes for the framework are located in +.Pa sys/sys/disk.h . +.Pp +The +.Ox +machine-independent SCSI disk and CD-ROM drivers utilize the disk framework. +They are located in +.Pa sys/scsi/sd.c +and +.Pa sys/scsi/cd.c . +.Pp +The +.Ox +.Xr vnd 4 +driver utilizes the detachment capability of the framework. +This is located in +.Pa sys/dev/vnd.c . +.Sh SEE ALSO +.Xr vnd 4 , +.Xr spl 9 +.Sh HISTORY +The +.Ox +generic disk framework first appeared in +.Nx 1.2 . +.Sh AUTHORS +The +.Ox +generic disk framework was architected and implemented within +.Nx +by +.An Jason R. Thorpe Aq Mt thorpej@NetBSD.ORG . diff --git a/static/openbsd/man9/disklabel.9 b/static/openbsd/man9/disklabel.9 new file mode 100644 index 00000000..69ab2a13 --- /dev/null +++ b/static/openbsd/man9/disklabel.9 @@ -0,0 +1,152 @@ +.\" $OpenBSD: disklabel.9,v 1.19 2025/09/15 10:33:02 krw Exp $ +.\" $NetBSD: disklabel.9,v 1.7 1999/03/06 22:09:29 mycroft 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 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 $Mdocdate: September 15 2025 $ +.Dt DISKLABEL 9 +.Os +.Sh NAME +.Nm disklabel , +.Nm readdisklabel , +.Nm writedisklabel , +.Nm setdisklabel , +.Nm bounds_check_with_label +.Nd disk label management routines +.Sh SYNOPSIS +.In sys/param.h +.In sys/disklabel.h +.Ft int +.Fn readdisklabel "dev_t dev" "void (*strat)(struct buf *)" "struct disklabel *lp" "int spoofonly" +.Ft int +.Fn writedisklabel "dev_t dev" "void (*strat)(struct buf *)" "struct disklabel *lp" +.Ft int +.Fn setdisklabel "struct disklabel *olp" "struct disklabel *nlp" "u_int64_t openmask" +.Ft int +.Fn bounds_check_with_label "struct buf *bp" "struct disklabel *lp" +.Sh DESCRIPTION +This collection of routines provides a disklabel management interface to +kernel device drivers. +These routines are classified as machine- or architecture-dependent because +of restrictions imposed by the machine architecture and boot-strapping code +on the location of the label, or because cooperation with other operating +systems requires specialized conversion code. +.Pp +.Fn readdisklabel +attempts to read a disklabel from the device identified by +.Fa dev , +using the device strategy routine passed in +.Fa strat . +Note that a buffer structure is required to pass to the strategy routine; +it needs to be acquired and parametrized for the intended I/O operation, +and disposed of when the operation has completed. +Some fields in the disklabel passed in +.Fa lp +may be pre-initialized by the caller in order to meet device driver +requirements for the I/O operation initiated to get to the disklabel data +on the medium. +In particular, the field +.Dq d_secsize , +if non-zero, is used by +.Fn readdisklabel +to get an appropriately sized buffer to pass to the device strategy routine. +Unspecified fields in +.Fa lp +should be set to zero. +If the medium does not contain a native disklabel that can be read in directly +or +.Fa spoofonly +argument is a true value, +If a disk label is found or can be constructed, a value of 0 is returned. +Otherwise the value of the I/O errno encountered is returned. +.Pp +.Fn writedisklabel +stores disk label information contained in the disk label structure given by +.Fa lp +on the device identified by +.Fa dev . +Like +.Fn readdisklabel , +it acquires and sets up an I/O buffer to pass to the strategy routine +.Fa strat . +.Fn writedisklabel +returns 0 on success and +.Dv EINVAL +if the disk label specifies invalid or unconvertible values. +Otherwise, any error condition reported by the device strategy routine +in the buffer's +.Dq Va b_error +field is returned. +.Pp +.Fn setdisklabel +checks a proposed new disk label passed in +.Fa nlp +for some amount of basic sanity. +This includes a check on attempts to +change the location, or reduce the size, of an existing disk partition +that is currently in use by the system. +The current disposition of the disk partitions is made available through +.Fa olp +and +.Fa openmask , +which provide, respectively, the existing disk label and a bit mask +identifying the partitions that are currently in use. +Failure to pass on +.Dq basic sanity , +results in a +.Dv EINVAL +return value, while a vetoed update of the partition layout is signalled by a +.Dv EBUSY +return value. +Otherwise, 0 is returned. +.Pp +.Fn bounds_check_with_label +is used to check whether a device transfer described by +.Fa bp +to the device identified by +.Fa dev , +is properly contained within a disk partition of the disk with label +.Fa lp . +If this check fails, +.Fn bounds_check_with_label +sets the buffer's +.Dq Va b_error +field to +.Dv EINVAL +and sets the +.Dv B_ERROR +flag in +.Dq Va b_flags . +A value of \-1 is returned if any of the bound checks failed, +a null transfer was attempted, +or transfer was attempted exactly at the end of the disk partition. +Otherwise the value of 0 is returned. +.Sh SEE ALSO +.Xr disklabel 5 , +.Xr disklabel 8 , +.Xr fdisk 8 diff --git a/static/openbsd/man9/dma_alloc.9 b/static/openbsd/man9/dma_alloc.9 new file mode 100644 index 00000000..5f0f74e7 --- /dev/null +++ b/static/openbsd/man9/dma_alloc.9 @@ -0,0 +1,74 @@ +.\" $OpenBSD: dma_alloc.9,v 1.8 2022/03/31 17:27:23 naddy Exp $ +.\" $NetBSD: pool.9,v 1.18 2001/06/21 11:59:01 wiz Exp $ +.\" +.\" Copyright (c) 2011 Theo de Raadt +.\" 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 $Mdocdate: March 31 2022 $ +.Dt DMA_ALLOC 9 +.Os +.Sh NAME +.Nm dma_alloc , +.Nm dma_free +.Nd DMA-safe memory allocator +.Sh SYNOPSIS +.In sys/types.h +.In sys/pool.h +.Ft void * +.Fo dma_alloc +.Fa "size_t size" +.Fa "int flags" +.Fc +.Ft void +.Fo dma_free +.Fa "void *m" +.Fa "size_t size" +.Fc +.Sh DESCRIPTION +This allocator provides DMA-safe memory managed using the +.Xr pool 9 +interface. +It is safe to call in most contexts and is +typically used for temporary buffers up to 65536 bytes. +When buffers are used many times, it may be better to consider +using other DMA-safe allocators. +.Pp +Interrupt protection is set to +.Va IPL_VM +using +.Xr pool_init 9 . +.Pp +The +.Ar flags +argument is a selection of +.Xr pool_get 9 +flag arguments. +.Pp +The same +.Va size +argument must be passed to both +.Fn dma_alloc +and the subsequent +.Fn dma_free . +Allocations over 65536 will fail. +.Sh SEE ALSO +.Xr bus_dma 9 , +.Xr mbuf 9 , +.Xr pool 9 +.Sh HISTORY +The +.Nm +interface first appeared in +.Ox 4.8 . diff --git a/static/openbsd/man9/dohooks.9 b/static/openbsd/man9/dohooks.9 new file mode 100644 index 00000000..a8a69e91 --- /dev/null +++ b/static/openbsd/man9/dohooks.9 @@ -0,0 +1,71 @@ +.\" $OpenBSD: dohooks.9,v 1.8 2015/12/12 11:26:32 mpi Exp $ +.\" +.\" Copyright (c) 2001 Niklas Hallqvist. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must 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 $Mdocdate: December 12 2015 $ +.Dt DOHOOKS 9 +.Os +.Sh NAME +.Nm dohooks +.Nd run all hooks in a list +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void +.Fn dohooks "struct hook_desc_head *head" "int flags" +.Sh DESCRIPTION +The +.Fn dohooks +function invokes all hooks established using the +.Xr hook_establish 9 +function. +Hooks are called in the order of the TAILQ that +.Fa head +points to, however +.Xr hook_establish 9 +can put the hooks either at the head or the tail of that queue, +making it possible to call the hooks either in the order of +establishment, or its reverse. +.Pp +The flags can specify +.Dv HOOK_REMOVE +to remove already processed hooks from the hook list and +.Dv HOOK_FREE +to also free them. +In most cases either no flags should be used or +.Dv HOOK_REMOVE +and +.Dv HOOK_FREE +at the same time, since just HOOK_REMOVE will drop the only reference to +allocated memory and should only be used in situations where freeing +memory would be illegal and unnecessary. +.Pp +This function is used to implement the +.Xr dostartuphooks 9 +macro. +.Sh SEE ALSO +.Xr dostartuphooks 9 , +.Xr hook_establish 9 diff --git a/static/openbsd/man9/dostartuphooks.9 b/static/openbsd/man9/dostartuphooks.9 new file mode 100644 index 00000000..dfdb8485 --- /dev/null +++ b/static/openbsd/man9/dostartuphooks.9 @@ -0,0 +1,61 @@ +.\" $OpenBSD: dostartuphooks.9,v 1.11 2014/12/10 15:29:52 mikeb Exp $ +.\" +.\" Copyright (c) 2001 Niklas Hallqvist. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must 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 $Mdocdate: December 10 2014 $ +.Dt DOSTARTUPHOOKS 9 +.Os +.Sh NAME +.Nm dostartuphooks +.Nd run all startup hooks +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void +.Fn dostartuphooks "void" +.Sh DESCRIPTION +The +.Fn dostartuphooks +function invokes all startup hooks established using the +.Xr startuphook_establish 9 +function. +Startup hooks are called in order, i.e., +the startup hook established first will be called first. +.Pp +This function is called from +.Fn main +with interrupts turned on. +It is called immediately before the system configures its root and swap +devices, but fully after all normal autoconfiguration. +This can be used to let device subsystems needing delayed configuration (e.g., +due to very long initialization times) still provide the root device. +.Pp +Startup hooks are implemented via the more general +.Xr dohooks 9 +API. +.Sh SEE ALSO +.Xr dohooks 9 , +.Xr startuphook_establish 9 diff --git a/static/openbsd/man9/evcount.9 b/static/openbsd/man9/evcount.9 new file mode 100644 index 00000000..e30fa494 --- /dev/null +++ b/static/openbsd/man9/evcount.9 @@ -0,0 +1,230 @@ +.\" $OpenBSD: evcount.9,v 1.8 2022/11/10 07:05:41 jmatthew Exp $ +.\" Written by Jared Yanovich +.\" This file belongs to the public domain, 11/02/2004. +.Dd $Mdocdate: November 10 2022 $ +.Dt EVCOUNT 9 +.Os +.Sh NAME +.Nm evcount , +.Nm evcount_attach , +.Nm evcount_detach , +.Nm evcount_percpu , +.Nm evcount_inc +.Nd generic interrupt and event counter kernel API +.Sh SYNOPSIS +.In sys/evcount.h +.Ft void +.Fn evcount_attach "struct evcount *ec" "const char *name" "void *data" +.Ft void +.Fn evcount_percpu "struct evcount *ec" +.Ft void +.Fn evcount_inc "struct evcount *ec" +.Ft void +.Fn evcount_detach "struct evcount *ec" +.Sh DESCRIPTION +The +.Nm +API provides an interface for generic event and interrupt counting, +whose statistics are made available to machine-independent +.Xr sysctl 2 +nodes. +.Ss Overview +With +.Nm , +an architecture can collect interrupt counting for any device. +All registered counters will be made available under the +.Va kern.evcount +.Xr sysctl 2 +node as a flat list. +The following is a sample list of counters provided by some +common architectures: +.Pp +.Bl -tag -width 8n -offset indent -compact +.It clock +Interrupt counter for the system clock +.It stat +Second-level interrupt decrementer counter +.It rtc +Real-time clock counter +.It prof +System profiler counter +.It pciide0 +PCI IDE controller counter (see +.Xr pciide 4 ) +.It uhci0 +USB 1.0 controller counter (see +.Xr usb 4 ) +.El +.Pp +See +.Xr intro 4 +for a list of devices for any of which +.Nm +may track interrupt counting. +.Pp +The +.Xr systat 1 +and +.Xr vmstat 8 +utilities can be used to view interrupts collected by +.Nm . +.Ss The API +The +.Vt evcount +structure has the following definition: +.Bd -literal -offset indent +struct evcount { + u_int64_t ec_count; /* main counter */ + int ec_id; /* counter ID */ + const char *ec_name; /* counter name */ + void *ec_data; /* user data */ + struct cpumem *ec_cpumem; /* per-cpu counter */ + + TAILQ_ENTRY(evcount) next; +}; +.Ed +.Pp +The +.Fn evcount_attach ec name data +function adds the given event counter to the system's counter list. +.Fa name +provides the counter name, which is modeled after a +device, such as +.Dq clock +or +.Dq pciide0 . +.Fa data +provides a chunk of data that will be made available through the +.Xr sysctl 2 +call. +.Pp +The +.Fn evcount_percpu ec +function configures +.Fa ec +with one counter for each CPU in the system. +It should be used when +.Fa ec Ns 's +corresponding interrupt can occur simultaneously on multiple CPUs. +It must be called immediately after +.Fn evcount_attach +is called for a given counter. +.Pp +The +.Fn evcount_inc ec +function increments the given counter. +.Pp +The +.Fn evcount_detach ec +function removes the given event counter +.Fa ec +from the counter list. +.Sh EXAMPLES +The following is an outline of code that provides routines to register +and de-register interrupt handlers for devices, plugging the counting of +interrupts generated by them during system operation into the +.Nm +framework. +.Bd -literal +#include +#include + +/* + * machine/intr.h provides a structure, intrhand, which is + * machine-dependent but is usually similar to this: + * + * struct intrhand { + * int (*ih_fun)(void *); + * void *ih_arg; + * int ih_level; + * struct intrhand *ih_next; + * int ih_irq; + * struct evcount ih_count; + * } + */ + +/* + * Register an interrupt handler. + */ +void * +intr_establish(void *lcv, int irq, int type, int level, + int (*ih_fun)(void *), void *ih_arg, char *name) +{ + struct intrhand *ih, **p; + + /* + * Allocate memory for the handler, sanity-check incoming + * values (IRQ#, etc.), and link the handler into + * machine-dependent data structures. + */ + + /* + * Fill out the handler. + */ + ih->ih_fun = ih_fun; + ih->ih_arg = ih_arg; + ih->ih_next = NULL; + ih->ih_level = level; + ih->ih_irq = irq; + + /* + * Attach it. + */ + evcount_attach(&ih->ih_count, name, &ih->ih_irq); + + return (ih); +} + +/* + * Deregister an interrupt handler. + */ +void +intr_disestablish(void *lcp, void *arg) +{ + struct intrhand *ih = arg; + + /* + * Sanity-check incoming values (IRQ, etc.) and remove + * the interrupt handler from machine-dependent data + * structures. + */ + + evcount_detach(&ih->ih_count); + + /* + * Free up memory and install a null interrupt handler. + */ +} +.Ed +.Pp +An interrupt handler for a device will be registered during +.Xr autoconf 9 +with a call to the above +.Fn intr_establish . +.Pp +The main external interrupt handler, which handles all system +interrupts, will select the appropriate handler for the device +that created the interrupt when an interrupt is generated. +In this case, the handler is the routine assigned to +.Va ih_fun , +and +.Nm +will be made aware of interrupt occurrence. +.Sh SEE ALSO +.Xr systat 1 , +.Xr sysctl 2 , +.Xr queue 3 , +.Xr intro 4 , +.Xr vmstat 8 , +.Xr autoconf 9 , +.Xr counters_alloc 9 +.Sh AUTHORS +.An -nosplit +The +.Nm +API was written by +.An Artur Grabowski +and +.An Aaron Campbell +for +.Ox 3.6 . diff --git a/static/openbsd/man9/extent.9 b/static/openbsd/man9/extent.9 new file mode 100644 index 00000000..734afa53 --- /dev/null +++ b/static/openbsd/man9/extent.9 @@ -0,0 +1,425 @@ +.\" $OpenBSD: extent.9,v 1.20 2024/01/19 22:12:24 kettenis Exp $ +.\" $NetBSD: extent.9,v 1.15 1999/03/16 00:40:47 garbled Exp $ +.\" +.\" Copyright (c) 1996, 1998 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe and Greg Hudson. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 $Mdocdate: January 19 2024 $ +.Dt EXTENT 9 +.Os +.Sh NAME +.Nm extent_create , +.Nm extent_destroy , +.Nm extent_alloc , +.Nm extent_alloc_with_descr , +.Nm extent_alloc_subregion , +.Nm extent_alloc_subregion_with_descr , +.Nm extent_alloc_region , +.Nm extent_alloc_region_with_descr , +.Nm extent_free , +.Nm extent_print +.Nd general purpose extent manager +.Sh SYNOPSIS +.In sys/malloc.h +.In sys/extent.h +.Ft struct extent * +.Fn extent_create "char *name" "u_long start" "u_long end" "int mtype" "caddr_t storage" "size_t storagesize" "int flags" +.Ft void +.Fn extent_destroy "struct extent *ex" +.Ft int +.Fn extent_alloc "struct extent *ex" "u_long size" "u_long alignment" "u_long skew" "u_long boundary" "int flags" "u_long *result" +.Ft int +.Fn extent_alloc_with_descr "struct extent *ex" "u_long size" "u_long alignment" "u_long skew" "u_long boundary" "int flags" "struct extent_region *rp" "u_long *result" +.Ft int +.\" too many arguments for a single .Fn +.Fo extent_alloc_subregion +.Fa "struct extent *ex" +.Fa "u_long substart" +.Fa "u_long subend" +.Fa "u_long size" +.Fa "u_long alignment" +.Fa "u_long skew" +.Fa "u_long boundary" +.Fa "int flags" +.Fa "u_long *result" +.Fc +.Ft int +.\" way too many arguments for a single .Fn +.Fo extent_alloc_subregion_with_descr +.Fa "struct extent *ex" +.Fa "u_long substart" +.Fa "u_long subend" +.Fa "u_long size" +.Fa "u_long alignment" +.Fa "u_long skew" +.Fa "u_long boundary" +.Fa "int flags" +.Fa "struct extent_region *rp" +.Fa "u_long *result" +.Fc +.Ft int +.Fn extent_alloc_region "struct extent *ex" "u_long start" "u_long size" "int flags" +.Ft int +.Fn extent_alloc_region_with_descr "struct extent *ex" "u_long start" "u_long size" "int flags" "struct extent_region *rp" +.Ft int +.Fn extent_free "struct extent *ex" "u_long start" "u_long size" "int flags" +.Ft void +.Fn extent_print "struct extent *ex" +.Sh DESCRIPTION +The extent manager provides management of areas of memory or +other enumerable spaces (such as I/O ports). +An opaque structure called an +.Nm extent map +keeps track of allocated regions within the enumerable space. +.Pp +.Fn extent_create +creates an extent map managing the space from +.Fa start +to +.Fa end +inclusive. +All memory allocation will use the memory type +.Fa mtype +.Po +see +.Xr malloc 9 +.Pc . +The extent map will have the name +.Fa name , +used for identification in case of errors or in +.Xr ddb 4 +.Ic show extents . +If the flag +.Dv EX_NOCOALESCE +is set, internal coalescing of regions is disabled, +and only entire regions may be freed within the extent map, so that +.Fn extent_free +will never have to allocate a region descriptor. +If the flag +.Dv EX_FILLED +is set, the entire space managed by the extent map will be allocated +upon creation of the extent map, such that selected regions may be +made available through calls to +.Fn extent_free . +.Pp +Some applications may want to use an extent map but +can't use +.Fn malloc +and +.Fn free . +These applications may provide pre-allocated storage for +all descriptor overhead with the arguments +.Fa storage +and +.Fa storagesize . +An extent of this type is called a +.Nm fixed extent . +If the application can safely use +.Fn malloc +and +.Fn free , +.Fa storage +should be +.Dv NULL . +A fixed extent has a fixed number of region descriptors, so care +should be taken to provide enough storage for them; alternatively, the +flag +.Dv EX_MALLOCOK +may be passed to extent requests to indicate that a fixed extent +map may be extended using a call to +.Fn malloc . +Note that passing the flag +.Dv EX_FILLED +to +.Fn extent_create +will consume a region descriptor upon creation of the extent map. +.Pp +The caller should pass the flag +.Dv EX_WAITOK +or +.Dv EX_NOWAIT +to extent functions that have a memory overhead, to specify whether +it is okay to wait. +These functions are +.Fn extent_create +(non fixed extents), +.Fn extent_free +(unless +.Dv EX_NOCOALESCE +is set), +.Fn extent_alloc , +.Fn extent_alloc_subregion +and +.Fn extent_alloc_region . +.Pp +.Fn extent_destroy +destroys the extent map +.Fa ex , +freeing all allocated regions. +If the extent is not a fixed extent, +the region and internal extent descriptors themselves are freed. +This function always succeeds. +.Pp +.Fn extent_alloc +allocates a region in the extent map +.Fa ex +of size +.Fa size +that fits the provided parameters. +There are two distinct allocation policies, which are selected by the +.Fa flags +argument: +.Bl -tag -offset indent -width "XXXXXXXXX" +.It Dv EX_FAST +Allocate the first region that fits the provided parameters, regardless +of resulting extent fragmentation. +.It default +Allocate the smallest region that is capable of holding the request, +thus minimizing fragmentation of the extent. +.El +.Pp +The caller may specify that it is okay to wait for space to become free in the +extent by setting the flag +.Dv EX_WAITSPACE . +If +.Dv EX_WAITSPACE +is not set, the allocation will fail if the request cannot be +satisfied without sleeping. +.Pp +The request will be aligned to a multiple of +.Fa alignment . +That value must be a power of 2. +If no alignment is necessary, the value +.Dv EX_NOALIGN +should be specified. +If +.Fa skew +is non-zero, it modifies the requested alignment result in the following way: +the value +.Pq Fa result No - Fa skew +is aligned to +.Fa alignment +boundaries. +.Fa skew +must be a smaller number than +.Fa alignment . +If +.Fa boundary +is not +.Dv EX_NOBOUNDARY , +the allocated region will not cross any boundary lines, spaced +.Fa boundary +apart. +If the caller specifies the +.Dv EX_BOUNDZERO +flag, boundary lines begin at zero. +Otherwise, boundary lines begin at the beginning of the extent. +The allocated region may begin on a +boundary line, but the end of the region will not touch nor cross a +boundary line. +A +.Fa boundary +argument smaller than the sum of the requested skew and the size of +the request is invalid. +Upon successful completion, +.Fa *result +will contain the start of the allocated region. +.Pp +.Fn extent_alloc_with_descr +is similar to +.Fn extent_alloc +but allows the caller to provide a pre-allocated region descriptor instead +of having the function allocate one. +This function can only be used with extents that have the +.Dv EX_NOCOALESCE +property. +.Pp +.Fn extent_alloc_subregion +and +.Fn extent_alloc_subregion_with_descr +are generalized versions of +.Fn extent_alloc +and +.Fn extent_alloc_with_descr +that allow the caller to specify that the allocated region must fall +within the subregion from +.Fa substart +to +.Fa subend +inclusive. +.Pp +.Fn extent_alloc_region +allocates the specific region in the extent map +.Fa ex +beginning at +.Fa start +with the size +.Fa size . +If the caller specifies the +.Dv EX_CONFLICTOK +flag, the allocation will succeed even if part of the requested region +has already been allocated. +The caller may specify that it is okay to wait for the indicated +region to be free by setting the flag +.Dv EX_WAITSPACE . +If neither +.Dv EX_WAITSPACE +nor +.Dv EX_CONFLICTOK +is set, the allocation will fail if the request cannot be +satisfied without sleeping. +.Pp +.Fn extent_alloc_region_with_descr +is similar to +.Fn extent_alloc_region +but allows the caller to provide a pre-allocated region descriptor instead +of having the function allocate one. +This function can only be used with extents that have the +.Dv EX_NOCOALESCE +property. +.Pp +.Fn extent_free +frees a region of +.Fa size +bytes starting at +.Fa start +in the extent map +.Fa ex . +If the extent has the +.Dv EX_NOCOALESCE +property, only entire regions may be freed. +If the extent has the +.Dv EX_NOCOALESCE +property and the caller attempts to free a partial region, behavior is +undefined. +If called on an extent without the +.Dv EX_NOCOALESCE +property, this function can fail with error codes listed below, otherwise +this function will always succeed. +.Pp +.Fn extent_print +Prints out information about extent +.Fa ex . +This function always succeeds. +.Sh RETURN VALUES +The behavior of all extent manager functions is undefined if given +invalid arguments. +.Fn extent_create +returns the extent map on success, or +.Dv NULL +if it fails to allocate storage for the extent map. +It always succeeds when creating a fixed extent or when given the flag +.Dv EX_WAITOK . +.Fn extent_alloc , +.Fn extent_alloc_region , +.Fn extent_alloc_subregion , +and +.Fn extent_free +return one of the following values: +.Bl -tag -offset indent -width "XXXXXXXX" +.It Dv 0 +Operation was successful. +.It Dv ENOMEM +If +.Dv EX_NOWAIT +is specified, the extent manager was not able to allocate a region +descriptor for the new region or to split a region when freeing a +partial region. +.It Dv EAGAIN +Requested region is not available and +.Dv EX_WAITSPACE +was not specified. +.It Dv EINTR +Process received a signal while waiting for the requested region to +become available in the extent. +.El +.Sh EXAMPLES +Here is an example of a (useless) function that uses several of the +extent manager routines. +.Bd -literal +void +func() +{ + struct extent *foo_ex; + u_long region_start; + int error; + + /* + * Extent "foo" manages a 256k region starting at 0x0 and + * only allows complete regions to be freed so that + * extent_free() never needs to allocate memory. + */ + foo_ex = extent_create("foo", 0x0, 0x3ffff, M_DEVBUF, + NULL, 0, EX_WAITOK | EX_NOCOALESCE); + + /* + * Allocate an 8k region, aligned to a 4k boundary, which + * does not cross any of the 3 64k boundaries (at 64k, + * 128k, and 192k) within the extent. + */ + error = extent_alloc(foo_ex, 0x2000, 0x1000, 0x10000, + EX_NOWAIT, ®ion_start); + if (error) + panic("you lose"); + + /* + * Give up the extent. + */ + extent_destroy(foo_ex); +} +.Ed +.\" +.\" Yeah, right... document EX_CATCH first... +.\" +.\" .Sh LIMITATIONS +.\" The flag +.\" .Dv EX_CATCH +.\" cannot be used to catch signals in all circumstances since +.\" .Xr malloc 9 +.\" does not provide such a functionality. +.Sh CODE REFERENCES +The extent manager itself is implemented within the file +.Pa sys/kern/subr_extent.c . +.Pp +The i386 bus management code uses the extent manager for managing I/O +ports and I/O memory. +See +.Pa sys/arch/i386/i386/machdep.c . +.Sh SEE ALSO +.Xr ddb 4 , +.Xr malloc 9 +.Sh HISTORY +The extent manager appeared in +.Nx 1.3 . +.Sh AUTHORS +.An -nosplit +The extent manager was designed and implemented by +.An Jason R. Thorpe Aq Mt thorpej@NetBSD.ORG . +.An Matthias Drochner Aq Mt drochner@zelux6.zel.kfa-juelich.de +contributed to the initial testing and optimization of the implementation. +.An Chris Demetriou Aq Mt cgd@NetBSD.ORG +contributed many architectural suggestions. diff --git a/static/openbsd/man9/fb_setup.9 b/static/openbsd/man9/fb_setup.9 new file mode 100644 index 00000000..87fac07e --- /dev/null +++ b/static/openbsd/man9/fb_setup.9 @@ -0,0 +1,238 @@ +.\" $OpenBSD: fb_setup.9,v 1.7 2017/11/30 11:29:03 helg Exp $ +.\" +.\" Copyright (c) 2013 Sylvestre Gallon +.\" +.\" 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: November 30 2017 $ +.Dt FB_SETUP 9 +.Os +.Sh NAME +.Nm fb_setup , +.Nm fb_queue , +.Nm fb_delete +.Nd kernel messaging mechanism for file system in userland (FUSE) +.Sh SYNOPSIS +.In sys/fusebuf.h +.Ft struct fusebuf * +.Fn fb_setup "size_t size" "ino_t inode" "int type" "struct proc *p" +.Ft int +.Fn fb_queue "dev_t dev" "struct fusebuf *fbuf" +.Ft void +.Fn fb_delete "struct fusebuf *fbuf" +.Bd -literal +#define FUSEBUFMAXSIZE (4096*1024) +#define FUSEBUFSIZE (sizeof(struct fusebuf)) + +struct fb_hdr { + SIMPLEQ_ENTRY(fusebuf) fh_next; + size_t fh_len; + int fh_err; + int fh_type; + ino_t fh_ino; + uint64_t fh_uuid; +}; + +struct fb_io { + uint64_t fi_fd; + ino_t fi_ino; + off_t fi_off; + size_t fi_len; + mode_t fi_mode; + uint32_t fi_flags; +}; + +struct fusebuf { + struct fb_hdr fb_hdr; + union { + struct statvfs FD_stat; + struct stat FD_attr; + struct fb_io FD_io; + + } FD; + uint8_t *fb_dat; +}; + +#define fb_next fb_hdr.fh_next +#define fb_len fb_hdr.fh_len +#define fb_err fb_hdr.fh_err +#define fb_type fb_hdr.fh_type +#define fb_ino fb_hdr.fh_ino +#define fb_uuid fb_hdr.fh_uuid + +#define fb_stat FD.FD_stat +#define fb_attr FD.FD_attr +#define fb_io_fd FD.FD_io.fi_fd +#define fb_io_ino FD.FD_io.fi_ino +#define fb_io_off FD.FD_io.fi_off +#define fb_io_len FD.FD_io.fi_len +#define fb_io_mode FD.FD_io.fi_mode +#define fb_io_flags FD.FD_io.fi_flags +.Ed +.Sh DESCRIPTION +These functions provide a way to manage the kernel messaging mechanism for +.Xr fuse 4 +file systems. +It is based on +.Xr mbuf 9 . +.Pp +Each FUSE operation fits in a fusebuf +except for read, write, and readdirs, +which are split into several fusebufs with a changing value in +.Fa fb_io_off +for each. +The size of a fusebuf is +.Fa FUSEBUFSIZE . +.Pp +A fusebuf structure is defined as an +.Fa fb_hdr +followed by a structure containing a union and a buffer +.Fa F_Dat . +The header contains the following elements: +.Bl -tag -width foobarmoocow +.It Fa fh_next +A +.Xr SIMPLEQ_ENTRY 3 +needed to store the different fusebufs stored with +.Fn fb_queue . +.It Fa fh_len +Indicates the amount of data in +.Fa F_dat . +.It Fa fh_resid +Used for partial +.Xr fuse 4 +reads. +If the read does not fill the fusebuf, the number of bytes of +.Fa F_dat +written in this field are stored. +.It Fa fh_err +Indicates the +.Xr errno 2 +failure of a fusebuf. +.It Fa fh_type +Indicates the type of fusebuf transaction (see below). +.It Fa fh_ino +Indicates the inode on which the +.Xr fuse 4 +operation is done. +.It Fa fh_uuid +UUID to track the answer. +This number is generated with +.Xr arc4random 9 . +.El +.Pp +The +.Fa fh_type +variable can take the following values: +.Pp +.Bl -tag -compact -offset indent -width XXXXXXXXXXXXXXXXXX +.It Dv FBT_LOOKUP +The fusebuf is a lookup operation. +.It Dv FBT_GETATTR +The fusebuf is a gettattr operation. +.It Dv FBT_SETATTR +The fusebuf is a setattr operation. +.It Dv FBT_READLINK +The fusebuf is a readlink operation. +.It Dv FBT_SYMLINK +The fusebuf is a symlink operation. +.It Dv FBT_MKNOD +The fusebuf is a mknod operation. +.It Dv FBT_MKDIR +The fusebuf is a mkdir operation. +.It Dv FBT_UNLINK +The fusebuf is an unlink operation. +.It Dv FBT_RMDIR +The fusebuf is an rmdir operation. +.It Dv FBT_RENAME +The fusebuf is a rename operation. +.It Dv FBT_LINK +The fusebuf is a link operation. +.It Dv FBT_OPEN +The fusebuf is an open operation. +.It Dv FBT_READ +The fusebuf is a read operation. +.It Dv FBT_WRITE +The fusebuf is a write operation. +.It Dv FBT_STATFS +The fusebuf is a statfs operation. +.It Dv FBT_RELEASE +The fusebuf is a file close operation. +.It Dv FBT_FSYNC +The fusebuf is a file sync operation. +.It Dv FBT_FLUSH +The fusebuf is a flush operation. +.It Dv FBT_INIT +The fusebuf initializes the FUSE connection. +.It Dv FBT_OPENDIR +The fusebuf is an opendir operation. +.It Dv FBT_READDIR +The fusebuf is a readdir operation. +.It Dv FBT_RELEASEDIR +The fusebuf is a close dir operation. +.It Dv FBT_FSYNCDIR +The fusebuf is a dir sync operation. +.It Dv FBT_ACCESS +The fusebuf is an access operation. +.It Dv FBT_DESTROY +The fusebuf closes the FUSE connection. +.El +.Pp +All the data needed by the FUSE clients is contained in the +.Fa F_dat +structure. +This structure contains a union +.Fa FD +of frequently used type +and a buffer +.Fa F_databuf +to send data to libfuse. +The union contains the following elements: +.Bl -tag -width foobarmoocow +.It Fa FD_stat +A struct +.Xr statvfs 3 +filled in by the FUSE client statfs for the FUSE VFS statfs code. +.It Fa FD_attr +Used by the getattr and setattr calls. +.It Fa FD_io +Contains all fields commonly used by FUSE client callbacks to +provide information to FUSE vnops. +It is used by access, readdir, release, releasedir, read, write, +mkdir, and setattr. +.El +.Pp +Setattr uses a struct fb_io and a struct stat. +Settattr uses +.Fa FD_stat +and encapsulates a struct fb_io in +.Fa F_databuf +with +.Fa fbtod . +.Pp +Fusebufs can be deleted with the +.Fn fb_delete +helper. +.Sh SEE ALSO +.Xr errno 2 , +.Xr fuse_main 3 , +.Xr queue 3 , +.Xr statvfs 3 , +.Xr fuse 4 , +.Xr arc4random 9 , +.Xr mbuf 9 +.Sh HISTORY +The +.Nm +API first appeared in +.Ox 5.4 . diff --git a/static/openbsd/man9/ffs.9 b/static/openbsd/man9/ffs.9 new file mode 100644 index 00000000..c41f18ac --- /dev/null +++ b/static/openbsd/man9/ffs.9 @@ -0,0 +1,68 @@ +.\" $OpenBSD: ffs.9,v 1.2 2022/09/10 08:18:06 jsg Exp $ +.\" +.\" Copyright (c) 2002, 2003 CubeSoft Communications, 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, 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 $Mdocdate: September 10 2022 $ +.Dt FFS 9 +.Os +.Sh NAME +.Nm ffs , +.Nm fls , +.Nm flsl +.Nd kernel library find bit routines +.Sh SYNOPSIS +.In lib/libkern/libkern.h +.Ft int +.Fn ffs "int value" +.Ft int +.Fn fls "int value" +.Ft int +.Fn flsl "long value" +.Sh DESCRIPTION +The +.Fn ffs +function finds the first bit set in +.Fa value . +It has the same semantics as its libc counterpart +.Xr ffs 3 . +.Pp +The +.Fn fls +and +.Fn flsl +functions find the last bit set in +.Fa value +and return the index of that bit. +.Sh SEE ALSO +.Xr ffs 3 +.Sh STANDARDS +The +.Fn ffs +function conforms to +.St -p1003.1-2008 . +.Sh HISTORY +The +.Fn ffs +function is based on a vax instruction of the same name. diff --git a/static/openbsd/man9/file.9 b/static/openbsd/man9/file.9 new file mode 100644 index 00000000..22c7466c --- /dev/null +++ b/static/openbsd/man9/file.9 @@ -0,0 +1,154 @@ +.\" $OpenBSD: file.9,v 1.23 2024/11/09 15:54:14 matthieu Exp $ +.\" +.\" Copyright (c) 2002 Artur Grabowski +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the 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 $Mdocdate: November 9 2024 $ +.Dt FALLOC 9 +.Os +.Sh NAME +.Nm falloc , +.Nm fdrelease , +.Nm FREF , +.Nm FRELE , +.Nm fd_getfile , +.Nm fd_getfile_mode , +.Nm fd_checkclosed , +.Nm getsock , +.Nm getvnode +.Nd an overview of file descriptor handling +.Sh SYNOPSIS +.In sys/file.h +.In sys/filedesc.h +.Ft int +.Fn falloc "struct proc *p" "struct file **resultfp" "int *resultfd" +.Ft int +.Fn fdrelease "struct proc *p" "int fd" +.Ft void +.Fn FREF "struct file *fp" +.Ft int +.Fn FRELE "struct file *fp" "struct proc *p" +.Ft struct file * +.Fn fd_getfile "struct filedesc *fdp" "int fd" +.Ft struct file * +.Fn fd_getfile_mode "struct filedesc *fdp" "int fd" "int mode" +.Ft int +.Fn fd_checkclosed "struct filedesc *fdp" "int fd" "struct file *fp" +.Ft int +.Fn getsock "struct proc *p" "int fd" "struct file **fpp" +.In sys/file.h +.In sys/filedesc.h +.In sys/vnode.h +.Ft int +.Fn getvnode "struct proc *p" "int fd" "struct file **fpp" +.Sh DESCRIPTION +These functions provide the interface for the UNIX file descriptors. +File descriptors can be used to access vnodes (see +.Xr vnode 9 ) , +sockets (see +.Xr socket 2 ) , +pipes (see +.Xr pipe 2 ) , +kqueues (see +.Xr kqueue 2 ) , +and various special purpose communication endpoints. +.Pp +A new file and a file descriptor for it are allocated with the function +.Fn falloc . +The larval file and fd are returned via +.Fa resultfp +and +.Fa resultfd , +which must not be +.Dv NULL . +.Fn falloc +initializes the new file to have a reference count of two: +one for the reference from the file descriptor table and one +for the caller to release with +.Fn FRELE +when it's done initializing it. +.Pp +A file descriptor is freed with +.Fn fdrelease . +This releases the reference that it holds to the underlying file; +if that's the last reference then the file will be freed. +.\" with +.\" .Xr closef 9 . +The file descriptor table has to be locked on entry. +.Fn fdrelease +unlocks the table on return. +.Pp +The files are extracted from the file descriptor table using the +function +.Fn fd_getfile . +.Fn fd_getfile +performs all necessary checks to see if the file descriptor number is +within the range of file descriptor table, and if the descriptor is +valid. +It also increases the descriptor's use count with +.Fn FREF . +.Pp +.Fn fd_getfile_mode +is like +.Fn fd_getfile +but also checks if the file has been opened with the given mode. +.Pp +.Fn fd_checkclosed +checks if file descriptor +.Fa fd +has been closed and no longer points to file +.Fa fp . +The file must have been retrieved from the descriptor previously. +.Pp +The files are extracted from the process context using the +function +.Fn getsock +and +.Fn getvnode . +These functions are special cases that besides doing +.Fn fd_getfile +also check if the descriptor is a socket or a vnode respectively, +and return the proper errno on error. +.Sh CONCURRENT ACCESS +Since multiple processes can share the same file descriptor table, +it's important that the file is not freed in one process while some +other process is still accessing it. +To solve that problem a special use count is kept with the functions +.Fn FREF +and +.Fn FRELE . +The function +.Fn FREF +increases the use count of a file descriptor. +The function +.Fn FRELE +decreases the use count, and releases the file descriptor if the use count +becomes zero. +.Sh CODE REFERENCES +The majority of those functions are implemented in +.Pa sys/kern/kern_descrip.c . +The function prototypes and the macros are located in +.Pa sys/sys/file.h +and +.Pa sys/sys/filedesc.h . +.Sh SEE ALSO +.Xr vnode 9 diff --git a/static/openbsd/man9/fork1.9 b/static/openbsd/man9/fork1.9 new file mode 100644 index 00000000..e592b902 --- /dev/null +++ b/static/openbsd/man9/fork1.9 @@ -0,0 +1,167 @@ +.\" $OpenBSD: fork1.9,v 1.32 2022/12/29 06:49:34 jmc Exp $ +.\" $NetBSD: fork1.9,v 1.3 1999/03/16 00:40:47 garbled Exp $ +.\" +.\" Copyright (c) 1998 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. +.\" +.Dd $Mdocdate: December 29 2022 $ +.Dt FORK1 9 +.Os +.Sh NAME +.Nm fork1 +.Nd create a new process +.Sh SYNOPSIS +.In sys/types.h +.In sys/proc.h +.Ft int +.Fo fork1 +.Fa "struct proc *p1" +.Fa "int flags" +.Fa "void (*func)(void *)" +.Fa "void *arg" +.Fa "register_t *retval" +.Fa "struct proc **rnewprocp" +.Fc +.Sh DESCRIPTION +.Fn fork1 +creates a new process out of +.Ar p1 , +which should be the current thread. +This function is used primarily to implement the +.Xr fork 2 +and +.Xr vfork 2 +system calls, as well as the +.Xr kthread_create 9 +function. +.Pp +The +.Ar flags +argument is used to control the behavior of the fork and is created by +a bitwise-OR of the following values: +.Bl -tag -width FORK_SHAREFILES +.It Dv FORK_FORK +The call is done by the +.Xr fork 2 +system call. +Used only for statistics. +.It Dv FORK_VFORK +The call is done by the +.Xr vfork 2 +system call. +Used only for statistics. +.It Dv FORK_PPWAIT +Suspend the parent process until the child is terminated (by calling +.Xr _exit 2 +or abnormally), or makes a call to +.Xr execve 2 . +.It Dv FORK_SHAREFILES +Let the child share the file descriptor table with the parent through +.Fn fdshare . +The default behavior is to copy the table through +.Fn fdcopy . +.It Dv FORK_IDLE +The new thread will be left in the +.Dv SIDL +state. +The default behavior is to make it runnable and add it to the run queue. +.It Dv FORK_NOZOMBIE +The child will be dissociated from the parent and will not leave a status +for the parent to collect. +See +.Xr wait 2 . +.It Dv FORK_SHAREVM +The child will share the parent's address space. +The default behavior is +that the child gets a copy-on-write copy of the address space. +.It Dv FORK_SYSTEM +The child will be marked as a system process. +.It Dv FORK_PTRACE +The child will start with tracing enabled, as if +ptrace(PT_TRACE_ME, 0, 0, 0) had been invoked in the child. +.El +.Pp +The new thread will begin execution by calling +.Fa func , +which must not be +.Dv NULL . +If +.Fa arg +is not +.Dv NULL , +it is passed as the argument to +.Fa func . +Otherwise, a pointer to the new process's only thread is passed. +.Pp +If +.Fa retval +is not +.Dv NULL , +the PID of the child process will be stored in +.Fa *retval +on successful completion. +.Pp +If +.Fa rnewprocp +is not +.Dv NULL , +the newly created thread is stored in +.Fa *rnewprocp +on successful completion. +.Sh RETURN VALUES +Upon successful completion of the fork operation, +.Fn fork1 +returns 0. +Otherwise, the following error values are returned: +.Bl -tag -width [EAGAIN] +.It Bq Er EAGAIN +The system limits on the total number of threads or processes would +be exceeded. +.It Bq Er EAGAIN +The limit +.Dv RLIMIT_NPROC +on the total number of processes under execution by this +user id would be exceeded. +.It Bq Er ENOMEM +There is insufficient swap space for the new thread. +.El +.Sh SEE ALSO +.Xr execve 2 , +.Xr fork 2 , +.Xr vfork 2 , +.Xr kthread_create 9 , +.Xr psignal 9 , +.Xr tfind 9 +.Sh CAVEATS +The +.Nm +function semantics are specific to +.Ox . +Other +.Bx +systems have different semantics. diff --git a/static/openbsd/man9/getdevvp.9 b/static/openbsd/man9/getdevvp.9 new file mode 100644 index 00000000..b0376977 --- /dev/null +++ b/static/openbsd/man9/getdevvp.9 @@ -0,0 +1,90 @@ +.\" $OpenBSD: getdevvp.9,v 1.10 2025/09/20 13:56:15 mpi Exp $ +.\" +.\" Copyright (C) 2002 Peter A. Werner. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, 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 $Mdocdate: September 20 2025 $ +.Dt GETDEVVP 9 +.Os +.Sh NAME +.Nm getdevvp , +.Nm bdevvp , +.Nm cdevvp +.Nd create a vnode for a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn getdevvp "dev_t dev" "struct vnode **vpp" "enum vtype type" +.Ft int +.Fn bdevvp "dev_t dev" "struct vnode **vpp" +.Ft int +.Fn cdevvp "dev_t dev" "struct vnode **vpp" +.Sh DESCRIPTION +The +.Fn getdevvp +function creates a vnode for a device of type +.Fa type +with a device number of +.Fa dev , +and returns a pointer to it in +.Fa vpp . +.Pp +Its arguments are: +.Bl -tag -width "rootrefs" +.It Fa dev +The device number of the desired device. +.It Fa vpp +Where the vnode will be returned on success. +.It Fa type +The type of device, either: +.Bl -tag -width "VBLK" +.It Dv VBLK +For a block device, or +.It Dv VCHR +for a character device. +.El +.El +.Pp +.Fn bdevvp +and +.Fn cdevvp +use getdevvp internally, specifying the third argument. +.Fn bdevvp +will create a vnode for a block device, and is used for the root file system +and swap areas, among other things. +.Fn cdevvp +will create a vnode for a character device and is used in console handling. +.Sh RETURN VALUES +All functions return 0 on success. +If an error occurs, vpp will point to +.Dv NULL . +See +.Xr getnewvnode 9 +for further return values. +.Sh SEE ALSO +.Xr getnewvnode 9 , +.Xr vnode 9 diff --git a/static/openbsd/man9/getnewvnode.9 b/static/openbsd/man9/getnewvnode.9 new file mode 100644 index 00000000..e531070c --- /dev/null +++ b/static/openbsd/man9/getnewvnode.9 @@ -0,0 +1,83 @@ +.\" $OpenBSD: getnewvnode.9,v 1.11 2020/11/14 10:35:58 jmc Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/getnewvnode.9,v 1.1 2001/12/02 02:13:35 alfred Exp $ +.\" +.Dd $Mdocdate: November 14 2020 $ +.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 +.Fo getnewvnode +.Fa "enum vtagtype tag" +.Fa "struct mount *mp" +.Fa "const struct vops *vops" +.Fa "struct vnode **vpp" +.Fc +.Sh DESCRIPTION +The +.Fn getnewvnode +function initializes a new vnode, assigning it the vnode operations passed in +.Fa vops . +It will have its v_tag field set to +.Fa tag +and be placed in the mount queue for the mount point represented by +.Fa mp . +.Pp +The vnode is either freshly allocated, taken from the free list or taken from +the hold list. +If there are no vnodes on the free list, half the time a vnode +referencing buffers will be taken from the hold list, otherwise it will be +freshly allocated. +.Pp +The arguments to +.Fn getnewvnode +are: +.Bl -tag -width "vops" +.It Fa tag +The file system type. +.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, or ENFILE if the vnode table is full. +.Sh AUTHORS +This man page was originally written by +.An Chad David Aq Mt davidc@acns.ab.ca +for +.Fx . diff --git a/static/openbsd/man9/getsn.9 b/static/openbsd/man9/getsn.9 new file mode 100644 index 00000000..20487427 --- /dev/null +++ b/static/openbsd/man9/getsn.9 @@ -0,0 +1,48 @@ +.\" $OpenBSD: getsn.9,v 1.2 2018/04/25 11:15:58 dlg Exp $ +.\" +.\" Copyright (c) 2002, 2003 CubeSoft Communications, 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, 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 $Mdocdate: April 25 2018 $ +.Dt GETSN 9 +.Os +.Sh NAME +.Nm getsn +.Nd read user input from the console +.Sh SYNOPSIS +.In lib/libkern/libkern.h +.Ft size_t +.Fn getsn "char *cp" "size_t size" +.Sh DESCRIPTION +The +.Fn getsn +function reads user input from the console and returns on newline. +The result is written into +.Fa cp , +which is assumed to be +.Fa size +bytes long. +.Sh RETURN VALUES +.Fn getsn +returns the total length of the string it tried to create. diff --git a/static/openbsd/man9/hardclock.9 b/static/openbsd/man9/hardclock.9 new file mode 100644 index 00000000..a53388f4 --- /dev/null +++ b/static/openbsd/man9/hardclock.9 @@ -0,0 +1,77 @@ +.\" $OpenBSD: hardclock.9,v 1.13 2020/06/26 18:48:31 cheloha Exp $ +.\" +.\" Copyright (c) 2001 Kenneth R Westerback +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR OR HIS RELATIVES BE 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 $Mdocdate: June 26 2020 $ +.Dt HARDCLOCK 9 +.Os +.Sh NAME +.Nm hardclock +.Nd real-time system clock +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fo hardclock +.Fa "struct clockframe *frame" +.Fc +.Sh DESCRIPTION +.Fn hardclock +implements the real-time system clock, interrupting +.Xr hz 9 +times a second. +The argument +.Fa frame +is an opaque, machine dependent structure that encapsulates the +previous machine state. +.Pp +.Fn hardclock +performs a variety of time related housekeeping tasks, such as: +.Bl -bullet -offset indent +.It +If the current process has virtual or profiling interval +timers, update the timers and deliver appropriate signals. +.It +If there is no separate statistics clock, execute +.Fn statclock . +.It +Increment the time of day, implementing any adjustments requested by +.Xr adjtime 2 +or required as a result of running an NTP daemon or other configured +external clock. +.It +Update the real-time timeout queue, calling +.Fn softclock +directly if the current interrupt priority is low enough. +.El +.Sh CODE REFERENCES +.Fn hardclock +is implemented in the file +.Pa sys/kern/kern_clock.c . +.Sh SEE ALSO +.Xr adjtime 2 , +.Xr hz 9 , +.Xr microtime 9 , +.Xr spl 9 , +.Xr timeout 9 diff --git a/static/openbsd/man9/hashinit.9 b/static/openbsd/man9/hashinit.9 new file mode 100644 index 00000000..b19fc58e --- /dev/null +++ b/static/openbsd/man9/hashinit.9 @@ -0,0 +1,91 @@ +.\" $OpenBSD: hashinit.9,v 1.9 2016/09/24 18:59:04 tedu 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. +.\" 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 $Mdocdate: September 24 2016 $ +.Dt HASHINIT 9 +.Os +.Sh NAME +.Nm hashinit , +.Nm hashfree +.Nd kernel hashtable functions +.Sh SYNOPSIS +.In sys/systm.h +.Ft void * +.Fn hashinit "int num" "int type" "int flags" "u_long *mask" +.Ft void +.Fn hashfree "void *hash" "int num" "int type" +.Sh DESCRIPTION +The +.Fn hashinit +function is used to allocate a hashtable of a desired size given by the +.Fa num +argument. +The +.Fn hashinit +function will round this number to the next power of two, and +allocate and initialize the requested hashtable. +The +.Fa type +and +.Fa flags +arguments are passed to the +.Xr malloc 9 +function unchanged. +The +.Fa mask +argument is used to pass back the mask for use with the allocated +hashing table. +.Pp +The +.Fn hashfree +function causes memory allocated by the +.Fn hashinit +function to be released. +The +.Fa num +and +.Fa type +arguments of related calls must match. +.Sh RETURN VALUES +The +.Fn hashinit +function returns a pointer to the allocated and initialized hash table. +.Sh SEE ALSO +.Xr free 9 , +.Xr malloc 9 +.Sh LIMITATIONS +The +.Fn hashinit +function currently only allocates hash tables with LIST bucket pointers +at this time. +Future enhancements to allocate QUEUE bucket pointers may be warranted. +This may necessitate an API change to accommodate. +.Sh HISTORY +The +.Nm +function first appeared in +.Bx 4.4 . diff --git a/static/openbsd/man9/hook_establish.9 b/static/openbsd/man9/hook_establish.9 new file mode 100644 index 00000000..d8a047db --- /dev/null +++ b/static/openbsd/man9/hook_establish.9 @@ -0,0 +1,89 @@ +.\" $OpenBSD: hook_establish.9,v 1.12 2015/12/12 11:26:32 mpi Exp $ +.\" +.\" Copyright (c) 2001 Niklas Hallqvist. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must 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 $Mdocdate: December 12 2015 $ +.Dt HOOK_ESTABLISH 9 +.Os +.Sh NAME +.Nm hook_establish , +.Nm hook_disestablish +.Nd add or remove a hook from a specified list +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void * +.Fn hook_establish "struct hook_desc_head *head" "int tail" "void (*fn)(void *)" "void *arg" +.Ft void +.Fn hook_disestablish "struct hook_desc_head *head" "void *cookie" +.Sh DESCRIPTION +The +.Fn hook_establish +function adds +.Fa fn +to the list of hooks invoked by +.Xr dohooks 9 . +If +.Fa tail +is non-zero, the hook is added to the tail of the list +denoted by the TAILQ_HEAD pointer +.Fa head , +otherwise to the front. +The +.Xr dohooks 9 +function will at its invocation call each hook from the front of this +list. +When invoked, the hook function +.Fa fn +will be passed +.Fa arg +as its only argument. +.Pp +The +.Fn hook_disestablish +function removes the hook described by the opaque pointer +.Fa cookie +from the list of hooks denoted by the TAILQ_HEAD pointer +.Fa head . +If +.Fa cookie +is invalid, the result of +.Fn hook_disestablish +is undefined. +.Pp +The startup and mountroot systems use this API for their +implementation. +.Sh RETURN VALUES +If successful, +.Fn hook_establish +returns an opaque pointer describing the newly established +hook. +Otherwise, it returns +.Dv NULL . +.Sh SEE ALSO +.Xr dohooks 9 , +.Xr dostartuphooks 9 , +.Xr startuphook_establish 9 diff --git a/static/openbsd/man9/hz.9 b/static/openbsd/man9/hz.9 new file mode 100644 index 00000000..c4964dbd --- /dev/null +++ b/static/openbsd/man9/hz.9 @@ -0,0 +1,91 @@ +.\" $OpenBSD: hz.9,v 1.9 2019/01/14 02:05:46 tedu Exp $ +.\" +.\" Copyright (c) 1999 Marc Espie +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list 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 $Mdocdate: January 14 2019 $ +.Dt HZ 9 +.Os +.Sh NAME +.Nm hz , +.Nm tick , +.Nm tickadj , +.Nm stathz , +.Nm profhz +.Nd system time model +.Sh SYNOPSIS +.Vt extern int hz; +.Vt extern int tick; +.Vt extern int tickadj; +.Vt extern int stathz; +.Vt extern int profhz; +.Sh DESCRIPTION +The system is driven by +.Xr hardclock 9 +interrupts, which occur at +.Va hz +frequency, and are used to keep track of real time. +.Pp +On systems where another independent clock is available, it is set at +.Va stathz +frequency, and used to gather timing statistics. +Ideally, it would be better to drive +.Va stathz +with a slightly randomized clock, that is still a fixed number on average, +as this would prevent malicious processes from working around the scheduler. +If a separate clock is not available, +.Va stathz +is set to +.Va hz . +.Pp +If profiling is enabled, the clock normally used to drive +.Va stathz +may be run at a higher rate +.Va profhz , +which must be a multiple of +.Va stathz . +This will give higher resolution profiling information. +.Pp +Normally, +.Xr hardclock 9 +increments +.Va time +by +.Va tick +each time it is called. +If the system clock has drifted, +.Xr adjtime 2 +may be used to skew this increment, but by no more +than ten times +.Va tickadj . +.Pp +These system variables are available by reading +.Dv KERN_CLOCKRATE +from +.Xr sysctl 2 . +.Sh SEE ALSO +.Xr adjtime 2 , +.Xr clock_getres 2 , +.Xr sysctl 2 , +.Xr hardclock 9 , +.Xr microtime 9 diff --git a/static/openbsd/man9/idgen32.9 b/static/openbsd/man9/idgen32.9 new file mode 100644 index 00000000..20926655 --- /dev/null +++ b/static/openbsd/man9/idgen32.9 @@ -0,0 +1,56 @@ +.\" $OpenBSD: idgen32.9,v 1.4 2015/11/23 17:53:57 jmc Exp $ +.\" +.\" Copyright (c) 2008 Damien Miller +.\" 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 $Mdocdate: November 23 2015 $ +.Dt IDGEN32 9 +.Os +.Sh NAME +.Nm idgen32 , +.Nm idgen32_init +.Nd non-repeating ID generation +.Sh SYNOPSIS +.In crypto/idgen.h +.Ft void +.Fn idgen32_init "struct idgen32_ctx *ctx" +.Ft uint32_t +.Fn idgen32 "struct idgen32_ctx *ctx" +.Sh DESCRIPTION +The +.Fn idgen32 +functions provide a facility to generate a stream of 32-bit numbers +that are strongly unpredictable and have a repetition cycle close to +2^32. +Such numbers are useful as protocol identifiers where there are negative +consequences to reusing an ID within a short time period, as may happen +if they are simply assigned at random. +.Pp +The +.Fn idgen32_init +function prepares a context structure for use. +.Pp +The +.Fn idgen32 +function returns a new ID in host byte order. +Note that this function will never return 0 as it often has a special +meaning in network protocols. +.Sh SEE ALSO +.Xr arc4random 9 +.Sh HISTORY +The +.Nm +functions were added in +.Ox 4.4 . diff --git a/static/openbsd/man9/ieee80211.9 b/static/openbsd/man9/ieee80211.9 new file mode 100644 index 00000000..070e7995 --- /dev/null +++ b/static/openbsd/man9/ieee80211.9 @@ -0,0 +1,285 @@ +.\" $OpenBSD: ieee80211.9,v 1.15 2022/03/29 18:15:52 naddy Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211.9,v 1.3 2004/07/07 12:59:39 ru Exp $ +.\" $Id: ieee80211.9,v 1.15 2022/03/29 18:15:52 naddy Exp $ +.\" +.Dd $Mdocdate: March 29 2022 $ +.Dt IEEE80211_IFATTACH 9 +.Os +.Sh NAME +.Nm ieee80211_ifattach , ieee80211_ifdetach , +.Nm ieee80211_mhz2ieee , ieee80211_chan2ieee , ieee80211_ieee2mhz , +.Nm ieee80211_media_init , ieee80211_media_change , ieee80211_media_status , +.Nm ieee80211_watchdog , +.Nm ieee80211_setmode , ieee80211_chan2mode , +.Nm ieee80211_rate2media , ieee80211_media2rate , +.Nm ieee80211_rate2plcp , ieee80211_plcp2rate +.Nd core 802.11 network stack functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_proto.h +.Ft void +.Fn ieee80211_ifattach "struct ifnet *ifp" +.Ft void +.Fn ieee80211_ifdetach "struct ifnet *ifp" +.Ft u_int +.Fn ieee80211_mhz2ieee "u_int freq" "u_int flags" +.Ft u_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 void +.Fo ieee80211_media_init +.Fa "struct ifnet *ifp" "ifm_change_cb_t media_change" +.Fa "ifm_stat_cb_t media_stat" +.Fc +.Ft int +.Fn ieee80211_media_change "struct ifnet *ifp" +.Ft void +.Fn ieee80211_media_status "struct ifnet *ifp" "struct ifmediareq *imr" +.Ft void +.Fn ieee80211_watchdog "struct ifnet *ifp" +.Ft int +.Fn ieee80211_setmode "struct ieee80211com *ic" "enum ieee80211_phymode mode" +.Ft enum ieee80211_phymode +.Fo ieee80211_chan2mode +.Fa "struct ieee80211com *ic" "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" +.Ft u_int8_t +.Fn ieee80211_rate2plcp "u_int8_t rate" "enum ieee80211_phymode mode" +.Ft u_int8_t +.Fn ieee80211_plcp2rate "u_int8_t plcp" "enum ieee80211_phymode mode" +.Sh DESCRIPTION +The +.Nm ieee80211 +collection of functions are used to manage wireless network interfaces in the +system which use the system's software 802.11 network stack. +Most of these functions require that attachment to the stack is performed +before calling. +Several utility functions are also provided; these are safe to call from +any driver without prior initialization. +.Pp +.\" +The +.Fn ieee80211_ifattach +function attaches the network interface +.Fa ifp +to the 802.11 network stack layer. +This function must be called before using any of the +.Nm ieee80211 +functions which need to store driver state across invocations. +The +.Vt struct ifnet +instance pointed to by +.Fa ifp +MUST be an instance of +.Vt struct ieee80211com , +with various fields initialized to tell +.Nm ieee80211 +about its capabilities. +This function performs Ethernet and BPF attachment (by calling +.Fn ether_ifattach +and +.Fn bpfattach ) +on behalf of the caller. +It also implements the +.Vt ifmedia +interface. +.Pp +.\" +The +.Fn ieee80211_ifdetach +function frees any +.Nm ieee80211 +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 ieee80211 +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_init +function initializes media data structures used by the +.Vt ifmedia +interface, for the driver +.Fa ifp . +It must be called by the driver after calling +.Fn ieee80211_ifattach +and before calling most +.Nm ieee80211 +functions. +The +.Fa media_change +and +.Fa media_stat +arguments specify helper functions which will be invoked by the +.Vt ifmedia +framework when the user changes or queries media options, +using a command such as +.Xr ifconfig 8 . +.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_watchdog +function is intended to be called from a driver's +.Va if_watchdog +routine. +It is used to perform periodic cleanup of state within the software 802.11 +stack, as well as timing out scans. +.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 +on the device +.Fa ic . +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 +function performs the reverse of this conversion, +returning the bit rate (in 0.5Mbps units) corresponding to an +.Vt ifmedia +sub-type. +.Pp +.\" +The +.Fn ieee80211_rate2plcp +function converts the bit rate +.Fa rate +(measured in units of 0.5Mbps) to a +.Vt plcp +signal (in msb-first R4-R1 format). +The +.Fn ieee80211_plcp2rate +function performs the reverse of this conversion, +returning the bit rate (in 0.5Mbps units) corresponding to a +.Vt plcp +signal (in msb-first R4-R1 format). +.\" +.Sh SEE ALSO +.Xr ifmedia 4 , +.Xr ieee80211_crypto 9 , +.Xr ieee80211_input 9 , +.Xr ieee80211_ioctl 9 , +.Xr ieee80211_node 9 , +.Xr ieee80211_output 9 , +.Xr ieee80211_proto 9 , +.Xr ieee80211_radiotap 9 , +.Xr rssadapt 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 +and +.Ox 3.6 . +.Sh AUTHORS +.An -nosplit +This 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/openbsd/man9/ieee80211_crypto.9 b/static/openbsd/man9/ieee80211_crypto.9 new file mode 100644 index 00000000..a7411ccc --- /dev/null +++ b/static/openbsd/man9/ieee80211_crypto.9 @@ -0,0 +1,101 @@ +.\" $OpenBSD: ieee80211_crypto.9,v 1.6 2015/11/23 17:53:57 jmc Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_crypto.9,v 1.2 2004/07/07 12:59:39 ru Exp $ +.\" $Id: ieee80211_crypto.9,v 1.6 2015/11/23 17:53:57 jmc Exp $ +.\" +.Dd $Mdocdate: November 23 2015 $ +.Dt IEEE80211_CRYPTO_ATTACH 9 +.Os +.Sh NAME +.Nm ieee80211_crypto_attach , ieee80211_crypto_detach , ieee80211_wep_crypt +.Nd 802.11 WEP encryption functions +.Sh SYNOPSIS +.Ft void +.Fn ieee80211_crypto_attach "struct ifnet *ifp" +.Ft void +.Fn ieee80211_crypto_detach "struct ifnet *ifp" +.Ft struct mbuf * +.Fn ieee80211_wep_crypt "struct ifnet *ifp" "struct mbuf *m0" "int txflag" +.Sh DESCRIPTION +These functions provide software encryption support +for 802.11 device drivers. +.Pp +.\" +The +.Fn ieee80211_crypto_attach +function initializes crypto support for the interface +.Fa ifp , +and sets the initialization vector (IV) for WEP encryption to +a random number derived from a secure PRNG. +.Pp +.\" +The +.Fn ieee80211_crypto_detach +function frees data structures associated with crypto support +for the interface +.Fa ifp . +.Pp +.\" +The +.Fn ieee80211_wep_crypt +function runs the appropriate WEP encryption algorithm over the 802.11 +encapsulated frame held in the mbuf chain +.Fa m0 , +for transmission or reception on the interface +.Fa ifp . +The +.Fa txflag +argument specifies whether the frame is being received or transmitted. +A value of 0 indicates that the frame is being received and should +therefore be decrypted; a non-zero value indicates that the frame +is being transmitted +and should be encrypted. +.\" +.Sh IMPLEMENTATION NOTES +The +.Fn ieee80211_wep_crypt +function stores its IV in the interface's embedded +.Vt struct ieee80211com +instance. +.Sh SEE ALSO +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 +and +.Ox 3.6 . +.Sh AUTHORS +.An -nosplit +This 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/openbsd/man9/ieee80211_input.9 b/static/openbsd/man9/ieee80211_input.9 new file mode 100644 index 00000000..8d2500c3 --- /dev/null +++ b/static/openbsd/man9/ieee80211_input.9 @@ -0,0 +1,115 @@ +.\" $OpenBSD: ieee80211_input.9,v 1.5 2022/03/29 18:15:52 naddy Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_input.9,v 1.2 2004/07/07 12:59:39 ru Exp $ +.\" $Id: ieee80211_input.9,v 1.5 2022/03/29 18:15:52 naddy Exp $ +.\" +.Dd $Mdocdate: March 29 2022 $ +.Dt IEEE80211_INPUT 9 +.Os +.Sh NAME +.Nm ieee80211_input , ieee80211_decap , ieee80211_recv_mgmt +.Nd software 802.11 stack input functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_proto.h +.Ft void +.Fo ieee80211_input +.Fa "struct ifnet *ifp" "struct mbuf *m" "struct ieee80211_node *ni" +.Fa "int rssi" "u_int32_t rstamp" +.Fc +.Ft struct mbuf * +.Fn ieee80211_decap "struct ifnet *ifp" "struct mbuf *m" +.Ft void +.Fo ieee80211_recv_mgmt +.Fa "struct ieee80211com *ic" "struct mbuf *m0" "struct ieee80211_node *ni" +.Fa "int subtype" "int rssi" "u_int32_t rstamp" +.Fc +.Sh DESCRIPTION +These +functions process received 802.11 frames. +.Pp +.\" +The +.Fn ieee80211_input +function takes an mbuf chain +.Fa m +containing a complete 802.11 frame from the driver +.Fa ifp +and passes it to the software 802.11 stack for input processing. +The +.Fa ni +argument specifies an instance of +.Vt struct ieee80211_node +(which may be driver-specific) representing the node from which the +frame was received. +The arguments +.Fa rssi +and +.Fa stamp +are typically derived from on-card data structures; they are used for +recording the signal strength and time received of the frame respectively. +.Pp +.\" +The +.Fn ieee80211_decap +function performs decapsulation of the 802.11 frame in the mbuf chain +.Fa m +received by the device +.Fa ifp , +taking the form of the 802.11 address fields into account; +the structure of 802.11 addresses vary according to the intended +source and destination of the frame. +It is typically called from within +.Fn ieee80211_input . +.Pp +.\" +The +.Fn ieee80211_recv_mgmt +function performs input processing for 802.11 management frames. +It is typically called from within +.Fn ieee80211_input . +.\" +.Sh SEE ALSO +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 +and +.Ox 3.6 . +.Sh AUTHORS +.An -nosplit +This man page was written by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +and +.An Darron Broad Aq Mt darron@kewl.org . +.Sh BUGS +There is no netisr queue specifically for the software 802.11 stack yet. diff --git a/static/openbsd/man9/ieee80211_ioctl.9 b/static/openbsd/man9/ieee80211_ioctl.9 new file mode 100644 index 00000000..380d5959 --- /dev/null +++ b/static/openbsd/man9/ieee80211_ioctl.9 @@ -0,0 +1,82 @@ +.\" $OpenBSD: ieee80211_ioctl.9,v 1.5 2013/07/17 20:21:53 schwarze Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_ioctl.9,v 1.2 2004/07/07 12:59:39 ru Exp $ +.\" $Id: ieee80211_ioctl.9,v 1.5 2013/07/17 20:21:53 schwarze Exp $ +.\" +.Dd $Mdocdate: July 17 2013 $ +.Dt IEEE80211_IOCTL 9 +.Os +.Sh NAME +.Nm ieee80211_ioctl +.Nd 802.11 interface ioctl commands +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_proto.h +.In net80211/ieee80211_ioctl.h +.Ft int +.Fn ieee80211_ioctl "struct ifnet *ifp" "u_long cmd" "caddr_t data" +.Sh DESCRIPTION +These +functions are typically invoked by drivers in response to requests +for information or to change settings from the userland. +.Pp +.\" +The +.Fn ieee80211_ioctl +function provides a default implementation of the +.Dv SIOCS80211 +and +.Dv SIOCG80211 +ifioctls commands for 802.11 drivers. +The call signature is identical to that of the +.Va if_ioctl +member found in +.Vt struct ifnet , +however, many drivers store attributes such as +.Dv IEEE80211_IOC_STATIONNAME +in the driver's private soft state structure, so driver writers may prefer +to use this as the catch-all in a switch statement to avoid code duplication. +.\" +.Sh SEE ALSO +.Xr ifconfig 8 , +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 +and +.Ox 3.6 . +.Sh AUTHORS +.An -nosplit +This 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/openbsd/man9/ieee80211_node.9 b/static/openbsd/man9/ieee80211_node.9 new file mode 100644 index 00000000..2be7738b --- /dev/null +++ b/static/openbsd/man9/ieee80211_node.9 @@ -0,0 +1,267 @@ +.\" $OpenBSD: ieee80211_node.9,v 1.9 2015/11/23 17:53:57 jmc Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_node.9,v 1.3 2004/07/07 12:59:39 ru Exp $ +.\" $Id: ieee80211_node.9,v 1.9 2015/11/23 17:53:57 jmc Exp $ +.\" +.Dd $Mdocdate: November 23 2015 $ +.Dt IEEE80211_NODE_ATTACH 9 +.Os +.Sh NAME +.Nm ieee80211_node_attach , +.Nm ieee80211_node_lateattach , +.Nm ieee80211_node_detach , +.Nm ieee80211_begin_scan , +.Nm ieee80211_next_scan , +.Nm ieee80211_create_ibss , +.Nm ieee80211_end_scan , +.Nm ieee80211_alloc_node , +.Nm ieee80211_dup_bss , +.Nm ieee80211_find_node , +.Nm ieee80211_release_node , +.Nm ieee80211_free_node , +.Nm ieee80211_free_allnodes , +.Nm ieee80211_iterate_nodes +.Nd software 802.11 stack node management functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_proto.h +.In net80211/ieee80211_node.h +.Ft void +.Fn ieee80211_node_attach "struct ifnet *ifp" +.Ft void +.Fn ieee80211_node_lateattach "struct ifnet *ifp" +.Ft void +.Fn ieee80211_node_detach "struct ifnet *ifp" +.Ft void +.Fn ieee80211_begin_scan "struct ifnet *ifp" +.Ft void +.Fn ieee80211_next_scan "struct ifnet *ifp" +.Ft void +.Fo ieee80211_create_ibss +.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan" +.Fc +.Ft void +.Fn ieee80211_end_scan "struct ifnet *ifp" +.Ft struct ieee80211_node * +.Fn ieee80211_alloc_node "struct ieee80211com *ic" "const u_int8_t *macaddr" +.Ft struct ieee80211_node * +.Fn ieee80211_dup_bss "struct ieee80211com *ic" "const u_int8_t *macaddr" +.Ft struct ieee80211_node * +.Fn ieee80211_find_node "struct ieee80211com *ic" "const u_int8_t *macaddr" +.Ft void +.Fn ieee80211_release_node "struct ieee80211com *ic" "struct ieee80211_node *ni" +.Ft void +.Fn ieee80211_free_node "struct ieee80211com *ic" "struct ieee80211_node *ni" +.Ft void +.Fn ieee80211_free_allnodes "struct ieee80211com *ic" +.Ft void +.Fo ieee80211_iterate_nodes +.Fa "struct ieee80211com *ic" "ieee80211_iter_func *f" "void *arg" +.Fc +.Sh DESCRIPTION +These functions are used to manage node lists within the software +802.11 stack. +These lists are typically used for implementing host-mode AP functionality, +or providing signal quality information about neighbouring nodes. +.Pp +.\" +The +.Fn ieee80211_node_attach +function is called from +.Xr ieee80211_ifattach 9 +to initialize node database management callbacks for the interface +.Fa ifp +(specifically for memory allocation, node copying and node +signal inspection). +These functions may be overridden in special circumstances, +as long as this is done after calling +.Xr ieee80211_ifattach 9 +and prior to any other call which may allocate a node. +.Pp +.\" +The +.Fn ieee80211_node_lateattach +function initialises the +.Va ic_bss +node element of the interface +.Fa ifp +during +.Xr ieee80211_media_init 9 . +This late attachment is to account for certain special cases described under +.Fn ieee80211_node_attach . +.Pp +.\" +The +.Fn ieee80211_node_detach +function destroys all node database state associated with the interface +.Fa ifp , +and is usually called during device detach. +.Pp +.\" +The +.Fn ieee80211_begin_scan +function initialises the node database in preparation of an active +scan for an access point on the interface +.Fa ifp . +The scan begins on the next radio channel by calling +.Fn ieee80211_next_scan +internally. +The actual scanning for an access point is not automated; +the device driver itself only handles setting the radio frequency +of the card and stepping through the channels. +.Pp +.\" +The +.Fn ieee80211_next_scan +function is used to inform the +.Xr ieee80211 9 +layer that the interface +.Fa ifp +is now scanning for an access point on the next radio channel. +A device driver is expected to first call +.Fn ieee80211_begin_scan , +to initialize the node database, +then set the radio channel on the device; +then, after a certain time has elapsed (200ms for example), call +.Fn ieee80211_next_scan +to move to the next channel. +Typically, a timeout is used to automate this process; see +.Xr timeout 9 +for more information on how to use timeouts. +.Pp +.\" +The +.Fn ieee80211_create_ibss +function sets up the net80211-specific portion of an interface's softc, +.Fa ic , +for use in IBSS mode. +.Pp +.\" +The +.Fn ieee80211_end_scan +function is called by +.Fn ieee80211_next_scan +when the state machine has performed a full cycle of scanning on +all available radio channels. +Internally, +.Fn ieee80211_end_scan +will inspect the node cache associated with the interface +.Fa ifp +for suitable access points found during scanning, and associate with one, +should the parameters of the node match those of the configuration +requested from userland. +.Pp +.\" +The +.Fn ieee80211_alloc_node +function allocates an instance of +.Vt "struct ieee80211_node" +for a node having the MAC address +.Fa macaddr , +and associates it with the interface +.Fa ic . +If the allocation is successful, the node structure is initialised by +.Fn ieee80211_setup_node ; +otherwise, +.Dv NULL +is returned. +.Pp +.\" +The +.Fn ieee80211_dup_bss +function is similar to +.Fn ieee80211_alloc_node , +but is instead used to create a node database entry for the BSSID +.Fa macaddr +associated with the interface +.Fa ic . +If the allocation is successful, the node structure is initialised by +.Fn ieee80211_setup_node ; +otherwise, +.Dv NULL +is returned. +.Pp +.\" +The +.Fn ieee80211_find_node +function will iterate through the node list associated with the interface +.Fa ic , +searching for a node entry which matches +.Fa macaddr . +If the entry is found, its reference count is incremented, and +a pointer to the node is returned; otherwise, +.Dv NULL +will be returned. +.Pp +.\" +The +.Fn ieee80211_free_node +function will remove the node +.Fa ni +from the node database entries associated with the interface +.Fa ic , +and free any memory associated with the node. +This private method can be overridden in +.Fn ieee80211_node_attach . +.\" +.Pp +The +.Fn ieee80211_free_allnodes +function will iterate through the node list calling +.Fn ieee80211_free_node +for all nodes associated with the interface +.Fa ic . +.Pp +.\" +The +.Fn ieee80211_iterate_nodes +function will call the user-defined callback function +.Fa f +for all nodes in the node database associated with the interface +.Fa ic . +The callback is invoked with the with the user-supplied value +.Fa arg +and a pointer to the current node. +.\" +.Sh SEE ALSO +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 +and +.Ox 3.6 . +.Sh AUTHORS +.An -nosplit +This 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/openbsd/man9/ieee80211_output.9 b/static/openbsd/man9/ieee80211_output.9 new file mode 100644 index 00000000..c18dd53a --- /dev/null +++ b/static/openbsd/man9/ieee80211_output.9 @@ -0,0 +1,154 @@ +.\" $OpenBSD: ieee80211_output.9,v 1.6 2015/11/23 17:53:57 jmc Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_output.9,v 1.2 2004/07/07 12:59:39 ru Exp $ +.\" $Id: ieee80211_output.9,v 1.6 2015/11/23 17:53:57 jmc Exp $ +.\" +.Dd $Mdocdate: November 23 2015 $ +.Dt IEEE80211_ENCAP 9 +.Os +.Sh NAME +.Nm ieee80211_encap , ieee80211_add_rates , +.Nm ieee80211_add_xrates , +.Nm ieee80211_send_mgmt +.Nd software 802.11 stack output functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_proto.h +.Ft struct mbuf * +.Fo ieee80211_encap +.Fa "struct ifnet *ifp" "struct mbuf *m" "struct ieee80211_node **pni" +.Fc +.Ft u_int8_t * +.Fn ieee80211_add_rates "u_int8_t *frm" "const struct ieee80211_rateset *rs" +.Ft u_int8_t * +.Fn ieee80211_add_xrates "u_int8_t *frm" "const struct ieee80211_rateset *rs" +.Ft int +.Fo ieee80211_send_mgmt +.Fa "struct ieee80211com *ic" "struct ieee80211_node *ni" "int type" "int arg" +.Fc +.Sh DESCRIPTION +These functions handle the encapsulation and transmission of 802.11 frames +within the software 802.11 stack. +.Pp +The +.Fn ieee80211_encap +function encapsulates an outbound data frame contained within the +mbuf chain +.Fa m +from the interface +.Fa ifp . +The argument +.Fa *pni +is a reference to the destination node. +.Pp +If the function is successful, the mbuf chain is updated with the +802.11 frame header prepended, and a pointer to the head of the chain +is returned. +If an error occurs, +.Dv NULL +will be returned, and +.Fa *pni +is also set to +.Dv NULL . +The caller is responsible for freeing the node reference if +.Fa *pni +is +.Pf non- Dv NULL +on return. +The convention is that +.Va ic_bss +is not reference counted; the caller is responsible for maintaining this +reference count. +.Pp +.\" +The +.Fn ieee80211_add_rates +utility function is used to add the rate set element +.Fa *rs +to the frame +.Fa frm . +A pointer to the location in the buffer after the addition of the rate set +is returned. +It is typically used when constructing management frames from within the +software 802.11 stack. +.Pp +.\" +The +.Fn ieee80211_add_xrates +utility function is used to add the extended rate set element +.Fa *rs +to the frame +.Fa frm . +A pointer to the location in the buffer after the addition of the rate set +is returned. +It is typically used when constructing management frames from within the +software 802.11 stack in 802.11g mode. +.Pp +.\" +The +.Fn ieee80211_send_mgmt +function transmits a management frame on the interface +.Fa ic +to the destination node +.Fa ni +of type +.Fa type . +.Pp +The argument +.Fa arg +specifies either a sequence number for authentication operations, +a status code for [re]association operations, +or a reason for deauthentication and deassociation operations. +.Pp +Nodes other than +.Va ic_bss +have their reference count incremented to reflect their use for an +indeterminate amount of time. +This reference is freed when the function returns. +.Pp +The function returns 0 if successful; if temporary buffer space is not +available, the function returns +.Er ENOMEM . +.\" +.Sh SEE ALSO +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 +and +.Ox 3.6 . +.Sh AUTHORS +.An -nosplit +This 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/openbsd/man9/ieee80211_proto.9 b/static/openbsd/man9/ieee80211_proto.9 new file mode 100644 index 00000000..1333f0b4 --- /dev/null +++ b/static/openbsd/man9/ieee80211_proto.9 @@ -0,0 +1,77 @@ +.\" $OpenBSD: ieee80211_proto.9,v 1.5 2013/07/17 20:21:53 schwarze Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_proto.9,v 1.2 2004/07/07 12:59:39 ru Exp $ +.\" $Id: ieee80211_proto.9,v 1.5 2013/07/17 20:21:53 schwarze Exp $ +.\" +.Dd $Mdocdate: July 17 2013 $ +.Dt IEEE80211_PROTO 9 +.Os +.Sh NAME +.Nm ieee80211_proto_attach , +.Nm ieee80211_proto_detach , +.Nm ieee80211_print_essid , +.Nm ieee80211_dump_pkt , +.Nm ieee80211_fix_rate , +.Nm ieee80211_proto +.Nd software 802.11 stack protocol helper functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_proto.h +.Ft void +.Fn ieee80211_proto_attach "struct ifnet *ifp" +.Ft void +.Fn ieee80211_proto_detach "struct ifnet *ifp" +.Ft void +.Fn ieee80211_print_essid "const u_int8_t *essid" "int len" +.Ft void +.Fn ieee80211_dump_pkt "const u_int8_t *buf" "int len" "int rate" "int rssi" +.Ft int +.Fo ieee80211_fix_rate +.Fa "struct ieee80211com *ic" "struct ieee80211_node *ni" "int flags" +.Fc +.Sh DESCRIPTION +These +functions are helper functions used throughout the software 802.11 protocol +stack. +.Sh SEE ALSO +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 +and +.Ox 3.6 . +.Sh AUTHORS +.An -nosplit +This 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/openbsd/man9/ieee80211_radiotap.9 b/static/openbsd/man9/ieee80211_radiotap.9 new file mode 100644 index 00000000..452b61f6 --- /dev/null +++ b/static/openbsd/man9/ieee80211_radiotap.9 @@ -0,0 +1,259 @@ +.\" $OpenBSD: ieee80211_radiotap.9,v 1.15 2020/10/09 08:53:16 mpi Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/ieee80211_radiotap.9,v 1.3 2004/07/07 12:59:39 ru Exp $ +.\" $Id: ieee80211_radiotap.9,v 1.15 2020/10/09 08:53:16 mpi Exp $ +.\" +.Dd $Mdocdate: October 9 2020 $ +.Dt IEEE80211_RADIOTAP 9 +.Os +.Sh NAME +.Nm ieee80211_radiotap +.Nd software 802.11 stack packet capture definitions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_ioctl.h +.In net80211/ieee80211_radiotap.h +.In net/bpf.h +.\" +.Sh DESCRIPTION +The +.Nm +definitions provide a device-independent +.Xr bpf 4 +attachment for the +capture of information about 802.11 traffic which is not part of +the 802.11 frame structure. +.Pp +Radiotap was designed to balance the desire for a capture format +that conserved CPU and memory bandwidth on embedded systems, +with the desire for a hardware-independent, extensible format +that would support the diverse capabilities of virtually all +802.11 +radios. +.Pp +These considerations led radiotap to settle on a format consisting of +a standard preamble followed by an extensible bitmap indicating the +presence of optional capture fields. +.Pp +The capture fields were packed into the header as compactly as possible, +modulo the requirements that they had to be packed swiftly, +with suitable alignment, in the same order as the bits indicating +their presence. +.Pp +This typically includes information such as signal quality and +timestamps. +This information may be used by a variety of user agents, including +.Xr tcpdump 8 . +It is requested by using the +.Xr bpf 4 +data-link type +.Dv DLT_IEEE802_11_RADIO . +.Pp +.\" +Each frame using this attachment has the following header prepended to it: +.Bd -literal -offset indent +struct ieee80211_radiotap_header { + u_int8_t it_version; /* set to 0 */ + u_int8_t it_pad; + u_int16_t it_len; /* entire length */ + u_int32_t it_present; /* fields present */ +} __packed; +.Ed +.Pp +.\" +A device driver implementing +.Vt radiotap +typically defines a packed structure embedding an instance of +.Vt "struct ieee80211_radiotap_header" +at the beginning, +with subsequent fields in the appropriate order, +and a macro to set the bits of the +.Va it_present +bitmap to indicate which fields exist and are filled in by the driver. +.\" +.Pp +Radiotap headers are copied to userland via a separate bpf attachment. +It is necessary for the driver to create this attachment after calling +.Xr ieee80211_ifattach 9 +by calling +.Fn bpfattach2 +with the data-link type set to +.Dv DLT_IEEE802_11_RADIO . +.Pp +.\" +When the information is available, +usually immediately before a link-layer transmission or after a receive, +the driver copies it to the bpf layer using the +.Fn bpf_mtap2 +function. +.Pp +.\" +The following extension fields are defined for +.Vt radiotap , +in the order in which they should appear in the buffer copied to userland: +.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 timer, +when the first bit of the MPDU arrived at the MAC. +This field should be present for received frames only. +.It Dv IEEE80211_RADIOTAP_FLAGS +This field contains a single unsigned 8-bit value, containing a bitmap +of flags specifying properties of the frame being transmitted or received. +.It Dv IEEE80211_RADIOTAP_RATE +This field contains a single unsigned 8-bit value, which is the data rate in +use in units of 500Kbps. +If the most significant bit is set, the remaining bits contain an MCS index +instead of a data rate. +.It Dv IEEE80211_RADIOTAP_CHANNEL +This field contains two unsigned 16-bit values. +The first value is the frequency upon which this PDU was transmitted +or received. +The second value is a bitmap containing flags which specify properties of +the channel in use. +These are documented within the header file +.In net80211/ieee80211_radiotap.h . +.It Dv IEEE80211_RADIOTAP_FHSS +This field contains two 8-bit values. +This field should be present for frequency-hopping radios only. +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, which 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, which 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 +For radios which support antenna diversity, this field contains a single +unsigned 8-bit value specifying which antenna is being used to transmit +or receive this frame. +The first antenna is antenna 0. +.It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL +This field contains a single unsigned 8-bit value, which 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, which indicates the +RF noise power at the antenna, in decibels difference from an +arbitrary, fixed reference. +.It Dv IEEE80211_RADIOTAP_RSSI +This field contains two unsigned 8-bit values. +The first value is the received signal strength index (RSSI) +which indicates the RF signal power at the antenna. +The second value is the relative maximum RSSI value of the RF +interface. +.It Dv IEEE80211_RADIOTAP_EXT +This bit is reserved for any future extensions to the +.Vt radiotap +structure. +A driver can set +.Dv IEEE80211_RADIOTAP_EXT +to extend the it_present bitmap by another 64 bits. +The bitmap can be extended by multiples of 32 bits to 96, 128, 160 bits, +or longer, by setting +.Dv IEEE80211_RADIOTAP_EXT +in the extensions. +The bitmap ends at the first extension field where +.Dv IEEE80211_RADIOTAP_EXT +is not set. +.El +.Sh EXAMPLES +Radiotap header for the Realtek RTL8180L driver +.Xr rtw 4 : +.Bd -literal -offset indent +struct rtw_rx_radiotap_header { + struct ieee80211_radiotap_header rr_ihdr; + u_int64_t rr_tsft; + u_int8_t rr_flags; + u_int8_t rr_rate; + u_int16_t rr_chan_freq; + u_int16_t rr_chan_flags; + u_int16_t rr_barker_lock; + u_int8_t rr_antsignal; +} __packed; +.Ed +.Pp +Bitmap indicating which fields are present in the above structure: +.Bd -literal -offset indent +#define RTW_RX_RADIOTAP_PRESENT \e + ((1 << IEEE80211_RADIOTAP_TSFT) | \e + (1 << IEEE80211_RADIOTAP_FLAGS) | \e + (1 << IEEE80211_RADIOTAP_RATE) | \e + (1 << IEEE80211_RADIOTAP_CHANNEL) | \e + (1 << IEEE80211_RADIOTAP_LOCK_QUALITY) | \e + (1 << IEEE80211_RADIOTAP_DB_ANTSIGNAL) | \e + 0) +.Ed +.Sh SEE ALSO +.Xr bpf 4 , +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm +definitions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 +and +.Ox 3.6 . +.\" +.Sh AUTHORS +.An -nosplit +The +.Nm +interface was designed and implemented by +.An David Young Aq Mt dyoung@pobox.com . +.Pp +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/openbsd/man9/if_addrhook_add.9 b/static/openbsd/man9/if_addrhook_add.9 new file mode 100644 index 00000000..64c4c1be --- /dev/null +++ b/static/openbsd/man9/if_addrhook_add.9 @@ -0,0 +1,120 @@ +.\" $OpenBSD: if_addrhook_add.9,v 1.3 2024/02/22 08:10:08 jsg Exp $ +.\" +.\" Copyright (c) 2019 David Gwynne +.\" +.\" 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: February 22 2024 $ +.Dt IF_ADDRHOOK_ADD 9 +.Os +.Sh NAME +.Nm if_addrhook_add , +.Nm if_addrhook_del , +.\" .Nm if_addrhooks_run , +.Nm if_detachhook_add , +.Nm if_detachhook_del , +.Nm if_linkstatehook_add , +.Nm if_linkstatehook_del +.Nd interface event hook API +.Sh SYNOPSIS +.In net/if_var.h +.Ft void +.Fn if_addrhook_add "struct ifnet *ifp" "struct task *t" +.Ft void +.Fn if_addrhook_del "struct ifnet *ifp" "struct task *t" +.\" .Ft void +.\" .Fn if_addrhooks_run "struct ifnet *ifp" +.Ft void +.Fn if_detachhook_add "struct ifnet *ifp" "struct task *t" +.Ft void +.Fn if_detachhook_del "struct ifnet *ifp" "struct task *t" +.Ft void +.Fn if_linkstatehook_add "struct ifnet *ifp" "struct task *t" +.Ft void +.Fn if_linkstatehook_del "struct ifnet *ifp" "struct task *t" +.Sh DESCRIPTION +The interface hook API allows for the registration of a task that +will be called when an IP address change, link state, or detach event +occurs on the specified interface. +Tasks should be initialised with +.Xr task_add 9 +or +.Xr TASK_INITIALIZER 9 +before being used with the following functions. +.Pp +The +.Fn if_addrhook_add +function registers the task +.Fa t +on the +.Fa ifp +interface. +The event will fire every time an IPv4 or IPv6 address change occurs +on the interface until explicitly removed with +.Fn if_addrhook_del . +.Pp +The +.Fn if_addrhook_del +function removes the task +.Fa t +from the +.Fa ifp +interface. +.Pp +The +.Fn if_detachhook_add +function registers the task +.Fa t +on the +.Fa ifp +interface. +The event will fire when the interface is being destroyed. +.Pp +The +.Fn if_detachhook_del +function removes the task +.Fa t +from the +.Fa ifp +interface. +.Pp +The +.Fn if_linkstatehook_add +function registers the task +.Fa t +on the +.Fa ifp +interface. +The event will fire for every link state change, or when the interface +is brought up or down, until explicitly removed with +.Fn if_linkstatehook_del . +.Pp +The +.Fn if_linkstatehook_del +function removes the task +.Fa t +from the +.Fa ifp +interface. +.Sh CONTEXT +.Fn if_addrhook_add , +.Fn if_addrhook_del , +.\" .Fn if_addrhooks_run , +.Fn if_detachhook_add , +.Fn if_detachhook_del , +.Fn if_linkstatehook_add , +and +.Fn if_linkstatehook_del +can be called during autoconf, from process context, or from interrupt context. +.Sh SEE ALSO +.Xr task_set 9 diff --git a/static/openbsd/man9/if_get.9 b/static/openbsd/man9/if_get.9 new file mode 100644 index 00000000..4138c747 --- /dev/null +++ b/static/openbsd/man9/if_get.9 @@ -0,0 +1,80 @@ +.\" $OpenBSD: if_get.9,v 1.3 2021/01/18 09:55:43 mvs Exp $ +.\" +.\" Copyright (c) 2015 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 $Mdocdate: January 18 2021 $ +.Dt IF_GET 9 +.Os +.Sh NAME +.Nm if_get , +.Nm if_unit , +.Nm if_put +.Nd get an interface pointer from an interface index +.Sh SYNOPSIS +.In net/if.h +.Ft struct ifnet * +.Fn if_get "unsigned int ifidx" +.Ft struct ifnet * +.Fn if_unit "const char *name" +.Ft void +.Fn if_put "struct ifnet *ifp" +.Sh DESCRIPTION +The +.Fn if_get +function returns a pointer to the interface descriptor corresponding to the +unique index +.Fa ifidx . +This descriptor is guaranteed to be valid until +.Fn if_put +is called on the returned pointer. +.Pp +The index value +.Dv 0 +is never associated with an interface descriptor and can be used to determine if +an interface index is valid or not. +.Pp +The +.Fn if_unit +function returns a pointer to the interface descriptor corresponding to the +unique name +.Fa name . +This descriptor is guaranteed to be valid until +.Fn if_put +is called on the returned pointer. +.Pp +The +.Fn if_put +function releases a reference on the interface descriptor pointed by +.Fa ifp . +If +.Fa ifp +is a +.Dv NULL +pointer, no action occurs. +.Sh CONTEXT +.Fn if_get , +.Fn if_unit +and +.Fn if_put +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn if_get +returns a pointer to an interface descriptor if the index is valid, otherwise +.Dv NULL . +.Pp +.Fn if_unit +returns a pointer to an interface descriptor if the interface with present +name exists, otherwise +.Dv NULL . diff --git a/static/openbsd/man9/if_rxr_init.9 b/static/openbsd/man9/if_rxr_init.9 new file mode 100644 index 00000000..2eb41723 --- /dev/null +++ b/static/openbsd/man9/if_rxr_init.9 @@ -0,0 +1,189 @@ +.\" $OpenBSD: if_rxr_init.9,v 1.10 2022/09/10 08:50:53 jsg Exp $ +.\" +.\" Copyright (c) 2014 David Gwynne +.\" +.\" 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: September 10 2022 $ +.Dt IF_RXR_INIT 9 +.Os +.Sh NAME +.Nm if_rxr_init , +.Nm if_rxr_get , +.Nm if_rxr_put , +.Nm if_rxr_livelocked , +.Nm if_rxr_needrefill , +.Nm if_rxr_inuse , +.Nm if_rxr_cwm , +.Nm if_rxr_ioctl , +.Nm if_rxr_info_ioctl +.Nd Interface Receive Ring accounting +.Sh SYNOPSIS +.In net/if.h +.Ft void +.Fn if_rxr_init "struct if_rxring *rxr" "unsigned int lwm" "unsigned int hwm" +.Ft unsigned int +.Fn if_rxr_get "struct if_rxring *rxr" "unsigned int max" +.Ft void +.Fn if_rxr_put "struct if_rxring *rxr" "unsigned int n" +.Ft void +.Fn if_rxr_livelocked "struct if_rxring *rxr" +.Ft int +.Fn if_rxr_needrefill "struct if_rxring *rxr" +.Ft unsigned int +.Fn if_rxr_inuse "struct if_rxring *rxr" +.Ft unsigned int +.Fn if_rxr_cwm "struct if_rxring *rxr" +.Ft int +.Fo if_rxr_ioctl +.Fa "struct if_rxrinfo *ifri" +.Fa "const char *name" +.Fa "unsigned int size" +.Fa "struct if_rxring *rxr" +.Fc +.Ft int +.Fo if_rxr_info_ioctl +.Fa "struct if_rxrinfo *ifri" +.Fa "unsigned int n" +.Fa "struct if_rxring_info *rings" +.Fc +.Sh DESCRIPTION +The Interface Receive Ring accounting API provides a mechanism to +manage the number of available descriptors on a network card's receive +ring. +The API restricts the allocation of receive descriptors using a +heuristic that monitors the use of the ring. +The number of descriptors granted on the ring may increase over time +as the interface proves it uses them. +Additionally, if the algorithm detects that the system is livelocked +as a result of being overwhelmed with network traffic, it will +restrict the number of available receive descriptors. +.Pp +.Fn if_rxr_init +initialises the +.Fa rxr +structure. +The +.Fa lwm +argument defines the minimum number of descriptors the chip needs +to operate the ring correctly. +.Fa hwm +is used to describe the maximum number of descriptors the ring can contain. +.Pp +.Fn if_rxr_get +allocates and accounts for up to +.Fa max +descriptors in the ring as being used. +.Pp +.Fn if_rxr_put +returns +.Fa n +receive descriptor slots to the ring. +.Pp +.Fn if_rxr_livelocked +can signal that the receive ring is generating too much load. +.Pp +.Fn if_rxr_needrefill +signals that the receive ring runs below the low watermark of descriptors. +.Pp +.Fn if_rxr_inuse +can be used to determine how many descriptor slots have been allocated +on the ring. +.Pp +.Fn if_rxr_cwm +can be used to determine what the current watermark is for the ring. +.Pp +The +.Fn if_rxr_ioctl +and +.Fn if_rxr_info_ioctl +functions are provided to assist drivers in reporting their rings' +state to userland via a +.Dv SIOCGIFRXR +ioctl request. +The ioctl data payload will be an ifreq structure, with ifr_data pointing at a +struct if_rxrinfo in userland memory. +This if_rxrinfo pointer should be passed via +.Fa ifri . +.Pp +If a driver only has a single receive ring, it may pass the ring state to +.Fn if_rxr_ioctl +via the +.Fa rxr +argument. +.Fa size +is used to describe the size of the mbuf cluster the receive ring uses. +If the driver wishes to name the ring it can pass it via +.Fa name , +otherwise +.Dv NULL . +.Pp +If the driver has multiple receive rings, it can prepare an array +of if_rxring_info structures and pass that to +.Fn if_rxr_info_ioctl +via +.Fa rings +with the number of elements in the array passed via +.Fa n . +.Pp +For the heuristic to work correctly, a driver using this API should +return all possible descriptor slots with +.Fn if_rxr_put +before calling +.Fn if_rxr_get +to fill them again. +.Sh CONTEXT +.Fn if_rxr_init , +.Fn if_rxr_get , +.Fn if_rxr_put , +.Fn if_rxr_livelocked , +.Fn if_rxr_needrefill , +.Fn if_rxr_inuse , +and +.Fn if_rxr_cwm +can be called during autoconf, from process context, or from interrupt context. +.Pp +.Fn if_rxr_ioctl +and +.Fn if_rxr_info_ioctl +can be called from process context, and only from the context of +the process generating an ioctl call. +.Pp +It is up to the caller to provide appropriate locking around calls +to these functions to prevent inconsistencies in the relevant +if_rxring data structure. +.Sh RETURN VALUES +.Fn if_rxr_get +returns the number of receive descriptors available on the ring. +The number of descriptors may be less than the +.Fa max +requested. +.Pp +.Fn if_rxr_needrefill +returns 1 if the number of receive descriptor slots currently in use on the +ring is below the value of +.Fa lwm . +Otherwise, zero is returned. +.Pp +.Fn if_rxr_inuse +returns the number of receive descriptor slots currently in use on the ring. +.Pp +.Fn if_rxr_cwm +returns the currently allowed allocation watermark. +.Sh SEE ALSO +.Xr autoconf 9 +.Sh HISTORY +The Interface Receive Ring API was originally written by +.An David Gwynne Aq Mt dlg@openbsd.org . +The API first appeared in +.Ox 5.6 . diff --git a/static/openbsd/man9/ifiq_input.9 b/static/openbsd/man9/ifiq_input.9 new file mode 100644 index 00000000..025ee55d --- /dev/null +++ b/static/openbsd/man9/ifiq_input.9 @@ -0,0 +1,66 @@ +.\" $OpenBSD: ifiq_input.9,v 1.4 2022/03/31 17:27:23 naddy Exp $ +.\" +.\" Copyright (c) 2020 David Gwynne +.\" +.\" 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: March 31 2022 $ +.Dt IFIQ_INPUT 9 +.Os +.Sh NAME +.Nm ifiq_input , +.Nm ifiq_enqueue +.Nd network interface input queue (ifiqueue) API +.Sh SYNOPSIS +.In net/if_var.h +.Ft int +.Fn ifiq_input "struct ifiqueue *ifiq" "struct mbuf_list *ml" +.Ft void +.Fn ifiq_enqueue "struct ifiqueue *ifiq" "struct mbuf *m" +.Sh DESCRIPTION +The network interface input queue (ifiqueue) API provides functions +for network drivers to queue received packets for processing by the +network stack. +.Bl -tag -width Ds +.It Fn ifiq_input "struct ifiqueue *ifq" "struct mbuf_list *ml" +Enqueue the list of mbufs in +.Fa ml +on the +.Fa ifiq +interface input queue and notify the network stack to process them. +If the queue rejects the packets, they will be freed +and counted as drops. +.It Fn ifiq_enqueue "struct ifiqueue *ifq" "struct mbuf *m" +Enqueue the mbuf +.Fa m +on the +.Fa ifiq +interface input queue and notify the network stack to process it. +.El +.Sh CONTEXT +.Fn ifiq_input +and +.Fn ifiq_enqueue +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn ifiq_input +returns a non-zero value if mbufs are queued too rapidly for the +stack to process. +If possible, the caller should attempt to reduce the number of mbufs +being generated in the future. +For example, if mbufs are being received from +hardware managed with the interface RX ring API, +.Xr if_rxr_livelocked 9 +can be called to indicate to the hardware that backpressure is required. +.Sh SEE ALSO +.Xr if_rxr_livelocked 9 diff --git a/static/openbsd/man9/ifq_deq_begin.9 b/static/openbsd/man9/ifq_deq_begin.9 new file mode 100644 index 00000000..0467a2ca --- /dev/null +++ b/static/openbsd/man9/ifq_deq_begin.9 @@ -0,0 +1,76 @@ +.\" $OpenBSD: ifq_deq_begin.9,v 1.5 2021/03/20 21:02:56 sthen Exp $ +.\" +.\" Copyright (c) 2015 David Gwynne +.\" +.\" 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: March 20 2021 $ +.Dt IFQ_DEQ_BEGIN 9 +.Os +.Sh NAME +.Nm ifq_deq_begin , +.Nm ifq_deq_commit , +.Nm ifq_deq_rollback +.Nd dequeue an mbuf from an interface sending queue +.Sh SYNOPSIS +.In net/if_var.h +.Ft struct mbuf * +.Fn ifq_deq_begin "struct ifqueue *ifq" +.Ft void +.Fn ifq_deq_commit "struct ifqueue *ifq" "struct mbuf *m" +.Ft void +.Fn ifq_deq_rollback "struct ifqueue *ifq" "struct mbuf *m" +.Sh DESCRIPTION +The ifq_deq_* +set of functions provides a non-atomic alternative to +.Xr ifq_dequeue 9 . +Their use is discouraged, code should use +.Xr ifq_dequeue 9 +whenever possible. +.Bl -tag -width Ds +.It Fn ifq_deq_begin "struct ifqueue *ifq" +Get a reference to the next mbuf to be transmitted from the +.Fa ifq +interface send queue. +If an mbuf is to be transmitted, also acquire a lock on the send queue +to exclude modification or freeing of the referenced mbuf. +Its packet header must not be modified until the mbuf has been dequeued with +.Fn ifq_deq_commit . +.It Fn ifq_deq_commit "struct ifqueue *ifq" "struct mbuf *m" +Dequeue the mbuf +.Fa m +that was referenced by a previous call to +.Fn ifq_deq_begin +and release the lock on +.Fa ifq . +.It Fn ifq_deq_rollback "struct ifqueue *ifq" "struct mbuf *m" +Release the lock on the interface send queue +.Fa ifq +that was acquired while a reference to +.Fa m +was being held. +.El +.Sh CONTEXT +.Fn ifq_deq_begin , +.Fn ifq_deq_commit , +and +.Fn ifq_deq_rollback +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn ifq_deq_begin +returns the next mbuf to be transmitted by the interface. +If no packet is available for transmission, +.Dv NULL +is returned. +.Sh SEE ALSO +.Xr ifq_dequeue 9 diff --git a/static/openbsd/man9/ifq_enqueue.9 b/static/openbsd/man9/ifq_enqueue.9 new file mode 100644 index 00000000..a4cae893 --- /dev/null +++ b/static/openbsd/man9/ifq_enqueue.9 @@ -0,0 +1,172 @@ +.\" $OpenBSD: ifq_enqueue.9,v 1.13 2022/03/31 17:27:23 naddy Exp $ +.\" +.\" Copyright (c) 2015 David Gwynne +.\" +.\" 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: March 31 2022 $ +.Dt IFQ_ENQUEUE 9 +.Os +.Sh NAME +.Nm ifq_enqueue , +.Nm ifq_dequeue , +.Nm ifq_purge , +.Nm ifq_len , +.Nm ifq_empty , +.Nm ifq_hdatalen , +.Nm ifq_set_oactive , +.Nm ifq_clr_oactive , +.Nm ifq_is_oactive , +.Nm ifq_restart , +.Nm ifq_barrier +.Nd interface send queue API +.Sh SYNOPSIS +.In net/if_var.h +.Ft int +.Fn ifq_enqueue "struct ifqueue *ifq" "struct mbuf *m" +.Ft struct mbuf * +.Fn ifq_dequeue "struct ifqueue *ifq" +.Ft unsigned int +.Fn ifq_purge "struct ifqueue *ifq" +.Ft unsigned int +.Fn ifq_len "struct ifqueue *ifq" +.Ft unsigned int +.Fn ifq_empty "struct ifqueue *ifq" +.Ft int +.Fn ifq_hdatalen "struct ifqueue *ifq" +.Ft void +.Fn ifq_set_oactive "struct ifqueue *ifq" +.Ft void +.Fn ifq_clr_oactive "struct ifqueue *ifq" +.Ft unsigned int +.Fn ifq_is_oactive "struct ifqueue *ifq" +.Ft void +.Fn ifq_restart "struct ifqueue *ifq" +.Ft void +.Fn ifq_barrier "struct ifqueue *ifq" +.Sh DESCRIPTION +The ifqueue API provides implementations of data structures and +operations for the network stack to queue mbufs for a network driver +to dequeue from its start routine for transmission. +.Bl -tag -width Ds +.It Fn ifq_enqueue "struct ifqueue *ifq" "struct mbuf *m" +Enqueue mbuf +.Fa m +on the +.Fa ifq +interface send queue. +If the queue rejects the packet, it will be freed with +.Xr m_freem 9 +and counted as a drop. +.It Fn ifq_dequeue "struct ifqueue *ifq" +Dequeue the next mbuf to be transmitted from the +.Fa ifq +interface send queue. +.It Fn ifq_purge "struct ifqueue *ifq" +Free all the mbufs on the interface send queue +.Fa ifq . +Freed mbufs will be accounted as drops. +.It Fn ifq_len "struct ifqueue *ifq" +Return the number of mbufs on the interface send queue +.Fa ifq . +Note that while +.Fn ifq_len +may report that mbufs are on the queue, the current queue +discipline may not make them available for dequeueing with +.Fn ifq_dequeue +or +.Fn ifq_deq_begin . +.It Fn ifq_empty "struct ifqueue *ifq" +Return if the interface send queue +.Fa ifq +is empty. +.It Fn ifq_hdatalen "struct ifqueue *ifq" +Return the number of bytes in the mbuf at the head of the interface +send queue +.Fa ifq . +.It Fn ifq_set_oactive "struct ifqueue *ifq" +.Fn ifq_set_oactive +is called by the relevant driver to mark the hardware associated +with the interface send queue +.Fa ifq +as unable to transmit more packets. +.It Fn ifq_clr_oactive "struct ifqueue *ifq" +.Fn ifq_clr_oactive +is called by the relevant driver to clear the "active" mark on the +hardware associated with the interface send queue +.Fa ifq , +meaning it is now able to transmit packets. +.It Fn ifq_is_oactive "struct ifqueue *ifq" +Return if the hardware associated with the interface send queue +.Fa ifq +is unable to transmit more packets. +.It Fn ifq_restart "struct ifqueue *ifq" +Dispatch a call to +.Fn ifq_clr_oactive +and the interface's start routine. +This call is serialised with other calls to the start routine via +.Fn if_start +and therefore provides race free modification of the "active" mark. +.It Fn ifq_barrier "struct ifqueue *ifq" +.Fn ifq_barrier +guarantees that any work currently running in the interface queue +serialiser (e.g. work dispatched by +.Fn ifq_restart +or the interface's start routine) has finished before +.Fn ifq_barrier +returns. +.El +.Sh CONTEXT +.Fn ifq_enqueue , +.Fn ifq_dequeue , +.Fn ifq_purge , +.Fn ifq_len , +.Fn ifq_empty , +.Fn ifq_hdatalen , +.Fn ifq_set_oactive , +.Fn ifq_clr_oactive , +.Fn ifq_is_oactive , +and +.Fn ifq_restart +can be called during autoconf, from process context, or from interrupt context. +.Pp +.Fn ifq_barrier +can be called from process context. +.Sh RETURN VALUES +.Fn ifq_enqueue +returns 0 if the mbuf was successfully queued, or non-zero if mbuf was freed. +.Pp +.Fn ifq_dequeue +returns the next mbuf to be transmitted by the interface. +If no packet is available for transmission, +.Dv NULL +is returned. +.Pp +.Fn ifq_purge +returns the number of mbufs that were removed from the queue and freed. +.Pp +.Fn ifq_len +returns the number of mbufs on the queue. +.Pp +.Fn ifq_empty +returns a non-zero value if the queue is empty, otherwise 0. +.Pp +.Fn ifq_hdatalen +returns the size of a packet on the queue, or 0 if the queue is empty; +.Pp +.Fn ifq_is_oactive +returns a non-zero value if the hardware associated with the interface +send queue is unable to transmit more packets, otherwise 0. +.Sh SEE ALSO +.Xr ifq_deq_begin 9 , +.Xr m_freem 9 diff --git a/static/openbsd/man9/iic.9 b/static/openbsd/man9/iic.9 new file mode 100644 index 00000000..ce3bb006 --- /dev/null +++ b/static/openbsd/man9/iic.9 @@ -0,0 +1,360 @@ +.\" $OpenBSD: iic.9,v 1.10 2022/02/09 07:58:24 visa 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 $Mdocdate: February 9 2022 $ +.Dt IIC_ACQUIRE_BUS 9 +.Os +.Sh NAME +.Nm iic_acquire_bus , +.Nm iic_release_bus , +.Nm iic_exec , +.Nm iic_smbus_write_byte , +.Nm iic_smbus_read_byte , +.Nm iic_smbus_receive_byte , +.Nm iic_is_compatible +.Nd Inter IC (I2C) bus +.Sh SYNOPSIS +.In dev/i2c/i2cvar.h +.Ft int +.Fo iic_acquire_bus +.Fa "i2c_tag_t ic" +.Fa "int flags" +.Fc +.Ft int +.Fo iic_release_bus +.Fa "i2c_tag_t ic" +.Fa "int flags" +.Fc +.Ft int +.Fo iic_exec +.Fa "i2c_tag_t ic" +.Fa "i2c_op_t op" +.Fa "i2c_addr_t addr" +.Fa "const void *cmdbuf" +.Fa "size_t cmdlen" +.Fa "void *buf" +.Fa "size_t len" +.Fa "int flags" +.Fc +.Ft int +.Fo iic_smbus_write_byte +.Fa "i2c_tag_t ic" +.Fa "i2c_addr_t addr" +.Fa "uint8_t cmd" +.Fa "uint8_t data" +.Fa "int flags" +.Fc +.Ft int +.Fo iic_smbus_read_byte +.Fa "i2c_tag_t ic" +.Fa "i2c_addr_t addr" +.Fa "uint8_t cmd" +.Fa "uint8_t *datap" +.Fa "int flags" +.Fc +.Ft int +.Fo iic_smbus_receive_byte +.Fa "i2c_tag_t ic" +.Fa "i2c_addr_t addr" +.Fa "uint8_t *datap" +.Fa "int flags" +.Fc +.Ft int +.Fo iic_is_compatible +.Fa "const struct i2c_attach_args *ia" +.Fa "const char *name" +.Fc +.Sh DESCRIPTION +I2C is a two-wire bus developed by Philips used for connecting +integrated circuits. +It is commonly used for connecting devices such as EEPROMs, +temperature sensors, fan controllers, real-time clocks, tuners, +and other types of integrated circuits. +The +.Nm iic +interface provides a means of communicating with I2C-connected devices. +The System Management Bus, or SMBus, is a variant of the I2C bus with +a simplified command protocol and some electrical differences. +.Sh DATA TYPES +Drivers for devices attached to the I2C bus will make use of the +following data types: +.Bl -tag -width i2c_addr_t +.It Fa i2c_tag_t +Controller tag for the I2C bus. +This is a pointer to a +.Fa struct i2c_controller , +consisting of function pointers filled in by the I2C +controller driver. +.It Fa i2c_op_t +I2C bus operation. +The following I2C bus operations are defined: +.Bl -tag -width XXXX +.It I2C_OP_READ +Perform a read operation. +.It I2C_OP_READ_WITH_STOP +Perform a read operation and send a STOP condition on the I2C bus at +the conclusion of the read. +.It I2C_OP_WRITE +Perform a write operation. +.It I2C_OP_WRITE_WITH_STOP +Perform a write operation and send a STOP condition on the I2C bus at +the conclusion of the write. +.El +.It Fa i2c_addr_t +I2C device address. +.It Fa struct i2c_attach_args +Devices are attached to an I2C bus using this structure. +The structure is defined as follows: +.Bd -literal +struct i2c_attach_args { + i2c_tag_t ia_tag; /* controller */ + i2c_addr_t ia_addr; /* address of device */ + int ia_size; /* size (for EEPROMs) */ + char *ia_name; /* chip name */ + size_t ia_namelen /* length of name concatenation */ + void *ia_cookie; /* pass extra info from + bus to dev */ + void *ia_intr /* interrupt info */ + int ia_poll; /* to force polling */ +}; +.Ed +.El +.Sh FUNCTIONS +The following functions comprise the API provided to drivers of +I2C-connected devices: +.Bl -tag -width iic_exec +.It Fn iic_acquire_bus "ic" "flags" +Acquire an exclusive lock on the I2C bus. +This is required since only one device may communicate on the +I2C bus at a time. +Drivers should acquire the bus lock, perform the I2C bus operations +necessary, and then release the bus lock. +Passing the +.Fa I2C_F_POLL +flag indicates to +.Fn iic_acquire_bus +that sleeping is not permitted. +.It Fn iic_release_bus "ic" "flags" +Release an exclusive lock on the I2C bus. +If the +.Fa I2C_F_POLL +flag was passed to +.Fn iic_acquire_bus , +it must also be passed to +.Fn iic_release_bus . +.It Xo +.Fo iic_exec +.Fa "ic" +.Fa "op" +.Fa "addr" +.Fa "cmdbuf" +.Fa "cmdlen" +.Fa "buf" +.Fa "len" +.Fa "flags" +.Fc +.Xc +Perform a series of I2C transactions on the bus. +.Fn iic_exec +initiates the operation by sending a START condition on the I2C +bus and then transmitting the address of the target device along +with the transaction type. +If +.Fa cmdlen +is non-zero, the command pointed to by +.Fa cmdbuf +is then sent to the device. +If +.Fa buflen +is non-zero, +.Fn iic_exec +will then transmit or receive the data, as indicated by +.Fa op . +If +.Fa op +indicates a read operation, +.Fn iic_exec +will send a REPEATED START before transferring the data. +If +.Fa op +so indicates, a STOP condition will be sent on the I2C +bus at the conclusion of the operation. +Passing the +.Fa I2C_F_POLL +flag indicates to +.Fn iic_exec +that sleeping is not permitted. +.It Fn iic_smbus_write_byte "ic" "addr" "cmd" "data" "flags" +Perform an SMBus WRITE BYTE operation. +This is equivalent to +I2C_OP_WRITE_WITH_STOP with +.Fa cmdlen +of 1 and +.Fa len +of 1. +.It Fn iic_smbus_read_byte "ic" "addr" "cmd" "datap" "flags" +Perform an SMBus READ BYTE operation. +This is equivalent to +I2C_OP_READ_WITH_STOP with +.Fa cmdlen +of 1 and +.Fa len +of 1. +.It Fn iic_smbus_receive_byte "ic" "addr" "datap" "flags" +Perform an SMBus RECEIVE BYTE operation. +This is equivalent to +I2C_OP_READ_WITH_STOP with +.Fa cmdlen +of 0 and +.Fa len +of 1. +.It Fn iic_is_compatible "ia" "name" +Test if the device is compatible with +.Fa name . +.El +.Sh CONTROLLER INTERFACE +The I2C controller driver must fill in the function pointers of +an +.Fa i2c_controller +structure, which is defined as follows: +.Bd -literal +struct i2c_controller { + void *ic_cookie; /* controller private */ + + int (*ic_acquire_bus)(void *, int); + void (*ic_release_bus)(void *, int); + + int (*ic_exec)(void *, i2c_op_t, i2c_addr_t, + const void *, size_t, void *, size_t, int); + + int (*ic_send_start)(void *, int); + int (*ic_send_stop)(void *, int); + int (*ic_initiate_xfer)(void *, i2c_addr_t, int); + int (*ic_read_byte)(void *, uint8_t *, int); + int (*ic_write_byte)(void *, uint8_t, int); +}; +.Ed +.Pp +The +.Fn (*ic_acquire_bus) +and +.Fn (*ic_release_bus) +functions must always be provided. +.Pp +The controller driver may elect to provide an +.Fn (*ic_exec) +function. +This function is intended for use by automated controllers +that do not provide manual control over I2C bus conditions +such as START and STOP. +.Pp +If the +.Fn (*ic_exec) +function is not provided, the following 5 functions will be +used by +.Fn iic_exec +in order to execute the I2C bus operation: +.Bl -tag -width XXXX +.It Fn (*ic_send_start) "cookie" "flags" +Send a START condition on the I2C bus. +The +.Fa I2C_F_POLL +flag indicates that sleeping is not permitted. +.It Fn (*ic_send_stop) "cookie" "flags" +Send a STOP condition on the I2C bus. +The +.Fa I2C_F_POLL +flag indicates that sleeping is not permitted. +.It Fn (*ic_initiate_xfer) "cookie" "addr" "flags" +Initiate a transfer on the I2C bus by sending a START condition and +then transmitting the I2C device address and transfer type. +The +.Fa I2C_F_READ +flag indicates a read transfer; the lack of this flag indicates a +write transfer. +The +.Fa I2C_F_POLL +flag indicates that sleeping is not permitted. +The error code +.Dv ETIMEDOUT +should be returned if a timeout that would indicate that the +device is not present occurs. +.It Fn (*ic_read_byte) "cookie" "datap" "flags" +Read a byte from the I2C bus into the memory location referenced by +.Fa datap . +The +.Fa I2C_F_LAST +flag indicates that this is the final byte of the transfer, and that +a NACK condition should be sent on the I2C bus following the transfer +of the byte. +The +.Fa I2C_F_STOP +flag indicates that a STOP condition should be sent on the I2C bus following +the transfer of the byte. +The +.Fa I2C_F_POLL +flag indicates that sleeping is not permitted. +.It Fn (*ic_write_byte) "cookie" "data" "flags" +Write the byte contained in +.Fa data +to the I2C bus. +The +.Fa I2C_F_STOP +flag indicates that a STOP condition should be sent on the I2C bus following +the transfer of the byte. +The +.Fa I2C_F_POLL +flag indicates that sleeping is not permitted. +.El +.Sh SEE ALSO +.Xr iic 4 +.Sh HISTORY +The +.Nm iic +API first appeared in +.Nx 2.0 . +.Ox +support was added in +.Ox 3.6 . +.Sh AUTHORS +The +.Nm iic +API was written by +Steve C. Woodford and Jason R. Thorpe for +.Nx +and then ported to +.Ox +by +.An Alexander Yurchenko Aq Mt grange@openbsd.org . diff --git a/static/openbsd/man9/imax.9 b/static/openbsd/man9/imax.9 new file mode 100644 index 00000000..6feff124 --- /dev/null +++ b/static/openbsd/man9/imax.9 @@ -0,0 +1,93 @@ +.\" $OpenBSD: imax.9,v 1.2 2018/04/23 11:11:38 jmc Exp $ +.\" +.\" Copyright (c) 2002, 2003 CubeSoft Communications, 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, 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 $Mdocdate: April 23 2018 $ +.Dt IMAX 9 +.Os +.Sh NAME +.Nm imax , +.Nm imin , +.Nm lmax , +.Nm lmin , +.Nm max , +.Nm min , +.Nm ulmax , +.Nm ulmin , +.Nm abs +.Nd kernel library math routines +.Sh SYNOPSIS +.In lib/libkern/libkern.h +.Ft int +.Fn imax "int a" "int b" +.Ft int +.Fn imin "int a" "int b" +.Ft long +.Fn lmax "long a" "long b" +.Ft long +.Fn lmin "long a" "long b" +.Ft u_int +.Fn max "u_int a" "u_int b" +.Ft u_int +.Fn min "u_int a" "u_int b" +.Ft u_long +.Fn ulmax "u_long a" "u_long b" +.Ft u_long +.Fn ulmin "u_long a" "u_long b" +.Ft int +.Fn abs "int j" +.Sh DESCRIPTION +The +.Fn min , +.Fn imin , +.Fn lmin +and +.Fn ulmin +functions return the smallest integer between +.Fa a +and +.Fa b , +inclusive. +The +.Fn max , +.Fn imax , +.Fn lmax +and +.Fn ulmax +functions return the largest integer between +.Fa a +and +.Fa b , +inclusive. +.Pp +The +.Fn abs +function computes the absolute value of integer +.Fa j . +.Sh STANDARDS +The +.Fn abs +function conforms to +.St -ansiC . diff --git a/static/openbsd/man9/inittodr.9 b/static/openbsd/man9/inittodr.9 new file mode 100644 index 00000000..f708d0b9 --- /dev/null +++ b/static/openbsd/man9/inittodr.9 @@ -0,0 +1,95 @@ +.\" $OpenBSD: inittodr.9,v 1.12 2020/06/26 18:48:31 cheloha Exp $ +.\" $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 $Mdocdate: June 26 2020 $ +.Dt INITTODR 9 +.Os +.Sh NAME +.Nm inittodr +.Nd initialize system time +.Sh SYNOPSIS +.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 reported by the file +system, as given in +.Fa base . +Those heuristics 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 nonsensical or was not provided (was given as zero), +an arbitrary base (typically some time in the late 1970s) +will be used. +.El +.Pp +Once a system time has been determined, it is passed to the +.Fn tc_setclock +function. +.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 microtime 9 , +.Xr resettodr 9 +.Sh BUGS +Each system's heuristics for picking the correct time are slightly +different. diff --git a/static/openbsd/man9/intr_barrier.9 b/static/openbsd/man9/intr_barrier.9 new file mode 100644 index 00000000..9dae3144 --- /dev/null +++ b/static/openbsd/man9/intr_barrier.9 @@ -0,0 +1,42 @@ +.\" $OpenBSD: intr_barrier.9,v 1.2 2015/09/13 17:55:42 jmc Exp $ +.\" +.\" Copyright (c) 2015 Mark Kettenis +.\" +.\" 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: September 13 2015 $ +.Dt INTR_BARRIER 9 +.Os +.Sh NAME +.Nm intr_barrier +.Nd interrupt barrier +.Sh SYNOPSIS +.In machine/intr.h +.Ft void +.Fn intr_barrier "void *ih" +.Sh DESCRIPTION +This function guarantees that any interrupt handler invocations for the +interrupt handler specified by +.Fa ih +has finished before it returns. +The cookie passed to +.Fn intr_barrier +should be the value returned when the interrupt handler was established, +for example the return value of +.Xr pci_intr_establish 9 . +.Sh CONTEXT +.Fn intr_barrier +can be called from process context. +.Sh SEE ALSO +.Xr pci_intr_establish 9 , +.Xr spl 9 diff --git a/static/openbsd/man9/intrmap_create.9 b/static/openbsd/man9/intrmap_create.9 new file mode 100644 index 00000000..f711ff9f --- /dev/null +++ b/static/openbsd/man9/intrmap_create.9 @@ -0,0 +1,125 @@ +.\" $OpenBSD: intrmap_create.9,v 1.4 2022/07/31 12:55:31 denis Exp $ +.\" +.\" Copyright (c) 2020 David Gwynne +.\" +.\" 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: July 31 2022 $ +.Dt INTRMAP_CREATE 9 +.Os +.Sh NAME +.Nm intrmap_create , +.Nm intrmap_destroy , +.Nm intrmap_count , +.Nm intrmap_cpu +.Nd interrupt to CPU mapping API +.Sh SYNOPSIS +.In sys/intrmap.h +.Ft struct intrmap * +.Fo intrmap_create +.Fa "const struct device *dv" +.Fa "unsigned int nintr" +.Fa "unsigned int maxintr" +.Fa "unsigned int flags" +.Fc +.Ft void +.Fn intrmap_destroy "struct intrmap *im" +.Ft unsigned int +.Fn intrmap_count "struct intrmap *im" +.Ft struct cpu_info * +.Fn intrmap_cpu "struct intrmap *im" "unsigned int index" +.Sh DESCRIPTION +The interrupt to CPU mapping API supports the use of multiple CPUs +by hardware drivers. +Drivers that can use multiple interrupts use the API to request a +set of CPUs that they can establish those interrupts on. +The API limits the requested number of interrupts to what is available +on the system, and attempts to distribute the requested interrupts +over those CPUs. +On some platforms the API will filter the set of available CPUs. +.\" to avoid hyperthreads, basically. +.Pp +.Fn intrmap_create +allocates an interrupt map data structure for use by the driver +identified by +.Fa dv . +The number of interrupts the hardware supports is specified via the +.Fa nintr +argument. +The driver supplies the maximum number of interrupts it can support +via +.Fa maxintr , +which, along with the number of available CPUs at the time the +function is called, is used as a constraint on the number of requested +interrupts. +.Fa nintr +may be zero to use the driver limit as the number of requested +interrupts. +The +.Fa flags +argument may have the following defines OR'ed together: +.Bl -tag -width xxx -offset indent +.It Dv INTRMAP_POWEROF2 +The hardware only supports a power of 2 number of interrupts, so +constrain the number of supplied interrupts after the system and +driver limits are applied. +.El +.Pp +.Fn intrmap_destroy +frees the memory associated with the interrupt map data structure +passed via +.Fa im . +.Pp +.Fn intrmap_count +returns the number of interrupts that the driver can establish +according to the +.Fa im +interrupt map. +.Pp +.Fn intrmap_cpu +returns which CPU the interrupt specified in +.Fa index +should be established on according to the +.Fa im +interrupt map. +Interrupts are identified as a number from 0 to the value returned by +.Fn intrmap_count . +.Sh CONTEXT +.Fn intrmap_create , +.Fn intrmap_destroy , +.Fn intrmap_count , +and +.Fn intrmap_cpu +can be called during autoconf, or from process context. +.Sh RETURN VALUES +.Fn intrmap_create +returns a pointer to an interrupt mapping structure on success, or +.Dv NULL +on failure. +.Pp +.Fn intrmap_count +returns the number of interrupts that were allocated for the driver +to use. +.Pp +.Fn intrmap_cpu +returns a pointer to the cpu_info structure for the CPU that the +interrupt should be established on. +.\" .Sh SEE ALSO +.\" .Xr pci_intr_establish_cpuid 9 +.Sh HISTORY +The interrupt mapping API is based on the if_ringmap API in +.Dx . +It was ported to +.Ox 6.8 +by +.An David Gwynne Aq Mt dlg@openbsd.org . diff --git a/static/openbsd/man9/intro.9 b/static/openbsd/man9/intro.9 new file mode 100644 index 00000000..037f6a60 --- /dev/null +++ b/static/openbsd/man9/intro.9 @@ -0,0 +1,46 @@ +.\" $OpenBSD: intro.9,v 1.14 2018/09/30 13:24:33 schwarze Exp $ +.\" +.\" Copyright (c) 1996 Michael Shalayeff +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 $Mdocdate: September 30 2018 $ +.Dt INTRO 9 +.Os +.Sh NAME +.Nm intro +.Nd introduction to the kernel internals +.Sh DESCRIPTION +The manual pages in section 9 contain information related to the +internal kernel data structures, variables and functions. +.Sh CODE REFERENCES +This section describes places within the +.Ox +source tree where actual code implementing or using kernel internals +can be found. +All pathnames are relative to +.Pa /usr/src . +.Sh HISTORY +An +.Nm +manual for section 9 appeared in +.Ox 1.2 . diff --git a/static/openbsd/man9/kcov_remote_register.9 b/static/openbsd/man9/kcov_remote_register.9 new file mode 100644 index 00000000..62c4042e --- /dev/null +++ b/static/openbsd/man9/kcov_remote_register.9 @@ -0,0 +1,95 @@ +.\" $OpenBSD: kcov_remote_register.9,v 1.6 2021/02/01 07:09:37 jmc Exp $ +.\" +.\" Copyright (c) 2020 Anton Lindqvist +.\" +.\" 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: February 1 2021 $ +.Dt KCOV_REMOTE_REGISTER 9 +.Os +.Sh NAME +.Nm kcov_remote_register , +.Nm kcov_remote_unregister , +.Nm kcov_remote_enter , +.Nm kcov_remote_leave +.Nd remote kernel code coverage collection interface +.Sh SYNOPSIS +.In sys/kcov.h +.Ft void +.Fn kcov_remote_register "int subsystem" "void *id" +.Ft void +.Fn kcov_remote_unregister "int subsystem" "void *id" +.Ft void +.Fn kcov_remote_enter "int subsystem" "void *id" +.Ft void +.Fn kcov_remote_leave "int subsystem" "void *id" +.Sh DESCRIPTION +These functions provide an interface to collect code coverage from various +kernel subsystems using +.Xr kcov 4 . +The +.Fa subsystem +must be one of the following: +.Pp +.Dl #define KCOV_REMOTE_COMMON 0 +.Pp +The +.Va id +must be a unique identifier for a resource tied to +.Va subsystem +that is known both by kernel and user space. +For instance, a network interface driver could form a subsystem using the +unique interface identifier as the +.Fa id . +.Pp +.Fn kcov_remote_register +registers a new instance of the given +.Fa subsystem . +Calling this function more than once with the same arguments is idempotent. +.Pp +.Fn kcov_remote_unregister +unregisters an existing instance of the given +.Fa subsystem , +if present. +If one or many threads are currently within a remote section, +.Fn kcov_remote_unregister +will sleep until all the sections have been left. +.Pp +.Fn kcov_remote_enter +enters a remote section. +If the current thread has +.Xr kcov 4 +enabled, code coverage will collected inside the remote section. +Remote sections may not be nested. +.Pp +.Fn kcov_remote_leave +leaves a remote section. +.Sh CONTEXT +.Fn kcov_remote_register +and +.Fn kcov_remote_unregister +can be called from process context. +.Fn kcov_remote_enter +and +.Fn kcov_remote_leave +can be called from interrupt and process context. +.Sh CODE REFERENCES +These functions are implemented in +.Pa sys/dev/kcov.c . +.Sh SEE ALSO +.Xr kcov 4 +.Sh HISTORY +These functions first appeared in +.Ox 6.8 . +.Sh AUTHORS +.An Anton Lindqvist Aq Mt anton@openbsd.org diff --git a/static/openbsd/man9/km_alloc.9 b/static/openbsd/man9/km_alloc.9 new file mode 100644 index 00000000..2feb82cd --- /dev/null +++ b/static/openbsd/man9/km_alloc.9 @@ -0,0 +1,181 @@ +.\" $OpenBSD: km_alloc.9,v 1.9 2019/12/06 19:15:16 jmc Exp $ +.\" Copyright (c) 2011 Artur Grabowski +.\" 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 $Mdocdate: December 6 2019 $ +.Dt KM_ALLOC 9 +.Os +.Sh NAME +.Nm km_alloc , +.Nm km_free +.Nd kernel memory allocator +.Sh SYNOPSIS +.In sys/types.h +.In uvm/uvm_extern.h +.Ft void * +.Fn km_alloc "size_t sz" "const struct kmem_va_mode *kv" "const struct kmem_pa_mode *kp" "const struct kmem_dyn_mode *kd" +.Ft void +.Fn km_free "void *v" "size_t sz" "const struct kmem_va_mode *kv" "const struct kmem_pa_mode *kp" +.Sh DESCRIPTION +The +.Fn km_alloc +function allocates kernel virtual space optionally backed by physical pages. +The +.Fn km_free +function frees the space that was previously allocated by +.Fn km_alloc . +.Pp +The +.Fa sz +argument specifies the size of the allocation and must be a multiple +of +.Dv PAGE_SIZE . +The +.Fa kv +and +.Fa kp +arguments specify the type of virtual and physical memory to be allocated. +The +.Fa kd +argument specifies additional options for the allocation. +The arguments passed to +.Fn km_free +must match those that were used to obtain the space in +.Fn km_alloc . +.Pp +Typically a user will use certain predefined modes for memory allocation. +For virtual space the predefined modes are: +.Pp +.Bl -tag -width kv_intrsafe -offset 3n -compact +.It kv_any +Allocates the virtual space anywhere. +.It kv_intrsafe +Allocates the virtual space in the interrupt safe map. +.It kv_page +Allocates single pages. +.El +.Pp +For physical pages the predefined modes are: +.Pp +.Bl -tag -width kp_pageable -offset 3n -compact +.It kp_dirty +Maps dirty pages into the allocation. +.It kp_zero +Maps zeroed pages into the allocation. +.It kp_dma +Maps dma-accessible pages into the allocation. +.It kp_dma_zero +Maps zeroed dma-accessible pages into the allocation. +.It kp_pageable +Pages will be demand paged. +.It kp_none +Leaves the allocation unmapped. +.El +.Pp +The other parameters for allocation are: +.Pp +.Bl -tag -width kd_trylock -offset 3n -compact +.It kd_waitok +Sleeping for physical pages is allowed. +.It kd_nowait +Sleeping is not allowed. +.It kd_trylock +Fail if the allocator cannot obtain locks without waiting. +.El +.Pp +In case the predefined allocation modes are not sufficient, a custom allocation +mode can be created. +The structure controlling the virtual space allocation is: +.Bd -literal +struct kmem_va_mode { + struct vm_map **kv_map; + vsize_t kv_align; + int kv_wait; + int kv_singlepage; +}; +.Ed +.Bl -tag -width kv_singlepage +.It kv_map +A pointer to the pointer to the uvm_map the space will be allocated from. +.It kv_align +Alignment constraint of the allocated space. +.It kv_wait +A flag indicating whether the allocator should wait for space to be freed if +the allocation cannot be satisfied. +.It kv_singlepage +A flag indicating if the allocations will always be for single pages. +.El +.Bd -literal +struct kmem_pa_mode { + struct uvm_constraint_range *kp_constraint; + struct uvm_object **kp_object; + paddr_t kp_align; + paddr_t kp_boundary; + int kp_nomem; + int kp_maxseg; + int kp_zero; + int kp_pageable; +}; +.Ed +.Bl -tag -width kp_constraint +.It kp_constraint +A pointer to physical allocation constraints. +.It kp_object +A pointer to a pointer to a uvm_object if the pages should be backed by a +kernel object. +.It kp_align +Physical alignment of the first page in the allocation. +.It kp_boundary +Boundary that the physical addresses can't cross if the allocation is +contiguous. +.It kp_nomem +A flag that specifies that the allocation should not be backed by physical +pages. +.It kp_maxseg +Maximal amount of contiguous physical segments in the allocation. +.It kp_zero +A flag that specifies if the returned memory should be zeroed. +.It kp_pageable +A flag that specifies if the returned memory should be demand paged from the +backing object instead of being allocated up front. +.El +.Bd -literal +struct kmem_dyn_mode { + int kd_waitok; + int kd_trylock; + voff_t kd_prefer; + int *kd_slowdown; +}; +.Ed +.Bl -tag -width kd_slowdown +.It kd_waitok +A flag that specifies if the allocator may sleep waiting for memory. +.It kd_trylock +A flag that specifies if the allocator should fail if it can't immediately +obtain a lock. +.It kd_prefer +An offset given to PMAP_PREFER to virtually align the allocated space. +.It kd_slowdown +A pointer to an integer that will be set to 1 if the internal single page +allocator needs the caller to back off to allow the allocator to catch up. +.El +.Sh RETURN VALUES +.Fn km_alloc +returns a kernel virtual address or +.Dv NULL +if the allocation cannot be satisfied. +.Sh SEE ALSO +.Xr malloc 9 , +.Xr uvm_init 9 diff --git a/static/openbsd/man9/knote.9 b/static/openbsd/man9/knote.9 new file mode 100644 index 00000000..81b66310 --- /dev/null +++ b/static/openbsd/man9/knote.9 @@ -0,0 +1,114 @@ +.\" $OpenBSD: knote.9,v 1.10 2023/02/10 14:34:16 visa Exp $ +.\" $NetBSD: knote.9,v 1.9 2003/04/16 13:35:29 wiz Exp $ +.\" +.\" Copyright (c) 2001, 2002, 2003 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation is derived from text contributed 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 $Mdocdate: February 10 2023 $ +.Dt KNOTE 9 +.Os +.Sh NAME +.Nm knote , +.Nm knote_locked +.Nd raise kernel event +.Sh SYNOPSIS +.In sys/param.h +.In sys/event.h +.Ft void +.Fn knote "struct klist *list" "long hint" +.Ft void +.Fn knote_locked "struct klist *list" "long hint" +.Sh DESCRIPTION +The +.Fn knote +and +.Fn knote_locked +functions provide a hook into the kqueue kernel event notification +mechanism to allow sections of the kernel to raise a kernel event +in the form of a +.Sq knote , +which is a +.Fa struct knote +as defined in +.In sys/event.h . +.Pp +.Fn knote +takes a singly linked +.Fa list +of knotes, along with a +.Fa hint +(which is passed to the appropriate filter routine). +.Fn knote +then locks and walks the +.Fa list +making calls to the filter routine for each knote. +As each knote contains a reference to the data structure that it is +attached to, the filter may choose to examine the data structure in +deciding whether an event should be reported. +The +.Fa hint +is used to pass in additional information, which may not be present in +the data structure that the filter examines. +.Pp +If the filter decides that the event should be returned, it returns a +non-zero value and +.Fn knote +links the knote onto the tail end of the active list in the +corresponding kqueue for the application to retrieve. +If the knote is already on the active list, no action is taken, but the +call to the filter occurs in order to provide an opportunity for the +filter to record the activity. +.Pp +.Fn knote_locked +is like +.Fn knote +but assumes that the +.Fa list +is already locked. +.Pp +.Fn knote +and +.Fn knote_locked +must not be called from interrupt contexts running at an interrupt +priority level higher than +.Fn splsched . +.\" .Sh ERRORS +.Sh SEE ALSO +.Xr kqueue 2 +.\" .Xr kfilter_register 9 +.Sh HISTORY +The +.Fn knote +functions first appeared in +.Fx 4.1 , +and then in +.Ox 2.9 . +.Sh AUTHORS +The +.Fn kqueue +system was written by +.An Jonathan Lemon Aq Mt jlemon@FreeBSD.org . diff --git a/static/openbsd/man9/kstat_create.9 b/static/openbsd/man9/kstat_create.9 new file mode 100644 index 00000000..f17112ee --- /dev/null +++ b/static/openbsd/man9/kstat_create.9 @@ -0,0 +1,268 @@ +.\" $OpenBSD: kstat_create.9,v 1.7 2022/09/10 08:50:53 jsg Exp $ +.\" +.\" Copyright (c) 2020 David Gwynne +.\" +.\" 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: September 10 2022 $ +.Dt KSTAT_CREATE 9 +.Os +.Sh NAME +.Nm kstat_create , +.Nm kstat_read_nop , +.Nm kstat_set_wlock , +.Nm kstat_set_rlock , +.Nm kstat_set_mutex , +.Nm kstat_install , +.Nm kstat_remove , +.Nm kstat_destroy +.Nd kernel statistics provider API +.Sh SYNOPSIS +.In sys/kstat.h +.Ft struct kstat * +.Fo kstat_create +.Fa "const char *provider" +.Fa "unsigned int instance" +.Fa "const char *name" +.Fa "unsigned int unit" +.Fa "unsigned int type" +.Fa "unsigned int flags" +.Fc +.Ft int +.Fn kstat_read_nop "struct kstat *ks" +.Ft void +.Fn kstat_set_wlock "struct kstat *ks" "struct rwlock *rwl" +.Ft void +.Fn kstat_set_rlock "struct kstat *ks" "struct rwlock *rwl" +.Ft void +.Fn kstat_set_mutex "struct kstat *ks" "struct mutex *mtx" +.Ft void +.Fn kstat_install "struct kstat *ks" +.Ft void +.Fn kstat_remove "struct kstat *ks" +.Ft void +.Fn kstat_destroy "struct kstat *ks" +.Sh DESCRIPTION +Kernel subsystems can provide statistics to userland using the kernel +statistics (kstat) API. +.Pp +A kstat is uniquely identified by a tuple made up of the +.Fa provider , +.Fa instances , +.Fa name , +and +.Fa unit +arguments. +.\" Once created, the kstat API allocates a unique 64bit identifier for +.\" the kstat. +.Pp +The information exported by a kstat is typed. +The supported kstat types are +.Bl -tag -width xxx -offset indent +.It Dv KSTAT_T_RAW +The kstat provides raw bytes. +.It Dv KSTAT_T_KV +The kstat provides a series of +.Vt struct kstat_kv +structures that represent key/value information. +See +.Xr kstat_kv_init 9 +for more detail. +.El +.Pp +Below is a simplified version of the +.Vt kstat +structure that shows the fields that a subsystem operates on: +.Bd -literal +struct kstat { + void *ks_softc; + void *ks_ptr; + + void *ks_data; + size_t ks_datalen; + struct timespec ks_updated; + + int (*ks_read)(struct kstat *ks); + int (*ks_copy)(struct kstat *ks, void *dst); + + const struct kstat_lock_ops * + ks_lock_ops; + void *ks_lock; +}; +.Ed +.Pp +The +.Fa ks_softc +and +.Fa ks_ptr +fields are available for the subsystem providing the kstat to use. +For example, if a hardware device driver is providing a kstat then +.Fa ks_softc +can be initialised with a reference to the softc structure allocated +for that device driver. +.Fa ks_ptr +is intended for use by a subsystem to refer to data or state that +is only needed when providing the kstat which would not otherwise +be referenced by the provider. +.Pp +The +.Fa ks_datalen +field specifies how much data is exported by the kstat to userland. +.Pp +.Fa ks_updated +is set by the provider to the system uptime when the kstat data was +updated. +.Pp +.Fa ks_data +may be set to a data buffer used to store the kstat data payload. +.Pp +The +.Fa ks_read +handler is called by the kstat API when userland requests the current +kstat data. +A kstat provider may ignore the request via and update the data by +another process. +For example, a device may periodically update a set of statistics +and notify the kernel when the new statistics are available with +an interrupt. +Such a driver would update the kstat data and +.Fa ks_updated +when the interrupt is processed, and ignore the request to update +from userland. +The default +.Fa ks_read +handler sets +.Fa ks_updated +using +.Xr getnanouptime 9 . +.Pp +The +.Fa ks_copy +handler is used by the kstat API to copy the current kstat data into the +.Fa dst +buffer. +The default +.Fa ks_copy +handler uses +.Xr memcpy 3 +to copy +.Fa ks_datalen +bytes from +.Fa ks_data +to +.Fa dst . +.Pp +Accesses to the above +.Vt kstat +structure fields and calls to the +.Fa ks_read +and +.Fa ks_copy +handlers by the kstat subsystem are serialised by the locking primitive +referenced by +.Fa ks_lock . +By default +.Fa ks_lock +references a global write lock provided by the kstat API, +but should be set to a provider specific lock with the +.Fa kstat_set_rlock , +.Fa kstat_set_wlock , +or +.Fa kstat_set_mutex +functions. +.Pp +The +.Fn kstat_create +function allocates a +.Vt kstat +structure and adds it to the list of statistics that userland can +query. +Once a +.Vt kstat +structure has been created, +the caller is responsible for initialising the structure. +.Pp +.Fn kstat_read_nop +can be used as a +.Fa ks_read +handler to ignore the request to update the kstat data and +.Fa ks_updated +timestamp. +.Pp +The +.Fn kstat_set_wlock +and +.Fn kstat_set_rlock +functions specifies that the +.Fa rwl +read/write lock should be used as an exclusive or shared lock +respectively by the kstat API when interacting with the provider. +.Pp +The +.Fn kstat_set_mutex +function specifies that the +.Fa mtx +mutex should be acquired by the kstat API when interacting with the +provider. +.Pp +After the structure has been initialised, +.Fn kstat_install +notifies the kstat subsystem that +.Fa ks +can be used to export information to userland. +.Pp +.Fn kstat_remove +disables the kstat, preventing it from being used to export information +to userland. +This allows allocations referenced by the kstat struct to be released +and configuration torn down before the kstat itself is freed with +.Fn kstat_destroy . +.Pp +.Fn kstat_destroy +removes +.Fa ks +from the list of exported statistics and frees it. +.Sh CONTEXT +.Fn kstat_create , +.Fn kstat_install , +.Fn kstat_remove , +.Fn kstat_set_wlock , +.Fn kstat_set_rlock , +.Fn kstat_set_mutex , +and +.Fn kstat_destroy +can be called during autoconf, or from process context. +They cannot be called by a +.Fa ks_read +or +.Fa ks_copy +handler. +.Sh RETURN VALUES +.Fn kstat_create +returns a pointer to a +.Vt kstat +structure on success, or +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr kstat 1 , +.Xr memcpy 3 , +.Xr kstat 4 , +.Xr kstat_kv_init 9 , +.Xr mtx_enter 9 , +.Xr rw_enter 9 +.Sh HISTORY +These functions first appeared in +.Ox 6.8 . +.Sh AUTHORS +.An David Gwynne Aq Mt dlg@openbsd.org diff --git a/static/openbsd/man9/kstat_kv_init.9 b/static/openbsd/man9/kstat_kv_init.9 new file mode 100644 index 00000000..522a76db --- /dev/null +++ b/static/openbsd/man9/kstat_kv_init.9 @@ -0,0 +1,125 @@ +.\" $OpenBSD: kstat_kv_init.9,v 1.2 2020/08/10 11:33:58 schwarze Exp $ +.\" +.\" Copyright (c) 2020 David Gwynne +.\" +.\" 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: August 10 2020 $ +.Dt KSTAT_KV_INIT 9 +.Os +.Sh NAME +.Nm kstat_kv_init , +.Nm kstat_kv_unit_init , +.Nm KSTAT_KV_INITIALIZER , +.Nm KSTAT_KV_UNIT_INITIALIZER +.Nd kernel statistic key/value data API +.Sh SYNOPSIS +.In sys/kstat.h +.Ft void +.Fo kstat_kv_init +.Fa "struct kstat_kv *kv" +.Fa "const char *key" +.Fa "enum kstat_kv_type type" +.Fc +.Ft void +.Fo kstat_kv_unit_init +.Fa "struct kstat_kv *kv" +.Fa "const char *key" +.Fa "enum kstat_kv_type type" +.Fa "enum kstat_kv_unit unit" +.Fc +.Fo KSTAT_KV_INITIALIZER +.Fa "const char *name" +.Fa "enum kstat_kv_type type" +.Fc +.Fo KSTAT_KV_UNIT_INITIALIZER +.Fa "const char *name" +.Fa "enum kstat_kv_type type" +.Fa "enum kstat_kv_unit unit" +.Fc +.Sh DESCRIPTION +The kstat key/value data API supports the creation and maintenance of +.Vt kstat_kv +structures that can be exported to userland using the kstat API. +.Pp +A kstat key/value data payload for a +.Vt kstat +structure +.Po +created using +.Xr kstat_create 9 +with +.Dv KSTAT_T_KV +as the +.Fa type +argument +.Pc +is a series of +.Vt kstat_kv +structures in memory. +kstat_kv values are typed, and the memory used to store values of +different types is either inline as part of the structure, or is +extra bytes following a structure of a specified length. +.\" .Pp +.\" kstat_kv structures contain the following fields: +.Pp +.Fn kstat_kv_init +initialises +.Fa kv +with a name specified as +.Fa key . +The type of the value is specified as +.Fa type . +.Pp +.Fn kstat_kv_unit_init +initialises +.Fa kv +with a name specified as +.Fa key . +The integer or counter type of the value is specified as +.Fa type , +and specifies the units for the values in +.Fa unit . +.Pp +A +.Vt kstat_kv +structure can be initialised at compile time with the +.Fn KSTAT_KV_INITIALIZER +macro. +The +.Vt kstat_kv +structure will be declared with the name +.Fa key +with the type of the values as +.Fa type . +.Pp +A +.Vt kstat_kv +structure can be initialised at compile time with the +.Fn KSTAT_KV_UNIT_INITIALIZER +macro. +The +.Vt kstat_kv +structure will be declared with the name +.Fa key +with the integer or counter type of the values as +.Fa type , +and specifies the units for the values in +.Fa unit . +.Sh SEE ALSO +.Xr kstat_create 9 +.Sh HISTORY +These functions first appeared in +.Ox 6.8 . +.Sh AUTHORS +.An David Gwynne Aq Mt dlg@openbsd.org diff --git a/static/openbsd/man9/kthread.9 b/static/openbsd/man9/kthread.9 new file mode 100644 index 00000000..5556b093 --- /dev/null +++ b/static/openbsd/man9/kthread.9 @@ -0,0 +1,97 @@ +.\" $OpenBSD: kthread.9,v 1.10 2013/11/18 20:21:50 deraadt Exp $ +.\" +.\" Copyright (c) 1999 Marc Espie +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list 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 $Mdocdate: November 18 2013 $ +.Dt KTHREAD 9 +.Os +.Sh NAME +.Nm kthread_create , +.Nm kthread_exit , +.Nm kthread_create_deferred +.Nd kernel threads +.Sh SYNOPSIS +.In sys/kthread.h +.Ft int +.Fn kthread_create "void (*func)(void *)" "void *arg" "struct proc **newpp" "const char *name" +.Ft void +.Fn kthread_exit "int ecode" +.Ft void +.Fn kthread_create_deferred "void (*func)(void *)" "void *arg" +.Sh DESCRIPTION +Kernel threads are system light-weight processes: cloned from process 0 +(the swapper), sharing its memory map and limits, but with a copy of its +file descriptor table. +They don't receive broadcast nor group signals and they can't be swapped. +.Pp +Any process can call +.Fn kthread_create +to create a kernel thread. +The new process starts up executing +.Fa func +with argument +.Fa arg . +If +.Fa newpp +is not +.Dv NULL , +it is filled with the address of the new process. +.Fa name +is used to name the process. +.Pp +A kernel thread will terminate by calling +.Fn kthread_exit , +with exit code +.Fa ecode . +.Pp +Since the system has to be up and running for creating +new processes, device drivers that want to create kernel threads early +(e.g., at attach time) may use +.Fn kthread_create_deferred +instead. +The system will call back the function +.Fa func +with argument +.Fa arg +when it can create threads, so it is up to +.Fa func +to call +.Fn kthread_create +at that point. +.Sh RETURN VALUES +Upon successful completion, +.Fn kthread_create +returns 0. +Otherwise, the following error values are returned: +.Bl -tag -width [EAGAIN] +.It Bq Er EAGAIN +The limit on the total number of system processes would be exceeded. +.El +.Sh SEE ALSO +.Xr fork1 9 +.Sh BUGS +There is currently no way to use +.Va ecode +to any sensible purpose from +.Fn kthread_exit . diff --git a/static/openbsd/man9/ktrace.9 b/static/openbsd/man9/ktrace.9 new file mode 100644 index 00000000..36fbc29a --- /dev/null +++ b/static/openbsd/man9/ktrace.9 @@ -0,0 +1,157 @@ +.\" $OpenBSD: ktrace.9,v 1.14 2023/12/13 06:39:10 jmc Exp $ +.\" +.\" Copyright (c) 2003 Michael Shalayeff +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 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 $Mdocdate: December 13 2023 $ +.Dt KTRACE 9 +.Os +.Sh NAME +.Nm ktrgenio , +.Nm ktrnamei , +.Nm ktrpsig , +.Nm ktrsyscall , +.Nm ktrsysret , +.Nm KTRPOINT +.Nd process tracing kernel interface +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.In sys/ktrace.h +.Fn KTRPOINT "struct proc *p" "int type" +.Ft void +.Fn ktrgenio "struct proc *p" "int fd" "enum uio_rw rw" "struct iovec *iov" "int len" "int error" +.Ft void +.Fn ktrnamei "struct proc *p" "char *path" +.Ft void +.Fn ktrpsig "struct proc *p" "int sig" "sig_t action" "int mask" "int code" "siginfo_t *si" +.Ft void +.Fn ktrsyscall "struct proc *p" "register_t code" "size_t argsize" "register_t args[]" +.Ft void +.Fn ktrsysret "struct proc *p" "register_t code" "int error" "register_t retval" +.Sh DESCRIPTION +This interface is meant for kernel subsystems and machine dependent code +to inform the user about the events occurring to the process should +tracing of such be enabled using the +.Xr ktrace 2 +system call. +Each of the functions (except for +.Nm KTRPOINT ) +is meant for a particular type of event and is described below. +.Pp +The +.Fn KTRPOINT +macro should be used before calling any of the other tracing functions +to verify that tracing for that particular type of events has been enabled. +.Fa type +must be a KTR_ value corresponding to a KTRFAC_ value described in +.Xr ktrace 2 . +.Pp +.Fn ktrgenio +should be called for each generic input/output transaction that is +described by the +.Fa fd +file descriptor, +.Fa rw +transaction type (consult +.Pa sys/sys/uio.h +for the +.Nm enum uio_rw +definition), +.Fa iov +input/output data vector, +.Fa len +size of the +.Fa iov +vector, +and, lastly, +.Fa error +status of the transaction. +.Pp +.Fn ktrnamei +should be called every time a +.Xr namei 9 +operation is performed over the +.Fa path +name. +.Pp +.Fn ktrpsig +should be called for each signal +.Fa sig +posted for the traced process. +The +.Fa action +taken is one of +.Nm SIG_DFL , +.Nm SIG_IGN , +or +.Nm SIG_ERR +as described in the +.Xr sigaction 2 +document. +.Fa mask +is the current traced process' signal mask. +Signal-specific code and +.Em siginfo_t +structure as described in +.In sys/siginfo.h +are given in the +.Fa code +and +.Fa si +arguments respectively. +.Pp +.Fn ktrsyscall +should be called for each system call number +.Fa code +executed with arguments in +.Fa args +of total count of +.Fa argsize . +.Pp +.Fn ktrsysret +should be called for a return from each system call number +.Fa code +and error number of +.Fa error +as described in +.Xr errno 2 +and a return value in +.Fa retval +that is syscall dependent. +.Sh CODE REFERENCES +The process tracing facility is implemented in +.Pa sys/kern/kern_ktrace.c . +.Sh SEE ALSO +.Xr errno 2 , +.Xr ktrace 2 , +.Xr namei 9 , +.Xr syscall 9 +.Sh HISTORY +The process tracing facility first appeared in +.Bx 4.3 Reno . +.Pp +The +.Nm ktrace +section manual page appeared in +.Ox 3.4 . diff --git a/static/openbsd/man9/lim_cur.9 b/static/openbsd/man9/lim_cur.9 new file mode 100644 index 00000000..5558c2c0 --- /dev/null +++ b/static/openbsd/man9/lim_cur.9 @@ -0,0 +1,119 @@ +.\" $OpenBSD: lim_cur.9,v 1.2 2019/06/21 12:56:46 visa Exp $ +.\" +.\" Copyright (c) 2019 Visa Hankala +.\" +.\" 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: June 21 2019 $ +.Dt LIM_CUR 9 +.Os +.Sh NAME +.Nm lim_cur , +.Nm lim_cur_proc , +.Nm lim_fork , +.Nm lim_free , +.Nm lim_read_enter , +.Nm lim_read_leave +.Nd Resource limit interface +.Sh SYNOPSIS +.In sys/types.h +.In sys/resourcevar.h +.Ft rlim_t +.Fn "lim_cur" "int which" +.Ft rlim_t +.Fn "lim_cur_proc" "struct proc *p" "int which" +.Ft struct plimit * +.Fn "lim_fork" "struct process *parent" "struct process *child" +.Ft void +.Fn "lim_free" "struct plimit *limit" +.Ft struct plimit * +.Fn "lim_read_enter" +.Ft void +.Fn "lim_read_leave" "struct plimit *limit" +.Sh DESCRIPTION +The resource limit interface provides read access to the resource limits +of the process. +.Pp +.Fn lim_cur +returns the value of limit +.Fa which +of the current process. +The +.Fa which +can take one of the following values: +.Bd -literal +#define RLIMIT_CPU 0 /* cpu time in milliseconds */ +#define RLIMIT_FSIZE 1 /* maximum file size */ +#define RLIMIT_DATA 2 /* data size */ +#define RLIMIT_STACK 3 /* stack size */ +#define RLIMIT_CORE 4 /* core file size */ +#define RLIMIT_RSS 5 /* resident set size */ +#define RLIMIT_MEMLOCK 6 /* locked-in-memory address space */ +#define RLIMIT_NPROC 7 /* number of processes */ +#define RLIMIT_NOFILE 8 /* number of open files */ +.Ed +.Pp +.Fn lim_cur_proc +is like +.Fn lim_cur +but returns the value of limit +.Fa which +of thread +.Fa p . +.Pp +.Fn lim_read_enter +begins read access to the current process' resource limit structure. +.Pp +.Fn lim_read_leave +finishes read access to the resource limit structure. +.Pp +Sections denoted by +.Fn lim_read_enter +and +.Fn lim_read_leave +cannot nest. +Using +.Fn lim_cur +inside the read section is not allowed +because the function uses +.Fn lim_read_enter +and +.Fn lim_read_leave +internally. +.Pp +.Fn lim_free +releases the reference +.Fa limit . +.Pp +.Fn lim_fork +makes the process +.Fa child +share the resource limits of process +.Fa parent . +.Sh CONTEXT +.Fn lim_cur , +.Fn lim_cur_proc , +.Fn lim_fork , +.Fn lim_free , +.Fn lim_read_enter +and +.Fn lim_read_leave +can be called during autoconf, or from process context. +.Sh RETURN VALUES +.Fn lim_cur +and +.Fn lim_cur_proc +return the value of the given resource limit. +.Pp +.Fn lim_read_enter +returns a read reference to the current process' resource limits. diff --git a/static/openbsd/man9/loadfirmware.9 b/static/openbsd/man9/loadfirmware.9 new file mode 100644 index 00000000..fb672ce6 --- /dev/null +++ b/static/openbsd/man9/loadfirmware.9 @@ -0,0 +1,58 @@ +.\" $OpenBSD: loadfirmware.9,v 1.4 2013/06/04 19:27:08 schwarze Exp $ +.\" +.\" Copyright (c) 2004 Theo de Raadt +.\" 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 $Mdocdate: June 4 2013 $ +.Dt LOADFIRMWARE 9 +.Os +.Sh NAME +.Nm loadfirmware +.Nd load a firmware file from the filesystem +.Sh SYNOPSIS +.In sys/device.h +.Ft int +.Fn loadfirmware "const char *filename" "u_char **buf" "size_t *buflen" +.Sh DESCRIPTION +The +.Fn loadfirmware +function loads a firmware from the file specified by +.Ar filename +in the directory +.Pa /etc/firmware . +Memory for the firmware is allocated using +.Xr malloc 9 +with type +.Va M_DEVBUF +as need be, within a reasonable size limit. +.Pp +If no longer needed, the firmware buffer +.Va buf +can be freed using +.Xr free 9 +with type +.Va M_DEVBUF . +.Sh RETURN VALUES +If successful, +.Ar buf +is set to point to the allocation and +.Ar buflen +is set to the size of the firmware. +Then +.Fn loadfirmware +returns 0. +Otherwise, it returns an +.Va errno +style error. diff --git a/static/openbsd/man9/log.9 b/static/openbsd/man9/log.9 new file mode 100644 index 00000000..f5afab28 --- /dev/null +++ b/static/openbsd/man9/log.9 @@ -0,0 +1,75 @@ +.\" $OpenBSD: log.9,v 1.11 2015/09/14 15:14:55 schwarze Exp $ +.\" $NetBSD: log.9,v 1.6 1999/08/17 05:24:06 enami Exp $ +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Michael Graff. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 $Mdocdate: September 14 2015 $ +.Dt LOG 9 +.Os +.Sh NAME +.Nm log , +.Nm addlog +.Nd log a message from the kernel through the /dev/klog device +.Sh SYNOPSIS +.In sys/syslog.h +.Ft void +.Fo log +.Fa "int level" +.Fa "const char *format" +.Fa "..." +.Fc +.Ft void +.Fn addlog "const char *format" ... +.Sh DESCRIPTION +The +.Fn log +function allows the kernel to send formatted messages to user processes +listening on +.Pa /dev/klog . +Usually +.Xr syslogd 8 +monitors +.Pa /dev/klog +for these messages and writes them to a log file. +.Pp +All messages are formatted using +.Xr printf 9 , +logged using facility +.Dv LOG_KERN , +and priority level +.Fa level . +.Pp +The +.Fn addlog +function is used to build a log message in steps, by adding information +to an initial call to +.Fn log . +.Sh SEE ALSO +.Xr syslog 3 , +.Xr syslogd 8 , +.Xr printf 9 diff --git a/static/openbsd/man9/malloc.9 b/static/openbsd/man9/malloc.9 new file mode 100644 index 00000000..a1fa4be2 --- /dev/null +++ b/static/openbsd/man9/malloc.9 @@ -0,0 +1,403 @@ +.\" $OpenBSD: malloc.9,v 1.72 2024/01/19 15:10:27 deraadt Exp $ +.\" $NetBSD: malloc.9,v 1.2 1996/10/30 05:29:54 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 $Mdocdate: January 19 2024 $ +.Dt MALLOC 9 +.Os +.Sh NAME +.Nm malloc , +.Nm mallocarray , +.Nm free +.Nd kernel memory allocator +.Sh SYNOPSIS +.In sys/types.h +.In sys/malloc.h +.Ft void * +.Fn malloc "size_t size" "int type" "int flags" +.Ft void * +.Fn mallocarray "size_t nmemb" "size_t size" "int type" "int flags" +.Ft void +.Fn free "void *addr" "int type" "size_t size" +.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 mallocarray +function is the same as +.Fn malloc , +but allocates space for an array of +.Fa nmemb +objects and checks for arithmetic overflow. +.Pp +The +.Fn free +function releases memory at address +.Fa addr +that was previously allocated by +.Fn malloc +or +.Fn mallocarray +for re-use. +The same object size originally provided to +.Fn malloc +should be specified by +.Fa size , +because +.Fn free +will operate faster knowing this. +If tracking the size is difficult, specify +.Ar size +as 0. +If +.Fa addr +is a null pointer, no action occurs. +.Pp +The +.Fa flags +argument affects the operational characteristics of +.Fn malloc +and +.Fn mallocarray +as follows: +.Bl -tag -width xxx -offset indent +.It Dv M_WAITOK +If memory is currently unavailable, +.Fn malloc +may call sleep to wait for resources to be released by other processes. +.It Dv M_NOWAIT +Causes +.Fn malloc +to return +.Dv NULL +if the request cannot be immediately fulfilled due to resource shortage. +.It Dv M_CANFAIL +In the +.Dv M_WAITOK +case, if not enough memory is available, return +.Dv NULL +instead of calling +.Xr panic 9 . +If +.Fn mallocarray +detects an overflow +or +.Fn malloc +detects an excessive allocation, return +.Dv NULL +instead of calling +.Xr panic 9 . +.It Dv M_ZERO +Causes allocated memory to be zeroed. +.El +.Pp +One of +.Dv M_NOWAIT +or +.Dv M_WAITOK +must be specified via the +.Fa flags +argument. +.Pp +The +.Fa type +argument broadly identifies the kernel subsystem for which the allocated +memory was needed, and is commonly used to maintain statistics about +kernel memory usage. +These statistics can be examined using +.Xr vmstat 8 +or +.Xr systat 1 +if either of the kernel +.Xr options 4 +.Cm KMEMSTATS +or +.Cm DEBUG +are enabled. +.Pp +The following types are currently defined: +.Pp +.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact +.\" START DEFINES sys/malloc.h (M_FREE,M_LAST) +.It Dv M_DEVBUF +Device driver memory. +.It Dv M_PCB +Protocol control blocks. +.It Dv M_RTABLE +Routing tables. +.It Dv M_PF +Packet filter structures. +.It Dv M_IFADDR +Interface addresses. +.It Dv M_IFGROUP +Interface groups. +.It Dv M_SYSCTL +Sysctl persistent buffers. +.It Dv M_COUNTERS +Per-CPU counters via +.Xr counters_alloc 9 . +.It Dv M_IOCTLOPS +Ioctl data buffers. +.It Dv M_IOV +Large IOVs. +.It Dv M_MOUNT +VFS mount structs. +.It Dv M_NFSREQ +NFS request headers. +.It Dv M_NFSMNT +NFS mount structures. +.It Dv M_LOG +Messages in kernel log stash. +.It Dv M_VNODE +Dynamically allocated vnodes. +.It Dv M_DQUOT +UFS quota entries. +.It Dv M_UFSMNT +UFS mount structures. +.It Dv M_SHM +SVID compatible shared memory segments. +.It Dv M_VMMAP +VM map structures. +.It Dv M_SEM +SVID compatible semaphores. +.It Dv M_DIRHASH +UFS directory hash structures. +.It Dv M_ACPI +ACPI structures. +.It Dv M_VMPMAP +VM pmap data. +.It Dv M_FILEDESC +Open file descriptor tables. +.It Dv M_SIGIO +Sigio structures. +.It Dv M_PROC +Proc structures. +.It Dv M_SUBPROC +Proc sub-structures. +.It Dv M_MFSNODE +MFS vnode private part. +.It Dv M_NETADDR +Export host address structures. +.It Dv M_NFSSVC +NFS server structures. +.It Dv M_NFSD +NFS server daemon structures. +.It Dv M_IPMOPTS +Internet multicast options. +.It Dv M_IPMADDR +Internet multicast addresses. +.It Dv M_IFMADDR +Link-level multicast addresses. +.It Dv M_MRTABLE +Multicast routing tables. +.It Dv M_ISOFSMNT +ISOFS mount structures. +.It Dv M_ISOFSNODE +ISOFS vnode private part. +.It Dv M_MSDOSFSMNT +MSDOS FS mount structures. +.It Dv M_MSDOSFSFAT +MSDOS FS FAT tables. +.It Dv M_MSDOSFSNODE +MSDOS FS vnode private part. +.It Dv M_TTYS +Allocated tty structures. +.It Dv M_EXEC +Argument lists & other mem used by exec. +.It Dv M_MISCFSMNT +Miscellaneous FS mount structures. +.It Dv M_FUSEFS +FUSE FS mount structures. +.It Dv M_PINSYSCALL +.Xr pinsyscalls 2 +related data. +.It Dv M_PFKEY +Pfkey data. +.It Dv M_TDB +Transforms database. +.It Dv M_XDATA +IPsec data. +.It Dv M_PAGEDEP +File page dependencies. +.It Dv M_INODEDEP +Inode dependencies. +.It Dv M_NEWBLK +New block allocation. +.It Dv M_INDIRDEP +Indirect block dependencies. +.It Dv M_VMSWAP +VM swap structures. +.It Dv M_UVMAMAP +UVM amap and related. +.It Dv M_UVMAOBJ +UVM aobj and related. +.It Dv M_USB +USB general. +.It Dv M_USBDEV +USB device driver. +.It Dv M_USBHC +USB host controller. +.It Dv M_WITNESS +.Xr witness 4 +memory. +.It Dv M_MEMDESC +Memory range. +.It Dv M_CRYPTO_DATA +.Xr crypto 9 +data buffers. +.It Dv M_CREDENTIALS +.Xr ipsec 4 +related credentials. +.It Dv M_IP6OPT +IPv6 options. +.It Dv M_IP6NDP +IPv6 Neighbor Discovery structures. +.It Dv M_TEMP +Miscellaneous temporary data buffers. +.It Dv M_NTFSMNT +NTFS mount structures. +.It Dv M_NTFSNTNODE +NTFS ntnode information. +.It Dv M_NTFSFNODE +NTFS fnode information. +.It Dv M_NTFSDIR +NTFS directory buffers. +.It Dv M_NTFSNTHASH +NTFS ntnode hash tables. +.It Dv M_NTFSNTVATTR +NTFS file attribute information. +.It Dv M_NTFSRDATA +NTFS resident data. +.It Dv M_NTFSDECOMP +NTFS decompression temporary storage. +.It Dv M_NTFSRUN +NTFS vrun storage. +.It Dv M_KEVENT +.Xr kqueue 2 +data structures. +.It Dv M_SYNCACHE +SYN cache hash array. +.It Dv M_UDFMOUNT +UDF mount structures. +.It Dv M_UDFFENTRY +UDF file entries. +.It Dv M_UDFFID +UDF file IDs. +.It Dv M_AGP +AGP memory. +.It Dv M_DRM +Direct Rendering Manager. +.\" END DEFINES +.El +.Sh CONTEXT +.Fn malloc +and +.Fn mallocarray +can be called during autoconf, from process context, or from interrupt context +if +.Dv M_NOWAIT +is passed via +.Fa flags . +They can't be called from interrupt context if +.Dv M_WAITOK +is passed via +.Fa flags . +.Pp +.Fn free +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn malloc +and +.Fn mallocarray +return a kernel virtual address that is suitably aligned for storage of +any type of object. +.Sh DIAGNOSTICS +A kernel compiled with the +.Dv DIAGNOSTIC +configuration option attempts to detect memory corruption caused by +such things as writing outside the allocated area and unbalanced calls to +.Fn malloc +or +.Fn mallocarray , +and +.Fn free . +Failing consistency checks will cause a panic or a system console message: +.Pp +.Bl -bullet -offset indent -compact +.It +panic: +.Dq malloc: bogus type +.It +panic: +.Dq malloc: out of space in kmem_map +.It +panic: +.Dq malloc: allocation too large +.It +panic: +.Dq malloc: wrong bucket +.It +panic: +.Dq malloc: lost data +.It +panic: +.Dq mallocarray: overflow +.It +panic: +.Dq free: unaligned addr +.It +panic: +.Dq free: duplicated free +.It +panic: +.Dq free: multiple frees +.It +panic: +.Dq free: non-malloced addr +.It +panic: +.Dq free: size too large +.It +panic: +.Dq free: size too small +.It +panic: +.Dq kmeminit: minbucket too small/struct freelist too big +.It +.Dq multiply freed item Aq addr +.It +.Dq Data modified on freelist: Aq data object description +.El +.Sh SEE ALSO +.Xr systat 1 , +.Xr vmstat 8 diff --git a/static/openbsd/man9/mbuf.9 b/static/openbsd/man9/mbuf.9 new file mode 100644 index 00000000..73ef8064 --- /dev/null +++ b/static/openbsd/man9/mbuf.9 @@ -0,0 +1,826 @@ +.\" $OpenBSD: mbuf.9,v 1.127 2024/11/05 13:15:13 jsg Exp $ +.\" +.\" Copyright (c) 2001 Jean-Jacques Bernard-Gundol +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must 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 $Mdocdate: November 5 2024 $ +.Dt MGET 9 +.Os +.Sh NAME +.Nm m_copym , +.Nm m_free , +.Nm m_get , +.Nm MGET , +.Nm m_getclr , +.Nm m_gethdr , +.Nm m_removehdr , +.Nm m_resethdr , +.Nm m_calchdrlen , +.Nm MGETHDR , +.Nm m_prepend , +.Nm M_PREPEND , +.Nm m_pulldown , +.Nm m_pullup , +.Nm m_split , +.Nm m_makespace , +.Nm m_getptr , +.Nm m_adj , +.Nm m_copyback , +.Nm m_defrag , +.Nm m_freem , +.Nm m_freemp , +.Nm m_purge , +.Nm m_copydata , +.Nm m_cat , +.Nm m_devget , +.Nm m_apply , +.Nm MCLGET , +.Nm MCLGETL , +.Nm MEXTADD , +.Nm m_align , +.Nm M_READONLY , +.Nm m_leadingspace , +.Nm m_trailingspace , +.Nm mtod , +.Nm m_dup_pkt , +.Nm m_dup_pkthdr +.Nd kernel memory management for networking protocols +.Sh SYNOPSIS +.In sys/mbuf.h +.Ft struct mbuf * +.Fn m_copym "struct mbuf *m" "int off" "int len" "int wait" +.Ft struct mbuf * +.Fn m_free "struct mbuf *m" +.Ft struct mbuf * +.Fn m_get "int how" "int type" +.Fn MGET "struct mbuf *m" "int how" "int type" +.Ft struct mbuf * +.Fn m_getclr "int how" "int type" +.Ft void +.Fn m_removehdr "struct mbuf *m" +.Ft void +.Fn m_resethdr "struct mbuf *m" +.Ft void +.Fn m_calchdrlen "struct mbuf *m" +.Ft struct mbuf * +.Fn m_gethdr "int how" "int type" +.Fn MGETHDR "struct mbuf *m" "int how" "int type" +.Ft struct mbuf * +.Fn m_prepend "struct mbuf *m" "int len" "int how" +.Fn M_PREPEND "struct mbuf *m" "int plen" "int how" +.Ft struct mbuf * +.Fn m_pulldown "struct mbuf *m" "int off" "int len" "int *offp" +.Ft struct mbuf * +.Fn m_pullup "struct mbuf *n" "int len" +.Ft struct mbuf * +.Fn m_split "struct mbuf *m0" "int len0" "int wait" +.Ft struct mbuf * +.Fn m_makespace "struct mbuf *m0" "int skip" "int hlen" "int *off" +.Ft struct mbuf * +.Fn m_getptr "struct mbuf *m" "int loc" "int *off" +.Ft void +.Fn m_adj "struct mbuf *mp" "int req_len" +.Ft int +.Fn m_copyback "struct mbuf *m0" "int off" "int len" "const void *cp" "int wait" +.Ft int +.Fn m_defrag "struct mbuf *m" "int wait" +.Ft struct mbuf * +.Fn m_freem "struct mbuf *m" +.Ft struct mbuf * +.Fn m_freemp "struct mbuf **mp" +.Ft void +.Fn m_purge "struct mbuf *m" +.Ft void +.Fn m_copydata "struct mbuf *m" "int off" "int len" "void *cp" +.Ft void +.Fn m_cat "struct mbuf *m" "struct mbuf *n" +.Ft struct mbuf * +.Fn m_devget "char *buf" "int totlen" "int off" +.Ft int +.Fn m_apply "struct mbuf *m" "int off" "int len" \ +"int (*func)(caddr_t, caddr_t, unsigned int)" "caddr_t fstate" +.Fn MCLGET "struct mbuf *m" "int how" +.Ft struct mbuf * +.Fn MCLGETL "struct mbuf *m" "int how" "int len" +.Fn MEXTADD "struct mbuf *m" "caddr_t buf" "u_int size" "int flags" \ +"void (*free)(caddr_t, u_int, void *)" "void *arg" +.Ft void +.Fn m_align "struct mbuf *m" "int len" +.Fn M_READONLY "struct mbuf *m" +.Ft int +.Fn m_leadingspace "struct mbuf *m" +.Ft int +.Fn m_trailingspace "struct mbuf *m" +.Ft struct mbuf * +.Fn m_dup_pkt "struct mbuf *m" "u_int adj" "int how" +.Ft int +.Fn m_dup_pkthdr "struct mbuf *to" "struct mbuf *from" "int how" +.Bd -literal +#define MSIZE 256 + +#define MLEN (MSIZE - sizeof(struct m_hdr)) +#define MHLEN (MLEN - sizeof(struct pkthdr)) + +#define MAXMCLBYTES (64 * 1024) +#define MINCLSIZE (MHLEN + MLEN + 1) + +#define MCLSHIFT 11 + +#define MCLBYTES (1 << MCLSHIFT) + +#define mtod(m,t) ((t)((m)->m_data)) + +struct m_hdr { + struct mbuf *mh_next; + struct mbuf *mh_nextpkt; + caddr_t mh_data; + u_int mh_len; + short mh_type; + u_short mh_flags; +#ifndef __LP64__ + u_int mh_pad; +#endif +}; + +struct pkthdr { + void *ph_cookie; + SLIST_HEAD(, m_tag) ph_tags; + int64_t ph_timestamp; + int len; + u_int ph_rtableid; + u_int ph_ifidx; + u_int16_t ph_tagsset; + u_int16_t ph_flowid; + u_int16_t csum_flags; + u_int16_t ether_vtag; + u_int16_t ph_mss; + u_int8_t ph_loopcnt; + u_int8_t ph_family; + struct pkthdr_pf pf; +}; + +struct pkthdr_pf { + struct pf_state_key *statekey; + struct inpcb *inp; + u_int32_t qid; + u_int16_t tag; + u_int8_t flags; + u_int8_t routed; + u_int8_t prio; + u_int8_t pad[3]; +}; + +struct mbuf_ext { + caddr_t ext_buf; + void *ext_arg; + u_int ext_free_fn; + u_int ext_size; + struct mbuf *ext_nextref; + struct mbuf *ext_prevref; +}; + +struct mbuf { + struct m_hdr m_hdr; + union { + struct { + struct pkthdr MH_pkthdr; + union { + struct mbuf_ext MH_ext; + char MH_databuf[MHLEN]; + } MH_dat; + } MH; + char M_databuf[MLEN]; + } M_dat; +}; + +#define m_next m_hdr.mh_next +#define m_len m_hdr.mh_len +#define m_data m_hdr.mh_data +#define m_type m_hdr.mh_type +#define m_flags m_hdr.mh_flags +#define m_nextpkt m_hdr.mh_nextpkt +#define m_pkthdr M_dat.MH.MH_pkthdr +#define m_ext M_dat.MH.MH_dat.MH_ext +#define m_pktdat M_dat.MH.MH_dat.MH_databuf +#define m_dat M_dat.M_databuf +.Ed +.Sh DESCRIPTION +The +.Nm mbuf +functions provide a way to manage the memory buffers used by the kernel's +networking subsystem. +Several functions and macros are used to allocate and deallocate mbufs, +but also to get, inject, remove, copy, modify, prepend or append data +inside these mbufs. +The size of an +.Nm mbuf +is defined by MSIZE. +.Pp +An +.Nm mbuf +structure is defined as an +.Fa m_hdr +structure followed by a +union. +The header contains the following elements: +.Bl -tag -width foobarmoocow +.It Fa mh_next +A pointer to the next mbuf in the mbuf chain. +.It Fa mh_nextpkt +A pointer to the next mbuf chain (i.e., packet) in the queue. +.It Fa mh_data +Indicates the address of the beginning of data in the mbuf. +.It Fa mh_len +Indicates the amount of data in the mbuf. +.It Fa mh_type +Indicates the type of data contained in the mbuf (see below). +.It Fa mh_flags +Flags (see below). +.El +.Pp +The +.Fa mh_type +variable can take the following values: +.Pp +.Bl -tag -compact -offset indent -width XXXXXXXXXXXXXXXXXX +.It Dv MT_FREE +the mbuf should be on the free list. +.It Dv MT_DATA +the data in the mbuf was dynamically allocated. +.It Dv MT_HEADER +the data contains a packet header. +.It Dv MT_SONAME +the data is a socket name. +.It Dv MT_SOOPTS +the data are socket options. +.It Dv MT_FTABLE +the data is a fragment reassembly header. +.It Dv MT_CONTROL +the mbuf contains extra-data protocol message. +.It Dv MT_OOBDATA +the data consists of out-of-band data. +.El +.Pp +The +.Fa mh_flags +variable can take the following values: +.Pp +.Bl -tag -compact -offset indent -width XXXXXXXXXXXXXXXXXX +.It Dv M_EXT +mbuf has associated external storage. +.It Dv M_PKTHDR +the mbuf is the first that forms a packet. +.It Dv M_EOR +end of record. +.It Dv M_EXTWR +external storage is writable. +.It Dv M_PROTO1 +protocol-specific. +.It Dv M_VLANTAG +.Fa m_pkthdr.ether_vtag +variable is valid. +.It Dv M_LOOP +packet has been sent from local machine. +.It Dv M_BCAST +packet sent/received as link-level broadcast. +.It Dv M_MCAST +packet sent/received as link-level multicast. +.It Dv M_CONF +packet was encrypted (ESP-transport). +.It Dv M_AUTH +packet was authenticated (AH or ESP). +.It Dv M_TUNNEL +header was IP-in-IP encapsulated by tunnel mode IPsec. +.It Dv M_ZEROIZE +Zero the data part of the mbufs in the mbuf chain pointed to by +.Nm m_free . +.It Dv M_COMP +header was decompressed. +.It Dv M_LINK0 +link layer specific flag. +.El +.Pp +An external cluster is used when the data to hold in the mbuf is +large. +The size of an external cluster is between MCLBYTES and MAXMCLBYTES. +A cluster should be used when the size of the data reach MINCLSIZE +(the minimum size to be held by an external cluster). +.Pp +The combination of the M_EXT and M_PKTHDR flags give four types of +mbuf. +When none of these constants are in use, the mbuf is a "normal" +one, where the data part of the mbuf has the following elements: +.Bl -tag -width foobarmoocow +.It Fa m_dat +buffer holding the data (size MLEN). +.El +.Pp +When only M_PKTHDR is set, the data contained in the mbuf is a packet header. +The data itself is contained in the mbuf (just like the previous case), +but part of the mbuf is used to store a packet header. +The data part has then the following elements: +.Bl -tag -width foobarmoocow +.It Fa m_pkthdr +packet header, containing the length of the data, a pointer to the +interface on which the data was received, checksum information +and list of +.Xr mbuf_tags 9 . +.It Fa m_pktdat +buffer holding the data (size MHLEN). +.El +.Pp +The +.Fa m_pkthdr.csum_flags +variable can take the following values: +.Pp +.Bl -tag -compact -offset indent -width XXXXXXXXXXXXXXXXXX +.It Dv M_IPV4_CSUM_OUT +IPv4 checksum needed. +.It Dv M_TCP_CSUM_OUT +TCP checksum needed. +.It Dv M_UDP_CSUM_OUT +UDP checksum needed. +.It Dv M_ICMP_CSUM_OUT +ICMP/ICMPv6 checksum needed. +.It Dv M_IPV4_CSUM_IN_OK +IPv4 checksum verified. +.It Dv M_IPV4_CSUM_IN_BAD +IPv4 checksum bad. +.It Dv M_TCP_CSUM_IN_OK +TCP checksum verified. +.It Dv M_TCP_CSUM_IN_BAD +TCP checksum bad. +.It Dv M_UDP_CSUM_IN_OK +UDP checksum verified. +.It Dv M_UDP_CSUM_IN_BAD +UDP checksum bad. +.It Dv M_ICMP_CSUM_IN_OK +ICMP/ICMPv6 checksum verified. +.It Dv M_ICMP_CSUM_IN_BAD +ICMP/ICMPv6 checksum bad. +.It Dv M_IPV6_DF_OUT +Do not fragment IPv6 on output. +.It M_TIMESTAMP +.Fa m_pkthdr.ph_timestamp +is valid. +.It M_FLOWID +.Fa m_pkthdr.ph_flowid +is valid. +.It M_TCP_TSO +TCP Segmentation Offload needed and +.Fa m_pkthdr.ph_mss +is valid. +.El +.Pp +The +.Fa m_pkthdr.flowid +variable can contain a low resolution (15-bit) classification of a +flow or connection that the current mbuf is part of. +If the flowid is valid, it may be used as an alternative to hashing +the packets content to pick between different paths for the traffic. +The following masks can be ORed with the flowid: +.Pp +.Bl -tag -compact -offset indent -width XXXXXXXXXXXXXXXXXX +.It Dv M_FLOWID_VALID +The flow ID has been set. +.It Dv M_FLOWID_MASK +The flow ID. +.El +.Pp +When only M_EXT flag is set, an external storage buffer is being used to +hold the data, which is no longer stored in the mbuf. +The data part of the mbuf has now the following elements: +.Bl -tag -width foobarmoocow +.It Fa m_pkthdr +a packet header, just like the previous case, but it is empty. +No information is stored here. +.It Fa m_ext +a structure containing information about the external storage +buffer. +The information consists of the address of the external buffer, +a pointer to the function used to free the buffer, a pointer to the +arguments of the function, the size of the buffer, the type of the +buffer, and pointers to the previous and next mbufs using this +cluster. +.El +.Pp +When both the M_EXT and M_PKTHDR flags are set, an external storage buffer +is being used to store the data and this data contains a packet header. +The structure used is the same as the previous one except that the +.Fa m_pkthdr +element is not empty, it contains the same information as when +M_PKTHDR is used alone. +.Bl -tag -width Ds +.It Fn m_copym "struct mbuf *m" "int off" "int len" "int wait" +Copy an mbuf chain starting at +.Fa off +bytes from the beginning +and continuing for +.Fa len +bytes. +If +.Fa off +is zero and +.Fa m +has the M_PKTHDR flag set, +the header is copied. +If +.Fa len +is M_COPYALL, +the whole mbuf is copied. +The +.Fa wait +parameter can be M_WAIT or +M_DONTWAIT. +It does not copy clusters, it just increases their reference count. +.It Fn m_free "struct mbuf *m" +Free the mbuf pointed to by +.Fa m . +A pointer to the successor of the mbuf, +if it exists, is returned by the function. +If +.Fa m +is a +.Dv NULL +pointer, no action occurs and +.Dv NULL +is returned. +.It Fn m_get "int how" "int type" +Return a pointer to an mbuf of the type specified. +If the +.Fa how +argument is +.Fa M_WAITOK , +the function may call +.Xr tsleep 9 +to await resources. +If +.Fa how +is +.Fa M_DONTWAIT +and resources are not available, +.Fn m_get +returns NULL. +.It Fn MGET "struct mbuf *m" "int how" "int type" +Return a pointer to an mbuf in +.Fa m +of the type specified. +See +.Fn m_get +for a description of +.Fa how . +.It Fn m_getclr "int how" "int type" +Return a pointer to an mbuf of the type specified, and clear the data +area of the mbuf. +See +.Fn m_get +for a description of +.Fa how . +.It Fn m_removehdr "struct mbuf *m" +Convert an mbuf with packet header to one without. +Delete all +.Xr pf 4 +data and all tags attached to an +.Fa mbuf . +Keep the data and mbuf chain, clear the packet header. +.It Fn m_resethdr "struct mbuf *m" +Delete all +.Xr pf 4 +data and all tags attached to an +.Fa mbuf . +Keep the data and mbuf chain, initialize the packet header. +.It Fn m_calchdrlen "struct mbuf *m" +Set the packet header length to the sum of all length values in the +mbuf chain. +.It Fn m_gethdr "int how" "int type" +Return a pointer to an mbuf of the type specified after initializing +it to contain a packet header. +See +.Fn m_get +for a description of +.Fa how . +.It Fn MGETHDR "struct mbuf *m" "int how" "int type" +Return a pointer to an mbuf of the type specified after initializing +it to contain a packet header. +See +.Fn m_get +for a description of +.Fa how . +.It Fn m_prepend "struct mbuf *m" "int len" "int how" +Prepend space of size +.Fa plen +to the mbuf pointed to by +.Fa m . +If necessary, allocate a new mbuf and prepend it to the mbuf chain pointed to by +.Fa m . +If +.Fa m +points to an mbuf with a packet header, it is moved to the new +mbuf that has been prepended. +The return value is a pointer on the new mbuf chain. +If this function fails to allocate a new mbuf, +.Fa m +is freed. +See +.Fn m_get +for a description of +.Fa how . +.It Fn M_PREPEND "struct mbuf *m" "int plen" "int how" +Prepend space of size +.Fa plen +to the mbuf pointed to by +.Fa m . +If a new mbuf must be allocated, +.Fa how +specifies whether to wait or not. +If this function fails to allocate a new mbuf, +.Fa m +is freed. +.It Fn m_pulldown "struct mbuf *m" "int off" "int len" "int *offp" +Ensure that the data in the mbuf chain starting at +.Fa off +and ending at +.Fa off+len +will be put in a continuous memory region. +If memory must be allocated, then it will fail if the +.Fa len +argument is greater than MAXMCLBYTES. +The pointer returned points to an mbuf in the chain and the new offset +for data in this mbuf is +.Fa *offp . +If this function fails, +.Fa m +is freed. +.It Fn m_pullup "struct mbuf *n" "int len" +Ensure that the data in the mbuf chain starting at the beginning of +the chain and ending at +.Fa len +will be put in continuous memory region. +If memory must be allocated, then it will fail if the +.Fa len +argument is greater than MAXMCLBYTES. +If this function fails, +.Fa n +is freed. +.It Fn m_split "struct mbuf *m0" "int len0" "int wait" +Split an mbuf chain in two pieces, returning a pointer to +the tail (which is made of the previous mbuf chain except the first +.Fa len0 +bytes). +.It Fn m_makespace "struct mbuf *m0" "int skip" "int hlen" "int *off" +Make space for a continuous memory region of length +.Fa hlen +at +.Fa skip +bytes into the mbuf chain. +On success, the mbuf of the continuous memory is returned +together with an offset +.Fa off +into the mbuf. +On failure, NULL is returned and the mbuf chain may have been modified. +The caller is assumed to always free the chain. +.It Fn m_getptr "struct mbuf *m" "int loc" "int *off" +Returns a pointer to the mbuf containing the data located at +.Fa loc +bytes of the beginning. +The offset in the new mbuf is pointed to by +.Fa off . +.It Fn m_adj "struct mbuf *mp" "int req_len" +Trims +.Fa req_len +bytes of data from the mbuf chain pointed to by +.Fa mp . +If +.Fa req_len +is positive, the data will be trimmed from the head of the mbuf chain +and if it is negative, it will be trimmed from the tail of the mbuf +chain. +.It Fn m_copyback "struct mbuf *m0" "int off" "int len" "const void *cp" "int wait" +Copy data from a buffer pointed to by +.Fa cp +back into the mbuf chain pointed to by +.Fa m0 +starting at +.Fa off +bytes from the beginning, extending the mbuf chain if +necessary, sleeping for mbufs if +.Fa wait +is +.Fa M_WAIT . +If +.Fa M_NOWAIT +is set and no mbufs are available, +.Fn m_copyback +returns +.Er ENOBUFS . +The mbuf chain must be initialized properly, including setting +.Fa m_len . +.It Fn m_defrag "struct mbuf *m" "int wait" +Defragment the data mbufs referenced by +.Fa m +by replacing the chain with a copy of their contents made into a +single mbuf or cluster. +.Fa wait +specifies whether it can wait or not for the replacement storage. +.Fn m_defrag +returns 0 on success or +.Er ENOBUFS +on failure. +The mbuf pointer +.Fa m +remains in existence and unchanged on failure. +.It Fn m_freem "struct mbuf *m" +Free the mbuf chain pointed to by +.Fa m . +A pointer to the next mbuf in the list linked by m_nextpkt, +if it exists, is returned by the function. +If +.Fa m +is a +.Dv NULL +pointer, no action occurs and +.Dv NULL +is returned. +.It Fn m_freemp "struct mbuf **mp" +Set the input mbuf pointer to +.Dv NULL +and call +.Fn m_freem . +.It Fn m_purge "struct mbuf *m" +Free the list of mbufs linked by m_nextpkt that is pointed to by +.Fa m . +Each mbuf is freed by a call to +.Fn m_freem . +If +.Fa m +is a +.Dv NULL +pointer, no action occurs. +.It Fn m_copydata "struct mbuf *m" "int off" "int len" "void *cp" +Copy data from the mbuf chain pointed to by +.Fa m +starting at +.Fa off +bytes from the beginning and continuing for +.Fa len +bytes into the buffer pointed to by +.Fa cp . +.It Fn m_cat "struct mbuf *m" "struct mbuf *n" +Concatenate the mbuf chain pointed to by +.Fa n +to the mbuf chain pointed to by +.Fa m . +The mbuf chains must be of the same type. +.It Fn m_devget "char *buf" "int totlen" "int off" +Copy +.Fa totlen +bytes of data from device local memory pointed to by +.Fa buf . +The data is copied into an mbuf chain at offset +.Fa off +and a pointer to the head of the chain is returned. +Returns NULL on failure. +.It Fn m_apply "struct mbuf *m" "int off" "int len" \ +"int (*func)(caddr_t, caddr_t, unsigned int)" "caddr_t fstate" +Apply the function +.Fa func +to the data in the mbuf chain pointed to by +.Fa m +starting at +.Fa off +bytes from the beginning and continuing for +.Fa len +bytes. +.It Fn mtod "struct mbuf *m" "datatype" +Return a pointer to the data contained in the specified mbuf +.Fa m +cast to +.Fa datatype . +.It Fn MCLGET "struct mbuf *m" "int how" +Allocate and add an mbuf cluster to the mbuf pointed to by +.Fa m . +On success, the flag M_EXT is set in the mbuf. +See +.Fn m_get +for a description of +.Fa how . +.It Fn MCLGETL "struct mbuf *m" "int how" "int len" +If +.Fa m +is NULL, allocate it. +Then allocate and add an mbuf cluster of length +.Fa len +to the mbuf pointed to by +.Fa m . +Returns either the mbuf +.Fa m +that was passed in, or the newly allocated one which was allocated; in +either case the flag M_EXT is set in the mbuf. +See +.Fn m_get +for a description of +.Fa how . +.It Fn MEXTADD "struct mbuf *m" "caddr_t buf" "u_int size" "int flags" \ +"void (*free)(caddr_t, u_int, void *)" "void *arg" +Add pre-allocated storage to the mbuf pointed to by +.Fa m . +On success, the flag M_EXT is set in the mbuf, and M_EXTWR is specified in +.Fa flags . +.It Fn m_align "struct mbuf *m" "int len" +Set the +.Fa m_data +pointer of the newly allocated mbuf +.Fa m +to an object of the specified size +.Fa len +at the end of this mbuf data area, longword aligned. +.It Fn M_READONLY "struct mbuf *m" +Check if the data of the mbuf pointed to by +.Fa m +is read-only. +This is true for non-cluster external storage and for clusters that +are being referenced by more than one mbuf. +.It Fn m_leadingspace "struct mbuf *m" +Compute the amount of space available before the current start of data +in the mbuf pointed to by +.Fa m . +If the data of the mbuf pointed to by +.Fa m +is read-only then 0 is returned. +.It Fn m_trailingspace "struct mbuf *m" +Compute the amount of space available after the end of data in the +mbuf pointed to by +.Fa m . +If the data of the mbuf pointed to by +.Fa m +is read-only then 0 is returned. +.It Fn m_dup_pkt "struct mbuf *m" "u_int adj" "int how" +Allocate a new mbuf and storage and copy the packet data and header, +including mbuf tags, from +.Fa m . +The data in the new mbuf will be offset from the start of the storage by +.Fa adj +bytes. +See +.Fn m_get +for a description of +.Fa how . +.It Fn m_dup_pkthdr "struct mbuf *to" "struct mbuf *from" "int how" +Copy mbuf packet header, including mbuf tags, from +.Fa from +to +.Fa to . +See +.Fn m_get +for a description of +.Fa how . +.El +.Sh CODE REFERENCES +The mbuf management functions are implemented in the files +.Pa sys/kern/uipc_mbuf.c +and +.Pa sys/kern/uipc_mbuf2.c . +The function prototypes and the macros are located in +.Pa sys/sys/mbuf.h . +.Sh SEE ALSO +.Xr netstat 1 , +.Xr mbuf_tags 9 , +.Xr mutex 9 , +.Xr spl 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 +.Rs +.%A Jun-Ichiro Hagino +.%T "Mbuf issues in 4.4BSD IPv6/IPsec support (experiences from KAME IPv6/IPsec implementation)" +.%B "Proceedings of the Freenix Track: 2000 USENIX Annual Technical Conference" +.%D June 2000 +.Re diff --git a/static/openbsd/man9/mbuf_tags.9 b/static/openbsd/man9/mbuf_tags.9 new file mode 100644 index 00000000..2169e1c8 --- /dev/null +++ b/static/openbsd/man9/mbuf_tags.9 @@ -0,0 +1,265 @@ +.\" $OpenBSD: mbuf_tags.9,v 1.44 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" The author of this man page is Angelos D. Keromytis (angelos@cis.upenn.edu) +.\" +.\" 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 $Mdocdate: June 13 2025 $ +.Dt M_TAG_GET 9 +.Os +.Sh NAME +.Nm m_tag_get , +.Nm m_tag_find , +.Nm m_tag_prepend , +.Nm m_tag_delete , +.Nm m_tag_copy , +.Nm m_tag_delete_chain , +.Nm m_tag_init , +.Nm m_tag_copy_chain , +.Nm m_tag_first , +.Nm m_tag_next +.Nd a framework for generic packet attributes +.Sh SYNOPSIS +.In sys/mbuf.h +.Ft struct m_tag * +.Fn m_tag_get "int type" "int len" "int flags" +.Ft struct m_tag * +.Fn m_tag_find "struct mbuf *mbuf" "int type" "struct m_tag *tag" +.Ft void +.Fn m_tag_prepend "struct mbuf *mbuf" "struct m_tag *tag" +.Ft void +.Fn m_tag_delete "struct mbuf *mbuf" "struct m_tag *tag" +.Ft struct m_tag * +.Fn m_tag_copy "struct m_tag *tag" +.Ft void +.Fn m_tag_delete_chain "struct mbuf *mbuf" +.Ft void +.Fn m_tag_init "struct mbuf *mbuf" +.Ft int +.Fn m_tag_copy_chain "struct mbuf *mbuf" "struct mbuf *mbuf2" +.Ft struct m_tag * +.Fn m_tag_first "struct mbuf *mbuf" +.Ft struct m_tag * +.Fn m_tag_next "struct mbuf *mbuf" "struct m_tag *tag" +.Sh DESCRIPTION +These functions allow the manipulation of generic packet attributes. +They are used by the kernel to keep track of operations done or +scheduled to happen to packets. +These attributes are attached to +.Xr mbuf 9 +packet headers. +.Pp +Mbuf tags get allocated using +.Xr pool 9 . +.Pp +.Fn m_tag_get +allocates a new tag of type +.Va type +with +.Va len +bytes of space following the tag header itself. +The +.Va flag +argument is passed directly to +.Xr pool_get 9 . +If successful, +.Fn m_tag_get +returns a memory buffer of (len + sizeof (struct m_tag)) bytes. +The first sizeof(struct m_tag) bytes contain a struct m_tag: +.Bd -literal +struct m_tag { + SLIST_ENTRY(m_tag) m_tag_link; /* List of packet tags */ + u_int16_t m_tag_id; /* Tag ID */ + u_int16_t m_tag_len; /* Length of data */ +}; +.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 +and +.Va m_tag_len +fields are set to +.Va type +and +.Va len +respectively. +Following this structure are +.Va len +bytes of space that can be used to store tag-specific information. +.Pp +The currently defined tag types are: +.Bl -tag -width PACKET_TAG_PF_REASSEMBLED +.It PACKET_TAG_IPSEC_IN_DONE +Used by +.Xr ipsec 4 +to indicate successful processing performed on an input packet. +The tag contains a +.Va struct tdb_ident , +as defined in +.Pa sys/netinet/ip_ipsp.h , +identifying the security association under which the packet arrived. +.It PACKET_TAG_IPSEC_OUT_DONE +Used by IPsec to indicate that an output packet has been +IPsec-processed. +The tag contains a +.Va struct tdb_ident +identifying the security association applied to the packet. +This tag is primarily used to detect and avoid loops in IPsec +processing on output. +.It PACKET_TAG_IPSEC_FLOWINFO +Used by the IPv4 stack to specify the IPsec flow of an output IP packet. +The tag contains a +.Va u_int32_t +identifying the IPsec flow. +.It PACKET_TAG_WIREGUARD +Used by the +.Xr wg 4 +interface to detect loops in processing. +The tag contains a pointer to the wg peer that already processed the packet. +.It PACKET_TAG_GRE +Used by the +.Xr gre 4 +interface to detect loops in processing. +The tag contains a pointer to the gre interface that already processed +the packet. +.It PACKET_TAG_DLT +Used by +.Xr bpf 4 +to indicate that the packet was injected. +The tag contains a +.Va u_int +identifying the data link layer type. +.It PACKET_TAG_PF_DIVERT +Indicates that the packet was diverted by +.Xr pf 4 +using the +.Em divert-to +or +.Em divert-reply +directives. +The tag contains a +.Va struct pf_divert +identifying the port, address and routing domain the packet should be +diverted to. +.It PACKET_TAG_PF_REASSEMBLED +Used by +.Xr pf 4 +to reassemble IPv6 fragments. +The tag contains a +.Va struct pf_fragment_tag . +.It PACKET_TAG_SRCROUTE +Used by the IPv4 stack to keep track of the source route of an incoming +IP packet, in case a protocol wants to respond over the same route. +The tag contains a +.Va struct ip_srcrt . +.It PACKET_TAG_CARP_BAL_IP +Used by +.Xr carp 4 +to mark packets received in mode +.Va balancing ip . +These packets need some special treatment since they contain layer 3 unicast +inside layer 2 multicast. +The tag contains no data. +.El +.Pp +.Fn m_tag_find +finds an instance of a tag of type +.Va type +attached to packet +.Va mbuf . +If +.Va tag +is +.Dv NULL , +the first such tag is returned. +Otherwise, the first tag of type +.Va type +after +.Va tag +is returned. +If no such tag is found, +.Dv NULL +is returned. +.Pp +.Fn m_tag_prepend +adds the new tag +.Va tag +at the head of the tag list for packet +.Va mbuf . +.Pp +.Fn m_tag_delete +removes and then de-allocates tag +.Va tag +from the list of tags of packet +.Va mbuf . +.Pp +.Fn m_tag_copy +creates an unlinked copy of tag +.Va tag . +.Pp +.Fn m_tag_delete_chain +deletes all tags attached to packet +.Va mbuf . +.Pp +.Fn m_tag_init +initializes the tag storage for packet +.Va mbuf . +.Pp +.Fn m_tag_copy_chain +copies all tags from packet +.Va mbuf +to packet +.Va mbuf2 . +On success, it returns 0. +Otherwise, it returns +.Er ENOBUFS . +.Pp +.Fn m_tag_first +returns the first tag attached to packet +.Va mbuf . +.Pp +.Fn m_tag_next +returns the tag following +.Va tag +in packet +.Va mbuf . +.Pp +The +.Fn M_MOVE_PKTHDR +and +.Fn M_MOVE_HDR +macros defined in +.Pa sys/sys/mbuf.h +move the tags from the old to the new mbuf. +.Sh CODE REFERENCES +The tag-manipulating code is contained in the file +.Pa sys/kern/uipc_mbuf2.c . +.Sh SEE ALSO +.Xr bpf 4 , +.Xr bridge 4 , +.Xr gif 4 , +.Xr gre 4 , +.Xr ipsec 4 , +.Xr pf 4 , +.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/openbsd/man9/md5.9 b/static/openbsd/man9/md5.9 new file mode 100644 index 00000000..7966b187 --- /dev/null +++ b/static/openbsd/man9/md5.9 @@ -0,0 +1,72 @@ +.\" $OpenBSD: md5.9,v 1.14 2015/11/24 14:58:56 jmc Exp $ +.\" +.\" Copyright (c) 1996 Michael Shalayeff +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 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 $Mdocdate: November 24 2015 $ +.Dt MD5INIT 9 +.Os +.Sh NAME +.Nm MD5Init , +.Nm MD5Transform +.Nd message digest routines +.Sh SYNOPSIS +.In sys/kernel.h +.Ft void +.Fn MD5Init "u_int32_t buf[4]" +.Ft void +.Fn MD5Transform "u_int32_t buf[4]" "u_int32_t const in[16]" +.Sh DESCRIPTION +The +.Nm +module implements the RSA Data Security, Inc. +MD5 Message-Digest Algorithm (MD5). +It produces 128-bit MD5 Digest of data. +.Bl -hang -width MD5Transform +.It Fn MD5Init +must be called just before +.Fn MD5Transform +will be used to produce a digest. +The +.Fa buf +argument is the storage for the digest being produced on subsequent +calls to the +.Fn MD5Transform +routine. +.It Fn MD5Transform +is the core of the MD5 algorithm, this alters an existing MD5 hash +kept in +.Fa buf +to reflect the addition of 16 longwords +of new data passed in +.Fa in +argument. +.El +.Sh COPYRIGHTS +The code for MD5 transform was taken from Colin Plumb's +implementation, which has been placed in the public domain. +The MD5 cryptographic checksum was devised by Ronald Rivest, and is +documented in RFC 1321, "The MD5 Message Digest Algorithm". +.Sh SEE ALSO +.Xr random 4 , +.Xr arc4random 9 diff --git a/static/openbsd/man9/membar_sync.9 b/static/openbsd/man9/membar_sync.9 new file mode 100644 index 00000000..c2e8de71 --- /dev/null +++ b/static/openbsd/man9/membar_sync.9 @@ -0,0 +1,124 @@ +.\" $OpenBSD: membar_sync.9,v 1.4 2022/03/13 22:16:59 bluhm Exp $ +.\" +.\" Copyright (c) 2007, 2008 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 $Mdocdate: March 13 2022 $ +.Dt MEMBAR 9 +.Os +.Sh NAME +.Nm membar_enter , +.Nm membar_exit , +.Nm membar_producer , +.Nm membar_consumer , +.Nm membar_sync , +.Nm membar_enter_after_atomic , +.Nm membar_exit_before_atomic +.Nd memory access barrier operations +.Sh SYNOPSIS +.In sys/atomic.h +.Ft void +.Fn membar_enter "void" +.Ft void +.Fn membar_exit "void" +.Ft void +.Fn membar_producer "void" +.Ft void +.Fn membar_consumer "void" +.Ft void +.Fn membar_sync "void" +.Ft void +.Fn membar_enter_after_atomic "void" +.Ft void +.Fn membar_exit_before_atomic "void" +.Sh DESCRIPTION +The membar set of functions provide an interface for issuing memory barrier +access operations with respect to multiple processors in the system. +.Bl -tag -width "mem" +.It Fn membar_enter +Any store preceding +.Fn membar_enter +will reach global visibility before all loads and stores following it. +.Pp +.Fn membar_enter +is typically used in code that implements locking primitives to ensure +that a lock protects its data. +.It Fn membar_exit +All loads and stores preceding +.Fn membar_exit +will reach global visibility before any store that follows it. +.Pp +.Fn membar_exit +is typically used in code that implements locking primitives to ensure +that a lock protects its data. +.It Fn membar_producer +All stores preceding the memory barrier will reach global visibility +before any stores after the memory barrier reach global visibility. +.It Fn membar_consumer +All loads preceding the memory barrier will complete before any loads +after the memory barrier complete. +.It Fn membar_sync +All loads and stores preceding the memory barrier will complete and +reach global visibility before any loads and stores after the memory +barrier complete and reach global visibility. +.It Fn membar_enter_after_atomic +An atomic operation preceding +.Fn membar_enter_after_atomic +will reach global visibility before all loads and stores following it. +The atomic operation is used to protect the start of a critical section. +.It Fn membar_exit_before_atomic +All loads and stores preceding +.Fn membar_exit_before_atomic +will reach global visibility before atomic operation that follows it. +The atomic operation is used to protect the end of a critical section. +.El +.Pp +The atomic operations that can be used with +.Fn membar_enter_after_atomic +and +.Fn membar_exit_before_atomic +are the atomic_add, atomic_sub, atomic_inc, atomic_dec, and atomic_cas +set of functions. +For other cases use +.Fn membar_enter +or +.Fn membar_exit . +.Sh CONTEXT +.Fn membar_enter , +.Fn membar_exit , +.Fn membar_producer , +.Fn membar_consumer , +.Fn membar_sync , +.Fn membar_enter_after_atomic , +.Fn membar_exit_before_atomic +can all be called during autoconf, from process context, or from +interrupt context. +.Sh HISTORY +The membar functions first appeared in +.Nx 5.0 +and +.Ox 5.5 . diff --git a/static/openbsd/man9/memcmp.9 b/static/openbsd/man9/memcmp.9 new file mode 100644 index 00000000..cca6bed7 --- /dev/null +++ b/static/openbsd/man9/memcmp.9 @@ -0,0 +1,95 @@ +.\" $OpenBSD: memcmp.9,v 1.1 2018/04/23 10:30:39 dlg Exp $ +.\" +.\" Copyright (c) 2002, 2003 CubeSoft Communications, 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, 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 $Mdocdate: April 23 2018 $ +.Dt MEMCMP 9 +.Os +.Sh NAME +.Nm skpc , +.Nm scanc , +.Nm bcmp , +.Nm timingsafe_bcmp , +.Nm memchr , +.Nm memcmp +.Nd kernel library byte string routines +.Sh SYNOPSIS +.In lib/libkern/libkern.h +.Ft int +.Fn skpc "int mask" "size_t size" "u_char *cp" +.Ft int +.Fn scanc "u_int size" "const u_char *cp" "const u_char *table" "int mask" +.Ft int +.Fn bcmp "const void *b1" "const void *b2" "size_t len" +.Ft int +.Fn timingsafe_bcmp "const void *b1" "const void *b2" "size_t len" +.Ft void * +.Fn memchr "const void *b" "int c" "size_t len" +.Ft int +.Fn memcmp "const void *b1" "const void *b2" "size_t len" +.Sh DESCRIPTION +The +.Fn skpc +function locates the first unsigned character of value different than +.Fa mask +inside the string +.Fa cp . +.Pp +The +.Fn scanc +function expects a string of indexes into the table +.Fa table . +Each table element is bitwise ANDed against +.Fa mask . +.Pp +.Fn skpc +and +.Fn scanc +expect the string to be of size +.Fa size , +and return the index relative to the end of the string where the match +occurred, or zero if +.Fa mask +is not present in the string. +.Pp +The remaining functions have the same semantics as their libc counterparts, +.Xr bcmp 3 , +.Xr timingsafe_bcmp 3 , +.Xr memchr 3 , +and +.Xr memcmp 3 . +.Sh STANDARDS +The +.Fn memchr +and +.Fn memcmp +functions conform to +.St -ansiC . +.Sh HISTORY +The +.Fn skpc +and +.Fn scanc +functions are based on vax instructions of the same name. diff --git a/static/openbsd/man9/mi_switch.9 b/static/openbsd/man9/mi_switch.9 new file mode 100644 index 00000000..b8ecea18 --- /dev/null +++ b/static/openbsd/man9/mi_switch.9 @@ -0,0 +1,111 @@ +.\" $OpenBSD: mi_switch.9,v 1.7 2017/09/05 03:49:56 jmatthew Exp $ +.\" $NetBSD: ctxsw.9,v 1.9 1999/03/06 22:09:29 mycroft 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 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 $Mdocdate: September 5 2017 $ +.Dt MI_SWITCH 9 +.Os +.Sh NAME +.Nm mi_switch , +.Nm cpu_switchto +.Nd switch to another process context +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft void +.Fn mi_switch "void" +.Ft void +.Fn cpu_switchto "struct proc *old" "struct proc *new" +.Sh DESCRIPTION +The +.Fn mi_switch +function implements the machine-independent prelude to a process context +switch. +It is called from only a few distinguished places in the kernel code as a +result of the principle of non-preemptable kernel mode execution. +The three major uses of +.Fn mi_switch +can be enumerated as follows: +.Bl -enum -offset indent +.It +From within functions like +.Xr tsleep 9 , +when the current process sleeps to wait for some resource to become +available, or from within functions like +.Fn yield , +when it relinquishes the CPU to allow other processes to make progress. +.It +After handling a trap +.Pq e.g., a system call or device interrupt +when the kernel prepares a return to user-mode execution. +This case is typically handled by machine-dependent trap-handling code after +detection of a change in the signal disposition of the current process, or +when a higher priority process might be available to run. +The latter event is communicated by the machine-independent scheduling +routines by calling the machine-dependent +.Fn need_resched "void" . +.It +In the signal handling code +.Pq see Pa sys/kern/kern_sig.c +if a signal is delivered that causes a process to stop. +.El +.Pp +.Fn mi_switch +records the amount of time the current process has been running in the +process structure and checks this value against the CPU time limits +allocated to the process +.Pq see Xr getrlimit 2 . +Exceeding the soft limit results in a +.Dv SIGXCPU +signal to be posted to the process, while exceeding the hard limit will +cause a +.Dv SIGKILL . +After these administrative tasks are done, +.Fn mi_switch +chooses the next process to run and hands over control to the machine +dependent routine +.Fn cpu_switchto , +which will perform the actual process context switch. +.Pp +.Fn cpu_switchto +will save the context of the old process and switch to the new one. +A special case is when the old process is +.Dv NULL +which means that the old process has exited and doesn't need to be +saved. +.Pp +Note that +.Fn mi_switch +and thus +.Fn cpu_switchto +must be called while holding the scheduler lock. +.Sh SEE ALSO +.Xr spl 9 , +.Xr tsleep 9 , +.Xr wakeup 9 diff --git a/static/openbsd/man9/microtime.9 b/static/openbsd/man9/microtime.9 new file mode 100644 index 00000000..b2b0eb40 --- /dev/null +++ b/static/openbsd/man9/microtime.9 @@ -0,0 +1,219 @@ +.\" $OpenBSD: microtime.9,v 1.23 2022/12/28 15:46:39 cheloha Exp $ +.\" $NetBSD: microtime.9,v 1.2 1999/03/16 00:40:47 garbled Exp $ +.\" +.\" Copyright (c) 1998 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jeremy 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 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 $Mdocdate: December 28 2022 $ +.Dt MICROTIME 9 +.Os +.Sh NAME +.Nm microuptime , +.Nm getmicrouptime , +.Nm nanouptime , +.Nm getnanouptime , +.Nm nsecuptime , +.Nm getnsecuptime , +.Nm getuptime , +.Nm nanoruntime , +.Nm getnsecruntime , +.Nm microtime , +.Nm getmicrotime , +.Nm nanotime , +.Nm getnanotime , +.Nm gettime , +.Nm microboottime , +.Nm nanoboottime +.Nd get the time +.Sh SYNOPSIS +.In sys/time.h +.Ft void +.Fo microuptime +.Fa "struct timeval *tv" +.Fc +.Ft void +.Fo getmicrouptime +.Fa "struct timeval *tv" +.Fc +.Ft void +.Fo nanouptime +.Fa "struct timespec *ts" +.Fc +.Ft void +.Fo getnanouptime +.Fa "struct timespec *ts" +.Fc +.Ft uint64_t +.Fo nsecuptime +.Fa "void" +.Fc +.Ft uint64_t +.Fo getnsecuptime +.Fa "void" +.Fc +.Ft time_t +.Fo getuptime +.Fa "void" +.Fc +.Ft void +.Fo nanoruntime +.Fa "struct timespec *ts" +.Fc +.Ft uint64_t +.Fo getnsecruntime +.Fa "void" +.Fc +.Ft void +.Fo microtime +.Fa "struct timeval *tv" +.Fc +.Ft void +.Fo getmicrotime +.Fa "struct timeval *tv" +.Fc +.Ft void +.Fo nanotime +.Fa "struct timespec *ts" +.Fc +.Ft void +.Fo getnanotime +.Fa "struct timespec *ts" +.Fc +.Ft time_t +.Fo gettime +.Fa "void" +.Fc +.Ft void +.Fo microboottime +.Fa "struct timeval *tv" +.Fc +.Ft void +.Fo nanoboottime +.Fa "struct timespec *ts" +.Fc +.Sh DESCRIPTION +The kernel has three clocks and a variety of interfaces for reading them. +.Pp +The +.Sy uptime +clock measures the time elapsed since the system booted. +It begins at zero and advances monotonically. +The uptime clock may be read with the following functions: +.Bl -column "getmicrouptimeX" "Output Format" "Source" -offset indent +.It Em Name Ta Em Output Format Ta Em Source +.It Fn microuptime Ta Vt struct timeval Ta hardware +.It Fn getmicrouptime Ta Vt struct timeval Ta timestamp +.It Fn nanouptime Ta Vt struct timespec Ta hardware +.It Fn getnanouptime Ta Vt struct timespec Ta timestamp +.It Fn nsecuptime Ta Ft uint64_t Ta hardware +.It Fn getnsecuptime Ta Ft uint64_t Ta timestamp +.It Fn getuptime Ta Ft time_t Ta timestamp +.El +.Pp +The +.Sy runtime +clock measures the time elapsed since the system booted, +less any time the system is suspended or hibernating. +It begins at zero and normally advances monotonically, +but pauses while the system is suspended or hibernating. +The runtime clock may be read with the following functions: +.Bl -column "getnsecruntimeX" "Output Format" "Source" -offset indent +.It Em Name Ta Em Output Format Ta Em Source +.It Fn nanoruntime Ta Vt struct timespec Ta hardware +.It Fn getnsecruntime Ta Ft uint64_t Ta timestamp +.El +.Pp +The +.Sy UTC +clock measures the time elapsed since Jan 1 1970 00:00:00 +.Pq the Unix Epoch . +The clock normally advances monotonically, +but jumps when a process calls +.Xr clock_settime 2 +or +.Xr settimeofday 2 . +The UTC clock may be read with the following functions: +.Bl -column "getmicrotimeX" "Output Format" "Source" -offset indent +.It Em Name Ta Em Output Format Ta Em Source +.It Fn microtime Ta Vt struct timeval Ta hardware +.It Fn getmicrotime Ta Vt struct timeval Ta timestamp +.It Fn nanotime Ta Vt struct timespec Ta hardware +.It Fn getnanotime Ta Vt struct timespec Ta timestamp +.It Fn gettime Ta Ft time_t Ta timestamp +.El +.Pp +The kernel also maintains a +.Sy boot timestamp . +It is the moment on the UTC clock when the system booted. +The timestamp jumps when a process calls +.Xr clock_settime 2 +or +.Xr settimeofday 2 . +The boot timestamp may be read with the following functions: +.Bl -column "microboottimeX" "Output Format" "Source" -offset indent +.It Em Name Ta Em Output Format Ta Em Source +.It Fn microboottime Ta Vt struct timeval Ta timestamp +.It Fn nanoboottime Ta Vt struct timespec Ta timestamp +.El +.Pp +Functions that source from the +.Em hardware +provide the most precise result possible. +Functions that source from a +.Em timestamp +provide a far less precise result, +but do so very quickly. +On most platforms, +timestamps are updated approximately 100 times per second. +.Sh CONTEXT +These functions may be called during autoconf, +from process context, +or from any interrupt context. +.Sh RETURN VALUES +.Fn nsecuptime , +.Fn getnsecuptime , +and +.Fn getnsecruntime +return a count of nanoseconds. +.Pp +.Fn getuptime +and +.Fn gettime +return a count of seconds. +.Sh ERRORS +These functions are always successful, +and no return value is reserved to indicate an error. +.Sh CODE REFERENCES +.Pa sys/kern/kern_tc.c +.Sh SEE ALSO +.Xr clock_settime 2 , +.Xr settimeofday 2 , +.Xr timeradd 3 , +.Xr hardclock 9 , +.Xr hz 9 , +.Xr inittodr 9 , +.Xr tc_init 9 diff --git a/static/openbsd/man9/ml_init.9 b/static/openbsd/man9/ml_init.9 new file mode 100644 index 00000000..30b8daba --- /dev/null +++ b/static/openbsd/man9/ml_init.9 @@ -0,0 +1,184 @@ +.\" $OpenBSD: ml_init.9,v 1.15 2020/01/23 07:12:42 jmc Exp $ +.\" +.\" Copyright (c) 2015 David Gwynne +.\" +.\" 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 23 2020 $ +.Dt ML_INIT 9 +.Os +.Sh NAME +.Nm ml_init , +.Nm ml_enqueue , +.Nm ml_dequeue , +.Nm ml_enlist , +.Nm ml_dechain , +.Nm ml_len , +.Nm ml_empty , +.Nm ml_hdatalen , +.Nm ml_purge , +.Nm MBUF_LIST_INITIALIZER , +.Nm MBUF_LIST_FIRST , +.Nm MBUF_LIST_NEXT , +.Nm MBUF_LIST_FOREACH +.Nd mbuf list API +.Sh SYNOPSIS +.In sys/mbuf.h +.Ft void +.Fn ml_init "struct mbuf_list *ml" +.Ft void +.Fn ml_enqueue "struct mbuf_list *ml" "struct mbuf *m" +.Ft struct mbuf * +.Fn ml_dequeue "struct mbuf_list *ml" +.Ft void +.Fn ml_enlist "struct mbuf_list *ml" "struct mbuf_list *src" +.Ft struct mbuf * +.Fn ml_dechain "struct mbuf_list *ml" +.Ft unsigned int +.Fn ml_len "struct mbuf_list *ml" +.Ft int +.Fn ml_empty "struct mbuf_list *ml" +.Ft unsigned int +.Fn ml_hdatalen "struct mbuf_list *ml" +.Ft unsigned int +.Fn ml_purge "struct mbuf_list *ml" +.Ft struct mbuf_list +.Fn MBUF_LIST_INITIALIZER +.Ft struct mbuf * +.Fn MBUF_LIST_FIRST "struct mbuf_list *ml" +.Ft struct mbuf * +.Fn MBUF_LIST_NEXT "struct mbuf *m" +.Fn MBUF_LIST_FOREACH "struct mbuf_list *ml" "VARNAME" +.Sh DESCRIPTION +The mbuf list API provides implementations of data structures and operations +for managing lists of mbufs between contexts. +.Pp +mbuf_list structures support the following functionality: +.Pp +.Bl -enum -compact -offset indent +.It +Insertion of a new mbuf at the end of the list. +.It +Removal of an mbuf from the head of the list. +.El +.Bl -tag -width Ds +.It Fn ml_init "struct mbuf_list *ml" +Initialise the +.Fa ml +mbuf_list structure. +.It Fn MBUF_LIST_INITIALIZER +An initialiser for an mbuf_list structure declaration. +.It Fn ml_enqueue "struct mbuf_list *ml" "struct mbuf *m" +Enqueue mbuf +.Fa m +on the end of the +.Fa ml +mbuf list. +.It Fn ml_dequeue "struct mbuf_list *ml" +Dequeue an mbuf from the front of the +.Fa ml +mbuf list. +.It Fn ml_enlist "struct mbuf_list *ml" "struct mbuf_list *src" +Enqueue all the mbufs on the +.Fa src +mbuf list on to the end of the +.Fa ml +mbuf list. +.It Fn ml_dechain "struct mbuf_list *ml" +Dequeues all mbufs from the +.Fa ml +mbuf list. +.It Fn ml_len "struct mbuf_list *ml" +Return the number of mbufs on the +.Fa ml +mbuf list. +.It Fn ml_empty "struct mbuf_list *ml" +Return if the +.Fa ml +mbuf list is empty. +.It Fn ml_hdatalen "struct mbuf_list *ml" +Return the number of bytes in the packet at the head of the +.Fa ml +mbuf list. +.It Fn ml_purge "struct mbuf_list *ml" +Free all the mbufs on the +.Fa ml +mbuf list. +.It Fn MBUF_LIST_FIRST "struct mbuf_list *ml" +Access the first mbuf in the +.Fa ml +mbuf list for traversal. +.It Fn MBUF_LIST_NEXT "struct mbuf *m" +Access the next mbuf in the mbuf list after +.Fa m . +.It Fn MBUF_LIST_FOREACH "struct mbuf_list *ml" "VARNAME" +A convenience macro that can be used to iterate over the contents of the +.Fa ml +mbuf list. +.Fa VARNAME +identifies the name (not the address) of an mbuf pointer that will +be set to each entry on the list. +Note that it is unsafe to modify the list while iterating over it. +.El +.Sh CONTEXT +.Fn ml_init , +.Fn ml_enqueue , +.Fn ml_dequeue , +.Fn ml_enlist , +.Fn ml_dechain , +.Fn ml_len , +.Fn ml_empty , +.Fn ml_purge , +.Fn MBUF_LIST_INITIALIZER , +.Fn MBUF_LIST_FIRST , +.Fn MBUF_LIST_NEXT , +and +.Fn MBUF_LIST_FOREACH +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn ml_dequeue +returns the mbuf that was at the head of its list. +If the list was empty, +.Dv NULL +is returned. +.Pp +.Fn ml_dechain +returns all the mbufs that were on the list via +a pointer to an mbuf with the chain accessible via m_nextpkt members. +If the list was empty, +.Dv NULL +is returned. +.Pp +.Fn ml_len +returns the number of mbufs on the list. +.Pp +.Fn ml_empty +return a non-zero value if the list is empty, otherwise 0. +.Pp +.Fn ml_hdatalen +returns the size of a packet on the list, or 0 if the list is empty. +.Pp +.Fn ml_purge +returns the number of mbufs that were freed. +.Pp +.Fn MBUF_LIST_FIRST +returns the first mbuf in the mbuf list, or +.Dv NULL +if the list is empty. +.Pp +.Fn MBUF_LIST_NEXT +returns the next mbuf in the mbuf list, or +.Dv NULL +if the end of the list has been reached. +.Sh SEE ALSO +.Xr mbuf 9 diff --git a/static/openbsd/man9/mq_init.9 b/static/openbsd/man9/mq_init.9 new file mode 100644 index 00000000..3d37683a --- /dev/null +++ b/static/openbsd/man9/mq_init.9 @@ -0,0 +1,251 @@ +.\" $OpenBSD: mq_init.9,v 1.13 2020/08/28 09:15:16 fcambus Exp $ +.\" +.\" Copyright (c) 2015 David Gwynne +.\" +.\" 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: August 28 2020 $ +.Dt MQ_INIT 9 +.Os +.Sh NAME +.Nm mq_init , +.Nm mq_enqueue , +.Nm mq_push , +.Nm mq_dequeue , +.Nm mq_enlist , +.Nm mq_delist , +.Nm mq_dechain , +.Nm mq_len , +.Nm mq_empty , +.Nm mq_full , +.Nm mq_hdatalen , +.Nm mq_purge , +.Nm mq_drops , +.Nm mq_set_maxlen , +.Nm MBUF_QUEUE_INITIALIZER +.Nd mbuf queue API +.Sh SYNOPSIS +.In sys/mbuf.h +.Ft void +.Fn mq_init "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl" +.Ft int +.Fn mq_enqueue "struct mbuf_queue *mq" "struct mbuf *m" +.Ft int +.Fn mq_push "struct mbuf_queue *mq" "struct mbuf *m" +.Ft struct mbuf * +.Fn mq_dequeue "struct mbuf_queue *mq" +.Ft int +.Fn mq_enlist "struct mbuf_queue *mq" "struct mbuf_list *ml" +.Ft void +.Fn mq_delist "struct mbuf_queue *mq" "struct mbuf_list *ml" +.Ft struct mbuf * +.Fn mq_dechain "struct mbuf_queue *mq" +.Ft unsigned int +.Fn mq_len "struct mbuf_queue *mq" +.Ft int +.Fn mq_empty "struct mbuf_queue *mq" +.Ft int +.Fn mq_full "struct mbuf_queue *mq" +.Ft unsigned int +.Fn mq_hdatalen "struct mbuf_queue *mq" +.Ft unsigned int +.Fn mq_purge "struct mbuf_queue *mq" +.Ft unsigned int +.Fn mq_drops "struct mbuf_queue *mq" +.Ft void +.Fn mq_set_maxlen "struct mbuf_queue *mq" "unsigned int" +.Ft struct mbuf_queue +.Fn MBUF_QUEUE_INITIALIZER "unsigned int maxlen" "int ipl" +.Sh DESCRIPTION +The mbuf queue API provides implementations of data structures and operations +for queueing mbufs and lists of mbufs between contexts. +.Pp +mbuf_queue data structures provide a superset of the functionality +available in mbuf_lists, and protect themselves internally with a +.Xr mutex 9 , +making them useful for moving mbufs between contexts or subsystems. +Additionally, mbuf_queues provide a limit on the number of mbufs that +may be queued. +.Pp +mbuf_queue structures support the following functionality: +.Pp +.Bl -enum -compact -offset indent +.It +Insertion of a new mbuf at the end of the queue. +.It +Removal of an mbuf from the head of the queue. +.It +Reinsertion of an mbuf at the head of the queue. +.It +Removal of the entire chain of mbufs on the queue. +.It +Insertion of the mbufs in an mbuf_list at the end of the queue. +.It +Removal of all the mbufs on the queue as an mbuf_list. +.El +.Bl -tag -width Ds +.It Fn mq_init "struct mbuf_queue *mq" "unsigned int maxlen" "int ipl" +Initialises the mbuf queue structure +.Fa mq . +The maximum number of mbufs that should be queued is specified with +.Fa maxlen . +The highest interrupt priority level the queue will be operated at is +specified via +.Fa ipl . +.It Fn MBUF_QUEUE_INITIALIZER "unsigned int maxlen" "int ipl" +Initialises an mbuf queue structure declaration. +The maximum number of mbufs that should be queued is specified with +.Fa maxlen . +The highest interrupt priority level the queue will be operated at is +specified via +.Fa ipl . +.It Fn mq_enqueue "struct mbuf_queue *mq" "struct mbuf *m" +Enqueue mbuf +.Fa m +on the end of the +.Fa mq +mbuf queue. +If the queue is full then +.Fa m +will be dropped. +.It Fn mq_push "struct mbuf_queue *mq" "struct mbuf *m" +Enqueue mbuf +.Fa m +on the end of the +.Fa mq +mbuf queue. +If the queue is full then the mbuf at the head of the queue +will be dropped. +.It Fn mq_dequeue "struct mbuf_queue *mq" +Dequeue an mbuf from the front of the +.Fa mq +mbuf queue. +.It Fn mq_enlist "struct mbuf_queue *mq" "struct mbuf_list *ml" +Enqueue all the mbufs on the +.Fa ml +mbuf list on to the end of the +.Fa mq +mbuf queue. +Note, the number of mbufs placed on the queue may exceed its maximum length. +.It Fn mq_delist "struct mbuf_queue *mq" "struct mbuf_list *ml" +Dequeue all the mbufs on the +.Fa mq +mbuf queue on to the +.Fa ml +mbuf list. +.It Fn mq_dechain "struct mbuf_queue *mq" +Dequeue all mbufs from the +.Fa mq +mbuf queue. +.It Fn mq_len "struct mbuf_queue *mq" +Return the number of mbufs on the +.Fa mq +mbuf queue. +.It Fn mq_empty "struct mbuf_queue *mq" +Return if the +.Fa mq +mbuf queue is empty. +.It Fn mq_full "struct mbuf_queue *mq" +Return if the +.Fa mq +mbuf queue is full. +.It Fn mq_hdatalen "struct mbuf_queue *mq" +Return the number of bytes in the packet at the head of the +.Fa mq +mbuf queue. +.It Fn mq_purge "struct mbuf_queue *mq" +Free all the mbufs on the +.Fa mq +mbuf queue. +.It Fn mq_drops "struct mbuf_queue *mq" +Return how many mbufs were dropped and freed by +.Xr m_freem 9 +if the +.Fa mq +mbuf queue was too full. +.It Fn mq_set_maxlen "struct mbuf_queue *mq" "unsigned int" +Alter the maximum number of mbufs that should be queued on the +.Fa mq +mbuf queue. +Note, +.Fn mq_set_maxlen +will only set a new limit, it will not free any excess mbufs that may +already exist on the queue. +.El +.Sh CONTEXT +.Fn mq_init , +.Fn mq_enqueue , +.Fn mq_push , +.Fn mq_dequeue , +.Fn mq_enlist , +.Fn mq_delist , +.Fn mq_dechain , +.Fn mq_len , +.Fn mq_empty , +.Fn mq_full , +.Fn mq_purge , +.Fn mq_drops , +.Fn mq_set_maxlen , +and +.Fn MBUF_QUEUE_INITIALIZER +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn mq_dequeue +returns the mbuf that was at the head of its queue. +If the queue was empty, +.Dv NULL +is returned. +.Pp +.Fn mq_dechain +returns all the mbufs that were on its queues via a pointer to an mbuf +with the chain accessible via m_nextpkt members. +If the queue was empty, +.Dv NULL +is returned. +.Pp +.Fn mq_len +returns the number of mbufs on the queue. +.Pp +.Fn mq_empty +returns a non-zero value if the queue is empty, otherwise 0. +.Pp +.Fn mq_full +returns a non-zero value if the queue is full, otherwise 0. +.Pp +.Fn mq_enqueue +returns 0 if the mbuf was successfully queued, or non-zero if the +mbuf was freed because it would cause the queue to exceed its maximum +length. +.Pp +.Fn mq_push +returns 0 if there was space on the queue for the mbuf, or non-zero +if the head of the queue was freed to make space for it. +.Pp +.Fn mq_enlist +returns the number of mbufs that were dropped from the list if the +length of the queue exceeded its maximum length. +.Pp +.Fn mq_hdatalen +returns the size of a packet on the queue, or 0 if the queue is empty. +.Pp +.Fn mq_purge +returns the number of mbufs that were freed. +.Pp +.Fn mq_drops +returns the number of mbufs that were freed during +.Fn mq_enqueue +operations that would have caused the queue to exceed its maximum length. +.Sh SEE ALSO +.Xr mbuf 9 , +.Xr ml_init 9 , +.Xr mutex 9 diff --git a/static/openbsd/man9/mutex.9 b/static/openbsd/man9/mutex.9 new file mode 100644 index 00000000..332ead42 --- /dev/null +++ b/static/openbsd/man9/mutex.9 @@ -0,0 +1,186 @@ +.\" $OpenBSD: mutex.9,v 1.25 2019/11/04 18:18:03 anton Exp $ +.\" +.\" Copyright (c) 2005 Pedro Martelletto +.\" 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 $Mdocdate: November 4 2019 $ +.Dt MUTEX 9 +.Os +.Sh NAME +.Nm mutex , +.Nm mtx_init , +.Nm mtx_init_flags , +.Nm mtx_enter , +.Nm mtx_enter_try , +.Nm mtx_leave , +.Nm MUTEX_ASSERT_LOCKED , +.Nm MUTEX_ASSERT_UNLOCKED , +.Nm MUTEX_INITIALIZER , +.Nm MUTEX_INITIALIZER_FLAGS +.Nd interface to CPU mutexes +.Sh SYNOPSIS +.In sys/mutex.h +.Ft void +.Fn mtx_init "struct mutex *mtxp" "int wantipl" +.Ft void +.Fn mtx_init_flags "struct mutex *mtxp" "int wantipl" "const char *name" \ +"int flags" +.Ft void +.Fn mtx_enter "struct mutex *mtxp" +.Ft int +.Fn mtx_enter_try "struct mutex *mtxp" +.Ft void +.Fn mtx_leave "struct mutex *mtxp" +.Fn MUTEX_ASSERT_LOCKED "struct mutex *mtxp" +.Fn MUTEX_ASSERT_UNLOCKED "struct mutex *mtxp" +.Fn MUTEX_INITIALIZER "int wantipl" +.Fn MUTEX_INITIALIZER_FLAGS "int wantipl" "const char *name" "int flags" +.Sh DESCRIPTION +The +.Nm +set of functions provides a non-recursive, interrupt-aware spinning mechanism +to ensure mutual exclusion between different CPUs. +.Pp +The +.Fn mtx_init +function is used to initiate the mutex pointed to by +.Fa mtxp . +When acquired, the mutex will cause the processor interrupt level to be raised +to +.Fa wantipl +if necessary. +.Pp +The +.Fn mtx_init_flags +macro is similar to +.Fn mtx_init , +but it additionally accepts parameters for +.Xr witness 4 . +The pointer +.Fa name +differentiates a lock type. +Two mutexes have the same lock type only if they have been created by the same +occurrence of +.Fn mtx_init_flags +with the same pointer +.Fa name . +The +.Fa flags +parameter is a bitwise OR of the following options: +.Bl -tag -width MTX_NOWITNESS -offset indent +.It Dv MTX_DUPOK +Prevents +.Xr witness 4 +from logging when a CPU acquires more than one lock of this lock type. +.It Dv MTX_NOWITNESS +Instructs +.Xr witness 4 +to ignore this lock. +.El +.Pp +The +.Fn mtx_enter +function acquires a mutex, spinning if necessary. +.Pp +The +.Fn mtx_enter_try +function attempts to acquire a mutex. +.Pp +The +.Fn mtx_leave +function releases a mutex. +In case the acquisition of the mutex caused the interrupt level to be changed, +it is then restored. +.Pp +The +.Fn MUTEX_ASSERT_LOCKED +and +.Fn MUTEX_ASSERT_UNLOCKED +macros may be used to assert that a mutex is held locked or unlocked by +the current CPU. +.Pp +A mutex declaration may be initialised with the +.Fn MUTEX_INITIALIZER +macro. +When acquired, the mutex will cause the processor interrupt level to be raised +to +.Fa wantipl +if necessary. +.Pp +The +.Fn MUTEX_INITIALIZER_FLAGS +macro is similar to +.Fn MUTEX_INITIALIZER , +but it additionally accepts parameters for +.Xr witness 4 . +See the +.Fn mtx_init_flags +macro for details. +.Sh CONTEXT +.Fn mtx_init +and +.Fn mtx_init_flags +can be called during autoconf, from process context, or from interrupt +context. +.Pp +.Fn mtx_enter , +.Fn mtx_enter_try , +and +.Fn mtx_leave +can be called during autoconf, from process context, or from any +interrupt context at or below the interrupt level +.Fa mtxp +was initialised with. +.Sh RETURN VALUES +The +.Fn mtx_enter_try +function will return non-zero if it succeeds in acquiring the mutex +.Fa mtxp , +otherwise it will return 0. +.Sh SEE ALSO +.Xr witness 4 , +.Xr msleep 9 , +.Xr rwlock 9 , +.Xr spl 9 +.Sh HISTORY +The +.Nm +functions first appeared in +.Ox 3.6 . +.Sh AUTHORS +The +.Nm +functions were written by +.An Artur Grabowski Aq Mt art@openbsd.org . +.Sh CAVEATS +As these are spinning locks, don't sleep while holding one. +.Pp +Multiple mutexes may be nested, but not interleaved. +This is okay: +.Bd -literal -offset indent +mtx_enter(foo); +mtx_enter(bar); +mtx_leave(bar); +mtx_leave(foo); +.Ed +.Pp +While this is +.Fa not : +.Bd -literal -offset indent +mtx_enter(foo); +mtx_enter(bar); +mtx_leave(foo); +mtx_leave(bar); +.Ed diff --git a/static/openbsd/man9/namei.9 b/static/openbsd/man9/namei.9 new file mode 100644 index 00000000..a297dd5f --- /dev/null +++ b/static/openbsd/man9/namei.9 @@ -0,0 +1,326 @@ +.\" $OpenBSD: namei.9,v 1.23 2023/07/15 23:01:25 kn Exp $ +.\" $NetBSD: namei.9,v 1.9 2003/05/06 10:46:44 jmmv Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 $Mdocdate: July 15 2023 $ +.Dt NAMEI 9 +.Os +.Sh NAME +.Nm namei , +.Nm vfs_lookup , +.Nm vfs_relookup , +.Nm NDINIT , +.Nm NDINITAT +.Nd pathname lookup +.Sh SYNOPSIS +.In sys/param.h +.In sys/namei.h +.Ft int +.Fn namei "struct nameidata *ndp" +.Ft int +.Fn vfs_lookup "struct nameidata *ndp" +.Ft int +.Fn vfs_relookup "struct vnode *dvp" "struct vnode **vpp" \ +"struct componentname *cnp" +.Ft void +.Fn NDINIT "struct nameidata *ndp" "u_long op" "u_long flags" \ +"enum uio_seg segflg" "const char *namep" "struct proc *p" +.Ft void +.Fn NDINITAT "struct nameidata *ndp" "u_long op" "u_long flags" \ +"enum uio_seg segflg" "int dirfd" "const char *namep" "struct proc *p" +.Sh DESCRIPTION +The +.Fn namei +function converts a pathname to a +.Xr vnode 9 . +It uses the following structure: +.Bd -literal +struct nameidata { + /* + * Arguments to namei/lookup. + */ + const char *ni_dirp; /* pathname pointer */ + int ni_dirfd; /* AT_FDCWD or fd of base of */ + /* relative paths */ + enum uio_seg ni_segflg; /* location of pathname */ + /* + * Arguments to lookup. + */ + struct vnode *ni_startdir; /* starting directory */ + struct vnode *ni_rootdir; /* logical root directory */ + uint64_t ni_pledge; /* expected pledge for namei */ + u_char ni_unveil; /* required unveil flags for namei */ + /* + * Results: returned from/manipulated by lookup + */ + struct vnode *ni_vp; /* vnode of result */ + struct vnode *ni_dvp; /* vnode of intermediate dir */ + /* + * Shared between namei and lookup/commit routines. + */ + size_t ni_pathlen; /* remaining chars in path */ + char *ni_next; /* next location in pathname */ + u_long ni_loopcnt; /* count of symlinks encountered */ + struct unveil *ni_unveil_match; /* last matching unveil component */ + /* + * Lookup parameters + */ + struct componentname ni_cnd; +}; +.Ed +.Pp +The +.Fn namei +function accesses vnode operations by passing arguments in the +partially initialised +.Em componentname +structure +.Em ni_cnd . +This structure describes the subset of information from the nameidata +structure that is passed through to the vnode operations. +See +.Xr VOP_LOOKUP 9 +for more information. +The details of the componentname structure are not absolutely necessary +since the members are initialised by the helper macros +.Fn NDINIT +and +.Fn NDINITAT . +It is useful to know the operations and flags as specified in +.Xr VOP_LOOKUP 9 . +.Pp +The +.Fn namei +function overloads +.Em ni_cnd.cn_flags +with some additional flags. +These flags should be specific to +.Fn namei +and ignored by vnode operations. +However, due to the historic close relationship between +.Fn namei +and the vnode operations, these flags are sometimes used +(and set) by vnode operations, particularly +.Fn VOP_LOOKUP . +The additional flags are: +.Pp +.Bl -tag -offset indent -width NOCROSSMOUNT -compact +.It NOCROSSMOUNT +do not cross mount points +.It RDONLY +lookup with read-only semantics +.It HASBUF +caller has allocated pathname buffer +.Em ni_cnd.cn_pnbuf +.It SAVENAME +save pathname buffer +.It SAVESTART +save starting directory +.It ISDOTDOT +current pathname component is .. +.It MAKEENTRY +add entry to the name cache +.It ISLASTCN +this is last component of pathname +.It ISSYMLINK +symlink needs interpretation +.It REALPATH +save pathname buffer for realpath +.It REQUIREDIR +must be a directory +.It STRIPSLASHES +strip trailing slashes from the pathname +.It PDIRUNLOCK +.Fn VOP_LOOKUP +unlocked parent dir +.It BYPASSUNVEIL +bypass pledge paths checks +.It KERNELPATH +access file as kernel, not process +.El +.Pp +If the caller of +.Fn namei +sets the SAVENAME flag, then it must free the buffer. +If +.Fn VOP_LOOKUP +sets the flag, then the buffer must be freed by either the commit +routine or the +.Fn VOP_ABORT +routine. +The SAVESTART flag is set only by the callers of +.Fn namei . +It implies SAVENAME plus the addition of saving the parent directory +that contains the name in +.Em ni_startdir . +It allows repeated calls to +.Fn vfs_lookup +for the name being sought. +The caller is responsible for releasing the buffer and for invoking +.Fn vrele +on +.Em ni_startdir . +.Pp +All access to +.Fn namei , +.Fn vfs_lookup , +and +.Fn vfs_relookup +must be in process context. +Pathname lookups cannot be done in interrupt context. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn namei "ndp" +Convert a pathname into a pointer to a vnode. +The pathname is specified by +.Em ndp-\*[Gt]ni_dirp +and is of length +.Em ndp-\*[Gt]ni_pathlen . +The +.Em ndp-\*[Gt]segflg +flag defines whether the name in +.Em ndp-\*[Gt]ni_dirp +is an address in kernel space (UIO_SYSSPACE) or an address in user +space (UIO_USERSPACE). +The vnode for the pathname is referenced and returned in +.Em ndp-\*[Gt]ni_vp . +.Pp +If +.Em ndp-\*[Gt]ni_cnd.cn_flags +has the FOLLOW flag set then symbolic links are followed when they +occur at the end of the name translation process. +Symbolic links are always followed for all other pathname components +other than the last. +.Pp +If the LOCKLEAF flag is set, a locked vnode is returned. +.It Fn vfs_lookup "ndp" +Search for a pathname. +This is a very central and rather complicated routine. +.Pp +The pathname is specified by +.Em ndp-\*[Gt]ni_dirp +and is of length +.Em ndp-\*[Gt]ni_pathlen . +The starting directory is taken from +.Em ndp-\*[Gt]ni_startdir . +The pathname is descended until done, or a symbolic link is +encountered. +.Pp +The semantics of +.Fn vfs_lookup +are altered by the operation specified by +.Em ndp-\*[Gt]ni_cnd.cn_nameiop . +When CREATE, RENAME, or DELETE is specified, information usable in +creating, renaming, or deleting a directory entry may be calculated. +.Pp +If +.Em ndp-\*[Gt]ci_cnd.cn_flags +has LOCKPARENT set, the parent directory is returned locked in +.Em ndp-\*[Gt]ni_dvp . +If WANTPARENT is set, the parent directory is returned unlocked. +Otherwise the parent directory is not returned. +If the target of the pathname exists and LOCKLEAF is set, the target +is returned locked in +.Em ndp-\*[Gt]ni_vp , +otherwise it is returned unlocked. +.It Fn vfs_relookup "dvp" "vpp" "cnp" +Reacquire a path name component in a directory. +This is a quicker way to lookup a pathname component when the parent +directory is known. +The unlocked parent directory vnode is specified by +.Fa dvp +and the pathname component by +.Fa cnp . +The vnode of the pathname is returned in the address specified by +.Fa vpp . +.It Fn NDINITAT "ndp" "op" "flags" "segflg" "dirfd" "namep" "p" +Initialise a nameidata structure pointed to by +.Fa ndp +for use by the +.Nm +interfaces. +It saves having to deal with the componentname structure inside +.Fa ndp . +The operation and flags are specified by +.Fa op +and +.Fa flags +respectively. +These are the values to which +.Em ndp-\*[Gt]ni_cnd.cn_nameiop +and +.Em ndp-\*[Gt]ni_cnd.cn_flags +are respectively set. +The segment flag, which defines whether the pathname is in kernel +address space or user address space, is specified by +.Fa segflg . +The directory from which relative pathnames will be looked up is +specified by +.Fa dirfd , +with +.Dv AT_FDCWD +specifying use of the current working directory of process +.Fa p . +The argument +.Fa namep +is a pointer to the pathname that +.Em ndp-\*[Gt]ni_dirp +is set to and +.Fa p +is the calling process. +.It Fn NDINIT "ndp" "op" "flags" "segflg" "namep" "p" +Same as +.Fn NDINITAT "ndp" "op" "flags" "segflg" \fRAT_FDCWD\fP "namep" "p" . +.El +.Sh CODE REFERENCES +The name lookup subsystem is implemented within the file +.Pa sys/kern/vfs_lookup.c . +.Sh SEE ALSO +.Xr intro 9 , +.\" .Xr namecache 9 , +.Xr vfs 9 , +.Xr vnode 9 , +.Xr VOP_LOOKUP 9 +.Sh HISTORY +The +.Fn namei +function first appeared in +.At v4 . +Its name is an abbreviation for the name-to-inode conversion +which it performed before the appearance of +.Xr vfs 9 +in +.Bx 4.3 Reno . +.Sh BUGS +It is unfortunate that much of the +.Nm +interface makes assumptions on the underlying vnode operations. +These assumptions are an artefact of the introduction of the vfs +interface to split a file system interface which was historically +designed as a tightly coupled module. diff --git a/static/openbsd/man9/panic.9 b/static/openbsd/man9/panic.9 new file mode 100644 index 00000000..c32aa84d --- /dev/null +++ b/static/openbsd/man9/panic.9 @@ -0,0 +1,76 @@ +.\" $OpenBSD: panic.9,v 1.10 2021/05/16 15:11:08 deraadt Exp $ +.\" $NetBSD: panic.9,v 1.2 1996/10/09 17:20:04 explorer Exp $ +.\" +.\" Copyright (c) 1996 Michael Graff. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must 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. +.\" 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 $Mdocdate: May 16 2021 $ +.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 +.Ft void +.Fn panic "const char *fmt" ... +.Sh DESCRIPTION +The +.Fn panic +function makes the +.Ox +system terminate. +The message +.Fa fmt +is a +.Xr printf 9 +style format string. +The message is printed to the console (with a newline) and the location +pointed to by the global char pointer +.Fa panicstr +is set to the address of the message text for retrieval from the OS +core dump. +.Pp +If the kernel debugger is installed, control is passed to it. +Otherwise, an attempt is made to save a core dump of the OS to a configured +dump device. +.Pp +If +.Fn panic +is called twice (from the disk sync routines, for example) the system is +rebooted without syncing the disks. +.Sh RETURN VALUES +The +.Fn panic +function does not return. +.Sh SEE ALSO +.Xr printf 3 , +.Xr boot 9 , +.Xr printf 9 diff --git a/static/openbsd/man9/pci_conf_read.9 b/static/openbsd/man9/pci_conf_read.9 new file mode 100644 index 00000000..7c144508 --- /dev/null +++ b/static/openbsd/man9/pci_conf_read.9 @@ -0,0 +1,121 @@ +.\" $OpenBSD: pci_conf_read.9,v 1.14 2024/11/13 10:56:18 jsg Exp $ +.\" +.\" Copyright (c) 2005 Michael Shalayeff +.\" 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 $Mdocdate: November 13 2024 $ +.Dt PCI_CONF_READ 9 +.Os +.Sh NAME +.Nm pci_make_tag , +.Nm pci_decompose_tag , +.Nm pci_conf_read , +.Nm pci_conf_write +.Nd PCI config space manipulation functions +.Sh SYNOPSIS +.In alpha/pci/pci_machdep.h +.In i386/pci/pci_machdep.h +.In machine/pci_machdep.h +.Ft pcitag_t +.Fn pci_make_tag "pci_chipset_tag_t pc" "int bus" "int dev" "int func" +.Ft void +.Fn pci_decompose_tag "pci_chipset_tag_t pc" "pcitag_t tag" "int *busp" \ +"int *devp" "int *funcp" +.Ft pcireg_t +.Fn pci_conf_read "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" +.Ft void +.Fn pci_conf_write "pci_chipset_tag_t pc" "pcitag_t tag" "int reg" \ +"pcireg_t val" +.Sh DESCRIPTION +These functions provide a way to access PCI configuration space. +.Pp +The following types are defined in the machine dependent include file +.In pci_machdep.h . +.Pp +.Bl -tag -width pci_chipset_tag_t -offset indent -compact +.It pci_chipset_tag_t +a PCI chipset descriptor; +.It pcitag_t +a PCI device tag; +.It pcireg_t +a PCI register datum. +.El +.Pp +In order to access PCI configuration space, a device tag shall be made using +.Nm pci_make_tag +given the PCI chipset tag +.Ar pc +and the device specification in a tuple of +.Ar bus , +.Ar device , +.Ar function . +The PCI tag composition is a PCI chipset dependent operation +although often as simple as a shift and logical OR combination. +.Pp +The +.Nm pci_decompose_tag +provides a reverse operation. +Once a tag is composed, it is possible to perform configuration +space read and write with +.Nm pci_conf_read +and +.Nm pci_conf_write , +respectively. +Access to PCI configuration space is only provided for whole +.Nm pcireg_t +items, which is usually a 32-bit integer. +Access to non-existent PCI devices do not (or should not) generate +any kinds of faults or interruptions and thus allow for an easy device +scanning by cycling through all possible device and function numbers +for a given bus. +.Pp +Below is an overview of defined PCI configuration space registers for +devices: +.Bl -tag -width 0xff -offset indent +.It 0x00 +Vendor (lower word) and Product (higher word) identification +(see +.Pa /sys/dev/pci/pcidevs +for a comprehensive list). +.It 0x04 +Commands and Status register. +.It 0x08 +PCI device's class and subclass IDs. +See +.Pa /sys/dev/pci/pcireg.h +for PCI_CLASS_* and PCI_SUBCLASS_* definitions. +.It 0x0c +Specify (low byte to high): cache line size, PCI latency timer, header type, +and BIST. +.It 0x10 - 0x28 +Base address registers for I/O and memory space mapped registers. +.It 0x28 +CardBus CIS register. +.It 0x2c +Similar to 0x00 register's definitions for a subsystem identification. +.It 0x34 +A pointer to the capabilities list. +Each item is an offset in the configuration space itself. +.It 0x3c +Interrupt line and pin numbers. +.El +.Sh SEE ALSO +.Xr cardbus 4 , +.Xr pci 4 , +.Xr pci_intr_map 9 +.Sh HISTORY +These functions first appeared in +.Ox 1.2 . +.\" .Sh AUTHORS diff --git a/static/openbsd/man9/pci_intr_map.9 b/static/openbsd/man9/pci_intr_map.9 new file mode 100644 index 00000000..c8997f7d --- /dev/null +++ b/static/openbsd/man9/pci_intr_map.9 @@ -0,0 +1,193 @@ +.\" $OpenBSD: pci_intr_map.9,v 1.19 2024/11/13 10:56:18 jsg Exp $ +.\" +.\" Copyright (c) 2005 Michael Shalayeff +.\" 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 $Mdocdate: November 13 2024 $ +.Dt PCI_INTR_MAP 9 +.Os +.Sh NAME +.Nm pci_intr_map , +.Nm pci_intr_map_msi , +.Nm pci_intr_map_msix , +.Nm pci_intr_line , +.Nm pci_intr_string , +.Nm pci_intr_establish , +.\" .Nm pci_intr_establish_cpu , +.Nm pci_intr_disestablish +.Nd PCI interrupts +.Sh SYNOPSIS +.In alpha/pci/pci_machdep.h +.In i386/pci/pci_machdep.h +.In machine/pci_machdep.h +.Ft int +.Fn pci_intr_map "struct pci_attach_args *paa" "pci_intr_handle_t *ih" +.Ft int +.Fn pci_intr_map_msi "struct pci_attach_args *paa" "pci_intr_handle_t *ih" +.Ft int +.Fo pci_intr_map_msix +.Fa "struct pci_attach_args *paa" +.Fa "int vector" +.Fa "pci_intr_handle_t *ih" +.Fc +.Ft int +.Fn pci_intr_line "pci_intr_handle_t ih" +.Ft const char * +.Fn pci_intr_string "pci_chipset_tag_t pc" "pci_intr_handle_t ih" +.Ft void * +.Fo pci_intr_establish +.Fa "pci_chipset_tag_t pc" +.Fa "pci_intr_handle_t ih" +.Fa "int level" +.Fa "int (*func)(void *)" +.Fa "void *arg" +.Fa "const char *name" +.Fc +.\" .Ft void * +.\" .Fo pci_intr_establish_cpu +.\" .Fa "pci_chipset_tag_t pc" +.\" .Fa "pci_intr_handle_t ih" +.\" .Fa "int level" +.\" .Fa "struct cpu_info *ci" +.\" .Fa "int (*func)(void *)" +.\" .Fa "void *arg" +.\" .Fa "const char *name" +.\" .Fc +.Ft void +.Fn pci_intr_disestablish "pci_chipset_tag_t pc" "void *v" +.Sh DESCRIPTION +These functions are provided by the machine-dependent implementation +for attaching handler functions to the interrupts of PCI devices. +.Pp +An architect type is provided by the machine-dependent +code +.Va pci_intr_handle_t , +to be initialised by +.Fn pci_intr_map , +.Fn pci_intr_map_msi , +or +.Fn pci_intr_map_msix . +.Pp +The +.Fn pci_intr_map +function should be called first to establish a mapping between a PCI +pin and the interrupt controller's interrupt vector. +This process may include resolving the mapping through +firmware-provided information. +.Pp +For devices that support Message Signaled Interrupts (MSI) the +.Fn pci_intr_map_msi +function should be called instead. +This function can fail if the +system does not support MSI. +In that case +.Fn pci_intr_map +should be called to fall back on classic PCI interrupts. +.Pp +For devices that support Extended Message Signaled Interrupts (MSI-X) the +.Fn pci_intr_map_msix +function can be called instead. +This function can fail if the system does not support MSI-X. +In that case +.Fn pci_intr_map_msi +or +.Fn pci_intr_map +can be called to fall back on Message Signalled Interrupts or classic +PCI interrupts respectively. +MSI-X can provide multiple interrupt vectors per device. +For each vector, a separate call to +.Fn pci_intr_map_msix +is made with the +.Fa vector +argument specifying which interrupt vector to map. +.Pp +Having initialised the +.Fa pci_intr_handle_t +in the previous step, an interrupt handler can be established using +.Fn pci_intr_establish . +.\" or +.\" .Fn pci_intr_establish_cpu . +.\" .Fn pci_intr_establish_cpu +.\" establishes an interrupt on the CPU specified in the +.\" .Fa ci +.\" argument, while +.\" .Fn pci_intr_establish +.\" uses a system selected CPU. +An established interrupt handler is always called with the system +interrupt priority level set equal to, or higher than, +.Fa level . +.Pp +A printable string representation of an initialised interrupt mapping +can be generated with +.Fn pci_intr_string . +.Pp +.Fn pci_intr_line +provides the interrupt line extracted from the MD interrupt handle. +Upon device detachment, +.Fn pci_intr_disestablish +should be used to disassociate the handler from the interrupt. +.Pp +See +.Xr spl 9 +for an explanation of the +.Va ipl +.Dq interrupt priority levels . +.Sh EXAMPLES +A typical code sequence for establishing a handler +for a device interrupt in the driver might be: +.Bd -literal -offset 3n +int +xxxattach(struct device *parent, struct device *self, void *aux) +{ + struct xxx_softc *sc = (struct xxx_softc *)self; + struct pci_attach_args *pa = aux; + pci_intr_handle_t ih; + const char *intrstr; + bus_size_t size; + + \&... + + if (pci_intr_map_msi(pa, &ih) && pci_intr_map(pa, &ih)) { + printf(": can't map interrupt\en"); + bus_space_unmap(sc->iot, sc->ioh, size); + return; + } + intrstr = pci_intr_string(pa->pa_pc, ih); + sc->sc_ih = pci_intr_establish(pa->pa_pc, ih, IPL_NET, + xxx_intr, sc, sc->sc_dev.dv_xname); + if (!sc->sc_ih) { + printf(": can't establish interrupt"); + if (intrstr) + printf(" at %s", intrstr); + printf("\en"); + bus_space_unmap(sc->iot, sc->ioh, size); + return; + } + + printf(": %s\en", intrstr); + + \&... +} +.Ed +.Sh SEE ALSO +.Xr cardbus 4 , +.Xr pci 4 , +.Xr pcibios 4 , +.Xr pci_conf_read 9 , +.Xr spl 9 +.Sh HISTORY +These functions first appeared in +.Ox 1.2 . +.\" .Sh AUTHORS diff --git a/static/openbsd/man9/pci_mapreg_map.9 b/static/openbsd/man9/pci_mapreg_map.9 new file mode 100644 index 00000000..1cf53d40 --- /dev/null +++ b/static/openbsd/man9/pci_mapreg_map.9 @@ -0,0 +1,133 @@ +.\" $OpenBSD: pci_mapreg_map.9,v 1.2 2023/04/13 15:07:42 miod Exp $ +.\" +.\" Copyright (c) 2019 David Gwynne +.\" 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 $Mdocdate: April 13 2023 $ +.Dt PCI_MAPREG_MAP 9 +.Os +.Sh NAME +.Nm pci_mapreg_map , +.Nm pci_mapreg_info , +.Nm pci_mapreg_probe , +.Nm pci_mapreg_type +.Nd PCI register mappings +.Sh SYNOPSIS +.In dev/pci/pcivar.h +.Ft int +.Fo pci_mapreg_map +.Fa "struct pci_attach_args *paa" +.Fa "int reg" +.Fa "pcireg_t type" +.Fa "int flags" +.Fa "bus_space_tag_t *tagp" +.Fa "bus_space_handle_t *handlep" +.Fa "bus_addr_t *basep" +.Fa "bus_size_t *sizep" +.Fa "bus_size_t maxsize" +.Fc +.Ft int +.Fo pci_mapreg_info +.Fa "pci_chipset_tag_t pc" +.Fa "pcitag_t tag" +.Fa "int reg" +.Fa "pcireg_t type" +.Fa "bus_addr_t *basep" +.Fa "bus_size_t *sizep" +.Fa "int *flagsp" +.Fc +.Ft int +.Fo pci_mapreg_probe +.Fa "pci_chipset_tag_t pc" +.Fa "pcitag_t tag" +.Fa "int reg" +.Fa "pcireg_t *typep" +.Fc +.Ft pcireg_t +.Fo pci_mapreg_type +.Fa "pci_chipset_tag_t pc" +.Fa "pcitag_t tag" +.Fa "int reg" +.Fc +.Sh DESCRIPTION +These functions provide wrappers and helpers around +.Xr bus_space 9 +mappings for device registers described by the Base Address Registers +(BARs) in a PCI devices configuration space. +.Pp +.Nm pci_mapreg_map +wraps a call to +.Xr bus_space_map 9 +using information from the BAR referenced by +.Fa reg +for the device being attached with +.Fa paa . +Memory or I/O mappings are derived from the +.Fa type +argument. +The size of the register mapping can be restricted by specifying a +non-zero value in +.Fa maxsize . +The bus space tag and handle used for the mapping, as well +as the base address and size of the mapping, will be provided +to the caller via the optional +.Fa tagp , +.Fa handlep , +.Fa basep , +and +.Fa sizep +pointers. +.Pp +.Nm pci_mapreg_info +provides bus space mapping information from the BAR referenced by +.Fa reg . +The +.Fa type +argument specifies whether the mapping provides Memory or I/O access. +The base address, size, and bus space flags are optionally provided +to the caller via the +.Fa basep , +.Fa sizep , +and +.Fa flagsp +pointers. +.Pp +.Nm pci_mapreg_probe +attempts to determine if the BAR referenced by +.Fa reg +describes a valid register mapping. +.Pp +.Nm pci_mapreg_type +returns the type of register access for the registers at the BAR +referenced by +.Fa reg . +.Sh RETURN VALUES +.Nm pci_mapreg_map , +.Nm pci_mapreg_info , +and +.Nm pci_mapreg_probe +return 0 on success, or an +.Xr errno 2 +style value on failure. +.Pp +.Nm pci_mapreg_type +returns either +.Dv PCI_MAPREG_TYPE_IO +or +.Dv PCI_MAPREG_TYPE_MEM . +.Sh SEE ALSO +.Xr pci 4 , +.Xr bus_space 9 , +.Xr pci_conf_read 9 diff --git a/static/openbsd/man9/physio.9 b/static/openbsd/man9/physio.9 new file mode 100644 index 00000000..528581ee --- /dev/null +++ b/static/openbsd/man9/physio.9 @@ -0,0 +1,130 @@ +.\" $OpenBSD: physio.9,v 1.11 2019/12/06 19:12:37 jmc Exp $ +.\" $NetBSD: physio.9,v 1.5 1999/03/16 00:40:47 garbled 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 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 $Mdocdate: December 6 2019 $ +.Dt PHYSIO 9 +.Os +.Sh NAME +.Nm physio +.Nd initiate I/O on raw devices +.Sh SYNOPSIS +.Ft int +.Fo physio +.Fa "void (*strategy)(struct buf *)" +.Fa "dev_t dev" +.Fa "int flags" +.Fa "void (*minphys)(struct buf *)" +.Fa "struct uio *uio" +.Fc +.Sh DESCRIPTION +.Fn physio +is a helper function typically called from character device read and write +routines to start I/O on a user process buffer. +It calls back on the provided +.Fa strategy +routine one or more times to complete the transfer described by +.Fa uio . +The maximum amount of data to transfer with each call to +.Fa strategy +is determined by the +.Fa minphys +routine. +Since +.Fa uio +normally describes user space addresses, +.Fn physio +needs to lock the appropriate data area into memory before each transaction +with +.Fa strategy +(see +.Xr uvm_vslock_device 9 +and +.Xr uvm_vsunlock_device 9 ) . +.Fn physio +always awaits the completion of the entire requested transfer before +returning, unless an error condition is detected earlier. +.Pp +In all cases, a temporary buffer is allocated from a system pool. +This buffer will have the +.Dv B_BUSY , +.Dv B_PHYS , +and +.Dv B_RAW +flags set when passed to the strategy routine. +.Pp +A break-down of the arguments follows: +.Bl -tag -width indent +.It Fa strategy +The device strategy routine to call for each chunk of data to initiate +device I/O. +.It Fa dev +The device number identifying the device to interact with. +.It Fa flags +Direction of transfer; the only valid settings are +.Dv B_READ +or +.Dv B_WRITE . +.It Fa minphys +A device specific routine called to determine the maximum transfer size +that the device's strategy routine can handle. +.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 +.Sq uio_segflg +set to anything other than +.Dv UIO_USERSPACE , +are undefined. +.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 +.Sq 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 , +.Xr uvm_vslock 9 diff --git a/static/openbsd/man9/pmap.9 b/static/openbsd/man9/pmap.9 new file mode 100644 index 00000000..7c0e6dd7 --- /dev/null +++ b/static/openbsd/man9/pmap.9 @@ -0,0 +1,424 @@ +.\" $OpenBSD: pmap.9,v 1.21 2025/01/19 22:14:45 kettenis Exp $ +.\" +.\" Copyright (c) 2001, 2002, 2003 CubeSoft Communications, 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, 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 $Mdocdate: January 19 2025 $ +.Dt PMAP_INIT 9 +.Os +.Sh NAME +.Nm pmap_init , +.Nm pmap_enter , +.Nm pmap_kenter_pa , +.Nm pmap_remove , +.Nm pmap_kremove , +.Nm pmap_unwire , +.Nm pmap_protect , +.Nm pmap_page_protect , +.Nm pmap_is_modified , +.Nm pmap_clear_modify , +.Nm pmap_is_referenced , +.Nm pmap_clear_reference , +.Nm pmap_copy_page , +.Nm pmap_zero_page , +.Nm pmap_create , +.Nm pmap_reference , +.Nm pmap_destroy , +.Nm pmap_steal_memory , +.Nm pmap_growkernel , +.Nm pmap_update , +.Nm pmap_collect , +.Nm pmap_populate , +.Nm pmap_virtual_space +.Nd machine dependent interface to the MMU +.Sh SYNOPSIS +.In machine/pmap.h +.Sh DESCRIPTION +The architecture-dependent +.Nm pmap +module describes how the physical mapping is done between the user-processes +and kernel virtual addresses and the physical addresses of the main memory, +providing machine-dependent translation and access tables that are used +directly or indirectly by the memory-management hardware. +The +.Nm pmap +layer can be viewed as a big array of mapping entries that are indexed by +virtual address to produce a physical address and flags. +These flags describe +the page's protection, whether the page has been referenced or modified and +other characteristics. +.Pp +The +.Nm pmap +interface is consistent across all platforms and hides the way page mappings +are stored. +.Sh INITIALIZATION +.nr nS 1 +.Ft void +.Fn pmap_init "void" +.nr nS 0 +.Pp +The +.Fn pmap_init +function is called from the machine-independent +.Xr uvm_init 9 +initialization code, when the MMU is enabled. +.Sh PAGE MANAGEMENT +Modified/referenced information is only tracked for pages managed by UVM +(pages for which a vm_page structure exists). +Only managed mappings of those pages have modified/referenced tracking. +The use of unmanaged mappings should be limited to code which may execute +in interrupt context (such as +.Xr malloc 9 ) +or to enter mappings for physical addresses which are not managed by UVM. +This allows +.Nm pmap +modules to avoid blocking interrupts when manipulating data structures or +holding locks. +Unmanaged mappings may only be entered into the kernel's virtual address space. +The modified/referenced bits must be tracked on a per-page basis, as they +are not attributes of a mapping, but attributes of a page. +Therefore, even after all mappings for a given page have been removed, the +modified/referenced bits for that page must be preserved. +The only time the modified/referenced bits may be cleared is when UVM +explicitly calls the +.Fn pmap_clear_modify +and +.Fn pmap_clear_reference +functions. +These functions must also change any internal state necessary to detect +the page being modified or referenced again after the modified/referenced +state is cleared. +.Pp +Mappings entered by +.Fn pmap_enter +are managed, mappings entered by +.Fn pmap_kenter_pa +are not. +.Sh MAPPING ALLOCATION +.nr nS 1 +.Ft int +.Fn pmap_enter "pmap_t pmap" "vaddr_t va" "paddr_t pa" "vm_prot_t prot" \ + "int flags" +.Ft void +.Fn pmap_kenter_pa "vaddr_t va" "paddr_t pa" "vm_prot_t prot" +.Ft void +.Fn pmap_remove "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" +.Ft void +.Fn pmap_kremove "vaddr_t va" "vsize_t size" +.nr nS 0 +.Pp +The +.Fn pmap_enter +function creates a managed mapping for physical page +.Fa pa +at the specified virtual address +.Fa va +in the target physical map +.Fa pmap +with protection specified by +.Fa prot : +.Bl -tag -width "PROT_WRITE" +.It PROT_READ +The mapping must allow reading. +.It PROT_WRITE +The mapping must allow writing. +.It PROT_EXEC +The page mapped contains instructions that will be executed by the +processor. +.El +.Pp +The +.Fa flags +argument contains protection bits (the same bits used in the +.Fa prot +argument) indicating the type of access that caused the mapping to +be created. +This information may be used to seed modified/referenced +information for the page being mapped, possibly avoiding redundant +faults on platforms that track modified/referenced information in +software. +Other information provided by +.Fa flags : +.Bl -tag -width "PMAP_CANFAIL" +.It PMAP_WIRED +The mapping being created is a wired mapping. +.It PMAP_CANFAIL +The call to +.Fn pmap_enter +is allowed to fail. +If this flag is not set, and the +.Fn pmap_enter +call is unable to create the mapping, perhaps due to insufficient +resources, the +.Nm pmap +module must panic. +.El +.Pp +The access type provided in the +.Fa flags +argument will never exceed the protection specified by +.Fa prot . +.Pp +The +.Fn pmap_enter +function is called by the fault routine to establish a mapping for +the page being faulted in. +If +.Fn pmap_enter +is called to enter a mapping at a virtual address for which a mapping +already exists, the previous mapping must be invalidated. +.Fn pmap_enter +is sometimes called to change the protection for a pre-existing mapping, +or to change the +.Dq wired +attribute for a pre-existing mapping. +.Pp +The +.Fn pmap_kenter_pa +function creates an unmanaged mapping of physical address +.Fa pa +at the specified virtual address +.Fa va +with the protection specified by +.Fa prot . +.Pp +The +.Fn pmap_remove +function removes the range of virtual addresses +.Fa sva +to +.Fa eva +from +.Fa pmap , +assuming proper alignment. +.Fn pmap_remove +is called during an unmap +operation to remove low-level machine dependent mappings. +.Pp +The +.Fn pmap_kremove +function removes an unmanaged mapping at virtual address +.Fa va +of size +.Fa size . +.Pp +A call to +.Fn pmap_update +must be made after +.Fn pmap_kenter_pa +or +.Fn pmap_kremove +to notify the +.Nm pmap +layer that the mappings need to be made correct. +.Sh ACCESS PROTECTION +.nr nS 1 +.Ft void +.Fn pmap_unwire "pmap_t pmap" "vaddr_t va" +.Ft void +.Fn pmap_protect "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" "vm_prot_t prot" +.Ft void +.Fn pmap_page_protect "struct vm_page *pg" "vm_prot_t prot" +.nr nS 0 +.Pp +The +.Fn pmap_unwire +function clears the wired attribute for a map/virtual-address pair. +The mapping must already exist in +.Fa pmap . +.Pp +The +.Fn pmap_protect +function sets the physical protection on range +.Fa sva +to +.Fa eva , +in +.Fa pmap . +.Pp +The +.Fn pmap_protect +function is called during a copy-on-write operation to write protect +copy-on-write memory, and when paging out a page to remove all mappings +of a page. +The +.Fn pmap_page_protect +function sets the permission for all mapping to page +.Fa pg . +The +.Fn pmap_page_protect +function is called before a pageout operation to ensure that all pmap +references to a page are removed. +.Sh PHYSICAL PAGE-USAGE INFORMATION +.nr nS 1 +.Ft boolean_t +.Fn pmap_is_modified "struct vm_page *pg" +.Ft boolean_t +.Fn pmap_clear_modify "struct vm_page *pg" +.Ft boolean_t +.Fn pmap_is_referenced "struct vm_page *pg" +.Ft boolean_t +.Fn pmap_clear_reference "struct vm_page *pg" +.nr nS 0 +.Pp +The +.Fn pmap_is_modified +and +.Fn pmap_clear_modify +functions read/set the modify bits on the specified physical page +.Fa pg . +The +.Fn pmap_is_referenced +and +.Fn pmap_clear_reference +functions read/set the reference bits on the specified physical page +.Fa pg . +.Pp +The +.Fn pmap_is_referenced +and +.Fn pmap_is_modified +functions are called by the pagedaemon when looking for pages to free. +The +.Fn pmap_clear_referenced +and +.Fn pmap_clear_modify +functions are called by the pagedaemon to help identification of pages +that are no longer in demand. +.Sh PHYSICAL PAGE INITIALIZATION +.nr nS 1 +.Ft void +.Fn pmap_copy_page "struct vm_page *src" "struct vm_page *dst" +.Ft void +.Fn pmap_zero_page "struct vm_page *page" +.nr nS 0 +.Pp +The +.Fn pmap_copy_page +function copies the content of the physical page +.Fa src +to physical page +.Fa dst . +.Pp +The +.Fn pmap_zero_page +function fills +.Fa page +with zeroes. +.Sh INTERNAL DATA STRUCTURE MANAGEMENT +.nr nS 1 +.Ft pmap_t +.Fn pmap_create "void" +.Ft void +.Fn pmap_reference "pmap_t pmap" +.Ft void +.Fn pmap_destroy "pmap_t pmap" +.nr nS 0 +.Pp +The +.Fn pmap_create +function creates an instance of the +.Em pmap +structure. +.Pp +The +.Fn pmap_reference +function increments the reference count on +.Fa pmap . +.Pp +The +.Fn pmap_destroy +function decrements the reference count on physical map +.Fa pmap +and retires it from service if the count drops to zero, assuming +it contains no valid mappings. +.Sh OPTIONAL FUNCTIONS +.nr nS 1 +.Ft vaddr_t +.Fn pmap_steal_memory "vsize_t size" "vaddr_t *vstartp" "vaddr_t *vendp" +.Ft vaddr_t +.Fn pmap_growkernel "vaddr_t maxkvaddr" +.Ft void +.Fn pmap_update "pmap_t pmap" +.Ft void +.Fn pmap_collect "pmap_t pmap" +.Ft void +.Fn pmap_populate "pmap_t pmap" "vaddr_t va" +.Ft void +.Fn pmap_virtual_space "vaddr_t *vstartp" "vaddr_t *vendp" +.nr nS 0 +.Pp +Wired memory allocation before the virtual memory system is bootstrapped +is accomplished by the +.Fn pmap_steal_memory +function. +After that point, the kernel memory allocation routines should be used. +.Pp +The +.Fn pmap_growkernel +function can preallocate kernel page tables to a specified virtual address. +.Pp +The +.Fn pmap_update +function notifies the +.Nm pmap +module to force processing of all delayed actions for all pmaps. +.Pp +The +.Fn pmap_populate +function makes sure the resources necessary for mapping the specified +virtual address +.Fa va +are allocated in the target physical map +.Fa pmap . +.Pp +The +.Fn pmap_collect +function informs the +.Nm pmap +module that the given +.Em pmap +is not expected to be used for some time, giving the +.Nm pmap +module a chance to prioritize. +The initial bounds of the kernel virtual address space are returned by +.Fn pmap_virtual_space . +.Sh SEE ALSO +.Xr fork 2 , +.Xr uvm_init 9 +.Sh HISTORY +The +.Bx 4.4 +.Nm pmap +module is based on Mach 3.0. +The introduction of UVM +left the +.Nm pmap +interface unchanged for the most part. +.Sh BUGS +Ifdefs must be documented. +.Pp +.Fn pmap_update +should be mandatory. diff --git a/static/openbsd/man9/pool.9 b/static/openbsd/man9/pool.9 new file mode 100644 index 00000000..9801326f --- /dev/null +++ b/static/openbsd/man9/pool.9 @@ -0,0 +1,352 @@ +.\" $OpenBSD: pool.9,v 1.61 2025/10/27 00:41:37 dv Exp $ +.\" $NetBSD: pool.9,v 1.18 2001/06/21 11:59:01 wiz Exp $ +.\" +.\" Copyright (c) 1997, 1998 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 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 $Mdocdate: October 27 2025 $ +.Dt POOL_INIT 9 +.Os +.Sh NAME +.Nm pool_init , +.Nm pool_destroy , +.Nm pool_get , +.Nm pool_put , +.Nm pool_prime , +.Nm pool_sethiwat , +.Nm pool_setlowat , +.Nm pool_sethardlimit +.Nd resource-pool manager +.Sh SYNOPSIS +.In sys/types.h +.In sys/pool.h +.Ft void +.Fo pool_init +.Fa "struct pool *pool" +.Fa "size_t size" +.Fa "u_int align" +.Fa "int ipl" +.Fa "int flags" +.Fa "const char *wmesg" +.Fa "struct pool_allocator *palloc" +.Fc +.Ft void +.Fo pool_destroy +.Fa "struct pool *pp" +.Fc +.Ft void * +.Fn pool_get "struct pool *pp" "int flags" +.Ft void +.Fn pool_put "struct pool *pp" "void *item" +.Ft int +.Fn pool_prime "struct pool *pp" "int nitems" +.Ft void +.Fn pool_sethiwat "struct pool *pp" "int n" +.Ft void +.Fn pool_setlowat "struct pool *pp" "int n" +.Ft int +.Fo pool_sethardlimit +.Fa "struct pool *pp" +.Fa "unsigned n" +.Fc +.Sh DESCRIPTION +These utility routines provide management of pools of fixed-sized +areas of memory. +Resource pools set aside an amount of memory for exclusive use by the resource +pool owner. +This can be used by applications to guarantee the availability of a minimum +amount of memory needed to continue operation independent of the memory +resources currently available from the system-wide memory allocator +.Pq Xr malloc 9 . +The pool manager obtains memory by using the special-purpose memory +allocator +.Fa palloc +passed to +.Fn pool_init , +for extra pool items in case the number of allocations exceeds +the nominal number of pool items managed by a pool resource. +This temporary memory will be automatically returned to the system +at a later time. +.Ss CREATING A POOL +The function +.Fn pool_init +initializes a resource pool. +The arguments are: +.Bl -tag -offset indent -width "align_offset" +.It Fa pool +Specifies the pool storage to be initialized. +.It Fa size +Specifies the size of the memory items managed by the pool. +.It Fa align +Specifies the memory address alignment of the items returned by +.Fn pool_get . +This argument must be a power of two. +If zero, +the alignment defaults to an architecture-specific natural alignment. +.It Fa ipl +The interrupt protection level used to protect the pool's internals, +and at what level the pool can be safely used. +See +.Xr spl 9 +for a list of the IPLs. +.It Fa flags +The bitwise OR of zero or more of the following values: +.Pp +.Bl -tag -width "PR_WAITOK" -offset indent -compact +.It Dv PR_WAITOK +The pool doesn't need to be interrupt safe. +It is recommended to specify this flag if the pool will never be +accessed in interrupt context. +.It Dv PR_RWLOCK +The pool will use an +.Xr rwlock 9 +instead of a +.Xr mutex 9 +for exclusion. +Requires +.Dv PR_WAITOK +to be specified as well, both to +.Fn pool_init +and on all +.Fn pool_get +calls on this pool. +.El +.It Fa wmesg +The message passed on to +.Xr tsleep 9 +if +.Fn pool_get +must wait for items to be returned to the pool. +.It Fa palloc +The back-end allocator used to manage the memory for the pool. +.Fa palloc +may be +.Dv NULL , +in which case the pool manager chooses an appropriate back-end allocator. +.El +.Ss DESTROYING A POOL +The +.Fn pool_destroy +function destroys a resource pool. +It takes a single argument +.Fa pp +identifying the pool resource instance. +.Ss ALLOCATING ITEMS FROM A POOL +.Fn pool_get +allocates an item from the pool and returns a pointer to it. +.Bl -tag -offset indent -width "flags" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa flags +One or more flags. +Either +.Dv PR_WAITOK +or +.Dv PR_NOWAIT +must be specified +to define behaviour in case the pooled resources are depleted. +If no resources are available and +.Dv PR_NOWAIT +was specified, +this function returns +.Dv NULL . +If +.Dv PR_WAITOK +was specified +but +.Dv PR_LIMITFAIL +was not, +.Fn pool_get +will wait until items are returned to the pool. +If both +.Dv PR_WAITOK +and +.Dv PR_LIMITFAIL +were specified, and the pool has reached its hard limit, +.Fn pool_get +will return +.Dv NULL +without waiting, allowing the caller to do its own garbage collection; +however, it will still wait if the pool is not yet at its hard limit. +If +.Dv PR_ZERO +was specified and an item has been successfully allocated, it is zeroed before +being returned to the caller. +.El +.Ss RETURNING ITEMS TO A POOL +.Fn pool_put +returns the pool item pointed at by +.Fa item +to the resource pool identified by the pool handle +.Fa pp . +If the number of available items in the pool exceeds the maximum pool +size set by +.Fn pool_sethiwat +and there are no outstanding requests for pool items, +the excess items will be returned to the system if possible. +.Bl -tag -offset indent -width "item" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa item +A pointer to a pool item previously obtained by +.Fn pool_get . +.El +.Pp +If a non-interrupt safe allocator has been selected by passing the +.Dv PR_WAITOK +flag to +.Fn pool_init , +.Fn pool_put +may sleep when completely unused pages are released. +.Ss PRIMING A POOL +.Fn pool_prime +adds items to the pool. +Storage space for the items is allocated by using the page allocation +routine specified to +.Fn pool_init . +.Pp +.Fn pool_prime +.Bl -tag -offset indent -width "nitems" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa nitems +The number of items to add to the pool. +.El +.Ss SETTING POOL RESOURCE WATERMARKS +A pool will attempt to increase its resource usage to keep up with the demand +for its items. +Conversely, +it will return unused memory to the system should the number of accumulated +unused items in the pool exceed a programmable limit. +The limits for the minimum and maximum number of items which a pool should keep +at hand are known as the high and low +.Sy watermarks . +The functions +.Fn pool_sethiwat +and +.Fn pool_setlowat +set a pool's high and low watermarks, respectively. +.Pp +.Fn pool_sethiwat +.Bl -tag -offset indent -width "flags" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa n +The maximum number of items to keep in the pool. +As items are returned and the total number of pages in the pool is larger +than the maximum set by this function, +any completely unused pages are released immediately. +If this function is not used to specify a maximum number of items, +the pages will remain associated with the pool until the system runs low +on memory, +at which point the VM system will try to reclaim unused pages. +.El +.Pp +.Fn pool_setlowat +.Bl -tag -offset indent -width "flags" +.It Fa pp +The handle identifying the pool resource instance. +.It Fa n +The minimum number of items to keep in the pool. +The number of pages in the pool will not decrease below the required value to +accommodate the minimum number of items specified by this function. +.El +.Ss SETTING HARD LIMITS +The function +.Fn pool_sethardlimit +sets a hard limit on the pool to +.Fa n +items. +Upon successful completion, a value of 0 is returned. +The value EINVAL is returned when the current size of the pool +already exceeds the requested hard limit. +.Ss POTENTIAL PITFALLS +Note that undefined behaviour results when mixing the storage providing +methods supported by the pool resource routines. +.Pp +The pool resource code uses a per-pool lock to protect its internal state. +If any pool functions are called in an interrupt context, +the caller must block all interrupts that might cause the +code to be reentered. +.Sh CONTEXT +.Fn pool_init , +.Fn pool_destroy , +.Fn pool_prime , +.Fn pool_sethiwat , +.Fn pool_setlowat , +and +.Fn pool_sethardlimit +can be called during autoconf or from process context. +.Pp +.Fn pool_get +and +.Fn pool_put +can be called during autoconf or from process context. +If the pool has been initialised with an interrupt safe pool allocator +they can also be called from interrupt context at or below the +interrupt level specified by a call to +.Fn pool_init . +.Sh RETURN VALUES +.Fn pool_get +will return a pointer to an item allocated from the pool. +If +.Dv PR_NOWAIT +or +.Dv PR_LIMITFAIL +were passed as flags to the pool it may return +.Dv NULL +if there are no resources available or if the pool hard limit has been reached, +respectively. +.Pp +.Fn pool_prime +will return +.Dv ENOMEM +if the requested number of items could not be allocated. +Otherwise, the return value is 0. +.Pp +.Fn pool_sethardlimit +will return +.Dv EINVAL +if the current size of the pool exceeds the requested hard limit. +Otherwise, the return value is 0. +.Sh CODE REFERENCES +The pool manager is implemented in the file +.Pa sys/kern/subr_pool.c . +.Sh SEE ALSO +.Xr free 9 , +.Xr km_alloc 9 , +.Xr malloc 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr spl 9 +.Sh HISTORY +The pool manager first appeared in +.Nx 1.4 +and was ported to +.Ox +by +.An Artur Grabowski Aq Mt art@openbsd.org . diff --git a/static/openbsd/man9/pool_cache_init.9 b/static/openbsd/man9/pool_cache_init.9 new file mode 100644 index 00000000..69536e6d --- /dev/null +++ b/static/openbsd/man9/pool_cache_init.9 @@ -0,0 +1,198 @@ +.\" $OpenBSD: pool_cache_init.9,v 1.8 2018/01/12 04:36:45 deraadt Exp $ +.\" +.\" Copyright (c) 2017 David Gwynne +.\" +.\" 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 12 2018 $ +.Dt POOL_CACHE_INIT 9 +.Os +.Sh NAME +.Nm pool_cache_init , +.Nm pool_cache_destroy +.Nd per CPU caching of pool items +.Sh SYNOPSIS +.In sys/pool.h +.Ft void +.Fn pool_cache_init "struct pool *pp" +.Ft void +.Fn pool_cache_destroy "struct pool *pp" +.Sh DESCRIPTION +By default, pools protect their internal state using a single lock, +so concurrent access to a pool may suffer contention on that lock. +The pool API provides support for caching free pool items on each +CPU which can be enabled to mitigate against this contention. +.Pp +When per CPU caches are enabled on a pool, each CPU maintains an +active and inactive list of free pool items. +A global depot of free lists is initialised in the pool structure +to store excess lists of free items that may accumulate on CPUs. +.Pp +.Fn pool_cache_init +allocates the free lists on each CPU, initialises the global depot +of free lists, and enables their use to handle +.Xr pool_get 9 +and +.Xr pool_put 9 +operations. +.Pp +.Fn pool_cache_destroy +disables the use of the free lists on each CPU, returns items cached +on all the free lists in the subsystem back to the normal pool +allocator, and finally frees the per CPU data structures. +.Pp +Once per CPU caches are enabled, items returned to a pool with +.Xr pool_put 9 +are placed on the current CPU's active free list. +If the active list becomes full, it becomes the inactive list and +a new active list is initialised for the free item to go on. +If an inactive list already exists when the active list becomes +full, the inactive list is moved to the global depot of free lists +before the active list is moved into its place. +.Pp +Attempts to allocate items with +.Xr pool_get 9 +first try to get an item from the active free list on the CPU it is +called on. +If the active free list is empty but an inactive list of items is +available, the inactive list is moved back into place as the active +list so it can satisfy the request. +If no lists are available on the current CPU, an attempt to allocate +a free list from the global depot is made. +Finally, if no free list is available, +.Xr pool_get 9 +falls through to allocating a pool item normally. +.Pp +The maximum number of items cached on a free list is dynamically +scaled for each pool based on the contention on the lock around the +global depot of free lists. +A garbage collector runs periodically to recover idle free lists +and make the memory they consume available to the system for +use elsewhere. +.Pp +Information about the current state of the per CPU caches and +counters of operations they handle are available via +.Xr sysctl 2 , +or displayed in the pcache view in +.Xr systat 1 . +.Pp +The +.Vt kinfo_pool_cache +struct provides information about the global state of a pool's caches +via a node for each pool under the +.Dv CTL_KERN , +.Dv KERN_POOL , +.Dv KERN_POOL_CACHE +.Xr sysctl 2 +MIB hierarchy. +.Bd -literal -offset indent +struct kinfo_pool_cache { + uint64_t pr_ngc; + unsigned int pr_len; + unsigned int pr_nitems; + unsigned int pr_contention; +}; +.Ed +.Pp +.Va pr_ngc +indicates the number of times the garbage collector has recovered +an idle item free list. +.Pp +.Va pr_len +shows the maximum number of items that can be cached on a CPU's +active free list. +.Pp +.Va pr_nitems +shows the number of free items that are currently stored in the +global depot. +.Pp +.Va pr_contention +indicates the number of times that there was contention on the lock +protecting the global depot. +.Pp +The +.Vt kinfo_pool_cache_cpus +struct provides information about the number of times the cache on +a CPU handled certain operations. +These counters may be accessed via a node for each pool under the +.Dv CTL_KERN , +.Dv KERN_POOL , +.Dv KERN_POOL_CACHE_CPUS +.Xr sysctl 2 +MIB hierarchy. +This sysctl returns an array of +.Vt kinfo_pool_cache_cpus +structures sized by the number of CPUs found in the system. +The number of CPUs in the system can be read from the +.Dv CTL_HW , +.Dv HW_NCPUFOUND +sysctl MIB. +.Bd -literal -offset indent +struct kinfo_pool_cache_cpu { + unsigned int pr_cpu; + uint64_t pr_nget; + uint64_t pr_nfail; + uint64_t pr_nput; + uint64_t pr_nlget; + uint64_t pr_nlfail; + uint64_t pr_nlput; +}; +.Ed +.Pp +.Va pr_cpu +indicates which CPU performed the relevant operations. +.Pp +.Va pr_nget +and +.Va pr_nfail +show the number of times the CPU successfully or unsuccessfully handled a +.Xr pool_get 9 +operation respectively. +.Va pr_nput +shows the number of times the CPU handled a +.Xr pool_put 9 +operation. +.Pp +.Va pr_nlget +and +.Va pr_nlfail +show the number of times the CPU successfully or unsuccessfully +requested a list of free items from the global depot. +.Va pr_nlput +shows the number of times the CPU pushed a list of free items to +the global depot. +.Sh CONTEXT +.Fn pool_cache_init +and +.Fn pool_cache_destroy +can be called from process context. +.Sh CODE REFERENCES +The pool implementation is in the file +.Pa sys/kern/subr_pool.c . +.Sh SEE ALSO +.Xr systat 1 , +.Xr sysctl 2 , +.Xr pool_get 9 +.Sh CAVEATS +Because the intention of per CPU pool caches is to avoid having +all CPUs coordinate via shared data structures for handling +.Xr pool_get 9 +and +.Xr pool_put 9 +operations, any limits set on the pool with +.Xr pool_sethardlimit 9 +are ignored. +If limits on the memory used by a pool with per CPU caches enabled +are needed, they must be enforced by a page allocator specified +when a pool is set up with +.Xr pool_init 9 . diff --git a/static/openbsd/man9/ppsratecheck.9 b/static/openbsd/man9/ppsratecheck.9 new file mode 100644 index 00000000..179ca9eb --- /dev/null +++ b/static/openbsd/man9/ppsratecheck.9 @@ -0,0 +1,89 @@ +.\" $OpenBSD: ppsratecheck.9,v 1.7 2020/06/26 18:48:31 cheloha Exp $ +.\" $NetBSD: ppsratecheck.9,v 1.1 2000/08/03 00:09:39 itojun Exp $ +.\" +.\" Copyright (c) 2000 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jun-ichiro itojun Hagino. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 $Mdocdate: June 26 2020 $ +.Dt PPSRATECHECK 9 +.Os +.Sh NAME +.Nm ppsratecheck +.Nd function to help implement rate-limited actions +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn ppsratecheck "struct timeval *lasttime" "int *curpps" "int maxpps" +.Sh DESCRIPTION +The +.Fn ppsratecheck +function provides an easy way to perform packet-per-sec, +or event-per-sec, rate limitation. +The motivation for implementing +.Fn ppsratecheck +was to provide a mechanism that could be used to add rate limitation to +network packet output. +For certain network packets, we may want to impose rate limitation, +to avoid denial-of-service attack possibilities. +.Pp +.Fa maxpps +specifies maximum permitted packets, or events, per second. +If +.Fn ppsratecheck +is called more than +.Fa maxpps +times in a given one second period, +the function will return 0, indicating that we exceeded the limit. +If we are below the limit, the function will return 1. +If +.Fa maxpps +is set to 0, the function will always return 0 +.Pq no packets/events are permitted . +Negative +.Fa maxpps +indicates that rate limitation is disabled, and +.Fn ppsratecheck +will always return 1. +.Pp +.Fa curpps +and +.Fa lasttime +are used to maintain the number of recent calls. +.Fa curpps +will be incremented every time +.Fn ppsratecheck +is called, and will be reset whenever necessary. +.Sh SEE ALSO +.Xr log 9 , +.Xr microtime 9 , +.Xr printf 9 , +.Xr ratecheck 9 +.Sh HISTORY +The +.Fn ppsratecheck +function appeared in +.Nx 1.5 . diff --git a/static/openbsd/man9/printf.9 b/static/openbsd/man9/printf.9 new file mode 100644 index 00000000..22497dde --- /dev/null +++ b/static/openbsd/man9/printf.9 @@ -0,0 +1,255 @@ +.\" $OpenBSD: printf.9,v 1.26 2022/09/11 06:38:11 jmc Exp $ +.\" $NetBSD: kprintf.9,v 1.6 1999/03/16 00:40:47 garbled Exp $ +.\" +.\" Copyright (c) 1998 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jeremy 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 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 $Mdocdate: September 11 2022 $ +.Dt PRINTF 9 +.Os +.Sh NAME +.Nm printf , +.Nm snprintf , +.Nm vprintf , +.Nm vsnprintf , +.Nm uprintf , +.Nm ttyprintf , +.Nm db_printf , +.Nm db_vprintf +.Nd kernel formatted output conversion +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft int +.Fo printf +.Fa "const char *format" +.Fa "..." +.Fc +.Ft int +.Fo snprintf +.Fa "char *buf" +.Fa "size_t size" +.Fa "const char *format" +.Fa "..." +.Fc +.Ft int +.Fo vprintf +.Fa "const char *format" +.Fa "va_list ap" +.Fc +.Ft int +.Fo vsnprintf +.Fa "char *buf" +.Fa "size_t size" +.Fa "const char *fmt" +.Fa "va_list ap" +.Fc +.Ft void +.Fo uprintf +.Fa "const char *format" +.Fa "..." +.Fc +.Ft void +.Fo ttyprintf +.Fa "struct tty *tty" +.Fa "const char *format" +.Fa "..." +.Fc +.In ddb/db_output.h +.Ft void +.Fn db_printf "const char *format" ... +.Ft void +.Fn db_vprintf "const char *format" "va_list ap" +.Sh DESCRIPTION +The +.Fn printf , +.Fn snprintf , +.Fn vprintf , +.Fn vsnprintf , +.Fn uprintf , +.Fn ttyprintf , +.Fn db_printf , +and +.Fn db_vprintf +functions allow the kernel to send formatted messages to various output +devices. +The functions +.Fn printf +and +.Fn vprintf +send formatted strings to the system console and to the system log. +The functions +.Fn uprintf +and +.Fn ttyprintf +send formatted strings to the current process's controlling tty and a specific +tty, +respectively. +The functions +.Fn db_printf +and +.Fn db_vprintf +send formatted strings to the ddb console, and are only used to implement +.Xr ddb 4 . +.Pp +Since each of these kernel functions is a variant of its user space +counterpart, this page describes only the differences between the user +space and kernel versions. +.Pp +Only a subset of the user space conversion specification is available to the +kernel version: +.Bd -filled -offset indent +.Sm off +.Cm % +.Op Ar width +.Op Ar size +.Ar conversion +.Sm on +.Ed +.Pp +Refer to +.Xr printf 3 +for functional details. +.Ss FORMAT OPTIONS +The kernel functions don't support as many formatting specifiers as their +user space counterparts. +In addition to the floating point formatting specifiers, +the following integer type specifiers are not supported: +.Bl -tag -width 5n +.It Li %hh +Argument of +.Vt char +type. +This format specifier is accepted by the kernel but will be handled as +.Li %h . +.It Li %j +Argument of +.Vt intmax_t +or +.Vt uintmax_t +type. +.It Li %t +Argument of +.Vt ptrdiff_t +type. +.El +.Pp +The kernel functions support some additional formatting specifiers: +.Bl -tag -width 5n +.It Li %b +Bit field expansion. +This format specifier is useful for decoding bit fields in device registers. +It displays an integer using a specified radix +.Pq base +and an interpretation of +the bits within that integer as though they were flags. +It requires two arguments from the argument vector, the first argument being +the bit field to be decoded +(of type +.Vt int , +unless a width modifier has been specified) +and the second being a decoding directive string. +.Pp +The decoding directive string describes how the bitfield is to be interpreted +and displayed. +The first character of the string is a binary character representation of the +output numeral base in which the bitfield will be printed before it is decoded. +Recognized radix values +.Pq "in C escape-character format" +are +.Li \e10 +.Pq octal , +.Li \e12 +.Pq decimal , +and +.Li \e20 +.Pq hexadecimal . +.Pp +The remaining characters in the decoding directive string are interpreted as a +list of bit-position\(endescription pairs. +A bit-position\(endescription pair begins with a binary character value +that represents the position of the bit being described. +A bit position value of one describes the least significant bit. +Whereas a position value of 32 +.Pq "octal 40, hexadecimal 20, the ASCII space character" +describes the most significant bit. +.Pp +To deal with more than 32 bits, the characters 128 +.Pq "octal 200, hexadecimal 80" +through 255 +.Pq "octal 377, hexadecimal FF" +are used. +The value 127 is subtracted from the character to determine the +bit position (1 is least significant, and 128 is most significant). +.Pp +The remaining characters in a bit-position\(endescription pair are the +characters to print should the bit being described be set. +Description strings are delimited by the next bit position value character +encountered +.Po +distinguishable by its value being \*(Le 32 or \*(Ge 128 +.Pc , +or the end of the decoding directive string itself. +.El +.Sh RETURN VALUES +The +.Fn printf +and +.Fn vprintf +functions return the number of characters printed. +.Pp +The +.Fn snprintf +and +.Fn vsnprintf +functions return the number of characters that would have been put into +the buffer +.Fa buf +if the +.Fa size +were unlimited. +.Sh EXAMPLES +Use of the +.Li %b +format specifier for decoding device registers. +.Bd -literal -offset indent +printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE") +\(rA "reg=3" + +printf("enablereg=%b\en", 0xe860, + "\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO" + "\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE" + "\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE") +\(rA "enablereg=e860" +.Ed +.Sh CODE REFERENCES +.Pa sys/kern/subr_prf.c +.Sh SEE ALSO +.Xr revoke 2 , +.Xr printf 3 , +.Xr ddb 4 , +.Xr log 9 diff --git a/static/openbsd/man9/psignal.9 b/static/openbsd/man9/psignal.9 new file mode 100644 index 00000000..254fe3ee --- /dev/null +++ b/static/openbsd/man9/psignal.9 @@ -0,0 +1,125 @@ +.\" $OpenBSD: psignal.9,v 1.8 2022/03/31 17:27:23 naddy Exp $ +.\" $NetBSD: psignal.9,v 1.5 1999/03/16 00:40:47 garbled 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 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 $Mdocdate: March 31 2022 $ +.Dt PSIGNAL 9 +.Os +.Sh NAME +.Nm psignal , +.Nm pgsignal , +.Nm pgsigio +.Nd post signal to a process +.Sh SYNOPSIS +.Ft void +.Fn psignal "struct proc *p" "int signum" +.Ft void +.Fn pgsignal "struct pgrp *pgrp" "int signum" "int checkctty" +.Ft void +.Fn pgsigio "struct sigio_ref *sir" "int sigum" "int checkctty" +.Sh DESCRIPTION +These functions post a signal to 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 psignal +function posts signal number +.Fa signum +to the process represented by the process structure +.Fa p . +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 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 +.Pq see Xr sigaction 2 , +the process is stopped without awakening it. +.It +.Dv SIGCONT +restarts a stopped process +.Pq or puts them back to sleep +regardless of the signal action +.Pq e.g., blocked or ignored . +.El +.Pp +If the target process is being traced, +.Fn 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. +If +.Fa pgrp +is +.Dv NULL , +no action is taken. +.Pp +The +.Fn pgsigio +function posts signal number +.Fa signum +to the process or each member of the process group indicated by reference +.Fa sir . +If +.Fa checkctty +is non-zero, the signal will be posted only to processes that have +a controlling terminal. +.Sh CODE REFERENCES +These functions are implemented in the file +.Pa sys/kern/kern_sig.c . +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigio_setown 9 , +.Xr tsleep 9 diff --git a/static/openbsd/man9/radio.9 b/static/openbsd/man9/radio.9 new file mode 100644 index 00000000..c70fd5ce --- /dev/null +++ b/static/openbsd/man9/radio.9 @@ -0,0 +1,118 @@ +.\" $OpenBSD: radio.9,v 1.12 2022/03/30 19:03:21 miod Exp $ +.\" $RuOBSD: radio.9,v 1.3 2001/10/26 05:38:44 form Exp $ +.\" +.\" Copyright (c) Maxim Tsyplakov +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list 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 $Mdocdate: March 30 2022 $ +.Dt RADIO 9 +.Os +.Sh NAME +.Nm radio +.Nd interface between low and high level radio drivers +.Sh DESCRIPTION +The radio device driver is divided into a high level, +hardware independent layer, and a low level hardware +dependent layer. +The interface between these is the +.Va radio_hw_if +structure. +.Bd -literal +struct radio_hw_if { + int (*open)(void *, int, int, struct proc *); + int (*close)(void *, int, int, struct proc *); + int (*get_info)(void *, struct radio_info *); + int (*set_info)(void *, struct radio_info *); + int (*search)(void *, int); +}; +.Ed +.Pp +The high level radio driver attaches to the low level driver +when the latter calls +.Va radio_attach_mi . +This call should be +.Bd -literal +.Ft void +.Fn radio_attach_mi "const struct radio_hw_if *rhwp" "void *hdlp" \ + "struct device * dev" +.Ed +.Pp +The +.Va radio_hw_if +struct is as shown above. +The +.Va hdlp +argument is a handle to some low level data structure. +It is sent as the first argument to all the functions in +.Va radio_hw_if +when the high level driver calls them. +.Va dev +is the device struct for the hardware device. +.Pp +The fields of +.Va radio_hw_if +are described in some more detail below. +.Bd -literal +.Ft int +.Fn open "void *" "int flags" "int fmt" "struct proc *p" + Optional. + Is called when the radio device is opened. + Returns 0 on success, otherwise an error code. + +.Ft int +.Fn close "void *" "int flags" "int fmt" "struct proc *p" + Optional. + Is called when the radio device is closed. + Returns 0 on success, otherwise an error code. + +.Ft int +.Fn get_info "void *" "struct radio_info *" + Fill the radio_info struct. + Returns 0 on success, otherwise an error code. + +.Ft int +.Fn set_info "void *" "struct radio_info *" + Set values from the radio_info struct. + Returns 0 on success, otherwise an error code. + +.Ft int +.Fn search "void *" "int" + Returns 0 on success, otherwise an error code. +.Ed +.Sh SEE ALSO +.Xr radio 4 +.Sh HISTORY +The +.Nm +device driver appeared in +.Ox 3.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was written by +.An Vladimir Popov Aq Mt jumbo@narod.ru +and +.An Maxim Tsyplakov Aq Mt tm@oganer.net . +The man page was written by +.An Maxim Tsyplakov Aq Mt tm@oganer.net . diff --git a/static/openbsd/man9/rasops.9 b/static/openbsd/man9/rasops.9 new file mode 100644 index 00000000..0b96169d --- /dev/null +++ b/static/openbsd/man9/rasops.9 @@ -0,0 +1,239 @@ +.\" $OpenBSD: rasops.9,v 1.18 2017/08/21 11:49:50 fcambus Exp $ +.\" $NetBSD: rasops.9,v 1.4 2002/02/13 08:18:50 ross Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 $Mdocdate: August 21 2017 $ +.Dt RASOPS 9 +.Os +.Sh NAME +.Nm rasops , +.Nm rasops_init , +.Nm rasops_reconfig +.Nd raster display operations +.Sh SYNOPSIS +.In dev/wscons/wsdisplayvar.h +.In dev/rasops/rasops.h +.Ft int +.Fn rasops_init "struct rasops_info *ri" "int wantrows" "int wantcols" +.Ft int +.Fn rasops_reconfig "struct rasops_info *ri" "int wantrows" "int wantcols" +.Sh DESCRIPTION +The +.Nm +subsystem is a set of raster operations for +.Xr wscons 4 . +.Pp +The primary data type for using the raster operations is the +.Em rasops_info +structure in +.Pa dev/rasops/rasops.h : +.Bd -literal +struct rasops_info { + + /* + * These must be filled in by the caller + */ + int ri_depth; /* depth in bits */ + u_char *ri_bits; /* ptr to bits */ + int ri_width; /* width (pels) */ + int ri_height; /* height (pels) */ + int ri_stride; /* stride in bytes */ + + /* + * These can optionally be left zeroed out. If you fill ri_font, + * but aren't using wsfont, set ri_wsfcookie to -1. + */ + struct wsdisplay_font *ri_font; + int ri_wsfcookie; /* wsfont cookie */ + void *ri_hw; /* driver private data */ + struct wsdisplay_charcell *ri_bs; /* character backing store */ + int ri_crow; /* cursor row */ + int ri_ccol; /* cursor column */ + int ri_flg; /* various operational flags */ + + /* + * These are optional and will default if zero. Meaningless + * on depths other than 15, 16, 24 and 32 bits per pel. On + * 24 bit displays, ri_{r,g,b}num must be 8. + */ + u_char ri_rnum; /* number of bits for red */ + u_char ri_gnum; /* number of bits for green */ + u_char ri_bnum; /* number of bits for blue */ + u_char ri_rpos; /* which bit red starts at */ + u_char ri_gpos; /* which bit green starts at */ + u_char ri_bpos; /* which bit blue starts at */ + + /* + * These are filled in by rasops_init() + */ + int ri_emuwidth; /* width we actually care about */ + int ri_emuheight; /* height we actually care about */ + int ri_emustride; /* bytes per row we actually care about */ + int ri_rows; /* number of rows (characters) */ + int ri_cols; /* number of columns (characters) */ + int ri_delta; /* row delta in bytes */ + int ri_pelbytes; /* bytes per pel (may be zero) */ + int ri_fontscale; /* fontheight * fontstride */ + int ri_xscale; /* fontwidth * pelbytes */ + int ri_yscale; /* fontheight * stride */ + u_char *ri_origbits; /* where screen bits actually start */ + int ri_xorigin; /* where ri_bits begins (x) */ + int ri_yorigin; /* where ri_bits begins (y) */ + int32_t ri_devcmap[16]; /* color -\*[Gt] framebuffer data */ + + /* + * The emulops you need to use, and the screen caps for wscons + */ + struct wsdisplay_emulops ri_ops; + int ri_caps; + + /* + * Callbacks so we can share some code + */ + void (*ri_do_cursor)(struct rasops_info *); + void (*ri_updatecursor)(struct rasops_info *); + +#if NRASOPS_ROTATION > 0 + /* Used to intercept putchar to permit display rotation */ + struct wsdisplay_emulops ri_real_ops; +#endif +}; +.Ed +.Pp +The value of the +.Em ri_flg +member is formed by OR'ing the following values: +.Pp +.Bl -tag -offset indent -width RI_CLEARMARGINS -compact +.It RI_FULLCLEAR +Force eraserows() to clear the whole screen instead of only text lines, +when invoked with an +.Em nrows +parameter equal to the number of text lines. +.It RI_FORCEMONO +Do not output coloured text, even if the display supports it. +.It RI_BSWAP +Specifies that the frame buffer endianness is different from the CPU's. +.It RI_CURSOR +Set when the text cursor is enabled. +.It RI_CLEAR +Clear the display upon initialization. +.It RI_CLEARMARGINS +Clear display margins upon initialization. +.It RI_CENTER +Center the text area. +.\" Only honoured if option RASOPS_CLIPPING which we don't use. +.\" .It RI_CURSORCLIP +.\" Cursor is currently clipped +.It RI_ROTATE_CW +Rotate the text display quarter clockwise. +.It RI_ROTATE_CCW +Rotate the text display quarter counter-clockwise. +.It RI_CFGDONE +.Fn rasops_reconfig +completed successfully +.It RI_VCONS +Support the use of multiple screens. +.It RI_WRONLY +Do not read back pixels from the frame buffer memory when performing +screen-to-screen copy operations. +This flag is ignored unless +.Dv RI_VCONS +is set or the +.Em ri_bs +member is set. +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn rasops_init "ri" "wantrows" "wantcols" +Initialise a +.Em rasops_info +descriptor. +The arguments +.Fa wantrows +and +.Fa wantcols +are the number of rows and columns we'd like. +In terms of +optimization, fonts that are a multiple of 8 pixels wide work the +best. +.It Fn rasops_reconfig "ri" "wantrows" "wantcols" +Reconfigure a +.Em rasops_info +descriptor because parameters have changed in some way. +The arguments +.Fa wantrows +and +.Fa wantcols +are the number of rows and columns we'd like. +If calling +.Fn rasops_reconfig +to change the font and ri_wsfcookie \*[Ge] 0, you must call +.Fn wsfont_unlock +on it, and reset it to -1 (or a new, valid cookie). +.El +.Sh CODE REFERENCES +This section describes places within the +.Ox +source tree where actual code implementing or utilising the rasops +subsystem can be found. +All pathnames are relative to +.Pa /usr/src . +.Pp +The rasops subsystem is implemented within the directory +.Pa sys/dev/rasops . +The +.Nm +module itself is implemented within the file +.Pa sys/dev/rasops/rasops.c . +.Sh SEE ALSO +.Xr intro 9 +.\" XXX These don't exist yet +.\" .Xr wscons 9 , +.\" .Xr wsdisplay 9 , +.\" .Xr wsfont 9 +.Sh HISTORY +The +.Nm +subsystem appeared in +.Nx 1.5 +and +.Ox +first support appeared in +.Ox 2.9 . +.Sh AUTHORS +.An -nosplit +The +.Nm +subsystem was written by +.An Andrew Doran Aq Mt ad@NetBSD.org . +Display rotation was written by +.An Christopher Pascoe Aq Mt pascoe@openbsd.org . +.Sh CAVEATS +Display rotation only works for 16bpp displays. diff --git a/static/openbsd/man9/ratecheck.9 b/static/openbsd/man9/ratecheck.9 new file mode 100644 index 00000000..77639bd8 --- /dev/null +++ b/static/openbsd/man9/ratecheck.9 @@ -0,0 +1,138 @@ +.\" $OpenBSD: ratecheck.9,v 1.13 2020/06/26 18:48:31 cheloha Exp $ +.\" $NetBSD: ratecheck.9,v 1.1.2.1 2000/02/18 20:26:43 he Exp $ +.\" +.\" Copyright (c) 2000 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 $Mdocdate: June 26 2020 $ +.Dt RATECHECK 9 +.Os +.Sh NAME +.Nm ratecheck +.Nd function to help implement rate-limited actions +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn ratecheck "struct timeval *lasttime" "const struct timeval *mininterval" +.Sh DESCRIPTION +The +.Fn ratecheck +function provides a simple time interval check which can be used +when implementing time-based rate-limited actions. +If the difference between the current monotonically-increasing +system time +.Pq Xr getmicrouptime 9 +and +.Fa lasttime +is less than the value given by the +.Fa mininterval +argument, zero is returned. +Otherwise, +.Fa lasttime +is set to the current time and a non-zero value is returned. +.Pp +The motivation for implementing +.Fn ratecheck +was to provide a mechanism that could be used to add rate limiting to +diagnostic message output. +If printed too often, diagnostic messages can +keep the system from doing useful work. +If the repeated messages can be caused by deliberate user action or +network events, they can be exploited to cause denial of system service. +.Pp +Note that using a very short time interval (less than a second) +for +.Fa mininterval +defeats the purpose of this function. +(It doesn't +take much to flood a 9600 baud serial console with output, for instance.) +.Sh EXAMPLES +Here is a simple example of use of the +.Fn ratecheck +function: +.Bd -literal +/* + * The following variables could be global, in a device softc, etc., + * depending on the exact usage. + */ +struct timeval drv_lasterr1time; /* time of last err1 message */ +long drv_err1count; /* # of err1 errs since last msg */ +struct timeval drv_lasterr2time; /* time of last err2 message */ +long drv_err2count; /* # of err2 errs since last msg */ + +/* + * The following variable will often be global or shared by all + * instances of a driver. It should be initialized, so it can be + * patched. Allowing it to be set via an option might be nice, + * but could lead to an insane proliferation of options. + */ +struct timeval drv_errinterval = { 5, 0 }; /* 5 seconds */ + +/* error handling/reporting function */ +void +drv_errhandler(int err1, int err2) +{ + + /* + * Note that you should NOT use the same last-event + * time variable for dissimilar messages! + */ + if (err1) { + /* handle err1 condition */ + ... + + drv_err1count++; + if (ratecheck(&drv_lasterr1time, + &drv_errinterval)) { + printf("drv: %ld err1 errors occurred", + drv_err1count); + drv_err1count = 0; + } + } + if (err2) { + /* handle err2 condition */ + ... + + drv_err2count++; + if (ratecheck(&drv_lasterr2time, + &drv_errinterval)) { + printf("drv: %ld err2 errors occurred", + drv_err2count); + drv_err2count = 0; + } + } +} +.Ed +.Sh SEE ALSO +.Xr log 9 , +.Xr microtime 9 , +.Xr printf 9 +.Sh HISTORY +The +.Fn ratecheck +function first appeared in +.Nx 1.5 . diff --git a/static/openbsd/man9/refcnt_init.9 b/static/openbsd/man9/refcnt_init.9 new file mode 100644 index 00000000..f1ab2fcc --- /dev/null +++ b/static/openbsd/man9/refcnt_init.9 @@ -0,0 +1,131 @@ +.\" $OpenBSD: refcnt_init.9,v 1.8 2025/08/05 12:52:20 bluhm Exp $ +.\" +.\" Copyright (c) 2015 David Gwynne +.\" +.\" 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: August 5 2025 $ +.Dt REFCNT_INIT 9 +.Os +.Sh NAME +.Nm refcnt_init , +.Nm refcnt_init_trace , +.Nm refcnt_take , +.Nm refcnt_rele , +.Nm refcnt_rele_wake , +.Nm refcnt_finalize , +.Nm refcnt_shared , +.Nm refcnt_read , +.Nm REFCNT_INITIALIZER +.Nd reference count API +.Sh SYNOPSIS +.In sys/refcnt.h +.Ft void +.Fn "refcnt_init" "struct refcnt *r" +.Ft void +.Fn "refcnt_init_trace" "struct refcnt *r" "int trace" +.Ft void +.Fn "refcnt_take" "struct refcnt *r" +.Ft int +.Fn "refcnt_rele" "struct refcnt *r" +.Ft void +.Fn "refcnt_rele_wake" "struct refcnt *r" +.Ft void +.Fn "refcnt_finalize" "struct refcnt *r" "const char *wmesg" +.Ft int +.Fn "refcnt_shared" "const struct refcnt *r" +.Ft unsigned int +.Fn "refcnt_read" "const struct refcnt *r" +.Fn "REFCNT_INITIALIZER" +.Sh DESCRIPTION +The refcnt API provides simple reference counters that can be used +to manage the lifetime of a shared object. +.Pp +.Fn refcnt_init +sets the initial value of the counter to 1 to account for the caller's +reference to the object. +.Fn refcnt_init_trace +additionally accepts a +.Xr dt 4 +static probe index. +.Pp +.Fn refcnt_take +is used to acquire a new reference. +It is the responsibility of the caller to guarantee that it holds +a valid reference before taking a new reference. +.Pp +.Fn refcnt_rele +is used to release an existing reference. +.Pp +.Fn refcnt_rele_wake +is used to release an existing reference and wakes up a process +that is currently waiting in +.Fn refcnt_finalize +for all the references to be released. +.Pp +.Fn refcnt_finalize +releases the caller's reference and sleeps until all the other +references to the relevant object have been released. +There may only be one caller to +.Fn refcnt_finalize +per refcnt +.Fa r . +.Pp +.Fn refcnt_rele , +.Fn refcnt_rele_wake +and +.Fn refcnt_finalize +order prior memory loads and stores before the release of the reference. +The functions enforce control dependency so that after the final reference +has been released, subsequent loads and stores happen after the release. +These ensure that concurrent accesses cease before the object's destructor +runs and that the destructor sees all updates done during the lifetime +of the object. +.Pp +.Fn refcnt_shared +tests if the object has multiple references. +.Pp +.Fn refcnt_read +returns a snapshot of the counter value. +Its use is discouraged, +code should use +.Fn refcnt_shared +whenever possible. +.Pp +.Fn REFCNT_INITIALIZER +initialises a declaration of a refcnt to 1. +.Sh CONTEXT +.Fn refcnt_init , +.Fn refcnt_init_trace , +.Fn refcnt_take , +.Fn refcnt_rele , +.Fn refcnt_rele_wake , +.Fn refcnt_shared +and +.Fn refcnt_read +can be called during autoconf, from process context, or from interrupt +context. +.Pp +.Fn refcnt_finalize +can be called from process context. +.Sh RETURN VALUES +.Fn refcnt_rele +returns a non-zero value if the last reference has been released, +otherwise 0. +.Pp +.Fn refcnt_shared +returns a non-zero value if the object has multiple references, +otherwise 0. +.Pp +.Fn refcnt_read +returns a snapshot of the counter value. diff --git a/static/openbsd/man9/resettodr.9 b/static/openbsd/man9/resettodr.9 new file mode 100644 index 00000000..59bd71d9 --- /dev/null +++ b/static/openbsd/man9/resettodr.9 @@ -0,0 +1,50 @@ +.\" $OpenBSD: resettodr.9,v 1.8 2020/06/26 18:48:31 cheloha Exp $ +.\" $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 $Mdocdate: June 26 2020 $ +.Dt RESETTODR 9 +.Os +.Sh NAME +.Nm resettodr +.Nd set battery-backed clock from system time +.Sh SYNOPSIS +.Ft void +.Fn resettodr "void" +.Sh DESCRIPTION +The +.Fn resettodr +function sets the system's battery backed clock to a value based on the +output of a function such as +.Xr microtime 9 . +.Sh SEE ALSO +.Xr inittodr 9 , +.Xr microtime 9 diff --git a/static/openbsd/man9/route.9 b/static/openbsd/man9/route.9 new file mode 100644 index 00000000..6976dd5f --- /dev/null +++ b/static/openbsd/man9/route.9 @@ -0,0 +1,103 @@ +.\" $OpenBSD: route.9,v 1.17 2017/01/11 15:09:52 rzalamena Exp $ +.\" +.\" Copyright (c) 2011 Bret S. Lambert +.\" 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 $Mdocdate: January 11 2017 $ +.Dt RT_SETGATE 9 +.Os +.Sh NAME +.Nm rt_setgate , +.Nm rtredirect , +.Nm rtdeletemsg +.Nd kernel routing interface +.Sh SYNOPSIS +.In net/route.h +.Ft int +.Fn rt_setgate "struct rtentry *rt" "struct sockaddr *gate" "u_int tableid" +.Ft void +.Fn rtredirect "struct sockaddr *dst" "struct sockaddr *gateway" \ +"struct sockaddr *src" "struct rtentry **rtp" "unsigned int rdomain" +.Ft int +.Fn rtdeletemsg "struct rtentry *rt" "struct ifnet *ifp" "u_int tableid" +.Sh DESCRIPTION +Routing entries describe the routes to be taken by packets in a router. +.Bl -tag -width Ds +.It Fn rt_setgate "struct rtentry *rt" "struct sockaddr *gate" "u_int tableid" +Set the address of the gateway for routes described by +.Fa rt +to +.Fa gate . +If memory must be allocated to hold the gateway address, +the address for which +.Fa rt +describes routes will be copied from +.Fa gate . +.It Fn rtredirect "struct sockaddr *dst" "struct sockaddr *gateway" \ +"struct sockaddr *src" "struct rtentry **rtp" "unsigned int rdomain" +Redirect routes to +.Fa dst +through +.Fa gateway , +such as in response to an ICMP redirect message. +.Fa src +should be the address from which the redirect message was received. +If +.Fa rtp +is not NULL, +it will be populated by the routing entry corresponding to +.Fa dst . +.It Fn rtdeletemsg "struct rtentry *rt" "struct ifnet *ifp" "u_int tableid" +Delete routing table entry +.Fa rt +from table +.Fa tableid +and forward a notification message to all +.Fa AF_ROUTE +sockets. +.El +.Sh RETURN VALUES +.Fn rt_setgate +may fail with: +.Pp +.Bl -tag -width Er -compact +.It Bq Er ENOBUFS +Memory could not be allocated for the gateway. +.El +.Pp +.Fn rtdeletemsg +may fail with: +.Pp +.Bl -tag -width Er -compact +.It Bq Er EAFNOSUPPORT +The protocol used by +.Fa rt +is not supported by table with ID +.Fa tableid . +.It Bq Er ESRCH +No routing entry for +.Fa rt +could be found. +.It Bq Er ESRCH +.Fa rt +is a multipath routing entry that conflicts with an existing one. +.El +.Sh SEE ALSO +.Xr route 4 , +.Xr route 8 , +.Xr rt_timer_add 9 , +.Xr rtable_add 9 , +.Xr rtlabel_id2name 9 , +.Xr rtrequest 9 diff --git a/static/openbsd/man9/rssadapt.9 b/static/openbsd/man9/rssadapt.9 new file mode 100644 index 00000000..db928597 --- /dev/null +++ b/static/openbsd/man9/rssadapt.9 @@ -0,0 +1,418 @@ +.\" $OpenBSD: rssadapt.9,v 1.8 2015/02/16 16:38:54 naddy Exp $ +.\" $NetBSD: rssadapt.9,v 1.4 2004/12/08 18:35:56 peter Exp $ +.\" +.\" Copyright (c) 2004 David Young. All rights reserved. +.\" +.\" This code is by David Young. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must 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 David Young may not be used to endorse or promote +.\" products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY David Young ``AS IS'' AND ANY +.\" EXPRESS OR 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 +.\" Young BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, +.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED +.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: February 16 2015 $ +.Dt RSSADAPT 9 +.Os +.Sh NAME +.Nm rssadapt , +.Nm ieee80211_rssadapt_choose , +.Nm ieee80211_rssadapt_input , +.Nm ieee80211_rssadapt_lower_rate , +.Nm ieee80211_rssadapt_raise_rate , +.Nm ieee80211_rssadapt_updatestats +.Nd rate adaptation based on received signal strength +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_rssadapt.h +.Ft void +.Fn ieee80211_rssadapt_input "struct ieee80211com *ic" \ +"st construct ieee80211_node *ni" "struct ieee80211_rssadapt *ra" "int rssi" +.Ft void +.Fn ieee80211_rssadapt_lower_rate "struct ieee80211com *ic" \ +"const struct ieee80211_node *ni" "struct ieee80211_rssadapt *ra" \ +"const struct ieee80211_rssdesc *id" +.Ft void +.Fn ieee80211_rssadapt_raise_rate "struct ieee80211com *ic" \ +"struct ieee80211_rssadapt *ra" "const struct ieee80211_rssdesc *id" +.Ft void +.Fn ieee80211_rssadapt_updatestats "struct ieee80211_rssadapt *ra" +.Ft int +.Fn ieee80211_rssadapt_choose "struct ieee80211_rssadapt *ra" \ +"const struct ieee80211_rateset *rs" "const struct ieee80211_frame *wh" \ +"u_int len" "int fixed_rate" "const char *dvname" "int do_not_adapt" +.Sh DESCRIPTION +The +.Nm +module provides rapid adaptation of transmission data rate to 802.11 +device drivers based on received-signal strength +.Pq RSS . +A driver needs only to provide +.Nm +with indications of RSS and failure/success of transmissions for +each 802.11 client or peer. +For each transmit packet, +.Nm +chooses the transmission data rate that offers the best expected +throughput, given the packet's length and destination. +.Pp +.Nm +models an 802.11 channel very simply +.Po +see also the +.Sx BUGS +section +.Pc . +It assumes that the packet-error rate +.Pq PER +is determined by the signal-to-noise ratio +.Pq S/N +at the receiver, the transmission data rate, and the packet length. +The S/N determines the choice of data rate that yields the lowest +PER for all packets of a certain length. +.Sh FUNCTIONS +.Bl -tag -width Ds -compact +.It Fn ieee80211_rssadapt_choose "ra" "rs" "wh" "len" "fixed_rate" "dvname" \ +"do_not_adapt" +.Pp +Choose the transmission data rate for a packet. +.Pp +.Bl -tag -width "do_not_adapt" -compact +.It Fa ra +Ordinarily, the +.Nm +state object belonging to the node which is the packet destination. +However, if the destination is a broadcast/multicast address, then +.Fa ra +belongs to the BSS node, +.Va ic->ic_bss . +.It Fa rs +A list of eligible data rates for the node; for example, the +rates negotiated when the node associated with the network. +.It Fa len +The packet length in bytes, including the 802.11 header and +frame check sequence +.Pq FCS . +.It Fa fixed_rate +If the operator has set the data rate using, for example, +.Ic "ifconfig wi0 media ds1" , +then +.Fa fixed_rate +tells the index of that rate in +.Fa rs . +.Nm +obeys a fixed data rate whenever the 802.11 standard allows it: +sometimes the standard requires multicast/broadcast packets to be +transmitted at a so-called +.Dq basic rate . +.It Fa dvname +The device driver uses +.Fa dvname +to indicate the name of the +interface for the purpose of diagnostic and debug messages. +The driver sets +.Fa dvname +to +.Dv NULL +when no messages are desired. +.It Fa do_not_adapt +If +.Fa do_not_adapt +is non-zero, then +.Fn ieee80211_rssadapt_choose +will choose the highest rate in +.Fa rs +that suits the destination, regardless of the RSS. +.El +The return value of +.Fn ieee80211_rssadapt_choose +is an index into +.Fa rs , +indicating its choice of transmit data rate. +.Pp +.It Fn ieee80211_rssadapt_input "ic" "ni" "ra" "rssi" +The RSS serves as a rough estimate of the S/N at each node. +A driver provides RSS updates using +.Fn ieee80211_rssadapt_input , +whose arguments are: +.Pp +.Bl -tag -width "rssi" -compact +.It Fa ic +The wireless interface's 802.11 state object. +.It Fa ni +The 802.11 node whose RSS the driver is updating. +.It Fa ra +The node's +.Nm +state object. +.It Fa rssi +The node's received signal strength indication. +The range of +.Fa rssi +is from 0 to 255. +.El +.Pp +.It Fn ieee80211_rssadapt_lower_rate "ic" "ni" "ra" "id" +.It Fn ieee80211_rssadapt_raise_rate "ic" "ra" "id" +Drivers call +.Fn ieee80211_rssadapt_raise_rate +and +.Fn ieee80211_rssadapt_lower_rate +to indicate transmit successes and failures, respectively. +.Pp +.Bl -tag -width Ds -compact +.It Fa ic +The 802.11 state object. +.It Fa ni +The neighbor to whom the driver transmitted. +.It Fa ra +The neighbor's +.Nm +state object. +.It Fa id +Displays statistics on the transmission attempt. +.El +.Pp +.It Fn ieee80211_rssadapt_updatestats "ra" +An 802.11 node is eligible for its RSS thresholds to decay every +1/10 to 10 seconds. +It is eligible more often (every 1/10 second) at high packet rates, +and less often (every 10 seconds) at low packet rates. +A driver assists +.Nm +in tracking the exponential-average packet rate by calling +.Fn ieee80211_rssadapt_updatestats +every 1/10th second for each node's +.Vt ieee80211_rssadapt +object. +.Pp +.Bl -tag -width Ds -compact +.It Fa ra +The neighbor's +.Nm +state object. +.El +.El +.Sh ALGORITHM +.Nm +monitors the RSS from neighboring 802.11 nodes, recording the +exponential average RSS in each neighbor's +.Vt ieee80211_rssadapt +structure. +.Nm +uses transmit success/failure feedback from the +device driver to fill a table of RSS thresholds. +The table is indexed by packet size, +.Va L , +and a data rate, +.Va R , +to find out the minimum exponential-average RSS that a node must show before +.Nm +will indicate that a packet +.Va L +bytes long can be transmitted R bits per second with optimal expected +throughput. +.Pp +When the driver indicates a unicast packet is transmitted unsuccessfully +.Po +that is, the NIC received no ACK for the packet +.Pc , +.Nm +will move the corresponding RSS threshold toward the exponential +average RSSI at the time of transmission. +Thus several consecutive transmit failures for the same +.Ao +.Va L , +.Va R +.Ac +tuple will ensure that the RSS threshold rises high enough that +rate +.Va R +is abandoned for packets +.Va L +bytes long. +When the driver indicates a successful transmission, +the RSS threshold corresponding to the same packet length, but the +next higher data rate, is lowered slightly. +The RSS threshold is said to +.Dq decay . +This ensures that occasionally +.Nm +indicates the driver should try the next higher data rate, +just in case conditions at the receiver have changed +.Po +for example, noise levels have fallen +.Pc +and a higher data rate can be supported at the same RSS level. +.Pp +The rate of decay is controlled. +In an interval of 1/10th second +to 10 seconds, only one RSS threshold per neighbor may decay. +The interval is connected to the exponential-average rate that packets +are being transmitted. +At high packet rates, the interval is shortest. +It is longest at low packet rates. +The rationale for this is that RSS thresholds should not decay +rapidly if there is no information from packet transmissions to +counteract their decay. +.Sh DATA STRUCTURES +An +.Vt ieee80211_rssdesc +describes a transmission attempt. +.Bd -literal -offset indent +struct ieee80211_rssdesc { + u_int id_len; + u_int id_rateidx; + struct ieee80211_node *id_node; + u_int8_t id_rssi; +}; +.Ed +.Pp +.Fa id_len +is the length, in bytes, of the transmitted packet. +.Fa id_node +points to the neighbor's +.Vt ieee8021_node , +and +.Fa id_rssi +is the exponential-average RSS at the time the packet was +transmitted. +.Fa id_rateidx +is an index into the destination neighbor's rate-set, +.Fa id_node->ni_rates , +indicating the transmit data rate for the packet. +.Pp +.Vt ieee80211_rssadapt +contains the rate-adaptation state for a neighboring 802.11 node. +Ordinarily a driver will +.Dq subclass +.Vt ieee80211_node . +The +.Vt ieee80211_rssadapt +structure will be a subclass member. +In this way, every node's +.Nm +condition is independently tracked and stored in its node object. +.Bd -literal -offset 4n +struct ieee80211_rssadapt { + u_int16_t ra_avg_rssi; + u_int32_t ra_nfail; + u_int32_t ra_nok; + u_int32_t ra_pktrate; + u_int16_t ra_rate_thresh[IEEE80211_RSSADAPT_BKTS] + [IEEE80211_RATE_SIZE]; + struct timeval ra_last_raise; + struct timeval ra_raise_interval; +}; +.Ed +.Pp +.Fa ra_avg_rssi +is the exponential-average RSS, shifted left 8 bits. +.Fa ra_nfail +indicates the number of transmit failures in the current update interval; +.Fa ra_nok +the number of transmit successes in the current update interval. +.Fa ra_pktrate +indicates the exponential average number of transmit failure/success +indications over past update intervals. +This approximates the rate of packet-transmission. +.Fa ra_rate_thresh +contains RSS thresholds that are indexed by +.Aq packet length, data rate +tuples. +When this node's exponential-average RSS exceeds +.Fa ra_rate_thresh[i][j] , +then packets at most 128 x 8^i bytes long are eligible to be +transmitted at the rate indexed by j. +.Pp +.Fa ra_last_raise +and +.Fa ra_raise_interval +are used to control the rate that RSS thresholds +.Dq decay . +.Fa ra_last_raise +indicates when +.Fn ieee80211_rssadapt_raise_rate +was last called and +.Fa ra_raise_interval +indicates the minimum period between consecutive calls to +.Fn ieee80211_rssadapt_raise_rate . +If +.Fn ieee80211_rssadapt_raise_rate +is called more than once in any period, the second and subsequent +calls are ignored. +.Sh CODE REFERENCES +This section describes places within the +.Ox +source tree where actual code implementing or using +.Nm +can be found. +All pathnames are relative to +.Pa /usr/src . +.Pp +The code for +.Nm +is in the file +.Pa sys/net80211/ieee80211_rssadapt.c . +.Pp +.Xr ath 4 +contains a reference implementation. +See +.Pa sys/dev/ic/ath.c . +.Sh SEE ALSO +.Xr ath 4 , +.Xr ieee80211 9 +.Rs +.%A Javier del Prado Pavon +.%A Sunghyun Choi +.%T "Link Adaptation Strategy for IEEE 802.11 WLAN via Received Signal \ +Strength Measurement" +.%J "ICC'03" +.%P pp. 1108-1113 +.%C Anchorage, Alaska +.%D May 2003 +.Re +.Sh HISTORY +.Nm +first appeared in +.Nx +and was ported to +.Ox +by +.An Todd C. Miller Aq Mt millert@OpenBSD.org +.Sh AUTHORS +.An David Young Aq Mt dyoung@NetBSD.org +.Sh BUGS +To cope with interference from microwave ovens, frequency-hopping +radios, and other sources of RF pulse-trains and bursts, +.Nm +should adapt the fragmentation threshold as well as the data rate. +.Pp +For improved throughput, +.Nm +should indicate to drivers when they should use the 802.11b +short-preamble. +.Pp +The constants in +.Fn ieee80211_rssadapt_updatestats +should be configurable. diff --git a/static/openbsd/man9/rt_ifa_add.9 b/static/openbsd/man9/rt_ifa_add.9 new file mode 100644 index 00000000..f0a54b2b --- /dev/null +++ b/static/openbsd/man9/rt_ifa_add.9 @@ -0,0 +1,121 @@ +.\" $OpenBSD: rt_ifa_add.9,v 1.6 2019/02/13 23:47:43 dlg Exp $ +.\" +.\" Copyright (c) 2014 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 $Mdocdate: February 13 2019 $ +.Dt RT_IFA_ADD 9 +.Os +.Sh NAME +.Nm rt_ifa_add , +.Nm rt_ifa_del , +.Nm rt_ifa_addlocal , +.Nm rt_ifa_dellocal +.Nd add or delete routing entries associated with an address +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/if.h +.In net/route.h +.Ft int +.Fo rt_ifa_add +.Fa "struct ifaddr *ifa" +.Fa "int flags" +.Fa "struct sockaddr *dst" +.Fa "unsigned int rdomain" +.Fc +.Ft int +.Fo rt_ifa_del +.Fa "struct ifaddr *ifa" +.Fa "int flags" +.Fa "struct sockaddr *dst" +.Fa "unsigned int rdomain" +.Fc +.Ft int +.Fn rt_ifa_addlocal "struct ifaddr *ifa" +.Ft int +.Fn rt_ifa_dellocal "struct ifaddr *ifa" +.Sh DESCRIPTION +These functions create and delete routing entries required by the network +stack and managed by the kernel. +.Bl -tag -width rt_ifa_addlocalxx +.It Fn rt_ifa_add +Creates and associates a connected routing entry with +.Fa ifa +in the routing domain specified by +.Fa rdomain . +.Pp +Connected routing entries represent routes to prefixes and should be created +with +.Dv RTF_CLONING +in +.Fa flags +and the address of +.Fa ifa +in +.Fa dst . +But for Point-to-Point interfaces, connected routing entries represent routes +to hosts and should be created +with +.Dv RTF_HOST +in +.Fa flags +and the destination address in +.Fa dst . +Connected routing entries have a priority of +.Dv RTP_CONNECTED . +.It Fn rt_ifa_del +Removes the connected routing entry associated with +.Fa ifa +in the routing domain specified by +.Fa rdomain . +.It Fn rt_ifa_addlocal +Creates and associates a local routing entry +with +.Fa ifa . +.Pp +Local routing entries are used to not send packets destined to a local +address on the wire and instead redirect them to +.Xr lo 4 . +They have the lowest priority available, +.Dv RTP_LOCAL , +and contain a special flag, +.Dv RTF_LOCAL , +that can be checked to determine if the address is configured on the system. +.It Fn rt_ifa_dellocal +Removes the local routing entry associated with +.Fa ifa . +.El +.Sh CONTEXT +.Fn rt_ifa_add , +.Fn rt_ifa_del , +.Fn rt_ifa_addlocal , +and +.Fn rt_ifa_dellocal +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn rt_ifa_add , +.Fn rt_ifa_del , +.Fn rt_ifa_addlocal , +and +.Fn rt_ifa_dellocal +will return +.Dv 0 +on success and the return value of +.Xr rtrequest 9 +otherwise. +.Sh SEE ALSO +.Xr lo 4 , +.Xr route 4 , +.Xr rtrequest 9 diff --git a/static/openbsd/man9/rt_timer_add.9 b/static/openbsd/man9/rt_timer_add.9 new file mode 100644 index 00000000..319591c2 --- /dev/null +++ b/static/openbsd/man9/rt_timer_add.9 @@ -0,0 +1,108 @@ +.\" $OpenBSD: rt_timer_add.9,v 1.5 2023/06/20 10:59:47 kn Exp $ +.\" +.\" Copyright (c) 2011 Bret S. Lambert +.\" 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 $Mdocdate: June 20 2023 $ +.Dt RT_TIMER_ADD 9 +.Os +.Sh NAME +.Nm rt_timer_add , +.Nm rt_timer_remove_all , +.Nm rt_timer_get_expire , +.Nm rt_timer_queue_init , +.Nm rt_timer_queue_change , +.Nm rt_timer_queue_flush , +.Nm rt_timer_queue_count +.Nd route timer queues interface +.Sh SYNOPSIS +.In net/route.h +.Ft int +.Fn rt_timer_add "struct rtentry *rt" \ +"struct rttimer_queue *queue" "u_int rtableid" +.Ft void +.Fn rt_timer_remove_all "struct rtentry *rt" +.Ft time_t +.Fn rt_timer_get_expire "const struct rtentry *rt" +.Ft void +.Fn rt_timer_queue_init "struct rttimer_queue *rtq" "int timeout" \ +"void (*func)(struct rtentry *, u_int)" +.Ft void +.Fn rt_timer_queue_change "struct rttimer_queue *rtq" "int timeout" +.Ft void +.Fn rt_timer_queue_flush "struct rttimer_queue *rtq" +.Ft unsigned long +.Fn rt_timer_queue_count "struct rttimer_queue *rtq" +.Sh DESCRIPTION +The +.Nm rt_timer +subsystem queues routing-related functions for asynchronous execution +in the future. +.Pp +.Fn rt_timer_add +allocates an rttimer_queue +.Fa rtq +to be called on +.Fa rt +using the timeout of +.Fa queue . +If an action already exists, it will be replaced with the new one. +.Pp +.Fn rt_timer_remove_all +removes all timeouts associated with +.Fa rt +from all routing timer queues. +.Pp +.Fn rt_timer_get_expire +returns the current expiry time in seconds. +.Pp +.Fn rt_timer_queue_init +creates a timer queue with a timeout of +.Fa timeout +seconds. +.Pp +.Fn rt_timer_queue_change +sets the timeout for +.Fa rtq +to +.Fa timeout +seconds. +.Pp +.Fn rt_timer_queue_flush +removes all timeouts from the routing timer queue +.Fa rtq , +executes their associated callback and destroys it. +.Pp +.Fn rt_timer_queue_count +returns the number of timers present in the queue +.Fa rtq . +.Sh CONTEXT +.Fn rt_timer_add , +.Fn rt_timer_remove_all , +.Fn rt_timer_get_expire , +.Fn rt_timer_queue_init , +.Fn rt_timer_queue_change , +.Fn rt_timer_queue_flush +and +.Fn rt_timer_queue_count +can be called during autoconf, from process context, or from interrupt context. +.Sh ERRORS +.Fn rt_timer_add +may fail with +.Er ENOBUFS +if memory could not be allocated for the timeout. +.Sh SEE ALSO +.Xr route 4 , +.Xr route 9 diff --git a/static/openbsd/man9/rtable_add.9 b/static/openbsd/man9/rtable_add.9 new file mode 100644 index 00000000..05d91ccb --- /dev/null +++ b/static/openbsd/man9/rtable_add.9 @@ -0,0 +1,92 @@ +.\" $OpenBSD: rtable_add.9,v 1.9 2021/03/26 22:41:06 mvs Exp $ +.\" +.\" Copyright (c) 2011 Bret S. Lambert +.\" 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 $Mdocdate: March 26 2021 $ +.Dt RTABLE_ADD 9 +.Os +.Sh NAME +.Nm rtable_add , +.Nm rtable_exists , +.Nm rtable_loindex , +.Nm rtable_l2 , +.Nm rtable_l2set +.Nd routing tables and routing domains interface +.Sh SYNOPSIS +.In net/rtable.h +.Ft int +.Fn rtable_add "unsigned int id" +.Ft int +.Fn rtable_exists "unsigned int id" +.Ft unsigned int +.Fn rtable_loindex "unsigned int id" +.Ft unsigned int +.Fn rtable_l2 "unsigned int id" +.Ft void +.Fn rtable_l2set "unsigned int id" "unsigned int rdomain" +.Sh DESCRIPTION +Routing tables contain layer 2 and 3 forwarding information. +Each address family in use will have its own routing table. +Routing domains are a way of logically segmenting a router among multiple +networks and may contain more than one routing table. +.Bl -tag -width Ds +.It Fn rtable_add "unsigned int id" +Add routing table with ID of +.Fa id +to routing domain +.Fa 0 . +.It Fn rtable_exists "unsigned int id" +Return +.Fa 1 +if routing table with ID +.Fa id +exists, +.Fa 0 +otherwise. +.It Fn rtable_loindex "unsigned int id" +Return the default +.Xr lo 4 +interface index for the routing table with ID of +.Fa id . +.It Fn rtable_l2 "unsigned int id" +Get the routing domain of routing table with ID of +.Fa id . +.It Fn rtable_l2set "unsigned int id" "unsigned int rdomain" +Place routing table with ID of +.Fa id +under the routing domain with ID of +.Fa rdomain . +.El +.Sh CONTEXT +.Fn rtable_add , +.Fn rtable_exists , +.Fn rtable_loindex , +.Fn rtable_l2 , +and +.Fn task_l2set +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn rtable_add +may fail with: +.Pp +.Bl -tag -width Er -compact +.It Bq Er ENOMEM +Memory could not be allocated to extend the list of routing domains. +.El +.Sh SEE ALSO +.Xr lo 4 , +.Xr route 4 , +.Xr route 8 diff --git a/static/openbsd/man9/rtable_walk.9 b/static/openbsd/man9/rtable_walk.9 new file mode 100644 index 00000000..02896947 --- /dev/null +++ b/static/openbsd/man9/rtable_walk.9 @@ -0,0 +1,74 @@ +.\" $OpenBSD: rtable_walk.9,v 1.1 2019/07/12 16:53:57 mpi Exp $ +.\" +.\" Copyright (c) 2019 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 $Mdocdate: July 12 2019 $ +.Dt RTABLE_WALK 9 +.Os +.Sh NAME +.Nm rtable_walk +.Nd iterate over a routing table +.Sh SYNOPSIS +.In net/rtable.h +.Ft int +.Fo rtable_walk +.Fa "unsigned int rtableid" +.Fa "sa_family_t af" +.Fa "struct rtentry **prt" +.Fa "int (*func)(struct rtentry *, void *, unsigned int)" +.Fa "void *arg" +.Fc +.Sh DESCRIPTION +The +.Fn rtable_walk +function iterates over the routing table +.Fa rtableid +and applies +.Fa func +to all entries of address family +.Fa af . +.Pp +The iteration is interrupted as soon as +.Fa func +returns a non-zero value. +If +.Fa prt +is not +.Dv NULL +when the iteration is interrupted, it is set to the current +routing entry. +In that case +.Fn rtfree +must be called on the routing entry pointed to by +.Fa prt . +.Sh CONTEXT +.Fn rtable_walk +can be called during autoconf or from process context. +.Sh RETURN VALUES +.Fn rtable_walk +returns any non-zero value returned by +.Fa func . +It may also fail with: +.Pp +.Bl -tag -width Er -compact +.It Bq Er EAFNOSUPPORT +A routing table with ID of +.Fa rtableid +and address family of +.Fa af +doesn't exist. +.El +.Sh SEE ALSO +.Xr rtfree 9 diff --git a/static/openbsd/man9/rtalloc.9 b/static/openbsd/man9/rtalloc.9 new file mode 100644 index 00000000..b9faff21 --- /dev/null +++ b/static/openbsd/man9/rtalloc.9 @@ -0,0 +1,106 @@ +.\" $OpenBSD: rtalloc.9,v 1.12 2019/07/12 16:53:57 mpi Exp $ +.\" +.\" Copyright (c) 2014-2015 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 $Mdocdate: July 12 2019 $ +.Dt RTALLOC 9 +.Os +.Sh NAME +.Nm rtalloc , +.Nm rtalloc_mpath , +.Nm rtisvalid , +.Nm rtref , +.Nm rtfree +.Nd routing entry interface +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/route.h +.Ft struct rtentry * +.Fn rtalloc "struct sockaddr *dst" "int flags" "unsigned int rtableid" +.Ft struct rtentry * +.Fn rtalloc_mpath "struct sockaddr *dst" "uint32_t *src" "unsigned int rtableid" +.Ft int +.Fn rtisvalid "struct rtentry *rt" +.Ft void +.Fn rtref "struct rtentry *rt" +.Ft void +.Fn rtfree "struct rtentry *rt" +.Sh DESCRIPTION +The +.Fn rtalloc +function looks in the routing table +.Fa rtableid +for an entry matching +.Fa dst . +The following +.Fa flags +can be specified: +.Bl -tag -width RT_RESOLVE -offset indent +.It Dv RT_RESOLVE +Allocate and return a cloned entry for +.Fa dst +if it does not exist and the lookup returned a cloning entry. +.El +.Pp +The +.Fn rtalloc_mpath +function does the same as +.Fn rtalloc +with the +.Dv RT_RESOLVE +.Fa flag , +but selects a multipath routing entry corresponding to +.Fa src +when possible. +.Pp +The +.Fn rtisvalid +function checks if the route entry +.Fa rt +is still valid and can be used. +Cached entries that are no longer valid should be released by calling +.Fn rtfree . +.Pp +The +.Fn rtref +function increments a reference to the routing entry +.Fa rt . +.Pp +The +.Fn rtfree +function releases a reference to the routing entry +.Fa rt , +freeing it if the reference count drops to 0. +If +.Fa rt +is a +.Dv NULL +pointer, no action occurs. +.Sh CONTEXT +.Fn rtalloc , +.Fn rtalloc_mpath , +.Fn rtisvalid , +.Fn rtref , +and +.Fn rtfree +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn rtisvalid +returns 1 if the route entry is valid, otherwise 0. +.Sh SEE ALSO +.Xr route 4 , +.Xr rtable_walk 9 , +.Xr rtrequest 9 diff --git a/static/openbsd/man9/rtlabel_id2name.9 b/static/openbsd/man9/rtlabel_id2name.9 new file mode 100644 index 00000000..a2acba1c --- /dev/null +++ b/static/openbsd/man9/rtlabel_id2name.9 @@ -0,0 +1,75 @@ +.\" $OpenBSD: rtlabel_id2name.9,v 1.4 2014/10/15 11:58:13 mpi Exp $ +.\" +.\" Copyright (c) 2011 Bret S. Lambert +.\" 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 $Mdocdate: October 15 2014 $ +.Dt RTLABEL_ID2NAME 9 +.Os +.Sh NAME +.Nm rtlabel_id2name , +.Nm rtlabel_id2sa , +.Nm rtlabel_name2id , +.Nm rtlabel_unref +.Nd manipulate route labels +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/route.h +.Ft const char * +.Fn rtlabel_id2name "u_int16_t id" +.Ft struct sockaddr * +.Fn rtlabel_id2sa "u_int16_t labelid" "struct sockaddr_rtlabel *sa_rl" +.Ft u_int16_t +.Fn rtlabel_name2id "char *name" +.Ft void +.Fn rtlabel_unref "u_int16_t id" +.Sh DESCRIPTION +Route labels are arbitrary data appended to route entries and can be acted +upon by +.Xr pf 4 . +.Bl -tag -width Ds +.It Fn rtlabel_name2id "char *name" +Return numerical ID of the route label named +.Fa name , +creating the label if it does not already exist. +.It Fn rtlabel_id2name "u_int16_t id" +Return the string name of the route label with ID +.Fa id . +.It Fn rtlabel_id2sa "u_int16_t labelid" "struct sockaddr_rtlabel *sa_rl" +Populate +.Fa sa_rl +with the data from the route label specified by +.Fa labelid . +.It Fn rtlabel_unref "u_int16_t id" +Remove a reference to the route label with ID +.Fa id , +freeing the label if the reference count drops to 0. +.El +.Sh CONTEXT +.Fn rtlabel_id2name , +.Fn rtlabel_id2sa , +.Fn rtlabel_name2id , +and +.Fn rtlabel_unref +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn rtlabel_name2id +returns +.Fa 0 +if it was unable to create a route label. +.Sh SEE ALSO +.Xr route 4 , +.Xr route 9 diff --git a/static/openbsd/man9/rtrequest.9 b/static/openbsd/man9/rtrequest.9 new file mode 100644 index 00000000..7de35a56 --- /dev/null +++ b/static/openbsd/man9/rtrequest.9 @@ -0,0 +1,138 @@ +.\" $OpenBSD: rtrequest.9,v 1.3 2019/07/12 16:57:45 mpi Exp $ +.\" +.\" Copyright (c) 2011 Bret S. Lambert +.\" 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 $Mdocdate: July 12 2019 $ +.Dt RTREQUEST 9 +.Os +.Sh NAME +.Nm rtrequest +.Nd add or remove entries from a routing table +.Sh SYNOPSIS +.In sys/types.h +.In net/route.h +.Ft int +.Fn rtrequest "int req" "struct rt_addrinfo *info" "u_int8_t prio" \ +"struct rtentry **rtp" "u_int rtableid" +.Bd -literal +struct rt_addrinfo { + int rti_addrs; + struct sockaddr *rti_info[RTAX_MAX]; + int rti_flags; + struct ifaddr *rti_ifa; + struct rt_msghdr *rti_rtm; + u_char rti_mpls; +}; + +#define RTAX_DST 0 /* destination sockaddr present */ +#define RTAX_GATEWAY 1 /* gateway sockaddr present */ +#define RTAX_NETMASK 2 /* netmask sockaddr present */ +#define RTAX_IFP 4 /* interface name sockaddr present */ +#define RTAX_IFA 5 /* interface addr sockaddr present */ +#define RTAX_AUTHOR 6 /* sockaddr for author of redirect */ +#define RTAX_BRD 7 /* for NEWADDR, broadcast or p-p dest */ +#define RTAX_SRC 8 /* source sockaddr present */ +#define RTAX_SRCMASK 9 /* source netmask present */ +#define RTAX_LABEL 10 /* route label present */ +#define RTAX_MAX 11 /* size of array to allocate */ +.Ed +.Sh DESCRIPTION +The +.Fn rtrequest +function is used to add or remove entries from a specific routing table. +It takes the following arguments: +.Bl -tag -width rtableid +.It Fa req +One of the following actions to perform: +.Bl -tag -width RTM_RESOLVE -offset indent +.It Dv RTM_ADD +Add an entry to a given routing table. +.It Dv RTM_DELETE +Remove an entry from a given routing table. +In case of a cloning entry, all its children are deleted. +.It Dv RTM_RESOLVE +Add a cloned entry, based on the parent cloning entry pointed by +.Fa rtp , +to a given routing table. +.El +.It Fa info +Describes the routing entry to add or remove. +.It Fa prio +Specifies the priority of the routing entry described by +.Fa info . +If it is +.Dv 0 +and the requested action is +.Dv RTM_ADD +then a default priority based on the priority of the associated +interface is chosen. +.It Fa rtp +Must point to the cloning entry if the action is +.Dv RTM_RESOLVE . +In all cases when no error is returned and it is not +.Dv NULL , +a pointer to the deleted or added entry is placed there. +The caller must take care of releasing the returned reference by +calling +.Xr rtfree 9 . +.It Fa rtableid +The ID of the routing table to modify. +.El +.Sh CONTEXT +.Fn rtrequest +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn rtrequest +may fail with: +.Pp +.Bl -tag -width Er -compact +.It Bq Er EAFNOSUPPORT +The routing table with ID of +.Fa rtableid +does not exist or it does not support the protocol specified in +.Fa info . +.It Bq Er ESRCH +No routing entry corresponding to +.Fa info +could be found. +.It Bq Er ESRCH +Multipath routing entry with no gateway provided in +.Fa info . +.It Bq Er ESRCH +The entry could not be found in the routing table of ID +.Fa rtableid . +specified +.It Bq Er EINVAL +The entry pointed by +.Fa rtp +is not valid or does not point to a cloning entry in the +.Dv RTM_RESOLVE +case. +.It Bq Er EEXIST +Multipath routing entry conflicts with an existing one. +.It Bq Er EEXIST +The entry could not be entered into the routing table. +.It Bq Er ENOMEM +Space for MPLS protocol data could not be allocated. +.It Bq Er ENOBUFS +Space for a new routing entry could not be allocated. +.It Bq Er ENETUNREACH +An interface address corresponding to the routing entry described by +.Fa info +could not be found. +.El +.Sh SEE ALSO +.Xr rtfree 9 diff --git a/static/openbsd/man9/rwlock.9 b/static/openbsd/man9/rwlock.9 new file mode 100644 index 00000000..6113426f --- /dev/null +++ b/static/openbsd/man9/rwlock.9 @@ -0,0 +1,271 @@ +.\" $OpenBSD: rwlock.9,v 1.30 2025/08/05 14:25:11 schwarze Exp $ +.\" +.\" Copyright (c) 2006 Pedro Martelletto +.\" 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 $Mdocdate: August 5 2025 $ +.Dt RWLOCK 9 +.Os +.Sh NAME +.Nm rwlock , +.Nm rw_init , +.Nm rw_init_flags , +.Nm rw_init_flags_trace , +.Nm rw_enter , +.Nm rw_exit , +.Nm rw_enter_read , +.Nm rw_enter_write , +.Nm rw_exit_read , +.Nm rw_exit_write , +.Nm rw_assert_wrlock , +.Nm rw_assert_rdlock , +.Nm rw_assert_anylock , +.Nm rw_assert_unlocked , +.Nm rw_status , +.Nm RWLOCK_INITIALIZER , +.Nm RWLOCK_INITIALIZER_TRACE , +.Nm rrw_init , +.Nm rrw_init_flags , +.Nm rrw_enter , +.Nm rrw_exit , +.Nm rrw_status +.Nd interface to read/write locks +.Sh SYNOPSIS +.In sys/rwlock.h +.Ft void +.Fn rw_init "struct rwlock *rwl" "const char *name" +.Ft void +.Fn rw_init_flags "struct rwlock *rwl" "const char *name" "int flags" +.Ft void +.Fo rw_init_flags_trace +.Fa "struct rwlock *rwl" +.Fa "const char *name" +.Fa "int flags" +.Fa "int trace" +.Fc +.Ft int +.Fn rw_enter "struct rwlock *rwl" "int flags" +.Ft void +.Fn rw_exit "struct rwlock *rwl" +.Ft void +.Fn rw_enter_read "struct rwlock *rwl" +.Ft void +.Fn rw_enter_write "struct rwlock *rwl" +.Ft void +.Fn rw_exit_read "struct rwlock *rwl" +.Ft void +.Fn rw_exit_write "struct rwlock *rwl" +.Ft void +.Fn rw_assert_wrlock "struct rwlock *rwl" +.Ft void +.Fn rw_assert_rdlock "struct rwlock *rwl" +.Ft void +.Fn rw_assert_anylock "struct rwlock *rwl" +.Ft void +.Fn rw_assert_unlocked "struct rwlock *rwl" +.Ft int +.Fn rw_status "struct rwlock *rwl" +.Fn RWLOCK_INITIALIZER "const char *name" +.Fn RWLOCK_INITIALIZER_TRACE "const char *name" "int trace" +.Ft void +.Fn rrw_init "struct rrwlock *rrwl" "const char *name" +.Ft void +.Fn rrw_init_flags "struct rrwlock *rrwl" "const char *name" "int flags" +.Ft int +.Fn rrw_enter "struct rrwlock *rrwl" "int flags" +.Ft void +.Fn rrw_exit "struct rrwlock *rrwl" +.Ft int +.Fn rrw_status "struct rrwlock *rrwl" +.Sh DESCRIPTION +The +.Nm +set of functions provides a multiple-reader, single-writer locking mechanism to +ensure mutual exclusion between different threads. +.Pp +Read locks can be acquired while the write lock is not held, and may coexist in +distinct threads at any time. +A write lock, however, can only be acquired when there are no read locks held, +granting exclusive access to a single thread. +.Pp +The +.Fn rw_init +function is used to initiate the lock pointed to by +.Fa rwl . +The +.Fa name +argument specifies the name of the lock, which is used as the wait message +if the thread needs to sleep. +.Pp +The +.Fn rw_init_flags +macro is similar to +.Fn rw_init , +but it additionally accepts a bitwise OR of the following flags: +.Bl -tag -width RWL_NOWITNESS -offset indent +.It Dv RWL_DUPOK +Prevents +.Xr witness 4 +from logging when a thread acquires more than one lock of this lock type. +.It Dv RWL_IS_VNODE +Make +.Xr witness 4 +ignore lock order issues between this lock type and any other lock type +tagged with the +.Dv RWL_IS_VNODE +flag. +.It Dv RWL_NOWITNESS +Instructs +.Xr witness 4 +to ignore this lock. +.El +.Fn rw_init_flags_trace +additionally accepts a +.Xr dt 4 +static probe index. +.Pp +The +.Fn rw_enter +function acquires a lock. +The +.Fa flags +argument specifies what kind of lock should be obtained and also +modifies the operation. +The possible flags are: +.Pp +.Bl -tag -offset indent -width RW_DOWNGRADEXXX -compact +.It Dv RW_READ +Acquire a shared lock. +.It Dv RW_WRITE +Acquire an exclusive lock. +.It Dv RW_DOWNGRADE +Safely release an exclusive lock and acquire a shared lock without +letting other exclusive locks in between. +.It Dv RW_UPGRADE +Upgrade a shared lock into an exclusive one. +Must be combined with +.Dv RW_NOSLEEP . +.It Dv RW_INTR +When waiting for a lock, allow signals to interrupt the sleep. +.It Dv RW_NOSLEEP +Do not wait for busy locks, fail with +.Dv EBUSY +instead. +.It Dv RW_DUPOK +Prevents +.Xr witness 4 , +for just this +.Fn rw_enter , +from logging when this thread already has a lock of this lock type. +.El +.Pp +The +.Fn rw_exit +function is used to release a held lock. +.Pp +The +.Fn rw_enter_read +function acquires a read lock, sleeping if necessary. +.Pp +The +.Fn rw_enter_write +function acquires a write lock, sleeping if necessary. +.Pp +The +.Fn rw_exit_read +function releases a read lock. +.Pp +The +.Fn rw_exit_write +function releases a write lock. +.Pp +The +.Fn rw_assert_wrlock , +.Fn rw_assert_rdlock , +.Fn rw_assert_anylock , +and +.Fn rw_assert_unlocked +functions check the status +.Fa rwl , +panicking if it is not write-, read-, any-, or unlocked, respectively. +.Pp +.Nm rw_status +returns the current state of the lock. +.Pp +A lock declaration may be initialised with the +.Fn RWLOCK_INITIALIZER +macro. +The +.Fa name +argument specifies the name of the lock, which is used as the wait message +if the thread needs to sleep. +.Fn RWLOCK_INITIALIZER_TRACE +additionally accepts a +.Xr dt 4 +static probe index. +.Pp +The +.Nm rrwlock +functions support recursive write locking by the same process. +They otherwise behave the same as their rwlock counterparts. +.Sh CONTEXT +.Fn rw_init , +.Fn rw_init_flags , +.Fn rw_init_flags_trace , +.Fn rrw_init +and +.Fn rrw_init_flags +can be called during autoconf, from process context, or from interrupt context. +.Pp +All other functions can be called during autoconf or from process context. +.Sh RETURN VALUES +.Nm rw_enter +and +.Nm rrw_enter +return 0 on success, or an +.Xr errno 2 +style value on failure. +.Pp +.Nm rw_status +and +.Nm rrw_status +return the state of the lock: +.Pp +.Bl -tag -width "RW_WRITE_OTHER" -offset indent -compact +.It Dv RW_WRITE +Lock is write locked by the calling thread. +.It Dv RW_WRITE_OTHER +Lock is write locked by a different thread. +.It Dv RW_READ +Lock is read locked. +The current thread may be one of the threads that has it locked. +.It 0 +Lock is not locked. +.El +.Sh SEE ALSO +.Xr witness 4 , +.Xr mutex 9 , +.Xr rwsleep 9 , +.Xr spl 9 +.Sh HISTORY +The +.Nm +functions first appeared in +.Ox 3.5 . +.Sh AUTHORS +The +.Nm +functions were written by +.An Artur Grabowski Aq Mt art@openbsd.org . diff --git a/static/openbsd/man9/sensor_attach.9 b/static/openbsd/man9/sensor_attach.9 new file mode 100644 index 00000000..d77b46e8 --- /dev/null +++ b/static/openbsd/man9/sensor_attach.9 @@ -0,0 +1,157 @@ +.\" $OpenBSD: sensor_attach.9,v 1.13 2015/09/14 15:14:55 schwarze Exp $ +.\" +.\" Copyright (c) 2006 Michael Knudsen +.\" Copyright (c) 2006 Constantine A. Murenin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the 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 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" 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 $Mdocdate: September 14 2015 $ +.Dt SENSOR_ATTACH 9 +.Os +.Sh NAME +.Nm sensor_attach , +.Nm sensor_detach , +.Nm sensor_find , +.Nm sensordev_install , +.Nm sensordev_deinstall , +.Nm sensordev_get , +.Nm sensor_task_register , +.Nm sensor_task_unregister +.Nd sensors framework +.Sh SYNOPSIS +.In sys/sensors.h +.Ft void +.Fn sensordev_install "struct ksensordev *sensdev" +.Ft void +.Fn sensordev_deinstall "struct ksensordev *sensdev" +.Ft struct ksensordev * +.Fn sensordev_get "int devnum" +.Pp +.Ft void +.Fn sensor_attach "struct ksensordev *sensdev" "struct ksensor *sens" +.Ft void +.Fn sensor_detach "struct ksensordev *sensdev" "struct ksensor *sens" +.Ft struct ksensor * +.Fn sensor_find "int devnum" "enum sensor_type stype" "int numt" +.Pp +.Ft struct sensor_task * +.Fn sensor_task_register "void *arg" "void (*func)(void *)" "int period" +.Ft void +.Fn sensor_task_unregister "struct sensor_task *st" +.Sh DESCRIPTION +The +sensors +framework API provides a mechanism for manipulation of hardware sensors +that are available under the +.Va hw.sensors +.Xr sysctl 8 +tree. +.Pp +.Fn sensor_attach +adds the sensor specified by the +.Fa sens +argument to the sensor device specified by the +.Fa sensdev +argument. +.Fn sensor_detach +can be used to remove sensors previously added by +.Fn sensor_attach . +.Pp +.Fn sensordev_install +registers the sensor device specified by the +.Fa sensdev +argument so that all sensors that are attached to the device become +accessible via the sysctl interface. +.Fn sensordev_deinstall +can be used to remove sensor devices previously registered by +.Fn sensordev_install . +.Pp +.Fn sensordev_get +takes ordinal number +.Fa devnum +specifying a sensor device and +returns a pointer to the corresponding +.Vt struct ksensordev , +or +.Dv NULL +if no such sensor device exists. +.Pp +.Fn sensor_find +takes ordinal number +.Fa devnum +specifying a sensor device, sensor type +.Fa stype +and ordinal number of sensor of such type +.Fa numt , +and returns a pointer to the corresponding +.Vt struct ksensor , +or +.Dv NULL +if no such sensor exists. +.Fn sensor_find +will always return +.Dv NULL +if the corresponding sensor devices are not registered by +.Fn sensordev_install . +.Pp +Drivers are responsible for retrieving, interpreting, and normalising +sensor values and updating the sensor struct periodically. +If the driver needs process context, for example to sleep, it can +register a task with the sensor framework. +.Pp +.Fn sensor_task_register +is used to register a periodic task to update sensors. +The +.Fa func +argument is a pointer to the function to run with an interval of +.Fa period +seconds. +The +.Fa arg +parameter is the argument given to the +.Fa func +function. +.Fn sensor_task_unregister +ensures that the task specified by the +.Fa st +argument is no longer running, and then removes it from the queue. +.Pp +All the functions in the sensor framework must be called during +.Xr autoconf 9 +or from a process context. +Additionally, +.Fn sensor_task_unregister +must not be called from the sensor task that it is about to remove. +.Sh SEE ALSO +.Xr sysctl 8 , +.Xr autoconf 9 +.Sh HISTORY +The sensor framework was written by +.An Alexander Yurchenko Aq Mt grange@openbsd.org +and first appeared in +.Ox 3.4 . +.An David Gwynne Aq Mt dlg@openbsd.org +later extended it for +.Ox 3.8 . +.An Constantine A. Murenin Aq Mt cnst+openbsd@bugmail.mojo.ru +extended it even further by introducing the concept of sensor devices in +.Ox 4.1 . diff --git a/static/openbsd/man9/sigio_init.9 b/static/openbsd/man9/sigio_init.9 new file mode 100644 index 00000000..745a3615 --- /dev/null +++ b/static/openbsd/man9/sigio_init.9 @@ -0,0 +1,147 @@ +.\" $OpenBSD: sigio_init.9,v 1.4 2020/01/08 16:27:40 visa Exp $ +.\" +.\" Copyright (c) 2018 Visa Hankala +.\" +.\" 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 8 2020 $ +.Dt SIGIO_INIT 9 +.Os +.Sh NAME +.Nm sigio_init , +.Nm sigio_free , +.Nm sigio_copy , +.Nm sigio_setown , +.Nm sigio_getown +.Nd asynchronous IO signal API +.Sh SYNOPSIS +.In sys/sigio.h +.Ft void +.Fn "sigio_init" "struct sigio_ref *sir" +.Ft void +.Fn "sigio_free" "struct sigio_ref *sir" +.Ft void +.Fn "sigio_copy" "struct sigio_ref *dst" "struct sigio_ref *src" +.Ft int +.Fn "sigio_setown" "struct sigio_ref *sir" "u_long cmd" "caddr_t data" +.Ft pid_t +.Fn "sigio_getown" "struct sigio_ref *sir" "u_long cmd" "caddr_t data" +.Sh DESCRIPTION +The asynchronous IO signal API provides a means to manage signal registrations. +It associates a process or process group with a signal source. +The association is revoked automatically when the process or process group +is deleted. +.Pp +.Fn sigio_init +initializes the sigio reference +.Fa sir . +.Pp +.Fn sigio_free +clears any process or process group associated with reference +.Fa sir . +.Pp +.Fn sigio_copy +copies registration from reference +.Fa src +to reference +.Fa dst . +.Pp +.Fn sigio_setown +associates the reference +.Fa sir +with a process or process group. +.Fa cmd +is one of ioctl commands +.Dv FIOSETOWN , +.Dv SIOCSPGRP +and +.Dv TIOCSPGRP . +.Fa data +is a pointer to a signed integer that represents the ID of the owner +of the registration. +For +.Dv FIOSETOWN +and +.Dv SIOCSPGRP , +a positive ID is taken as a process ID, +and a negative ID is taken as a process group ID. +If +.Fa cmd +is +.Dv TIOCSPGRP , +a positive ID is taken as a process group ID, +and negative ID values are not allowed. +For all values of +.Fa cmd , +the reference +.Fa sir +is cleared if the ID is zero. +.Pp +When +.Fn sigio_setown +is called, the invoking process' credentials are stored in the reference. +These credentials are checked when the reference is used with +.Xr pgsigio 9 . +.Pp +.Fn sigio_getown +stores the ID of the process or process group associated with the reference +.Fa sir +to the signed integer pointed by +.Fa data . +.Fa cmd +is one of ioctl commands +.Dv FIOGETOWN , +.Dv SIOCGPGRP +and +.Dv TIOCGPGRP . +For +.Dv FIOGETOWN +and +.Dv SIOCGPGRP , +a process ID is stored as a positive ID, +and a process group ID is stored as a negative ID. +For +.Dv TIOCGPGRP , +a process ID is stored as a negative ID, +and a process group ID is stored as a positive ID. +If there is no registered owner, a zero is stored in the integer. +.Sh CONTEXT +.Fn sigio_init , +.Fn sigio_free , +.Fn sigio_copy , +.Fn sigio_setown +and +.Fn sigio_getown +can be called during autoconf, or from process context. +.Sh RETURN VALUES +.Fn sigio_setown +returns 0 on success. +Otherwise, the following error values are returned: +.Bl -tag -width [EINVAL] +.It Bq Er EINVAL +The process group ID is invalid. +.It Bq Er EPERM +The invoking process belongs to another session than the process +or process group. +.It Bq Er ESRCH +The process or process group does not exist. +.It Bq Er ESRCH +The process is exiting. +.El +.Sh SEE ALSO +.Xr pgsigio 9 +.Sh HISTORY +The sigio routines were adapted from +.Fx +and first appeared in +.Ox 6.5 . diff --git a/static/openbsd/man9/smr_call.9 b/static/openbsd/man9/smr_call.9 new file mode 100644 index 00000000..2bce55e6 --- /dev/null +++ b/static/openbsd/man9/smr_call.9 @@ -0,0 +1,135 @@ +.\" $OpenBSD: smr_call.9,v 1.4 2022/06/22 14:10:49 visa Exp $ +.\" +.\" Copyright (c) 2019 Visa Hankala +.\" +.\" 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: June 22 2022 $ +.Dt SMR_CALL 9 +.Os +.Sh NAME +.Nm smr_read_enter , +.Nm smr_read_leave , +.Nm smr_init , +.Nm smr_call , +.Nm smr_barrier , +.Nm smr_flush , +.Nm SMR_ASSERT_CRITICAL , +.Nm SMR_ASSERT_NONCRITICAL +.Nd safe memory reclamation +.Sh SYNOPSIS +.In sys/smr.h +.Ft void +.Fn smr_read_enter +.Ft void +.Fn smr_read_leave +.Ft void +.Fn smr_init "struct smr_entry *smr" +.Ft void +.Fn smr_call "struct smr_entry *smr" "void (*fn)(void *)" "void *arg" +.Ft void +.Fn smr_barrier +.Ft void +.Fn smr_flush +.Ft void +.Fn SMR_ASSERT_CRITICAL +.Ft void +.Fn SMR_ASSERT_NONCRITICAL +.Sh DESCRIPTION +The safe memory reclamation API provides a mechanism for reclaiming +shared objects that readers can access without locking. +Objects that are reclaimed through SMR are called SMR-protected. +The mechanism guarantees that SMR-protected objects are not destroyed +while readers are using them. +However, it does not control how these objects are modified. +.Pp +Readers access SMR-protected objects inside an SMR read-side critical section +using +.Xr SMR_PTR_GET 9 . +.\" or with a higher level API built on top of it. +The section is entered with +.Fn smr_read_enter , +and exited with +.Fn smr_read_leave . +These routines never block. +Sleeping is not allowed within SMR read-side critical section. +.Pp +.Fn smr_init +initializes the entry +.Fa smr +for use with +.Fn smr_call . +.Pp +.Fn smr_call +schedules a callback to be invoked after the entry +.Fa smr +cannot be referenced by a reader in SMR read-side critical section. +On invocation, the system calls function +.Fa fn +with argument +.Fa arg +in process context without any locks held. +The implementation may delay the call in order to reduce +overall system overhead by amortization. +.Pp +.Fn smr_barrier +sleeps until any SMR read-side critical sections that are active on other CPUs +at the time of invocation have ended. +Like with +.Fn smr_call , +the processing of the request may be delayed. +.Pp +.Fn smr_flush +is like +.Fn smr_barrier +but the system is forced to process the request as soon as possible. +The use of this function is discouraged because of the heavy impact +on system performance. +.Pp +To avoid deadlocks, the caller of +.Fn smr_barrier +or +.Fn smr_flush +must not hold locks that can block the processing of SMR callbacks. +.Pp +The SMR implementation does not limit the number of deferred calls. +It is important to prevent arbitrary call rate of +.Fn smr_call . +Otherwise, it might be possible to exhaust system resources +if the system is not able to invoke callbacks quickly enough. +.Pp +.Fn SMR_ASSERT_CRITICAL +and +.Fn SMR_ASSERT_NONCRITICAL +can be used to assert that the current CPU is or is not +in SMR read-side critical section. +.Sh CONTEXT +.Fn smr_read_enter , +.Fn smr_read_leave , +.Fn smr_call +and +.Fn smr_init +can be called during autoconf, from process context, or from interrupt context. +.Pp +.Fn smr_barrier +and +.Fn smr_flush +can be called from process context. +.Sh SEE ALSO +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr SMR_LIST_INIT 9 , +.Xr SMR_PTR_GET 9 +.Sh HISTORY +The SMR API first appeared in +.Ox 6.5 . diff --git a/static/openbsd/man9/socreate.9 b/static/openbsd/man9/socreate.9 new file mode 100644 index 00000000..6da51de8 --- /dev/null +++ b/static/openbsd/man9/socreate.9 @@ -0,0 +1,312 @@ +.\" $OpenBSD: socreate.9,v 1.11 2022/09/11 06:38:11 jmc Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/socket.9,v 1.2 2006/12/16 10:32:10 rwatson Exp $ +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt SOCREATE 9 +.Os +.Sh NAME +.Nm sobind , +.Nm soclose , +.Nm soconnect , +.Nm socreate , +.Nm soreceive , +.Nm so_upcall , +.Nm sosetopt , +.Nm sogetopt , +.Nm sosend , +.Nm soshutdown +.Nd kernel socket interface +.Sh SYNOPSIS +.In sys/socket.h +.In sys/socketvar.h +.Ft int +.Fn sobind "struct socket *so" "struct mbuf *nam" "struct proc *p" +.Ft void +.Fn soclose "struct socket *so" "int flags" +.Ft int +.Fn soconnect "struct socket *so" "struct mbuf *nam" +.Ft int +.Fo socreate +.Fa "int dom" "struct socket **aso" "int type" "int proto" +.Fc +.Ft int +.Fo soreceive +.Fa "struct socket *so" "struct mbuf **paddr" "struct uio *uio" +.Fa "struct mbuf **mp0" "struct mbuf **controlp" "int *flagsp" +.Fa "socklen_t controllen" +.Fc +.Ft void +.Fn (*so_upcall) "struct socket *so" "caddr_t arg" "int waitflag" +.Ft int +.Fn sosetopt "struct socket *so" "int level" "int optname" "struct mbuf *m" +.Ft int +.Fn sogetopt "struct socket *so" "int level" "int optname" "struct mbuf *m" +.Ft int +.Fo sosend +.Fa "struct socket *so" "struct mbuf *addr" "struct uio *uio" +.Fa "struct mbuf *top" "struct mbuf *control" "int flags" +.Fc +.Ft int +.Fn soshutdown "struct socket *so" "int how" +.Sh DESCRIPTION +The kernel socket +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. +.Pp +Except where otherwise indicated, +.Nm +functions may sleep. +.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. +.Em Warning : +authorization of the socket creation operation will be performed +using +.Dv curproc +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 . +.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 process +.Fa p . +.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 +.Dv curproc . +Unlike the user system call, +.Fn soconnect +returns immediately; the caller may +.Xr tsleep 9 +on +.Fa so->so_timeo +and wait 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 +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. +.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 next two arguments in both +.Fn sogetopt +and +.Fn sosetopt +are +.Fa level +and +.Fa optname +describing the protocol level and socket option. +The last argument +.Fa m +is either a pointer to a prefilled mbuf or a pointer to an mbuf to retrieve +data. +.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 and awaiting 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. +If +.Fa mp0 +is not +.Dv NULL , +.Fa uio +must still be passed with uio_resid set to specify the maximum +amount of data to be returned to the caller via an mbuf chain. +The caller may optionally retrieve a socket address on a protocol with the +.Dv PR_ADDR +capability by providing storage via a +.Pf non- Dv NULL +.Fa paddr +argument. +The caller may optionally retrieve up to +.Fa controllen +bytes of control data in 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 +When the +.Fn so_upcall +function pointer is not +.Dv NULL , +it is called when +.Fn soreceive +matches an incoming connection. +.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 interrupt 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. +.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 tsleep 9 +.Sh HISTORY +The +.Xr socket 2 +system call appeared in +.Bx 4.2 . +This manual page was introduced in +.Fx 7.0 +and ported to +.Ox 4.5 . +.Sh AUTHORS +This manual page was written by +.An Robert Watson . +.Sh BUGS +The use of credentials hung from explicitly passed processes, +and the credential on +.Dv curproc , +and the cached credential from socket creation time is inconsistent, and may +lead to unexpected behaviour. +.Pp +The caller may need to manually clear +.Dv SS_ISCONNECTING +if +.Fn soconnect +returns an error. +.Pp +This manual page does not describe how to register socket upcalls or monitor +a socket for readability/writability without using blocking I/O. diff --git a/static/openbsd/man9/sosplice.9 b/static/openbsd/man9/sosplice.9 new file mode 100644 index 00000000..b51df25c --- /dev/null +++ b/static/openbsd/man9/sosplice.9 @@ -0,0 +1,279 @@ +.\" $OpenBSD: sosplice.9,v 1.11 2025/01/09 17:42:38 mvs Exp $ +.\" +.\" Copyright (c) 2011-2013 Alexander Bluhm +.\" +.\" 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 9 2025 $ +.Dt SOSPLICE 9 +.Os +.Sh NAME +.Nm sosplice , +.Nm somove +.Nd splice two sockets for zero-copy data transfer +.Sh SYNOPSIS +.Ft int +.Fn sosplice "struct socket *so" "int fd" "off_t max" "struct timeval *tv" +.Ft int +.Fn somove "struct socket *so" "int wait" +.Sh DESCRIPTION +The function +.Fn sosplice +is used to splice together a source and a drain socket. +The source socket is passed as the +.Fa so +argument; +the file descriptor of the drain is passed in +.Fa fd . +If +.Fa fd +is negative, an existing splicing gets dissolved. +If +.Fa max +is positive, at most that many bytes will get transferred. +If +.Fa tv +is not NULL, a +.Xr timeout 9 +is scheduled to dissolve splicing in the case when no data can be +transferred for the specified period of time. +Socket splicing can be invoked from userland via the +.Xr setsockopt 2 +system-call at the +.Dv SOL_SOCKET +level with the socket option +.Dv SO_SPLICE . +.Pp +Before connecting both sockets, several checks are executed. +See the +.Sx ERRORS +section for possible failures. +The connection between both sockets is implemented by setting these +additional fields in the +.Vt struct sosplice Va *so_sp +field in +.Vt struct socket : +.Pp +.Bl -dash -compact -offset indent +.It +.Vt struct socket Va *ssp_socket +links from the source to the drain socket. +.It +.Vt struct socket Va *ssp_soback +links back from the drain to the source socket. +.It +.Vt off_t Va ssp_len +counts the number of bytes spliced so far from this socket. +.It +.Vt off_t Va ssp_max +specifies the maximum number of bytes to splice from this socket if +non-zero. +.It +.Vt struct timeval Va ssp_idletv +specifies the maximum idle time if non-zero. +.It +.Vt struct timeout Va ssp_idleto +provides storage for the kernel timeout if idle time is used. +.El +.Pp +After connecting both sockets, +.Fn sosplice +calls +.Fn somove +to transfer the mbufs already in the source receive buffer to the +drain send buffer. +Finally the socket buffer flag +.Dv SB_SPLICE +is set on both socket buffers, to indicate that the protocol layer +has to call +.Fn somove +whenever data or space is available. +.Pp +The function +.Fn somove +transfers data from the source's receive buffer to the drain's send +buffer. +It must be called at +.Xr splsoftnet 9 +and +.Fa so +must be a spliced source socket. +It may be necessary to split an mbuf to handle out-of-band data +inline or when the maximum splice length has been reached. +If +.Fa wait +is +.Dv M_WAIT , +splitting mbufs will always succeed. +For +.Dv M_DONTWAIT +the out-of-band property might get lost or a short splice might +happen. +In the latter case, less than the given maximum number of bytes are +transferred and userland has to cope with this. +Note that a short splice cannot happen if +.Fn somove +was called by +.Fn sosplice . +So a second +.Xr setsockopt 2 +after a short splice pointing to the same maximum will always +succeed. +.Pp +Before transferring data, +.Fn somove +checks both sockets for errors and that the drain socket is connected. +If the drain cannot send anymore, an +.Er EPIPE +error is set on the source socket. +The data length to move is limited by the optional maximum splice +length and the space in the drain's send socket buffer. +Up to this amount of data is taken out of the source's receive +socket buffer. +To avoid splicing loops created by userland, the number of times +an mbuf may be moved between sockets is limited to 128. +.Pp +For atomic protocols, either one complete packet is taken out, or +nothing is taken at all if: +the packet is bigger than the drain's send buffer size, in which +case the splicing gets aborted with an +.Er EMSGSIZE +error; +the packet does not fit into the drain's current send buffer space, +in which case it is left in the source's receive buffer for later +processing; +or the maximum splice length is located within a packet, in which +case splicing gets dissolved like a short splice. +All address or control mbufs associated with the taken packet are +dropped. +.Pp +If the maximum splice length has been reached, an mbuf may get +split for non-atomic protocols. +Otherwise an mbuf is either moved completely to the send buffer or +left in the receive buffer for later processing. +If SO_OOBINLINE is set, out-of-band data will get moved as such +although this might not be reliable. +The data is sent out to the drain socket via the protocol function. +If that fails and the drain socket cannot send anymore, an +.Er EPIPE +error is set on the source socket. +.Pp +For packet oriented protocols +.Fn somove +iterates over the next packet queue. +.Pp +If a maximum splice length was specified and at least this amount +of data has been received from the drain socket, splicing gets +dissolved. +In this case, an +.Er EFBIG +error is set on the source socket if the maximum amount of data has +been transferred. +Userland can process this error to distinguish the full splice from +a short splice or to react to the completed maximum splice immediately. +If an idle timeout was specified and no data has been transferred +for that period of time, the handler +.Fn soidle +dissolves splicing and sets an +.Er ETIMEDOUT +error on the source socket. +.Pp +The function +.Fn sounsplice +is called to dissolve the socket splicing if the source socket +cannot receive anymore and its receive buffer is empty; or if the +drain socket cannot send anymore; or if the maximum has been reached; +or if an error occurred; or if the idle timeout has fired. +.Pp +If the socket buffer flag +.Dv SB_SPLICE +is set, the functions +.Fn sorwakeup +and +.Fn sowwakeup +will call +.Fn somove +to trigger the transfer when new data or buffer space is available. +While socket splicing is active, any +.Xr read 2 +from the source socket will block. +Neither read nor write wakeups will be delivered to the file +descriptors. +After dissolving, a read event or a socket error is signaled to +userland on the source socket. +If space is available, a write event will be signaled on the drain +socket. +.Sh RETURN VALUES +.Fn sosplice +returns 0 on success and otherwise the error number. +.Fn somove +returns 0 if socket splicing has been finished and 1 if it continues. +.Sh ERRORS +.Fn sosplice +will succeed unless: +.Bl -tag -width Er +.It Bq Er EBADF +The given file descriptor +.Fa fd +is not an active descriptor. +.It Bq Er EBUSY +The source or the drain socket is already spliced. +.It Bq Er EINVAL +The given maximum value +.Fa max +is negative. +.It Bq Er ENOTCONN +The source socket requires a connection and is neither connected +nor in the process of connecting to a peer. +.It Bq Er ENOTCONN +The drain socket is neither connected nor in the process of connecting +to a peer. +.It Bq Er EPROTO +The source socket is not spliced with the drain socket. +.It Bq Er ENOTSOCK +The given file descriptor +.Fa fd +is not a socket. +.It Bq Er EOPNOTSUPP +The source or the drain socket is a listen socket. +.It Bq Er EPROTONOSUPPORT +The source socket's protocol layer does not have the +.Dv PR_SPLICE +flag set. +Only TCP and UDP socket splicing is supported. +.It Bq Er EPROTONOSUPPORT +The drain socket's protocol does not have the same +.Fa pr_usrreq +function as the source. +.It Bq Er EWOULDBLOCK +The source socket is non-blocking and the receive buffer is already +locked. +.El +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr options 4 , +.Xr timeout 9 +.Sh HISTORY +Socket splicing for TCP first appeared in +.Ox 4.9 ; +support for UDP was added in +.Ox 5.3 . +.Sh AUTHORS +.An -nosplit +The idea for socket splicing originally came from +.An Markus Friedl Aq Mt markus@openbsd.org , +and +.An Alexander Bluhm Aq Mt bluhm@openbsd.org +implemented it. +.An Mike Belopuhov Aq Mt mikeb@openbsd.org +added the timeout feature. diff --git a/static/openbsd/man9/spl.9 b/static/openbsd/man9/spl.9 new file mode 100644 index 00000000..effcfb92 --- /dev/null +++ b/static/openbsd/man9/spl.9 @@ -0,0 +1,253 @@ +.\" $OpenBSD: spl.9,v 1.26 2016/08/16 23:49:35 dlg Exp $ +.\" $NetBSD: spl.9,v 1.1 1997/03/11 06:15:05 mikel Exp $ +.\" +.\" Copyright (c) 1997 Michael Long. +.\" Copyright (c) 1997 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. +.\" 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 $Mdocdate: August 16 2016 $ +.Dt SPLX 9 +.Os +.Sh NAME +.Nm splraise , +.Nm splhigh , +.Nm splserial , +.Nm splsched , +.Nm splclock , +.Nm splstatclock , +.Nm splvm , +.Nm spltty , +.Nm splsofttty , +.Nm splnet , +.Nm splbio , +.Nm splsoftnet , +.Nm splsoftclock , +.Nm spllowersoftclock , +.Nm spl0 , +.Nm splx , +.Nm splassert +.Nd modify system interrupt priority level +.Sh SYNOPSIS +.In machine/intr.h +.Ft int +.Fn splraise "int ipl" +.Ft int +.Fn splhigh void +.Ft int +.Fn splserial void +.Ft int +.Fn splsched void +.Ft int +.Fn splclock void +.Ft int +.Fn splstatclock void +.Ft int +.Fn splvm void +.Ft int +.Fn spltty void +.Ft int +.Fn splsofttty void +.Ft int +.Fn splnet void +.Ft int +.Fn splbio void +.Ft int +.Fn splsoftnet void +.Ft int +.Fn splsoftclock void +.Ft int +.Fn spllowersoftclock void +.Ft int +.Fn spl0 void +.Ft void +.Fn splx "int s" +.Ft void +.Fn splassert "int s" +.Sh DESCRIPTION +These functions raise and lower the system priority level. +They are used by kernel code to block interrupts with priority less +than or equal to the named level (i.e., +.Fn spltty +blocks interrupts of priority less than or equal to +.Dv IPL_TTY ) . +The code may then safely access variables and data structures which +are used by kernel code that runs at an equal or lower priority level. +.Pp +An +.Nm spl +function exists for each distinct priority level which can exist in +the system. +These macros and the corresponding priority levels are +used for various defined purposes, and may be divided into two main +types: hard and soft. +Hard interrupts are generated by hardware +devices, while soft interrupts are generated by callouts and called +from the kernel's periodic timer interrupt service routine. +.Pp +In order of highest to lowest priority, the priority-raising macros +are: +.Bl -tag -width splsoftclockXX +.It Fn splhigh +blocks all hard and soft interrupts. +It is used for code that cannot +tolerate any interrupts, like hardware context switching code and the +.Xr ddb 4 +in-kernel debugger. +.It Fn splserial +blocks hard interrupts from serial interfaces. +Code running at this level may not access the tty subsystem. +.It Fn splsched +blocks interrupts that may access scheduler data structures. +Specifically the clock interrupt that invokes the +.Fn schedclock +function needs to be blocked. +On some systems this is a separate clock; +on others it is the same as the statistics clock and, on these, +.Fn splsched +must block everything that +.Fn splstatclock +does. +Code running at or above this level may not call +.Xr tsleep 9 +or +.Xr wakeup 9 , +nor may it post signals. +Note that "running" means invoked by an interrupt handler that +operates at this level or higher. +Kernel code that operates in the context of a process and has called +.Fn splhigh +for blocking purposes can use +.Xr tsleep 9 +or +.Xr wakeup 9 . +.It Fn splclock +blocks the hardware clock interrupt. +It is used by +.Fn hardclock +to update kernel and process times, and must be used by any other code +that accesses time-related data. +.It Fn splstatclock +blocks the hardware statistics clock interrupt. +It is used by +.Fn statclock +to update kernel profiling and other statistics, and must be used by +any code that accesses that data. +This level is identical to +.Fn splclock +if there is no separate statistics clock. +.It Fn splvm +blocks hard interrupts from all devices that are allowed to use the +kernel +.Xr malloc 9 . +That includes all disk, network, and tty device interrupts. +.It Fn spltty +blocks hard interrupts from TTY devices. +.It Fn splsofttty +blocks soft interrupts generated by serial devices. +.It Fn splnet +blocks hard interrupts from network interfaces. +.It Fn splbio +blocks hard interrupts from disks and other mass-storage devices. +.It Fn splsoftnet +blocks soft network interrupts. +.It Fn splsoftclock +blocks soft clock interrupts. +.El +.Pp +Two macros lower the system priority level. +They are: +.Bl -tag -width spllowersoftclockXX +.It Fn spllowersoftclock +unblocks all interrupts but the soft clock interrupt. +.It Fn spl0 +unblocks all interrupts. +.El +.Pp +The +.Fn splraise +macro blocks interrupts at the interrupt priority level specified by +.Fa ipl . +.Pp +The +.Fn splx +macro restores the system priority level to the one encoded in +.Fa s , +which must be a value previously returned by one of the other +.Nm spl +macros. +.Pp +The +.Fn splassert +function checks that the system is running at a certain priority level. +The argument +.Fa s +should be one of these constants: +.Pp +.Bl -tag -width IPL_SOFTCLOCKXX -compact -offset indent +.It Dv IPL_STATCLOCK +.It Dv IPL_SCHED +.It Dv IPL_CLOCK +.It Dv IPL_VM +.It Dv IPL_BIO +.It Dv IPL_TTY +.It Dv IPL_NET +.It Dv IPL_SOFTNET +.It Dv IPL_SOFTCLOCK +.It Dv IPL_NONE +.El +.Pp +The +.Fn splassert +function is optional and is not necessarily implemented on +all architectures nor enabled in all kernel configurations. +It checks the current system priority level to see if it's +at least at the level specified in the argument +.Fa s . +If possible, it also checks if it hasn't been called from an +interrupt handler with a level higher than the one requested, which +must be an error (if some code is protected from +.Dv IPL_SOFTNET +interrupts, but accessed from an +.Dv IPL_NET +interrupt, it must be a design error in the code). +.Pp +The behavior of the +.Fn splassert +function is controlled by the kern.splassert +.Xr sysctl 8 . +Valid values for it are: +.Pp +.Bl -tag -width 1nr -compact -offset indent +.It 0 +disable error checking +.It 1 +print a message if an error is detected +.It 2 +print a message and a stack trace if possible +.It 3 +like 2 but also drop into the kernel debugger +.El +.Pp +Any other value causes a system panic on errors. diff --git a/static/openbsd/man9/srp_enter.9 b/static/openbsd/man9/srp_enter.9 new file mode 100644 index 00000000..c5825a67 --- /dev/null +++ b/static/openbsd/man9/srp_enter.9 @@ -0,0 +1,233 @@ +.\" $OpenBSD: srp_enter.9,v 1.17 2022/07/27 17:05:56 bluhm Exp $ +.\" +.\" Copyright (c) 2015 David Gwynne +.\" +.\" 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: July 27 2022 $ +.Dt SRP_ENTER 9 +.Os +.Sh NAME +.Nm srp_init , +.Nm srp_gc_init , +.Nm srp_update , +.Nm srp_update_locked , +.Nm srp_swap , +.Nm srp_swap_locked , +.Nm srp_enter , +.Nm srp_follow , +.Nm srp_leave , +.Nm srp_get_locked , +.Nm srp_finalize , +.Nm srp_gc_finalize , +.Nm SRP_INITIALIZER , +.Nm SRP_GC_INITIALIZER +.Nd shared reference pointers +.Sh SYNOPSIS +.In sys/srp.h +.Ft void +.Fn srp_init "struct srp *p" +.Ft void +.Fo srp_gc_init +.Fa "struct srp_gc *gc" +.Fa "void (*dtor)(void *, void *)" +.Fa "void *ctx" +.Fc +.Ft void * +.Fn srp_swap "struct srp *p" "void *v" +.Ft void * +.Fn srp_swap_locked "struct srp *p" "void *v" +.Ft void +.Fn srp_update "struct srp_gc *gc" "struct srp *p" "void *v" +.Ft void +.Fn srp_update_locked "struct srp_gc *gc" "struct srp *p" "void *v" +.Ft void * +.Fn srp_enter "struct srp_ref *sr" "struct srp *p" +.Ft void * +.Fn srp_follow "struct srp_ref *sr" "struct srp *n" +.Ft void +.Fn srp_leave "struct srp_ref *sr" +.Ft void * +.Fn srp_get_locked "struct srp *p" +.Ft void +.Fn srp_finalize "void *v" "const char *wmesg" +.Ft void +.Fn srp_gc_finalize "struct srp_gc *gc" +.Fn SRP_INITIALIZER +.Fo SRP_GC_INITIALIZER +.Fa "void (*dtor)(void *, void *)" +.Fa "void *ctx" +.Fc +.Sh DESCRIPTION +An +srp +structure represents a pointer or reference to an object in memory. +The +srp +API provides concurrent lock free access to these objects, and can +guarantee that the data isn't destroyed while that reference is in +use. +It does not prevent concurrent modification of the referenced object. +.Pp +.Fn srp_init +initialises the srp structure +.Fa p +to an empty state. +.Pp +.Fn srp_gc_init +initialises the srp_gc structure +.Fa gc +so it can be used as a garbage collector for data that gets referenced by srp +structures. +An update to an srp structure will cause the old data to be destroyed when it +is no longer referenced by any CPU in the system. +The old data will be destroyed by the garbage collector by a call to +.Fa dtor +with +.Fa ctx +as the first argument and the pointer to the data as the second argument. +.Pp +.Fn srp_update +and +.Fn srp_update_locked +replace the data referenced by the srp struct +.Fa p +with the data referenced by +.Fa v . +When the original data is no longer in use, it will be destroyed by the garbage +collector +.Fa gc . +.Fn srp_update +uses atomic CPU operations to change the references. +.Fn srp_update_locked +may be used if modifications to +.Fa p +are already serialised by the caller. +Both +.Fn srp_update +and +.Fn srp_update_locked +may sleep. +.Pp +.Fn srp_swap +and +.Fn srp_swap_locked +replace the data referenced by the srp struct +.Fa p +with the data referenced by +.Fa v . +When clearing or replacing the last reference to a data structure, +.Fn srp_finalize +must be used to ensure that the data is no longer in use via any srp +structures. +.Fn srp_swap +uses atomic CPU operations to change the reference. +.Fn srp_swap_locked +may be used if modifications to +.Fa p +are already serialised by the caller. +.Pp +.Fn srp_enter +returns a pointer to a data structure referenced by the srp struct +.Fa p +and guarantees it will remain available for use until it is released with a +call to +.Fn srp_leave +or +.Fn srp_follow . +The reference is held via +.Fa sr . +.Pp +.Fn srp_follow +replaces the reference held via +.Fa sr +with a reference to the data structure represented by +.Fa p . +.Pp +.Fn srp_leave +releases the reference held via +.Fa sr +and makes it available for garbage collection. +.Pp +.Fn srp_get_locked +provides access to the data referenced by the srp +.Fa p +if the caller has excluded updates to +.Fa p . +.Pp +.Fn srp_finalize +sleeps until there are no longer any references to +.Fa v +via any srp structure in the system. +.Pp +.Fn srp_gc_finalize +sleeps until all references to data by srp structures using the +garbage collector +.Fa gc +have completed. +That in turn means the +.Fa gc +structure will no longer be referenced and can itself be destroyed. +.Pp +A srp structure declaration can be initialised with the +.Fn SRP_INITIALIZER +macro. +.Pp +A srp_gc structure declaration can be initialised with the +.Fn SRP_GC_INITIALIZER +macro. +Data will be destroyed by the garbage collector by a call to +.Fa dtor +with +.Fa ctx +as the first argument and the pointer to the data as the second argument. +.Sh CONTEXT +.Fn srp_init , +.Fn srp_gc_init , +.Fn srp_update , +.Fn srp_update_locked , +.Fn srp_get_locked , +.Fn srp_finalize , +and +.Fn srp_gc_finalize +can be called during autoconf or from process context. +.Pp +.Fn srp_swap , +.Fn srp_swap_locked , +.Fn srp_enter , +.Fn srp_follow , +and +.Fn srp_leave +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn srp_swap +and +.Fn srp_swap_locked +return a pointer to the previous value referenced by the srp structure +.Fa p . +.Pp +.Fn srp_enter , +.Fn srp_follow , +and +.Fn srp_get_locked +return a pointer to the data referenced by the srp structure +.Fa p +or +.Dv NULL . +.Sh HISTORY +The srp API was originally written by +.An Jonathan Matthew Aq Mt jmatthew@openbsd.org +and +.An David Gwynne Aq Mt dlg@openbsd.org . +The srp API first appeared in +.Ox 5.8 . diff --git a/static/openbsd/man9/srpl_rc_init.9 b/static/openbsd/man9/srpl_rc_init.9 new file mode 100644 index 00000000..31ebde4d --- /dev/null +++ b/static/openbsd/man9/srpl_rc_init.9 @@ -0,0 +1,182 @@ +.\" $OpenBSD: srpl_rc_init.9,v 1.14 2016/11/21 07:11:13 dlg Exp $ +.\" +.\" Copyright (c) 2015 David Gwynne +.\" +.\" 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: November 21 2016 $ +.Dt SRPL_RC_INIT 9 +.Os +.Sh NAME +.Nm srpl_rc_init , +.Nm SRPL_HEAD , +.Nm SRPL_ENTRY , +.Nm SRPL_INIT , +.Nm SRPL_FIRST , +.Nm SRPL_NEXT , +.Nm SRPL_FOLLOW , +.Nm SRPL_FOREACH , +.Nm SRPL_LEAVE , +.Nm SRPL_RC_INITIALIZER +.Nd singly-linked shared reference pointer list +.Sh SYNOPSIS +.In sys/srp.h +.Vt struct srpl_rc; +.Ft void +.Fo "srpl_rc_init" +.Fa "struct srpl_rc *rc" +.Fa "void (*ref)(void *, void *)" +.Fa "void (*unref)(void *, void *)" +.Fa "void *ctx" +.Fc +.Fn SRPL_HEAD "HEADNAME" "TYPE" +.Fn SRPL_ENTRY "TYPE" +.Ft void +.Fn "SRPL_INIT" "SRPL_HEAD *sl" +.Ft void * +.Fn "SRPL_FIRST" "struct srp_ref *sr" "SRPL_HEAD *sl" +.Ft void * +.Fn "SRPL_NEXT" "struct srp_ref *sr" "struct TYPE *listelm" "FIELDNAME" +.Ft void * +.Fn "SRPL_FOLLOW" "struct srp_ref *sr" "struct TYPE *listelm" "FIELDNAME" +.Fo "SRPL_FOREACH" +.Fa "VARNAME" +.Fa "struct srp_ref *sr" +.Fa "SRPL_HEAD *sl" +.Fa "FIELDNAME" +.Fc +.Ft void +.Fn "SRPL_LEAVE" "struct srp_ref *sr" +.Fo "SRPL_RC_INITIALIZER" +.Fa "void (*ref)(void *, void *)" +.Fa "void (*unref)(void *, void *)" +.Fa "void *ctx" +.Fc +.Sh DESCRIPTION +The SRPL list +macros build a linked list on top of shared reference pointers. +This allows concurrent traversal of a linked list and access to the +items on the list. +.Pp +SRP lists are a generic type represented by a +.Vt SRPL_HEAD . +The elements inserted into the list must be structures that contain a +.Vt SRPL_ENTRY +field. +Further, the elements must also support reference counting as +insertion and removal operations can cause items to be temporarily +referenced by multiple SRPs within the list at the same time. +.Pp +.Fn srpl_rc_init +initialises the SRP list refcounts +.Fa rc +structure so it can be used to manage the reference counts on +elements in the list. +The insertion or removal of an element in an SRP list will increment +the reference counts on elements within the list via calls to +.Fa ref . +As these references are released by the SRP infrastructure, the +reference counts will be decremented by calls to +.Fa unref . +.Fa unref +is also responsible for freeing the element when the reference count +reaches 0. +Both +.Fa ref +and +.Fa unref +will be called with +.Fa ctx +as their first argument and a pointer to the element as their second +argument. +.Pp +.Fn SRPL_INIT +initialises the SRP list +.Fa sl +to an empty state. +.Pp +.Fn SRPL_FIRST +accesses the first element in the SRP list +.Fa sl +and holds its reference via +.Fa sr . +.Pp +.Fn SRPL_NEXT +accesses the element in the SRP list after +.Fa listelm +and holds its reference via +.Fa sr . +.\".Pp +.\"Every call to +.\".Fn SRPL_FIRST +.\"must have a corresponding call to +.\".Fn SRPL_LEAVE +.\"to release references to the list and its elements. +.Pp +.Fn SRPL_FOLLOW +accesses the element in the SRP list after +.Fa listelm +and swaps the previous reference held via +.Fa sr +for the reference of the newly accessed item. +.Pp +.Fn SRPL_FOREACH +creates a loop for traversing the list. +Every call to +.Fn SRPL_FOREACH +must have a corresponding call to +.Fn SRPL_LEAVE +to release references to the list and its elements. +.Pp +.Fn SRPL_LEAVE +releases references to the list and its elements held by previous +calls to +.Fn SRPL_FIRST , +.Fn SRPL_NEXT , +.Fn SRPL_FOLLOW , +or +.Fn SRPL_FOREACH . +.Pp +An srpl_rc declaration can be initialised with the +.Fn SRPL_RC_INITIALIZER +macro. +.Sh CONTEXT +.Fn SRPL_INIT , +.Fn SRPL_FIRST , +.Fn SRPL_NEXT , +.Fn SRPL_FOLLOW , +.Fn SRPL_FOREACH , +and +.Fn SRPL_LEAVE +may be called during autoconf, from process context, or from interrupt +context. +.Pp +.Fn srpl_rc_init , +may be called during autoconf or from process context. +.Sh RETURN VALUES +.Fn SRPL_FIRST , +.Fn SRPL_NEXT , +and +.Fn SRPL_FOLLOW +return a pointer to elements in the SRP list, or +.Dv NULL +if there are no more elements. +.Sh SEE ALSO +.Xr SRPL_FIRST_LOCKED 9 +.Sh HISTORY +The srp API was originally written by +.An Jonathan Matthew Aq Mt jmatthew@openbsd.org +and +.An David Gwynne Aq Mt dlg@openbsd.org . +The SRP list API first appeared in +.Ox 5.9 . diff --git a/static/openbsd/man9/startuphook_establish.9 b/static/openbsd/man9/startuphook_establish.9 new file mode 100644 index 00000000..c44d4910 --- /dev/null +++ b/static/openbsd/man9/startuphook_establish.9 @@ -0,0 +1,85 @@ +.\" $OpenBSD: startuphook_establish.9,v 1.8 2014/12/10 15:29:52 mikeb Exp $ +.\" +.\" Copyright (c) 1995 Niklas Hallqvist. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must 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 $Mdocdate: December 10 2014 $ +.Dt STARTUPHOOK_ESTABLISH 9 +.Os +.Sh NAME +.Nm startuphook_establish , +.Nm startuphook_disestablish +.Nd add or remove a startup hook +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void * +.Fn startuphook_establish "void (*fn)(void *)" "void *arg" +.Ft void +.Fn startuphook_disestablish "void *cookie" +.Sh DESCRIPTION +The +.Fn startuphook_establish +function adds +.Fa fn +to the list of hooks invoked by +.Xr dostartuphooks 9 +at startup. +When invoked, the hook function +.Fa fn +will be passed +.Fa arg +as its only argument. +.Pp +The +.Fn startuphook_disestablish +function removes the hook described by the opaque pointer +.Fa cookie +from the list of hooks to be invoked at startup. +If +.Fa cookie +is invalid, the result of +.Fn startuphook_disestablish +is undefined. +.Pp +Startup hooks should be used to perform one-time activities +that must happen immediately before the root and swap devices +are configured, but after normal device autoconfiguration. +.Pp +Startup hooks are implemented via the more general +.Xr dohooks 9 +API. +.Sh RETURN VALUES +If successful, +.Fn startuphook_establish +returns an opaque pointer describing the newly established +startup hook. +Otherwise, it returns +.Dv NULL . +.Sh SEE ALSO +.Xr dohooks 9 , +.Xr dostartuphooks 9 +.Sh BUGS +The names are clumsy, at best. diff --git a/static/openbsd/man9/stoeplitz_to_key.9 b/static/openbsd/man9/stoeplitz_to_key.9 new file mode 100644 index 00000000..c9401def --- /dev/null +++ b/static/openbsd/man9/stoeplitz_to_key.9 @@ -0,0 +1,136 @@ +.\" $OpenBSD: stoeplitz_to_key.9,v 1.8 2022/01/16 00:15:48 jsg Exp $ +.\" +.\" Copyright (c) 2020 David Gwynne +.\" +.\" 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 16 2022 $ +.Dt STOEPLITZ_TO_KEY 9 +.Os +.Sh NAME +.Nm stoeplitz_to_key , +.Nm stoeplitz_eaddr , +.Nm stoeplitz_ip4 , +.Nm stoeplitz_ip4port , +.Nm stoeplitz_ip6 , +.Nm stoeplitz_ip6port +.Nd symmetric Toeplitz hash API +.Sh SYNOPSIS +.In net/toeplitz.h +.Ft void +.Fn stoeplitz_to_key "void *key" "size_t keylen" +.Ft uint16_t +.Fo stoeplitz_eaddr +.Fa "const uint8_t *eaddr" +.Fc +.Ft uint16_t +.Fo stoeplitz_ip4 +.Fa "uint32_t srcaddr" +.Fa "uint32_t dstaddr" +.Fc +.Ft uint16_t +.Fo stoeplitz_ip4port +.Fa "uint32_t srcaddr" +.Fa "uint32_t dstaddr" +.Fa "uint16_t srcport" +.Fa "uint16_t dstport" +.Fc +.Ft uint16_t +.Fo stoeplitz_ip6 +.Fa "const struct in6_addr *srcaddr" +.Fa "const struct in6_addr *dstaddr" +.Fc +.Ft uint16_t +.Fo stoeplitz_ip6port +.Fa "const struct in6_addr *srcaddr" +.Fa "const struct in6_addr *dstaddr" +.Fa "uint16_t srcport" +.Fa "uint16_t dstport" +.Fc +.Sh DESCRIPTION +The Toeplitz hash algorithm is commonly used by network interface +controllers to generate a short hash based on the value of fields +in network packet headers. +.\" mention RSS? +The resulting hash value can be used as a flow identifier, which +in turn can be used to consistently select a context for processing +packets using those fields. +Traditionally, the Toeplitz hash produces different results depending +on the order of inputs, i.e. adding port 80 then 1234 as inputs would +produce a different result to hashing port 1234 then 80. +.Pp +The symmetric Toeplitz API uses a key selected to generate the same +hash result regardless of the order the inputs were added. +The API also supports producing Toeplitz hash keys for use by +network interface controllers that provide the same symmetric +property. +.Pp +The +.Fn stoeplitz_to_key +function generates a Toeplitz key for use by a network interface +controller based on the system's symmetric Toeplitz key. +A Toeplitz key of +.Fa keylen +bytes will be written to the buffer referenced by the +.Fa key +argument. +.Fa keylen +must be a multiple of 2 bytes. +.Pp +.Fn stoeplitz_eaddr +calculates a hash value for a single Ethernet address. +.Pp +.Fn stoeplitz_ip4 +calculates a hash value for a pair of IPv4 addresses. +.Pp +.Fn stoeplitz_ip4port +calculates a hash value for a pair of IPv4 addresses and ports as +used by protocols like TCP or UDP. +.Pp +.Fn stoeplitz_ip6 +calculates a hash value for a pair of IPv6 addresses. +.Pp +.Fn stoeplitz_ip6port +calculates a hash value for a pair of IPv6 addresses and ports as +used by protocols like TCP or UDP. +.Sh CONTEXT +.Fn stoeplitz_to_key , +.Fn stoeplitz_eaddr , +.Fn stoeplitz_ip4 , +.Fn stoeplitz_ip4port , +.Fn stoeplitz_ip6 , +and +.Fn stoeplitz_ip6port +can be called during autoconf, from process context, or from an +interrupt context. +.Sh RETURN VALUES +.Fn stoeplitz_eaddr , +.Fn stoeplitz_ip4 , +.Fn stoeplitz_ip4port , +.Fn stoeplitz_ip6 , +and +.Fn stoeplitz_ip6port +return a 16-bit hash value in host byte order. +.\" .Sh SEE ALSO +.\" .Xr mbuf 9 , +.\" .Xr spl 9 +.Sh HISTORY +The symmetric Toeplitz API is based on the ideas and implementation in +.Dx +by +.An Yanmin Qiao Aq Mt sephe@dragonflybsd.org +and +.An Simon Schubert Aq Mt corecode@fs.ei.tum.de . +.Pp +The API appeared in +.Ox 6.8 . diff --git a/static/openbsd/man9/strcmp.9 b/static/openbsd/man9/strcmp.9 new file mode 100644 index 00000000..0cf3b5f7 --- /dev/null +++ b/static/openbsd/man9/strcmp.9 @@ -0,0 +1,86 @@ +.\" $OpenBSD: strcmp.9,v 1.2 2018/04/23 11:11:38 jmc Exp $ +.\" +.\" Copyright (c) 2002, 2003 CubeSoft Communications, 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 ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, 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 $Mdocdate: April 23 2018 $ +.Dt STRCMP 9 +.Os +.Sh NAME +.Nm strlen , +.Nm strnlen , +.Nm strncpy , +.Nm strlcpy , +.Nm strlcat , +.Nm strcmp , +.Nm strncmp , +.Nm strncasecmp +.Nd kernel library string routines +.Sh SYNOPSIS +.In lib/libkern/libkern.h +.Ft size_t +.Fn strlen "const char *s" +.Ft size_t +.Fn strnlen "const char *s" "size_t maxlen" +.Ft char * +.Fn strncpy "char *dst" "const char *src" "size_t len" +.Ft size_t +.Fn strlcpy "char *dst" "const char *src" "size_t size" +.Ft size_t +.Fn strlcat "char *dst" "const char *src" "size_t size" +.Ft int +.Fn strcmp "const char *s1" "const char *s2" +.Ft int +.Fn strncmp "const char *s1" "const char *s2" "size_t len" +.Ft int +.Fn strncasecmp "const char *s1" "const char *s2" "size_tlen" +.Sh DESCRIPTION +These functions have the same semantics as their libc counterparts, +.Xr strlen 3 , +.Xr strncpy 3 , +.Xr strnlen 3 , +.Xr strlcpy 3 , +.Xr strlcat 3 , +.Xr strcmp 3 , +.Xr strncmp 3 +and +.Xr strncasecmp 3 . +.Sh SEE ALSO +.Xr strcmp 3 , +.Xr strlcat 3 , +.Xr strlcpy 3 , +.Xr strlen 3 , +.Xr strncmp 3 , +.Xr strncpy 3 , +.Xr strnlen 3 +.Sh STANDARDS +The +.Fn strlen , +.Fn strncpy , +.Fn strcmp , +.Fn strncmp +and +.Fn strcasecmp +functions conform to +.St -ansiC . diff --git a/static/openbsd/man9/strnstr.9 b/static/openbsd/man9/strnstr.9 new file mode 100644 index 00000000..70cbd659 --- /dev/null +++ b/static/openbsd/man9/strnstr.9 @@ -0,0 +1,90 @@ +.\" $OpenBSD: strnstr.9,v 1.1 2023/12/21 02:57:14 jsg Exp $ +.\" +.\" Copyright (c) 2001 Mike Barcroft +.\" 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 +.\" Chris Torek and 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 $Mdocdate: December 21 2023 $ +.Dt STRNSTR 9 +.Os +.Sh NAME +.Nm strnstr +.Nd locate a substring in a string +.Sh SYNOPSIS +.In lib/libkern/libkern.h +.Ft char * +.Fn strnstr "const char *big" "const char *little" "size_t len" +.Sh DESCRIPTION +The +.Fn strnstr +function +locates the first occurrence of the null-terminated string +.Fa little +in the string +.Fa big , +where not more than +.Fa len +characters are searched. +Characters that appear after a +.Ql \e0 +character are not searched. +.Sh RETURN VALUES +If +.Fa little +is an empty string, +.Fa big +is returned; +if +.Fa little +occurs nowhere in +.Fa big , +.Dv NULL +is returned; +otherwise a pointer to the first character of the first occurrence of +.Fa little +is returned. +.Sh EXAMPLES +The following sets the pointer +.Va ptr +to +.Dv NULL , +because only the first 4 characters of +.Va largestring +are searched: +.Bd -literal -offset indent +const char *largestring = "Foo Bar Baz"; +const char *smallstring = "Bar"; +char *ptr; + +ptr = strnstr(largestring, smallstring, 4); +.Ed +.Sh SEE ALSO +.Xr memchr 9 diff --git a/static/openbsd/man9/style.9 b/static/openbsd/man9/style.9 new file mode 100644 index 00000000..b44e6a79 --- /dev/null +++ b/static/openbsd/man9/style.9 @@ -0,0 +1,614 @@ +.\" Copyright (c) 1995 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. +.\" +.\" $OpenBSD: style.9,v 1.79 2022/09/11 06:38:11 jmc Exp $ +.\" +.Dd $Mdocdate: September 11 2022 $ +.Dt STYLE 9 +.Os +.Sh NAME +.Nm style +.Nd Kernel source file style guide (KNF) +.Sh DESCRIPTION +This file specifies the preferred style for kernel source files in the +.Ox +source tree. +It is also a guide for preferred userspace code style. +These guidelines should be followed for all new code. +In general, code can be considered +.Dq new code +when it makes up about 50% or more of the file(s) involved. +This is enough to break precedents in the existing code and use the +current style guidelines. +.Bd -literal -offset indent +/* + * Style guide for the OpenBSD KNF (Kernel Normal Form). + */ + +/* + * VERY important single-line comments look like this. + */ + +/* Most single-line comments look like this. */ + +/* + * Multi-line comments look like this. Make them real sentences. + * Fill them so they look like real paragraphs. + */ +.Ed +.Pp +Kernel include files (i.e., +.In sys/*.h ) +come first; normally, you'll need +.In sys/types.h +OR +.In sys/param.h , +but not both! +.In sys/types.h +includes +.In sys/cdefs.h , +and it's okay to depend on that. +.Bd -literal -offset indent +#include /* Non-local includes in brackets. */ +.Ed +.Pp +If it's a network program, put the network include files next. +.Bd -literal -offset indent +#include +#include +#include +#include +.Ed +.Pp +Then there's a blank line, followed by the +.Pa /usr/include +files. +The +.Pa /usr/include +files, for the most part, should be sorted. +.Pp +Global pathnames are defined in +.Pa /usr/include/paths.h . +Pathnames local to the program go in +.Pa pathnames.h +in the local directory. +.Bd -literal -offset indent +#include +.Ed +.Pp +Then there's a blank line, and the user include files. +.Bd -literal -offset indent +#include "pathnames.h" /* Local includes in double quotes. */ +.Ed +.Pp +All non-static 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. +In the kernel, private functions do not require a prototype as long +as they are defined before they are used. +In userspace, functions local to one source module should be declared +.Ql static . +This should not be done in the kernel since it makes it impossible +to use the kernel debugger. +.Pp +Functions used from other files are prototyped in the +relevant include file. +.Pp +Functions that are used locally in more than one module go into a +separate header file, e.g., +.Pa extern.h . +.Pp +Prototypes should not have variable names associated with the types; i.e., +.Bd -literal -offset indent +void function(int); +.Ed +not: +.Bd -literal -offset indent -compact +void function(int a); +.Ed +.Pp +Prototypes may have an extra space after a tab to enable function names +to line up: +.Bd -literal -offset indent +static char *function(int, const char *); +static void usage(void); +.Ed +.Pp +There should be no space between the function name and the argument list. +.Pp +Use +.Li __dead +from +.In sys/cdefs.h +for functions that don't return, i.e., +.Bd -literal -offset indent +__dead void abort(void); +.Ed +.Pp +In header files, put function prototypes within +.Dv __BEGIN_DECLS / __END_DECLS +matching pairs. +This makes the header file usable from C++. +.Pp +Macros are capitalized and parenthesized, and should avoid side-effects. +If they are an inline expansion of a function, the function is defined +all in lowercase; the macro has the same name all in uppercase. +If the macro needs more than a single line, use braces. +Right-justify the backslashes, as the resulting definition is easier to read. +If the macro encapsulates a compound statement, enclose it in a +.Dq Li do +loop, +so that it can safely be used in +.Dq Li 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 -offset indent +#define MACRO(x, y) do { \e + variable = (x) + (y); \e + (y) += 2; \e +} while (0) +.Ed +.Pp +If a macro with arguments declares local variables, +those variables should use identifiers beginning with two underscores. +This is required for macros implementing C and POSIX interfaces +and recommended for all macros for consistency. +.Pp +Enumeration values are all uppercase. +.Bd -literal -offset indent +enum enumtype { ONE, TWO } et; +.Ed +.Pp +When defining unsigned integers, use +.Dq "unsigned int" +rather than just +.Dq "unsigned" ; +the latter has been a source of confusion in the past. +.Pp +When declaring variables in structures, declare them sorted by use, then +by size (largest to smallest), then by alphabetical order. +The first category normally doesn't apply, but there are exceptions. +Each one gets its own line. +Put a tab after the first word, i.e., use +.Ql int^Ix; +and +.Ql struct^Ifoo *x; . +.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 +.Dq Li extern +if they are declared in a header file. +.Bd -literal -offset indent +struct foo { + struct foo *next; /* List of active foo */ + struct mumble amumble; /* Comment for mumble */ + int bar; +}; +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 -offset indent +#include +struct foo { + LIST_ENTRY(foo) link; /* Queue macro glue for foo lists */ + struct mumble amumble; /* Comment for mumble */ + int bar; +}; +LIST_HEAD(, foo) foohead; /* Head of global foo list */ +.Ed +.Pp +Avoid using typedefs for structure types. +This makes it impossible +for applications to use pointers to such a structure opaquely, which +is both possible and beneficial when using an ordinary struct tag. +When convention requires a 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 -offset indent +/* + * 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[]) +{ + int aflag, bflag, ch, num; + const char *errstr; +.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 switch statement, unless +parts of the switch cascade. +Elements in a switch statement that cascade should have a FALLTHROUGH comment. +Numerical arguments should be checked for accuracy. +.Bd -literal -offset indent +while ((ch = getopt(argc, argv, "abn:")) != -1) { + switch (ch) { /* Indent the switch. */ + case 'a': /* Don't indent the case. */ + aflag = 1; + /* FALLTHROUGH */ + case 'b': + bflag = 1; + break; + case 'n': + num = strtonum(optarg, 0, INT_MAX, &errstr); + if (errstr) { + warnx("number is %s: %s", errstr, optarg); + usage(); + } + break; + default: + usage(); + } +} +argc -= optind; +argv += optind; +.Ed +.Pp +Use a space after keywords +.Pf ( Li if , +.Li while , +.Li for , +.Li return , +.Li switch ) . +No braces are +used for control statements with zero or only a single statement unless that +statement is more than a single line, in which case they are permitted. +.Bd -literal -offset indent +for (p = buf; *p != '\e0'; ++p) + continue; +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; +} +.Ed +.Pp +Parts of a for loop may be left empty. +.Bd -literal -offset indent +for (; cnt < 15; cnt++) { + stmt1; + stmt2; +} +.Ed +.Pp +Indentation is an 8 character tab. +Second level indents are four spaces. +All code should fit in 80 columns. +.Bd -literal -offset indent +while (cnt < 20) + 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 else. +Braces that aren't necessary may be left out, unless they cause +a compiler warning. +.Bd -literal -offset indent +if (test) + stmt; +else if (bar) { + stmt; + stmt; +} else + stmt; +.Ed +.Pp +Do not use spaces after function names. +Commas have a space after them. +Do not use spaces after +.Sq \&( +or +.Sq \&[ +or preceding +.Sq \&] +or +.Sq \&) +characters. +.Bd -literal -offset indent +if ((error = function(a1, a2))) + exit(error); +.Ed +.Pp +Unary operators don't require spaces; binary operators do. +Don't use parentheses unless they're required for precedence, the statement +is confusing without them, or the compiler generates a warning without them. +Remember that other people may be confused more easily than you. +Do YOU understand the following? +.Bd -literal -offset indent +a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; +k = !(l & FLAGS); +.Ed +.Pp +Exits should be 0 on success, or non-zero for errors. +.Bd -literal -offset indent +/* + * Avoid obvious comments such as + * "Exit 0 on success." + */ +exit(0); +.Ed +.Pp +The function type should be on a line by itself +preceding the function. +.Bd -literal -offset indent +static char * +function(int a1, int a2, float fl, int a4) +{ +.Ed +.Pp +When declaring variables in functions, declare them sorted by size (largest to +smallest), then in alphabetical order; multiple ones per line are okay. +If a line overflows, reuse the type keyword. +.Pp +Be careful not to obfuscate the code by initializing variables in +the declarations. +Use this feature only thoughtfully. +DO NOT use function calls in initializers! +.Bd -literal -offset indent +struct foo one, *two; +double three; +int *four, five; +char *six, seven, eight, nine, ten, eleven, twelve; + +four = myfunction(); +.Ed +.Pp +Do not declare functions inside other functions. +.Pp +Casts and +.Fn sizeof +calls are not followed by a space. +Note that +.Xr indent 1 +does not understand this rule. +.Pp +Use of the +.Dq register +specifier is discouraged in new code. +Optimizing compilers such as gcc can generally do a better job +of choosing which variables to place in registers to improve +code performance. +The exception to this is in functions containing assembly code where the +.Dq register +specifier is required for proper code generation in the absence of +compiler optimization. +.Pp +When using +.Fn longjmp +or +.Fn vfork +in a program, the +.Fl W +or +.Fl Wall +flag should be used to verify that the compiler does not generate +warnings such as +.Bd -literal -offset indent +warning: variable `foo' might be clobbered by `longjmp' or `vfork'. +.Ed +.Pp +If any warnings of this type occur, you must apply the +.Dq volatile +type-qualifier to the variable in question. +Failure to do so may result in improper code generation when optimization +is enabled. +Note that for pointers, the location of +.Dq volatile +specifies if the type-qualifier applies to the pointer, or the thing being +pointed to. +A volatile pointer is declared with +.Dq volatile +to the right of the +.Dq * . +Example: +.Bd -literal -offset indent +char *volatile foo; +.Ed +.Pp +says that +.Dq foo +is volatile, but +.Dq *foo +is not. +To make +.Dq *foo +volatile use the syntax +.Bd -literal -offset indent +volatile char *foo; +.Ed +.Pp +If both the pointer and the thing pointed to are volatile, use +.Bd -literal -offset indent +volatile char *volatile foo; +.Ed +.Pp +.Dq const +is also a type-qualifier and the same rules apply. +The description of a read-only hardware register might look something like: +.Bd -literal -offset indent +const volatile char *reg; +.Ed +.Pp +Global flags set inside signal handlers should be of type +.Dq volatile sig_atomic_t +if possible. +This guarantees that the variable may be accessed as an atomic entity, +even when a signal has been delivered. +Global variables of other types (such as structures) are not +guaranteed to have consistent values when accessed via a signal handler. +.Pp +.Dv NULL +is the preferred null pointer constant. +Use +.Dv NULL +instead of +(type\ *)0 or (type\ *)NULL in all cases except for arguments to variadic +functions where the compiler does not know the type. +.Pp +Don't use +.Ql \&! +for tests unless it's a boolean, i.e., use +.Bd -literal -offset indent +if (*p == '\e0') +.Ed +not +.Bd -literal -offset indent -compact +if (!*p) +.Ed +.Pp +Routines returning +.Vt void * +should not have their return values cast to any pointer type. +.Pp +Use the +.Xr err 3 +and +.Xr warn 3 +family of functions. +Don't roll your own! +.Bd -literal -offset indent +if ((four = malloc(sizeof(struct foo))) == NULL) + err(1, NULL); +if ((six = (int *)overflow()) == NULL) + errx(1, "Number overflowed."); +return eight; +.Ed +.Pp +Always use ANSI function definitions. +Long parameter lists are wrapped with a normal four space indent. +.Pp +Variable numbers of arguments should look like this: +.Bd -literal -offset indent +#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 +Usage statements should take the same form as the synopsis in manual pages. +Options without +operands come first, in alphabetical order inside a single set of +braces, followed by options with operands, in alphabetical order, +each in braces, followed by required arguments in the order they +are specified, followed by optional arguments in the order they +are specified. +.Pp +A bar +.Pq Sq \&| +separates either-or options/arguments, +and multiple options/arguments which are specified together are +placed in a single set of braces. +.Pp +If numbers are used as options, they should be placed first, +as shown in the example below. +Uppercase letters take precedence over lowercase. +.Bd -literal -offset indent +"usage: f [-12aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en" +"usage: f [-a | -b] [-c [-de] [-n number]]\en" +.Ed +.Pp +The +.Xr getprogname 3 +function may be used instead of hard-coding the program name. +.Bd -literal -offset indent +fprintf(stderr, "usage: %s [-ab]\en", getprogname()); +exit(1); +.Ed +.Pp +New core kernel code should be reasonably compliant with the style guides. +The guidelines for third-party maintained modules and device drivers are more +relaxed but at a minimum should be internally consistent with their style. +.Pp +Whenever possible, code should be run through a code checker +(e.g., +.Dq Li gcc -Wall -W -Wpointer-arith -Wbad-function-cast ...\& +or splint from the ports tree) and produce minimal warnings. +Since lint has been removed, the only lint-style comment that should +be used is FALLTHROUGH, as it's useful to humans. +Other lint-style comments such as ARGSUSED, LINTED, and NOTREACHED +may be deleted. +.Pp +Note that documentation follows its own style guide, +as documented in +.Xr mdoc 7 . +.Sh FILES +.Bl -tag -width "/usr/share/misc/license.template " -compact +.It Pa /usr/share/misc/license.template +Example license for new code. +.El +.Sh SEE ALSO +.Xr indent 1 , +.Xr err 3 , +.Xr queue 3 , +.Xr warn 3 , +.Xr mdoc 7 +.Sh HISTORY +This man page is largely based on the src/admin/style/style file from the +.Bx 4.4 Lite2 +release, with updates to reflect the current practice and +desire of the +.Ox +project. diff --git a/static/openbsd/man9/syscall.9 b/static/openbsd/man9/syscall.9 new file mode 100644 index 00000000..32bad940 --- /dev/null +++ b/static/openbsd/man9/syscall.9 @@ -0,0 +1,244 @@ +.\" $OpenBSD: syscall.9,v 1.16 2023/12/13 06:39:10 jmc Exp $ +.\" +.\" Copyright (c) 2003 Michael Shalayeff +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 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 $Mdocdate: December 13 2023 $ +.Dt SYSCALL 9 +.Os +.Sh NAME +.Nm syscall +.Nd system calls overview +.Sh DESCRIPTION +System calls in the kernel are implemented through a set of +switch tables for each emulation type. +Each table is generated from the +.Dq master +file by +.Pa sys/kern/makesyscalls.sh +through the appropriate rules in the +.Pa Makefile . +.Pp +The +.Dq master +file is a text file consisting of a list of lines for each +system call. +Lines may be split by the means of back slashing the end of the line. +Each line is a set of fields separated by whitespace: +.Pp +.D1 Cd number type ... +.Pp +Where: +.Bl -tag -width number -compact +.It number +is the system call number; +.It type +is one of: +.Bl -tag -width COMPAT_XXX -compact +.It STD +always included; +.It OBSOL +obsolete, not included in the system; +.It UNIMPL +unimplemented, not included in the system; +.It NODEF +included, but don't define the syscall number; +.It NOARGS +included, but don't define the syscall args structure; +.It INDIR +included, but don't define the syscall args structure, +and allow it to be "really" varargs; +.It COMPAT_XX +a compatibility system call, only included if the corresponding +option is configured for the kernel (see +.Xr options 4 ) . +.El +.El +.Pp +The rest of the line for the STD, NODEF, NOARGS, and COMPAT_XX +types is: +.Pp +.D1 Cd { pseudo-proto } [alias] +.Pp +.Nm pseudo-proto +is a C-like prototype used to generate the system call argument list, +and alias is an optional name alias for the call. +The function in the prototype has to be defined somewhere in +the kernel sources as it will be used as an entry point for +the corresponding system call. +.Pp +For other types the rest of the line is a comment. +.Pp +To generate the header and code files from the +.Dq master +file a +.Xr make 1 +command has to be run from the directory containing the +.Dq master +file. +.Ss Usage +Entry from the user space for the system call is machine dependent. +Typical code to invoke a system call from the machine dependent +sources might look like this: +.Bd -literal -offset indent + + const struct sysent *callp; + register_t code, args[8], rval[2]; + struct proc *p = curproc; + int code, nsys; + +\&... + +/* "code" is the system call number passed from the user space */ + +\&... + +if (code < 0 || code >= nsys) + callp += p->p_emul->e_nosys; /* illegal */ +else + callp += code; + +/* copyin the arguments from the user space */ +\&... + rval[0] = 0; + +/* the following steps are now performed using mi_syscall() */ +#ifdef SYSCALL_DEBUG + scdebug_call(p, code, args); +#endif +#ifdef KTRACE + if (KTRPOINT(p, KTR_SYSCALL)) + ktrsyscall(p, code, argsize, args); +#endif + error = (*callp->sy_call)(p, args, rval); + + switch (error) { + case 0: + /* normal return */ + \&... + break; + case ERESTART: + /* + * adjust PC to point before the system call + * in the user space in order for the return + * back there we reenter the kernel to repeat + * the same system call + */ + \&... + break; + case EJUSTRETURN: + /* just return */ + break; + default: + /* + * an error returned: + * call an optional emulation errno mapping + * routine and return back to the user. + */ + if (p->p_emul->e_errno) + error = p->p_emul->e_errno[error]; + \&... + break; + } + +/* the following steps are now performed using mi_syscall_return() */ +#ifdef SYSCALL_DEBUG + scdebug_ret(p, code, orig_error, rval); +#endif + userret(p); +#ifdef KTRACE + if (KTRPOINT(p, KTR_SYSRET)) + ktrsysret(p, code, orig_error, rval[0]); +#endif + +.Ed +.Pp +The +.Dv SYSCALL_DEBUG +parts of the code are explained in the +.Sx Debugging +section below. +For the +.Dv KTRACE +portions of the code refer to the +.Xr ktrace 9 +document for further explanations. +.Ss Debugging +For debugging purposes the line +.Pp +.D1 Cd option SYSCALL_DEBUG +.Pp +should be included in the kernel configuration file (see +.Xr options 4 ) . +This allows tracing for calls, returns, and arguments for both +implemented and non-implemented system calls. +A global integer variable +.Va scdebug +contains a mask for the desired logging events: +.Pp +.Bl -tag -width SCDEBUG_SHOWARGS__ -compact +.It SCDEBUG_CALLS +(0x0001) show calls; +.It SCDEBUG_RETURNS +(0x0002) show returns; +.It SCDEBUG_ALL +(0x0004) show even syscalls that are implemented; +.It SCDEBUG_SHOWARGS +(0x0008) show arguments to calls. +.El +.Pp +Use +.Xr ddb 4 +to set +.Va scdebug +to the desired value. +.Sh CODE REFERENCES +.Bl -tag -width sys/kern/syscalls.master -compact +.It Pa sys/kern/makesyscalls.sh +a +.Xr sh 1 +script for generating C files out of the syscall master file; +.It Pa sys/kern/syscalls.conf +a configuration file for the shell script above; +.It Pa sys/kern/syscalls.master +master files describing names and numbers for the system calls; +.It Pa sys/kern/syscalls.c +system call names lists; +.It Pa sys/kern/init_sysent.c +system call switch tables; +.It Pa sys/sys/syscallargs.h +system call argument lists; +.It Pa sys/sys/syscall.h +system call numbers; +.It Pa sys/sys/syscall_mi.h +Machine-independent syscall entry end return handling. +.El +.Sh SEE ALSO +.Xr ktrace 2 , +.Xr ktrace 9 , +.Xr sysctl_int 9 +.Sh HISTORY +The +.Nm +section manual page appeared in +.Ox 3.4 . diff --git a/static/openbsd/man9/sysctl_int.9 b/static/openbsd/man9/sysctl_int.9 new file mode 100644 index 00000000..1755f85f --- /dev/null +++ b/static/openbsd/man9/sysctl_int.9 @@ -0,0 +1,281 @@ +.\" $OpenBSD: sysctl_int.9,v 1.9 2020/09/01 01:57:15 gnezdo Exp $ +.\" +.\" Copyright (c) 2006 Michael Shalayeff +.\" 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 $Mdocdate: September 1 2020 $ +.Dt SYSCTL_INT 9 +.Os +.Sh NAME +.Nm sysctl_int , +.Nm sysctl_bounded_arr , +.Nm sysctl_quad , +.Nm sysctl_string , +.Nm sysctl_tstring , +.Nm sysctl_rdint , +.Nm sysctl_rdquad , +.Nm sysctl_rdstring , +.Nm sysctl_rdstruct , +.Nm sysctl_struct +.Nd kernel sysctl interface +.Sh SYNOPSIS +.In sys/types.h +.In sys/sysctl.h +.Ft int +.Fo sysctl_int +.Fa "void *oldp" +.Fa "size_t *oldlenp" +.Fa "void *newp" +.Fa "size_t newlen" +.Fa "int *valp" +.Fc +.Ft int +.Fo sysctl_bounded_arr +.Fa "const struct sysctl_bounded_args *valpp" +.Fa "u_int valplen" +.Fa "int *name" +.Fa "u_int namelen" +.Fa "void *oldp" +.Fa "size_t *oldlenp" +.Fa "void *newp" +.Fa "size_t newlen" +.Fc +.Ft int +.Fo sysctl_quad +.Fa "void *oldp" +.Fa "size_t *oldlenp" +.Fa "void *newp" +.Fa "size_t newlen" +.Fa "int64_t *valp" +.Fc +.Ft int +.Fo sysctl_string +.Fa "void *oldp" +.Fa "size_t *oldlenp" +.Fa "void *newp" +.Fa "size_t newlen" +.Fa "char *str" +.Fa "int maxlen" +.Fc +.Ft int +.Fo sysctl_tstring +.Fa "void *oldp" +.Fa "size_t *oldlenp" +.Fa "void *newp" +.Fa "size_t newlen" +.Fa "char *str" +.Fa "int maxlen" +.Fc +.Ft int +.Fo sysctl_rdint +.Fa "void *oldp" +.Fa "size_t *oldlenp" +.Fa "void *newp" +.Fa "int val" +.Fc +.Ft int +.Fo sysctl_rdquad +.Fa "void *oldp" +.Fa "size_t *oldlenp" +.Fa "void *newp" +.Fa "int64_t val" +.Fc +.Ft int +.Fo sysctl_rdstring +.Fa "void *oldp" +.Fa "size_t *oldlenp" +.Fa "void *newp" +.Fa "const char *str" +.Fc +.Ft int +.Fo sysctl_rdstruct +.Fa "void *oldp" +.Fa "size_t *oldlenp" +.Fa "void *newp" +.Fa "const void *sp" +.Fa "int len" +.Fc +.Ft int +.Fo sysctl_struct +.Fa "void *oldp" +.Fa "size_t *oldlenp" +.Fa "void *newp" +.Fa "size_t newlen" +.Fa "void *sp" +.Fa "int len" +.Fc +.Sh DESCRIPTION +These functions and data structures aim to simplify and partially +implement operations for the kernel and user implementations of the +.Xr sysctl 2 +interface. +A single +.Xr syscall 9 +is used to request and modify kernel variables. +The +.Fa mib +argument is recursively scanned as an array of integers, either calling +further functions for parsing the rest of the MIB for nodes or operating +on kernel data for leaf nodes. +.Ss Data Structures +For each level of the MIB tree, the kernel header files provide a +.Xr cpp 1 +macro initialiser for an array of the following data structures: +.Bd -literal -offset indent +struct ctlname { + char *ctl_name; /* subsystem name */ + int ctl_type; /* type of name */ +}; +.Ed +.Pp +For example: +.Bd -literal -offset indent +#define CTL_NAMES { \e + { 0, 0 }, \e + { "kern", CTLTYPE_NODE }, \e + { "vm", CTLTYPE_NODE }, \e + { "fs", CTLTYPE_NODE }, \e + { "net", CTLTYPE_NODE }, \e + { "debug", CTLTYPE_NODE }, \e + { "hw", CTLTYPE_NODE }, \e + { "machdep", CTLTYPE_NODE }, \e + { "user", CTLTYPE_NODE }, \e + { "ddb", CTLTYPE_NODE }, \e + { "vfs", CTLTYPE_NODE }, \e +} +.Ed +.Pp +Each array element initialiser maps the correspondent MIB identifier. +The +.Fa ctl_name +field provides a string name. +The +.Fa ctl_type +field describes the identifier type, where possible values are: +.Pp +.Bl -tag -width CTLTYPE_STRING_ -compact -offset indent +.It CTLTYPE_NODE +The name is a node; +.It CTLTYPE_INT +The name describes an integer; +.It CTLTYPE_STRING +The name describes a string; +.It CTLTYPE_QUAD +The name describes a 64-bit number; +.It CTLTYPE_STRUCT +The name describes a structure. +.El +.Pp +For each of the types there are two functions provided to perform both +read and write or only a read operation on the identifier (see the +following subsection). +.Pp +These data structures are used by the +.Xr sysctl 8 +program to provide mapping into MIB identifiers. +.Ss Functions +All of the functions perform a write provided that +.Ar newp +is not a +.Dv NULL +pointer and +.Ar newlen +specifies an appropriate data length. +All read-only versions of the functions return +.Dv EPERM +if a write operation is requested. +.Pp +The following helper functions are provided to aid operation on the +kernel data variables referenced by the leaf nodes in the MIBs: +.Bl -tag -width sysctl_ +.It Fn sysctl_int "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "int *valp" +The variable referenced by +.Ar valp +is a 32-bit integer. +Read or write returning the previous value in the user memory location +pointed to by the +.Ar oldp +argument. +The value pointed to by +.Ar oldlenp +has to be no less than four. +.It Fn sysctl_rdint "void *oldp" "size_t *oldlenp" "void *newp" "int val" +A read-only version of the above. +.It Fn sysctl_bounded_arr "const struct sysctl_bounded_args *valpp" "u_int valplen" "int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" +Asserts the new value is in the range specified by the element of +.Ar valpp +with the value of the +.Va mib +field equal to +.Ar name[0] , +before invoking +.Fn sysctl_int +to read/write as normal. +.It Fn sysctl_quad "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "int64_t *valp" +The variable referenced is a 64-bit integer. +Read or write returning the previous value in the user memory location +pointed to by the +.Ar oldp +argument. +The value pointed to by +.Ar oldlenp +has to be no less than eight. +.It Fn sysctl_rdquad "void *oldp" "size_t *oldlenp" "void *newp" "int64_t val" +A read-only version of the above. +.It Fn sysctl_string "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "char *str" "int maxlen" +The variable referenced by the +.Ar str +argument is a string of maximum length of +.Ar maxlen . +The old value is copied out into a user buffer pointed to by the +.Ar oldp +argument. +If there is not enough space to store it, an +.Dv ENOMEM +is returned. +If +.Ar newlen +is larger than +.Ar maxlen , +an +.Dv EINVAL +error is returned. +.It Fn sysctl_tstring "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "char *str" "int maxlen" +A version of the above that truncates the old value that does not fit +into the buffer provided by +.Ar oldp +instead of returning +.Dv ENOMEM . +.It Fn sysctl_rdstring "void *oldp" "size_t *oldlenp" "void *newp" "const char *str" +A read-only version of +.Fn sysctl_string . +.It Fn sysctl_struct "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "void *sp" "int len" +Assume the area pointed to by the +.Ar sp +argument is an opaque array of bytes of size +.Ar len . +Old and new length checks are performed and data is copied in and/or out. +.It Fn sysctl_rdstruct "void *oldp" "size_t *oldlenp" "void *newp" "const void *sp" "int len" +A read-only version of the above. +.El +.Sh SEE ALSO +.Xr sysctl 2 , +.Xr sysctl.conf 5 , +.Xr sysctl 8 , +.Xr syscall 9 +.Sh HISTORY +These functions first appeared in +.Bx 4.4 . +.\" .Sh AUTHORS diff --git a/static/openbsd/man9/task_add.9 b/static/openbsd/man9/task_add.9 new file mode 100644 index 00000000..1d27044b --- /dev/null +++ b/static/openbsd/man9/task_add.9 @@ -0,0 +1,237 @@ +.\" $OpenBSD: task_add.9,v 1.23 2022/06/22 14:10:49 visa Exp $ +.\" +.\" Copyright (c) 2013 David Gwynne +.\" +.\" 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: June 22 2022 $ +.Dt TASK_ADD 9 +.Os +.Sh NAME +.Nm taskq_create , +.Nm taskq_destroy , +.Nm taskq_barrier , +.Nm taskq_del_barrier , +.Nm task_set , +.Nm task_add , +.Nm task_del , +.Nm task_pending , +.Nm TASK_INITIALIZER +.Nd task queues +.Sh SYNOPSIS +.In sys/task.h +.Ft struct taskq * +.Fo taskq_create +.Fa "const char *name" +.Fa "unsigned int nthreads" +.Fa "int ipl" +.Fa "unsigned int flags" +.Fc +.Ft void +.Fn taskq_destroy "struct taskq *tq" +.Ft void +.Fn taskq_barrier "struct taskq *tq" +.Ft void +.Fn taskq_del_barrier "struct taskq *tq" "struct task *t" +.Ft void +.Fn task_set "struct task *t" "void (*fn)(void *)" "void *arg" +.Ft int +.Fn task_add "struct taskq *tq" "struct task *t" +.Ft int +.Fn task_del "struct taskq *tq" "struct task *t" +.Ft int +.Fn task_pending "struct task *t" +.Vt extern struct taskq *const systq; +.Vt extern struct taskq *const systqmp; +.Fn TASK_INITIALIZER "void (*fn)(void *)" "void *arg" +.Sh DESCRIPTION +The +taskq +API provides a mechanism to defer work to a process context. +.Pp +.Fn taskq_create +allocates a taskq and a set of threads to be used to complete work +that would be inappropriate for the shared system taskq. +The +.Fa name +argument specifies the name of the kernel threads that are created +to service the work on the taskq. +.Fa nthreads +specifies the number of threads that will be created to handle the work. +.Fa ipl +specifies the highest interrupt protection level at which +.Fn task_add +and +.Fn task_del +will be called against the created taskq. +See +.Xr spl 9 +for a list of the IPLs. +The operational characteristics of the taskq +can be altered by OR'ing the following defines into the +.Fa flags +argument: +.Bl -tag -width xxx -offset indent +.It Dv TASKQ_MPSAFE +The threads servicing the taskq will be run without the kernel big lock. +.El +.Pp +.Fn taskq_destroy +causes the resources associated with a previously created taskq to be freed. +It will wait till all the tasks in the work queue are completed before +returning. +Calling +.Fn taskq_destroy +against the system taskq is an error and will lead to undefined +behaviour or a system fault. +.Pp +.Fn taskq_barrier +guarantees that any task that was running on the +.Fa tq +taskq when the barrier was called has finished by the time the barrier +returns. +.Pp +.Fn taskq_del_barrier +either removes +.Fa t +from the list of pending tasks on the +.Fa tq +taskq, or waits until any running task has completed. +.Pp +The caller of +.Fn taskq_barrier +or +.Fn taskq_del_barrier +must not hold locks that can block the taskq. +Otherwise, the system will deadlock. +.Pp +It is the responsibility of the caller to provide the +.Fn task_set , +.Fn task_add , +and +.Fn task_del +functions with pre-allocated task structures. +.Pp +.Fn task_set +prepares the task structure +.Fa t +to be used in future calls to +.Fn task_add +and +.Fn task_del . +.Fa t +will be prepared to call the function +.Fa fn +with the argument specified by +.Fa arg . +Once initialised, the +.Fa t +structure can be used repeatedly in calls to +.Fn task_add +and +.Fn task_del +and does not need to be reinitialised unless the function called +and/or its argument must change. +.Pp +.Fn task_add +schedules the execution of the work specified by the +task structure +.Fa t +on the +.Fa tq +taskq. +The task structure must already be initialised by +.Fn task_set . +.Pp +.Fn task_del +will remove the task structure +.Fa t +from the taskq +.Fa tq . +If the work was already executed or has not been added to the taskq, +the call will have no effect. +Calling +.Fn task_del +against a different taskq than the one given in a previous call to +.Fn task_add +is an error and will lead to undefined behaviour. +.Pp +The kernel provides two system taskqs: +.Va systq , +which executes while holding the kernel lock, and +.Va systqmp , +which does not hold the kernel lock during execution. +They can both be used by any subsystem for short lived tasks. +They are serviced by a single thread and can therefore provide predictable +ordering of work. +Work can be scheduled on the system taskqs from callers at or below IPL_HIGH. +.Pp +The +.Fn task_pending +macro can be used to check if a task is scheduled to run. +.Pp +A task declaration can be initialised with the +.Fn TASK_INITIALIZER +macro. +The task will be prepared to call the function specified by the +.Fa fn +argument with the +.Fa void * +argument given in +.Fa arg . +.Sh CONTEXT +.Fn taskq_create +and +.Fn taskq_destroy +can be called during autoconf, or from process context. +.Fn taskq_barrier +and +.Fn taskq_del_barrier +can be called from process context. +.Fn task_set , +.Fn task_add , +.Fn task_del , +and +.Fn task_pending +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn taskq_create +returns a pointer to a taskq structure on success or +.Dv NULL +on failure. +.Pp +.Fn task_add +will return 1 if the task +.Fa t +was added to the taskq +.Fa tq +or 0 if the task was already queued. +.Pp +.Fn task_del +will return 1 if the task +.Fa t +was removed from the taskq +.Fa tq +or 0 if the task was not already on the queue. +.Pp +.Fn task_pending +will return non-zero if the task is queued to run, or 0 if the task +is not queued. +.Sh SEE ALSO +.Xr autoconf 9 , +.Xr spl 9 +.Sh HISTORY +The task API was originally written by +.An David Gwynne Aq Mt dlg@openbsd.org . +The task API first appeared in +.Ox 5.5 . diff --git a/static/openbsd/man9/tc_init.9 b/static/openbsd/man9/tc_init.9 new file mode 100644 index 00000000..53446c84 --- /dev/null +++ b/static/openbsd/man9/tc_init.9 @@ -0,0 +1,141 @@ +.\" $OpenBSD: tc_init.9,v 1.12 2023/04/02 00:02:26 cheloha Exp $ +.\" +.\" Copyright (c) 2004 Alexander Yurchenko +.\" Copyright (c) 2023 Scott Cheloha +.\" +.\" 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: April 2 2023 $ +.Dt TC_INIT 9 +.Os +.Sh NAME +.Nm tc_init +.Nd timecounting subsystem +.Sh SYNOPSIS +.In sys/timetc.h +.Ft void +.Fn tc_init "struct timecounter *tc" +.Sh DESCRIPTION +The +.Sy timecounting +subsystem implements a uniform interface to timekeeping hardware, +measures the passage of time, +and implements the kernel's software clocks +.Po see +.Xr microtime 9 +for details +.Pc . +.Pp +A hardware clock is suitable for counting time if it meets the following +requirements: +.Bl -enum -offset indent +.It +It is a binary counter. +.It +It advances at a fixed, known frequency. +.It +Its count is synchronized between all CPUs on the system. +.It +It continues counting when it rolls over. +.It +If +.Xr hz 9 +is less than or equal to one millisecond, +the counter does not roll over in less than two milliseconds. +If +.Xr hz 9 +exceeds one millisecond, +the counter does not roll over in less than +.Pq 2 / Va hz +seconds. +.El +.Pp +Hardware clocks are described with a +.Va timecounter +structure: +.Bd -literal -offset indent +struct timecounter { + u_int (*tc_get_timecount)(struct timecounter *); + u_int tc_counter_mask; + u_int64_t tc_frequency; + char *tc_name; + int tc_quality; + void *tc_priv; + u_int tc_user; +}; +.Ed +.Bl -tag -width indent +.It Ft u_int Fn (*tc_get_timecount) "struct timecounter *" +Reads the hardware clock and returns its count. +Any unimplemented bits only need to be masked if they are not constant. +If the counter is larger than 32 bits, +this function must return a 32-bit subset. +The subsystem requires an upward count; +downward counts must be inverted before they are returned. +.It Va tc_counter_mask +The mask of implemented bits. +Used to discard unimplemented bits from +.Fn tc_get_timecount . +.It Va tc_frequency +The counter's fixed frequency. +.It Va tc_name +The counter's unique name. +A +.Dv NUL Ns -terminated string. +.It Va tc_quality +A relative quality metric used to compare counters. +Higher values indicate a better counter. +A negative value indicates that the counter is non-monotonic +or otherwise deficient. +The system will only use negative-quality counters if requested. +.It Va tc_priv +May point to anything the driver needs during +.Fn tc_get_timecount . +.It Va tc_user +If non-zero, +a unique value identifying the userspace implementation of +.Fn tc_get_timecount . +.El +.Pp +To register a timecounter, +a device driver initializes the above-described fields of a +.Va timecounter +structure and calls +.Fn tc_init +with a pointer to that structure as argument. +.Sh CONTEXT +.Fn tc_init +may only be called during autoconf. +.Sh CODE REFERENCES +.Pa sys/kern/kern_tc.c +.Sh SEE ALSO +.Xr amdpm 4 , +.Xr gscpm 4 , +.Xr ichpcib 4 , +.Xr viapm 4 , +.Xr hz 9 , +.Xr microtime 9 +.Rs +.%A Poul-Henning Kamp +.%T Timecounter: Efficient and precise timekeeping in SMP kernels +.%J The FreeBSD Project +.%D 2002 +.%U https://papers.freebsd.org/2002/phk-timecounters.files/timecounter.pdf +.Re +.Sh HISTORY +The timecounting subsystem first appeared in +.Fx 3.0 . +It was ported to +.Ox 3.6 . +.Sh AUTHORS +.An Poul-Henning Kamp diff --git a/static/openbsd/man9/tfind.9 b/static/openbsd/man9/tfind.9 new file mode 100644 index 00000000..18e3cdd1 --- /dev/null +++ b/static/openbsd/man9/tfind.9 @@ -0,0 +1,58 @@ +.\" $OpenBSD: tfind.9,v 1.3 2025/06/13 18:34:00 schwarze Exp $ +.\" +.\" Copyright (c) 1999 Marc Espie +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list 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 $Mdocdate: June 13 2025 $ +.Dt TFIND 9 +.Os +.Sh NAME +.Nm tfind , +.Nm prfind , +.Nm pgfind +.Nd find thread, process and process group by number +.Sh SYNOPSIS +.In sys/types.h +.In sys/signal.h +.In sys/proc.h +.Ft struct proc * +.Fn tfind "pid_t tid" +.Ft struct process * +.Fn prfind "pid_t pid" +.Ft struct pgrp * +.Fn pgfind "pid_t pgid" +.Sh DESCRIPTION +The +.Fn tfind , +.Fn prfind , +and +.Fn pgfind +functions retrieve thread, process and process group structures from thread, +process and process group IDs, respectively. +.Pp +These functions return +.Dv NULL +if the requested ID can't be found. +.Sh CODE REFERENCES +Those functions are implemented in the file +.Pa sys/kern/kern_proc.c . diff --git a/static/openbsd/man9/thread_fork.9 b/static/openbsd/man9/thread_fork.9 new file mode 100644 index 00000000..33058252 --- /dev/null +++ b/static/openbsd/man9/thread_fork.9 @@ -0,0 +1,105 @@ +.\" $OpenBSD: thread_fork.9,v 1.2 2017/02/15 03:33:13 guenther Exp $ +.\" $NetBSD: fork1.9,v 1.3 1999/03/16 00:40:47 garbled Exp $ +.\" +.\" Copyright (c) 1998 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. +.\" +.Dd $Mdocdate: February 15 2017 $ +.Dt THREAD_FORK 9 +.Os +.Sh NAME +.Nm thread_fork +.Nd create a new thread inside a process +.Sh SYNOPSIS +.In sys/types.h +.In sys/proc.h +.Ft int +.Fo thread_fork +.Fa "struct proc *p1" +.Fa "void *stack" +.Fa "void *tcb" +.Fa "pid_t *tidptr" +.Fa "register_t *retval" +.Fc +.Sh DESCRIPTION +.Fn thread_fork +creates a new thread out of +.Ar p1 , +which should be the current thread. +This function is used to implement the +.Xr __tfork 3 +system call. +.Pp +.Fa stack , +which must not be +.Dv NULL , +will be used as the initial value of the new thread's stack pointer. +.Pp +If +.Fa tcb +is not +.Dv NULL , +it will be used as the initial address of the new thread's TCB +(thread control block). +.Pp +If +.Fa tidptr +is not +.Dv NULL , +the TID of the new thread will be copied out there on success. +This is guaranteed to be done before the new thread is started. +.Pp +On successful completion the TID of the new thread will be stored in +.Fa *retval . +.Sh RETURN VALUES +Upon successful completion of the operation, +.Fn thread_fork +returns 0. +Otherwise, the following error values are returned: +.Bl -tag -width [EAGAIN] +.It Bq Er EAGAIN +The system limit on the total number of threads would be exceeded. +.It Bq Er ENOMEM +There is insufficient swap space for the new thread. +.It Bq Er EINVAL +The +.Fa stack +argument was +.Dv NULL . +.El +.Sh SEE ALSO +.Xr __get_tcb 2 , +.Xr fork 2 , +.Xr __tfork 3 , +.Xr tfind 9 +.Sh HISTORY +The +.Fn thread_fork +function +appeared in +.Ox 6.1 . diff --git a/static/openbsd/man9/timeout.9 b/static/openbsd/man9/timeout.9 new file mode 100644 index 00000000..38ed038a --- /dev/null +++ b/static/openbsd/man9/timeout.9 @@ -0,0 +1,419 @@ +.\" $OpenBSD: timeout.9,v 1.60 2025/05/23 23:56:15 dlg Exp $ +.\" +.\" Copyright (c) 2000 Artur Grabowski +.\" Copyright (c) 2021, 2022 Scott Cheloha +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the 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 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" 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 $Mdocdate: May 23 2025 $ +.Dt TIMEOUT_SET 9 +.Os +.Sh NAME +.Nm timeout_set , +.Nm timeout_set_flags , +.Nm timeout_set_proc , +.Nm timeout_add , +.Nm timeout_add_sec , +.Nm timeout_add_msec , +.Nm timeout_add_usec , +.Nm timeout_add_nsec , +.Nm timeout_abs_ts , +.Nm timeout_del , +.Nm timeout_del_barrier , +.Nm timeout_barrier , +.Nm timeout_pending , +.Nm timeout_initialized , +.Nm timeout_triggered , +.Nm TIMEOUT_INITIALIZER , +.Nm TIMEOUT_INITIALIZER_FLAGS +.Nd execute a function in the future +.Sh SYNOPSIS +.In sys/types.h +.In sys/timeout.h +.Ft void +.Fo timeout_set +.Fa "struct timeout *to" +.Fa "void (*fn)(void *)" +.Fa "void *arg" +.Fc +.Ft void +.Fo timeout_set_flags +.Fa "struct timeout *to" +.Fa "void (*fn)(void *)" +.Fa "void *arg" +.Fa "int kclock" +.Fa "int flags" +.Fc +.Ft void +.Fo timeout_set_proc +.Fa "struct timeout *to" +.Fa "void (*fn)(void *)" +.Fa "void *arg" +.Fc +.Ft int +.Fo timeout_add +.Fa "struct timeout *to" +.Fa "int nticks" +.Fc +.Ft int +.Fo timeout_add_sec +.Fa "struct timeout *to" +.Fa "int secs" +.Fc +.Ft int +.Fo timeout_add_msec +.Fa "struct timeout *to" +.Fa "uint64_t msecs" +.Fc +.Ft int +.Fo timeout_add_usec +.Fa "struct timeout *to" +.Fa "uint64_t usecs" +.Fc +.Ft int +.Fo timeout_add_nsec +.Fa "struct timeout *to" +.Fa "uint64_t nsecs" +.Fc +.Ft int +.Fo timeout_abs_ts +.Fa "struct timeout *to" +.Fa "const struct timespec *abs" +.Fc +.Ft int +.Fo timeout_del +.Fa "struct timeout *to" +.Fc +.Ft int +.Fo timeout_del_barrier +.Fa "struct timeout *to" +.Fc +.Ft void +.Fo timeout_barrier +.Fa "struct timeout *to" +.Fc +.Ft int +.Fo timeout_pending +.Fa "struct timeout *to" +.Fc +.Ft int +.Fo timeout_initialized +.Fa "struct timeout *to" +.Fc +.Ft int +.Fo timeout_triggered +.Fa "struct timeout *to" +.Fc +.Fo TIMEOUT_INITIALIZER +.Fa "void (*fn)(void *)" +.Fa "void *arg" +.Fc +.Fo TIMEOUT_INITIALIZER_FLAGS +.Fa "void (*fn)(void *)" +.Fa "void *arg" +.Fa "int kclock" +.Fa "int flags" +.Fc +.Sh DESCRIPTION +The +.Nm timeout +subsystem schedules functions for asynchronous execution in the future. +.Pp +All state is encapsulated in a +.Vt struct timeout +allocated by the caller. +A timeout must be initialized before it may be used as input to other +functions in the API. +Once initialized, +a timeout does not need to be reinitialized unless its function or argument +must change. +.Pp +The +.Fn timeout_set +function initializes the timeout +.Fa to . +When the timeout is executed, +the function +.Fa fn +will be called with +.Fa arg +as its sole parameter. +The timeout is implicitly scheduled against the +.Dv KCLOCK_NONE +clock and is not configured with any additional flags. +.Pp +The +.Fn timeout_set_flags +function is similar to +.Fn timeout_set , +except that it takes two additional parameters: +.Bl -tag -width kclock +.It Fa kclock +The timeout is scheduled against the given +.Fa kclock , +which must be one of the following: +.Bl -tag -width KCLOCK_UPTIME +.It Dv KCLOCK_NONE +Low resolution tick-based clock. +The granularity of this clock is limited by the +.Xr hardclock 9 , +which executes roughly +.Xr hz 9 +times per second. +.It Dv KCLOCK_UPTIME +The uptime clock. +Counts the time elapsed since the system booted. +.El +.It Fa flags +The timeout's behavior may be configured with the bitwise OR of +zero or more of the following +.Fa flags : +.Bl -tag -width TIMEOUT_MPSAFE +.It Dv TIMEOUT_PROC +Execute the timeout in a process context instead of the default +.Dv IPL_SOFTCLOCK +interrupt context. +.It Dv TIMEOUT_MPSAFE +Execute the timeout without the kernel lock. +Requires the +.Dv TIMEOUT_PROC +flag. +.El +.El +.Pp +The +.Fn timeout_set_proc +function is similar to +.Fn timeout_set , +except that the given timeout is configured with the +.Dv TIMEOUT_PROC +flag. +.Pp +A timeout may also be initialized statically. +The +.Fn TIMEOUT_INITIALIZER +macro is equivalent to the +.Fn timeout_set +function and the +.Fn TIMEOUT_INITIALIZER_FLAGS +macro is equivalent to the +.Fn timeout_set_flags +function. +.Pp +The interfaces available for scheduling a timeout vary with the +.Fa kclock +set during initialization. +.Pp +.Dv KCLOCK_NONE +timeouts may be scheduled with the function +.Fn timeout_add , +which schedules the given timeout to execute after at least +.Fa nticks +.Xr hardclock 9 +ticks have elapsed. +In practice, +.Fa nticks +ticks will usually elapse in slightly less than +.Pq Fa nticks Cm / Dv hz +seconds. +Negative values of +.Fa nticks +are illegal. +If +.Fa nticks +is zero it will be silently rounded up to one. +.Pp +For convenience, +.Dv KCLOCK_NONE +timeouts may also be scheduled with +.Fn timeout_add_sec , +.Fn timeout_add_msec , +.Fn timeout_add_usec , +or +.Fn timeout_add_nsec . +These wrapper functions convert their input durations to a count of +.Xr hardclock 9 +ticks before calling +.Fn timeout_add +to schedule the given timeout. +.Pp +Timeouts for any other +.Fa kclock +may be scheduled with +.Fn timeout_abs_ts , +which schedules the given timeout to execute at or after the absolute time +.Fa abs +has elapsed on the timeout's +.Fa kclock . +.Pp +Once scheduled, +a timeout is said to be +.Qq pending . +A pending timeout may not be reinitialized with +.Fn timeout_set , +.Fn timeout_set_flags , +or +.Fn timeout_set_proc +until it has been executed or it has been cancelled with +.Fn timeout_del +or +.Fn timeout_del_barrier . +A pending timeout may be rescheduled without first cancelling it with +.Fn timeout_del +or +.Fn timeout_del_barrier : +the new expiration time will quietly supersede the original. +.Pp +The function +.Fn timeout_del +cancels any pending execution of the given timeout. +.Pp +The +.Fn timeout_del_barrier +function is similar to +.Fn timeout_del , +except that it also blocks until any current execution of the given timeout +has completed. +.Pp +The +.Fn timeout_barrier +function blocks until any current execution of the given timeout +has completed. +.Pp +Callers of +.Fn timeout_barrier +and +.Fn timeout_del_barrier +must not hold locks that can block processing in the timeout's context. +Otherwise, the system will deadlock. +.Pp +The +.Fn timeout_pending +macro indicates whether the given timeout is scheduled for execution. +A timeout's pending status is cleared when it executes or is cancelled. +.Pp +The +.Fn timeout_initialized +macro indicates whether the given timeout has been initialized with +.Fn timeout_set +or +.Fn timeout_set_flags . +This macro must not be used unless the memory pointed to by +.Fa to +has been zeroed, +or its return value is meaningless. +.Pp +The +.Fn timeout_triggered +macro indicates whether the given timeout is executing or has finished +executing. +Rescheduling or cancelling a timeout clears its triggered status. +.Sh CONTEXT +.Fn timeout_set , +.Fn timeout_set_flags , +.Fn timeout_set_proc , +.Fn timeout_add , +.Fn timeout_add_sec , +.Fn timeout_add_msec , +.Fn timeout_add_usec , +.Fn timeout_add_nsec , +.Fn timeout_abs_ts , +.Fn timeout_del , +.Fn timeout_pending , +.Fn timeout_initialized , +and +.Fn timeout_triggered +may be called during autoconf, +from process context, +or from any interrupt context. +.Pp +.Fn timeout_barrier +and +.Fn timeout_del_barrier +may only be called from process context. +.Pp +When a timeout is executed, +the function +.Fa fn +set during initialization is called from the +.Dv IPL_SOFTCLOCK +interrupt context, +or a process context if the timeout was configured with the +.Dv TIMEOUT_PROC +flag. +The function +.Fa fn +must not block and must be safe to execute on any CPU in the system. +.Pp +Timeouts without the +.Dv TIMEOUT_MPSAFE +flag are executed under the kernel lock. +.Sh RETURN VALUES +.Fn timeout_add , +.Fn timeout_add_sec , +.Fn timeout_add_msec , +.Fn timeout_add_usec , +.Fn timeout_add_nsec , +and +.Fn timeout_abs_ts +return 1 if the timeout +.Fa to +is newly scheduled, +or zero if the timeout was already pending. +.Pp +.Fn timeout_del +and +.Fn timeout_del_barrier +return 1 if the timeout +.Fa to +was pending, +or zero otherwise. +.Pp +.Fn timeout_pending , +.Fn timeout_initialized , +and +.Fn timeout_triggered +return non-zero if the corresponding condition is true, +or zero otherwise. +.Sh CODE REFERENCES +.Pa sys/kern/kern_timeout.c +.Sh SEE ALSO +.Xr hardclock 9 , +.Xr hz 9 , +.Xr microtime 9 , +.Xr splclock 9 , +.Xr task_add 9 , +.Xr tsleep 9 , +.Xr tvtohz 9 +.Rs +.%A George Varghese +.%A Anthony Lauck +.%B Hashed and hierarchical timing wheels: efficient data structures for \ +implementing a timer facility +.%O especially Schemes 6 and 7 +.%I IEEE/ACM +.%J Transactions on Networking +.%V vol. 5 +.%N no. 6 +.%P pp. 824\(en834 +.%D December 1997 +.Re diff --git a/static/openbsd/man9/tsleep.9 b/static/openbsd/man9/tsleep.9 new file mode 100644 index 00000000..be46c21b --- /dev/null +++ b/static/openbsd/man9/tsleep.9 @@ -0,0 +1,287 @@ +.\" $OpenBSD: tsleep.9,v 1.18 2026/04/22 10:04:41 tb Exp $ +.\" $NetBSD: sleep.9,v 1.11 1999/03/24 06:15:12 mycroft 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 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 $Mdocdate: April 22 2026 $ +.Dt TSLEEP 9 +.Os +.Sh NAME +.Nm tsleep , +.Nm tsleep_nsec , +.Nm msleep , +.Nm msleep_nsec , +.Nm rwsleep , +.Nm rwsleep_nsec , +.Nm wakeup , +.Nm wakeup_n , +.Nm wakeup_one +.Nd process context sleep and wakeup +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.Fd #define INFSLP UINT64_MAX +.Fd #define MAXTSLP (UINT64_MAX - 1) +.Ft int +.Fo tsleep +.Fa "const volatile void *ident" +.Fa "int priority" +.Fa "const char *wmesg" +.Fa "int timo" +.Fc +.Ft int +.Fo tsleep_nsec +.Fa "const volatile void *ident" +.Fa "int priority" +.Fa "const char *wmesg" +.Fa "uint64_t nsecs" +.Fc +.Ft int +.Fo msleep +.Fa "const volatile void *ident" +.Fa "struct mutex *mtx" +.Fa "int priority" +.Fa "const char *wmesg" +.Fa "int timo" +.Fc +.Ft int +.Fo msleep_nsec +.Fa "const volatile void *ident" +.Fa "struct mutex *mtx" +.Fa "int priority" +.Fa "const char *wmesg" +.Fa "uint64_t nsecs" +.Fc +.Ft int +.Fo rwsleep +.Fa "const volatile void *ident" +.Fa "struct rwlock *rwl" +.Fa "int priority" +.Fa "const char *wmesg" +.Fa "int timo" +.Fc +.Ft int +.Fo rwsleep_nsec +.Fa "const volatile void *ident" +.Fa "struct rwlock *rwl" +.Fa "int priority" +.Fa "const char *wmesg" +.Fa "uint64_t nsecs" +.Fc +.Ft void +.Fn wakeup "const volatile void *ident" +.Ft void +.Fn wakeup_n "const volatile void *ident" "int count" +.Ft void +.Fn wakeup_one "const volatile void *ident" +.Sh DESCRIPTION +These functions implement voluntary context switching. +.Fn tsleep , +.Fn msleep +and +.Fn rwsleep +are used throughout the kernel whenever processing in the current context +cannot continue for any of the following reasons: +.Bl -bullet -offset indent +.It +The current process needs to await the results of a pending I/O operation. +.It +The current process needs resources +.Pq e.g. memory +which are temporarily unavailable. +.It +The current process wants access to data structures which are locked by +other processes. +.El +.Pp +The +.Fn wakeup , +.Fn wakeup_n , +and +.Fn wakeup_one +functions are used to notify sleeping processes of possible changes to the +condition that caused them to go to sleep. +Typically, an awakened process will \(em after it has acquired a context +again \(em retry the action that blocked its operation to see if the +.Dq blocking +condition has cleared. +.Pp +The +.Fn tsleep +function takes the following arguments: +.Bl -tag -width priority +.It Fa ident +An identifier of the +.Dq wait channel +representing the resource for which the current process needs to wait. +This typically is the virtual address of some kernel data structure related +to the resource for which the process is contending. +The same identifier must be used in a call to +.Fn wakeup +to get the process going again. +.Fa ident +should not be +.Dv NULL . +.It Fa priority +The process priority to be used when the process is awakened and put on +the queue of runnable processes. +This mechanism is used to optimize +.Dq throughput +of processes executing in kernel mode. +If the flag +.Dv PCATCH +is OR'ed into +.Fa priority , +the process checks for posted signals before and after sleeping. +.It Fa wmesg +A pointer to a character string indicating the reason a process is sleeping. +The kernel does not use the string, but makes it available +.Pq through the process structure field Li p_wmesg +for user level utilities such as +.Xr ps 1 . +.It Fa timo +If non-zero, the process will sleep for at most +.Li timo/hz +seconds. +If this amount of time elapses and no +.Fn wakeup "ident" +has occurred, and no signal +.Pq if Dv PCATCH No was set +was posted, +.Fn tsleep +will return +.Er EWOULDBLOCK . +.El +.Pp +The +.Fn msleep +function behaves just like +.Fn tsleep , +but takes an additional argument: +.Bl -tag -width priority +.It Fa mtx +A mutex that will be unlocked when the process is safely +on the sleep queue. +The mutex will be relocked at the end of msleep unless the +.Dv PNORELOCK +flag is set in the +.Fa priority +argument. +.El +.Pp +The +.Fn rwsleep +function behaves just like +.Fn tsleep , +but takes an additional argument: +.Bl -tag -width priority +.It Fa rwl +A read- or write-lock that will be unlocked when the process is safely +on the sleep queue. +The lock will be relocked at the end of rwsleep unless the +.Dv PNORELOCK +flag is set in the +.Fa priority +argument. +.El +.Pp +The +.Fn tsleep_nsec , +.Fn msleep_nsec , +and +.Fn rwsleep_nsec +functions behave like their unsuffixed counterparts except that they +accept a timeout in terms of nanoseconds. +These functions will always sleep for at least one tick, +even if +.Fa nsecs +is zero. +If +.Fa nsecs +is equal to +.Dv INFSLP +these functions do not time out, +otherwise they sleep for at least +.Fa nsecs +nanoseconds. +.Pp +The +.Fn wakeup +function will mark all processes which are currently sleeping on the identifier +.Fa ident +as runnable. +Eventually, each of the processes will resume execution in the kernel +context, causing a return from +.Fn tsleep . +Note that processes returning from sleep should always re-evaluate the +conditions that blocked them, since a call to +.Fn wakeup +merely signals a +.Em possible +change to the blocking conditions. +For example, when two or more processes are waiting for an exclusive lock, +only one of them will succeed in acquiring the lock when it is released. +All others will have to go back to sleep and wait for the next opportunity. +.Pp +The +.Fn wakeup_n +and +.Fn wakeup_one +functions behave similarly to +.Fn wakeup +except that only +.Fa count +or one process, respectively, is marked runnable. +.Sh RETURN VALUES +.Fn tsleep , +.Fn tsleep_nsec , +.Fn msleep , +.Fn msleep_nsec , +.Fn rwsleep , +and +.Fn rwsleep_nsec +return 0 if they return as a result of a +.Fn wakeup . +If they return as a result of a signal, the return value is +.Er ERESTART +if the signal has the +.Dv SA_RESTART +property +.Pq see Xr sigaction 2 , +and +.Er EINTR +otherwise. +If they return as a result of a timeout, the return value is +.Er EWOULDBLOCK . +.Sh CODE REFERENCES +These functions are implemented in the file +.Pa sys/kern/kern_synch.c . +.Sh SEE ALSO +.Xr hz 9 , +.Xr mi_switch 9 , +.Xr timeout 9 diff --git a/static/openbsd/man9/tvtohz.9 b/static/openbsd/man9/tvtohz.9 new file mode 100644 index 00000000..dd9f69cb --- /dev/null +++ b/static/openbsd/man9/tvtohz.9 @@ -0,0 +1,63 @@ +.\" $OpenBSD: tvtohz.9,v 1.11 2019/01/18 03:34:58 schwarze Exp $ +.\" +.\" Copyright (c) 1999 Marc Espie +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list 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 $Mdocdate: January 18 2019 $ +.Dt TVTOHZ 9 +.Os +.Sh NAME +.Nm tvtohz , +.Nm tstohz +.Nd translate time period to timeout delay +.Sh SYNOPSIS +.In sys/types.h +.In sys/time.h +.In sys/systm.h +.Ft int +.Fn tvtohz "const struct timeval *tv" +.Ft int +.Fn tstohz "const struct timespec *ts" +.Sh DESCRIPTION +The +.Fn tvtohz +and +.Fn tstohz +functions return the number of ticks in the specified amount of time. +If the return value would exceed the maximum value representable by an +.Vt int , +it is capped at +.Dv INT_MAX . +They are mainly used to translate a +.Vt timeval +or +.Vt timespec , +respectively, +into a suitable argument for +.Xr tsleep 9 . +.Sh CODE REFERENCES +These functions are implemented in the file +.Pa sys/kern/kern_clock.c . +.Sh SEE ALSO +.Xr hz 9 , +.Xr timeout 9 diff --git a/static/openbsd/man9/uiomove.9 b/static/openbsd/man9/uiomove.9 new file mode 100644 index 00000000..c29640ba --- /dev/null +++ b/static/openbsd/man9/uiomove.9 @@ -0,0 +1,137 @@ +.\" $OpenBSD: uiomove.9,v 1.19 2016/03/15 06:49:21 jmc Exp $ +.\" $NetBSD: uiomove.9,v 1.6 2001/12/26 00:16:30 wiz Exp $ +.\" +.\" Copyright (c) 1996 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 $Mdocdate: March 15 2016 $ +.Dt UIOMOVE 9 +.Os +.Sh NAME +.Nm uiomove +.Nd move data described by a struct uio +.Sh SYNOPSIS +.In sys/systm.h +.Ft int +.Fn uiomove "void *buf" "size_t n" "struct uio *uio" +.Sh DESCRIPTION +The +.Nm +function copies up to +.Fa n +bytes between the kernel-space address pointed +to by +.Fa buf +and the addresses described by +.Fa uio , +which may be in user-space or kernel-space. +.Pp +The +.Fa uio +argument is a pointer to a +.Fa struct uio +as defined by +.In sys/uio.h : +.Bd -literal +struct uio { + struct iovec *uio_iov; /* pointer to array of iovecs */ + int uio_iovcnt; /* number of iovecs in array */ + off_t uio_offset; /* offset into file this uio corresponds to */ + size_t uio_resid; /* residual i/o count */ + enum uio_seg uio_segflg; + enum uio_rw uio_rw; + struct proc *uio_procp;/* associated process or NULL */ +}; +.Ed +.Pp +A +.Fa struct uio +typically describes data in motion. +Several of the fields described below reflect that expectation. +.Bl -tag -width uio_xxxxxx +.It uio_iov +Pointer to array of +.Fa struct iovecs : +.Bd -literal +struct iovec { + void *iov_base; /* Base address. */ + size_t iov_len; /* Length. */ +}; +.Ed +.It uio_iovcnt +The number of iovecs in the array. +.It uio_offset +An offset into the corresponding object. +.It uio_resid +The amount of data remaining to be transferred. +.It uio_segflg +A flag indicating whether the space described is in user-space +(UIO_USERSPACE) or kernel-space (UIO_SYSSPACE). +.It uio_rw +A flag indicating whether data should be read into the space +(UIO_READ) or written from the space (UIO_WRITE). +.It uio_procp +A pointer to a process whose data area is described by the +structure, or which is having the I/O done on its behalf if +the area is in kernel-space. +.Nm uiomove +itself does not use this field if the area is in kernel-space, +but other functions that take a +.Fa struct uio +may depend on this information. +.El +.Pp +The value of +.Fa uio->uio_rw +controls whether +.Nm +copies data from +.Fa buf +to +.Fa uio +or vice versa. +.Pp +The lesser of +.Fa n +or +.Fa uio->uio_resid +bytes are copied. +.Pp +.Nm +changes fields of the structure pointed to by +.Fa uio , +such that +.Fa uio->uio_resid +is decremented by the amount of data moved, +.Fa uio->uio_offset +is incremented by the same amount, and the array of iovecs is adjusted +to point that much farther into the region described. +This allows multiple calls to +.Nm +to easily be used to fill or drain the region of data. +.Sh RETURN VALUES +.Nm +returns 0 on success or EFAULT if a bad address is encountered. +.Sh SEE ALSO +.Xr copy 9 diff --git a/static/openbsd/man9/usb_add_task.9 b/static/openbsd/man9/usb_add_task.9 new file mode 100644 index 00000000..d3885c4a --- /dev/null +++ b/static/openbsd/man9/usb_add_task.9 @@ -0,0 +1,122 @@ +.\" $OpenBSD: usb_add_task.9,v 1.3 2021/01/19 16:05:59 anton Exp $ +.\" +.\" Copyright (c) 2016 Adam Wolk +.\" +.\" 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 19 2021 $ +.Dt USB_ADD_TASK 9 +.Os +.Sh NAME +.Nm usb_add_task , +.Nm usb_rem_task , +.Nm usb_wait_task , +.Nm usb_rem_wait_task , +.Nm usb_init_task +.Nd USB task queues +.Sh SYNOPSIS +.In dev/usb/usbdi.h +.Ft void +.Fn usb_add_task "struct usbd_device *dev" "struct usb_task *task" +.Ft void +.Fn usb_rem_task "struct usbd_device *dev" "struct usb_task *task" +.Ft void +.Fn usb_wait_task "struct usbd_device *dev" "struct usb_task *task" +.Ft void +.Fn usb_rem_wait_task "struct usbd_device *dev" "struct usb_task *task" +.Ft void +.Fn usb_init_task "struct usb_task *task" "void (*fn)(void *)" "void *arg" "char type" +.Sh DESCRIPTION +The USB stack provides an API to manage task execution in a thread context at +the soonest opportunity. +There are three different task queues +that are executed on two separate threads. +All tasks executed via the USB task API are +serialized with USB events such as device detachments. +.Pp +The +.Fn usb_add_task +function enqueues a task to be executed by the task thread. +Subsequent calls to +.Fn usb_add_task +will not result in multiple executions being scheduled. +The task structure must already be initialised by +.Fn usb_init_task . +.Pp +The +.Fn usb_rem_task +function removes a scheduled task from its queue. +If the work was already executed or has not been added to the task queue, +the call will have no effect. +Calling +.Fn usb_rem_task +while the task is executing will not abort it. +.Pp +The +.Fn usb_wait_task +function sleeps until the given task is neither queued for execution +nor currently running. +.Pp +The +.Fn usb_rem_wait_task +function is the equivalent of calling +.Fn usb_rem_task +followed by +.Fn usb_wait_task . +.Pp +The +.Fn usb_init_task +macro prepares the task structure +.Fa task +to be used in future calls to +.Fn usb_add_task , +.Fn usb_rem_task , +.Fn usb_wait_task , +and +.Fn usb_rem_wait_task . +.Fa task +will be prepared to call the function +.Fa fn +with the argument specified by +.Fa arg . +The +.Fa type +of the task determines the queue +and thread that will be used for its execution: +.Bl -tag -width "USB_TASK_TYPE_EXPLORE" -offset indent +.It Dv USB_TASK_TYPE_GENERIC +Tasks used for general work that need to happen in a process context. +.It Dv USB_TASK_TYPE_EXPLORE +Device discovery tasks exploring the tree from the root. +.It Dv USB_TASK_TYPE_ABORT +Tasks of this type execute on a dedicated thread +not shared with other USB task types. +.El +.Pp +Most drivers will only define tasks of type +.Dv USB_TASK_TYPE_GENERIC . +Note that +.Dv USB_TASK_TYPE_ABORT +tasks are only used by host controller drivers +and should never be used by drivers. +Once initialised, the +.Fa task +can be used repeatedly in the API functions listed above +and does not need to be reinitialised +unless the function called and/or its argument must change. +.Sh CONTEXT +.Fn usb_task_add +can be called from any context. +.Sh SEE ALSO +.Xr usb 4 , +.Xr task_add 9 diff --git a/static/openbsd/man9/usbd_close_pipe.9 b/static/openbsd/man9/usbd_close_pipe.9 new file mode 100644 index 00000000..fbdee4a2 --- /dev/null +++ b/static/openbsd/man9/usbd_close_pipe.9 @@ -0,0 +1,48 @@ +.\" $OpenBSD: usbd_close_pipe.9,v 1.2 2018/09/04 12:46:32 mpi Exp $ +.\" +.\" Copyright (c) 2015 Sean Levy +.\" +.\" 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: September 4 2018 $ +.Dt USBD_CLOSE_PIPE 9 +.Os +.Sh NAME +.Nm usbd_close_pipe , usbd_abort_pipe +.Nd delete or abort transfers on a USB pipe +.Sh SYNOPSIS +.In dev/usb/usb.h +.In dev/usb/usbdi.h +.Ft usbd_status +.Fn usbd_close_pipe "struct usbd_pipe *pipe" +.Ft void +.Fn usbd_abort_pipe "struct usbd_pipe *pipe" +.Sh DESCRIPTION +The +.Fn usbd_abort_pipe +function aborts any transfers queued on +.Fa pipe . +.Pp +The +.Fn usbd_close_pipe +function aborts any transfers queued on +.Fa pipe +then deletes it. +.Sh CONTEXT +.Fn usbd_abort_pipe +and +.Fn usbd_close_pipe +can be called during autoconf or from process context. +.Sh SEE ALSO +.Xr usb 4 , +.Xr usbd_open_pipe 9 diff --git a/static/openbsd/man9/usbd_open_pipe.9 b/static/openbsd/man9/usbd_open_pipe.9 new file mode 100644 index 00000000..a70f6ae5 --- /dev/null +++ b/static/openbsd/man9/usbd_open_pipe.9 @@ -0,0 +1,132 @@ +.\" $OpenBSD: usbd_open_pipe.9,v 1.5 2022/03/29 18:15:52 naddy Exp $ +.\" +.\" Copyright (c) 2015 Sean Levy +.\" +.\" 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: March 29 2022 $ +.Dt USBD_OPEN_PIPE 9 +.Os +.Sh NAME +.Nm usbd_open_pipe , usbd_open_pipe_intr +.Nd create USB pipe +.Sh SYNOPSIS +.In dev/usb/usb.h +.In dev/usb/usbdi.h +.Ft usbd_status +.Fn usbd_open_pipe "struct usbd_interface *iface" "uint8_t address" "uint8_t flags" "struct usbd_pipe **pipe" +.Ft usbd_status +.Fn usbd_open_pipe_intr "struct usbd_interface *iface" "uint8_t address" "uint8_t flags" "struct usbd_pipe **pipe" "void *priv" "void *buffer" "uint32_t len" "usbd_callback cb" "int ival" +.Sh DESCRIPTION +The +.Fn usbd_open_pipe +and +.Fn usbd_open_pipe_intr +functions create pipes. +A pipe is a logical connection between the host and an endpoint on a +USB device. +USB drivers use pipes to manage transfers to or from a USB +endpoint. +.Pp +The +.Fn usbd_open_pipe +function takes the following arguments: +.Bl -tag -width callback +.It Fa iface +The USB interface for which the pipe is to be created. +.It Fa address +The address of the endpoint in that interface to which the pipe should be +connected. +.It Fa flags +A bitmask of flags. +Currently there is only one flag bit defined: +.Bl -tag -width xxx -offset indent +.It Dv USBD_EXCLUSIVE_USE +Do not allow other pipes to use this endpoint while this pipe exists. +.El +.It Fa pipe +A pointer to where the resulting +.Vt struct usbd_pipe * +should be stored if the call is successful. +.El +.Pp +The +.Fn usbd_open_pipe_intr +function takes the following arguments: +.Bl -tag -width callback +.It Fa iface +The USB interface for which the pipe is to be created. +.It Fa address +The endpoint in that interface to which the pipe should be connected. +.It Fa flags +A bitmask of flags. +These flags are not interpreted in the same way as the +.Fa flags +passed to +.Fn usbd_open_pipe . +Instead, +.Fn usbd_open_pipe_intr +implicitly turns on the +.Dv USBD_EXCLUSIVE_USE +bit for the pipe, disallowing multiple interrupt pipes for +the same endpoint. +The +.Fa flags +argument in this case is instead passed directly to +.Xr usbd_setup_xfer 9 +as its +.Fa flags +argument, whose interpretation is documented in +its man page. +.It Fa pipe +A pointer to where the resulting +.Vt struct usbd_pipe * +should be stored if the call is successful. +.It Fa priv +A pointer to a private cookie untouched by the USB stack for reuse in +the callback specified by the +.Fa cb +argument. +.It Fa buffer +A pointer to the data buffer for use by the implicit transfer +(see below). +.It Fa len +The length in bytes of +.Fa buffer . +.It Fa cb +A callback invoked every time the interrupt transfer completes. +.It Fa ival +The interval in milliseconds with which the interrupt pipe +should be polled by the USB stack. +.El +.Pp +Pipes created by +.Fn usbd_open_pipe_intr +implicitly have a repeating transfer queued on them which +is run every +.Fa ival +milliseconds. +This implicit transfer is not automatically removed from the list of +transfers maintained by the pipe, unlike normal transfers, and will +continue to be processed every +.Fa ival +milliseconds. +.Sh CONTEXT +.Fn usbd_open_pipe +and +.Fn usbd_open_pipe_intr +can be called during autoconf or from process context. +.Sh SEE ALSO +.Xr usb 4 , +.Xr usbd_close_pipe 9 , +.Xr usbd_transfer 9 diff --git a/static/openbsd/man9/usbd_ref_wait.9 b/static/openbsd/man9/usbd_ref_wait.9 new file mode 100644 index 00000000..1b675d7e --- /dev/null +++ b/static/openbsd/man9/usbd_ref_wait.9 @@ -0,0 +1,64 @@ +.\" $OpenBSD: usbd_ref_wait.9,v 1.3 2016/06/30 19:54:13 mglocker Exp $ +.\" +.\" Copyright (c) 2016 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 $Mdocdate: June 30 2016 $ +.Dt USBD_REF_WAIT 9 +.Os +.Sh NAME +.Nm usbd_ref_incr , usbd_ref_decr , usbd_ref_wait +.Nd wait for all USB device references to complete +.Sh SYNOPSIS +.In dev/usb/usb.h +.In dev/usb/usbdi.h +.Ft void +.Fn usbd_ref_incr "struct usbd_device *dev" +.Ft void +.Fn usbd_ref_decr "struct usbd_device *dev" +.Ft void +.Fn usbd_ref_wait "struct usbd_device *dev" +.Sh DESCRIPTION +The +.Fn usbd_ref_wait +function is used on a device level to +.Xr tsleep 9 +until the reference counter has reached zero. +.Pp +To increase the reference counter use +.Fn usbd_ref_incr . +To decrease the reference counter use +.Fn usbd_ref_decr . +Once the reference counter has been decreased to zero, +.Fn usbd_ref_decr +will call +.Fn wakeup +to interrupt the +.Fn tsleep +at the point where +.Fn usbd_ref_wait +was previously set. +.Pp +Typical use cases to wait for tasks to complete is at device closing +or detachment. +.Sh CONTEXT +.Fn usbd_ref_incr , +.Fn usbd_ref_decr , +and +.Fn usbd_ref_wait +can be called during autoconf or from process context. +.Sh SEE ALSO +.Xr usb 4 , +.Xr tsleep 9 , +.Xr wakeup 9 diff --git a/static/openbsd/man9/usbd_transfer.9 b/static/openbsd/man9/usbd_transfer.9 new file mode 100644 index 00000000..74eac53d --- /dev/null +++ b/static/openbsd/man9/usbd_transfer.9 @@ -0,0 +1,117 @@ +.\" $OpenBSD: usbd_transfer.9,v 1.7 2015/05/04 14:36:26 jmc Exp $ +.\" +.\" 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 $Mdocdate: May 4 2015 $ +.Dt USBD_TRANSFER 9 +.Os +.Sh NAME +.Nm usbd_setup_xfer , usbd_transfer +.Nd submit USB data transfers +.Sh SYNOPSIS +.In dev/usb/usb.h +.In dev/usb/usbdi.h +.Ft void +.Fn usbd_setup_xfer "struct usbd_xfer *xfer" "struct usbd_pipe *pipe" \ + "void *priv" "void *buffer" "uint32_t length" "uint16_t flags" \ + "uint32_t timeout" "usbd_callback callback" +.Ft usbd_status +.Fn usbd_transfer "struct usbd_xfer *xfer" +.Sh DESCRIPTION +These functions provide a controller independent mechanism to perform USB +data transfers. +They make use of a pipe created by +.Xr usbd_open_pipe 9 +or +.Xr usbd_open_pipe_intr 9 . +.Pp +The function +.Fn usbd_setup_xfer +is used to initialize the structure pointed to by +.Fa xfer , +describing an individual transfer to submit. +It takes the following arguments: +.Bl -tag -width callback +.It Fa xfer +A pointer to an existing structure describing a transfer. +.It Fa pipe +A pointer to a pipe associated with the endpoint for the transfer. +.It Fa priv +A pointer to a private cookie untouched by the USB stack for reuse in the +.Fa callback . +.It Fa buffer +A pointer to the data buffer. +.It Fa length +The total length of the data to read or write. +.It Fa flags +The characteristics of the transfer: +.Bl -tag -width xxx -offset indent +.It Dv USBD_NO_COPY +Do not copy data between +.Fa buffer +and the DMA buffer. +.It Dv USBD_SYNCHRONOUS +Causes +.Fn usbd_transfer +to sleep until the I/O transfer is complete or the +.Fa timeout +expires. +.It Dv USBD_SHORT_XFER_OK +Do not report short reads, when the length of the data read is lower than +.Fa length , +as errors. +.It Dv USBD_FORCE_SHORT_XFER +Submit a supplementary zero length packet at the end of the written data. +Some requests may need such packets in order to be properly terminated. +.It Dv USBD_CATCH +Used in conjunction with the +.Dv USBD_SYNCHRONOUS +flag to pass the +.Dv PCATCH +flag to +.Xr tsleep 9 +in order to check for signals before and after sleeping. +.El +.It Fa timeout +Timeout of the transfer in milliseconds. +.It Fa callback +A routine invoked upon completion of the transfer whether successful or not. +.El +.Pp +The function +.Fn usbd_transfer +is used to submit the USB transfer described by +.Fa xfer +to the corresponding +.Xr usb 4 +host controller to perform I/O with devices. +.Sh CONTEXT +.Fn usbd_setup_xfer +can be called during autoconf, from process context, or from interrupt context. +.Pp +.Fn usbd_transfer +can be called during autoconf, from process context, or from interrupt context +if +.Dv USBD_SYNCHRONOUS +has not been passed via +.Fa flags . +.Sh SEE ALSO +.Xr ehci 4 , +.Xr ohci 4 , +.Xr uhci 4 , +.Xr usb 4 , +.Xr tsleep 9 , +.Xr usbd_open_pipe 9 , +.Xr usbd_open_pipe_intr 9 diff --git a/static/openbsd/man9/uvm_fault.9 b/static/openbsd/man9/uvm_fault.9 new file mode 100644 index 00000000..adb4bff6 --- /dev/null +++ b/static/openbsd/man9/uvm_fault.9 @@ -0,0 +1,55 @@ +.\" $OpenBSD: uvm_fault.9,v 1.1 2019/12/05 15:14:28 mpi Exp $ +.\" $NetBSD: uvm.9,v 1.14 2000/06/29 06:08:44 mrg Exp $ +.\" +.\" Copyright (c) 1998 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. +.\" +.\" 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 $Mdocdate: December 5 2019 $ +.Dt UVM_FAULT 9 +.Os +.Sh NAME +.Nm uvm_fault +.Nd page fault handling +.Sh SYNOPSIS +.In sys/param.h +.In uvm/uvm.h +.Ft int +.Fn uvm_fault "vm_map_t orig_map" "vaddr_t vaddr" "vm_fault_t fault_type" "vm_prot_t access_type" +.Sh DESCRIPTION +The +.Fn uvm_fault +function is the main entry point for faults. +It takes +.Fa orig_map +as the map the fault originated in, a +.Fa vaddr +offset into the map the fault occurred, +.Fa fault_type +describing the type of fault, and +.Fa access_type +describing the type of access requested. +.Fn uvm_fault +returns a standard errno. +.Sh SEE ALSO +.Xr pmap 9 diff --git a/static/openbsd/man9/uvm_init.9 b/static/openbsd/man9/uvm_init.9 new file mode 100644 index 00000000..a8493cd9 --- /dev/null +++ b/static/openbsd/man9/uvm_init.9 @@ -0,0 +1,450 @@ +.\" $OpenBSD: uvm_init.9,v 1.7 2023/06/21 21:16:21 cheloha Exp $ +.\" $NetBSD: uvm.9,v 1.14 2000/06/29 06:08:44 mrg Exp $ +.\" +.\" Copyright (c) 1998 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. +.\" +.\" 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. +.\" +.\" XXX this manual sets nS to 1 or 0 in the description, to obtain +.\" synopsis-like function prototypes. any better way? +.\" +.Dd $Mdocdate: June 21 2023 $ +.Dt UVM_INIT 9 +.Os +.Sh NAME +.Nm uvm_init , +.Nm uvm_init_limits , +.Nm uvm_setpagesize , +.Nm uvm_swap_init , +.Nm uvm_io , +.Nm uvm_pageout , +.Nm uao_create , +.Nm uao_detach , +.Nm uao_reference , +.Nm uvm_chgkprot , +.Nm uvm_kernacc , +.Nm uvm_meter , +.Nm uvm_sysctl , +.Nm uvm_grow , +.Nm uvm_coredump_walkmap +.Nd virtual memory system external interface +.Sh SYNOPSIS +.In sys/param.h +.In uvm/uvm.h +.Sh DESCRIPTION +The UVM virtual memory system manages access to the computer's memory +resources. +User processes and the kernel access these resources through +UVM's external interface. +UVM's external interface includes functions that: +.Pp +.Bl -hyphen -compact +.It +initialise UVM subsystems +.It +manage virtual address spaces +.It +resolve page faults +.It +memory map files and devices +.It +perform uio-based I/O to virtual memory +.It +allocate and free kernel virtual memory +.It +allocate and free physical memory +.El +.Pp +In addition to exporting these services, UVM has two kernel-level processes: +pagedaemon and swapper. +The pagedaemon process sleeps until physical memory becomes scarce. +When that happens, pagedaemon is awoken. +It scans physical memory, paging out and freeing memory that has not been +recently used. +The swapper process swaps in runnable processes that are currently swapped out, +if there is room. +.Pp +UVM has a machine independent and a machine dependent layer. +See +.Xr pmap 9 +for the machine dependent layer. +.Sh INITIALISATION +.nr nS 1 +.Ft void +.Fn uvm_init "void" +.Ft void +.Fn uvm_init_limits "struct plimit *limit0" +.Ft void +.Fn uvm_setpagesize "void" +.Ft void +.Fn uvm_swap_init "void" +.nr nS 0 +.Pp +The +.Fn uvm_init +function sets up the UVM system at system boot time, after the +copyright has been printed. +It initialises global state, the page, map, kernel virtual memory state, +machine-dependent physical map, kernel memory allocator, +pager and anonymous memory subsystems, and then enables +paging of kernel objects. +.Fn uvm_init +must be called after machine-dependent code has registered some free RAM +with the +.Fn uvm_page_physload +function. +.Pp +The +.Fn uvm_init_limits +function initialises process limits in the given limit structure. +This is for use by the system startup for process zero, before any other +processes are created. +.Pp +The +.Fn uvm_setpagesize +function initialises the uvmexp members pagesize (if not already done by +machine-dependent code), pageshift and pagemask. +It should be called by machine-dependent code early in the +.Xr pmap_init 9 +call. +.Pp +The +.Fn uvm_swap_init +function initialises the swap subsystem. +.Sh VIRTUAL MEMORY I/O +.nr nS 1 +.Ft int +.Fn uvm_io "vm_map_t map" "struct uio *uio" +.nr nS 0 +.Pp +The +.Fn uvm_io +function performs the I/O described in +.Fa uio +on the memory described in +.Fa map . +.Sh PROCESSES +.nr nS 1 +.Ft void +.Fn uvm_pageout "void *arg" +.nr nS 0 +.Pp +The +.Fn uvm_pageout +function is the main loop for the page daemon. +The +.Fa arg +argument is ignored. +.Sh MISCELLANEOUS FUNCTIONS +.nr nS 1 +.Ft struct uvm_object * +.Fn uao_create "vsize_t size" "int flags" +.Ft void +.Fn uao_detach "struct uvm_object *uobj" +.Ft void +.Fn uao_reference "struct uvm_object *uobj" +.Ft boolean_t +.Fn uvm_chgkprot "caddr_t addr" "size_t len" "int rw" +.Ft void +.Fn uvm_kernacc "caddr_t addr" "size_t len" "int rw" +.Ft void +.Fn uvm_meter +.Ft int +.Fn uvm_sysctl "int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" "void *newp " "size_t newlen" "struct proc *p" +.Ft int +.Fn uvm_grow "struct proc *p" "vaddr_t sp" +.Ft int +.Fn uvm_coredump_walkmap "struct proc *p" "uvm_coredump_setup_cb *setup" "struct uvm_coredump_walk_cb *walk" "void *cookie" +.nr nS 0 +.Pp +The +.Fn uao_create , +.Fn uao_detach +and +.Fn uao_reference +functions operate on anonymous memory objects, such as those used to support +System V shared memory. +.Fn uao_create +returns an object of size +.Fa size +with flags: +.Bd -literal +#define UAO_FLAG_KERNOBJ 0x1 /* create kernel object */ +#define UAO_FLAG_KERNSWAP 0x2 /* enable kernel swap */ +.Pp +.Ed +which can only be used once each at system boot time. +.Fn uao_reference +creates an additional reference to the named anonymous memory object. +.Fn uao_detach +removes a reference from the named anonymous memory object, destroying +it if removing the last reference. +.Pp +The +.Fn uvm_kernacc +function checks the access at address +.Fa addr +to +.Fa addr + len +for +.Fa rw +access, in the kernel address space. +.Pp +The +.Fn uvm_meter +function calculates the load average and wakes up the swapper if necessary. +.Pp +The +.Fn uvm_sysctl +function provides support for the +.Dv CTL_VM +domain of the +.Xr sysctl 2 +hierarchy. +.Fn uvm_sysctl +handles the +.Dv VM_LOADAVG , +.Dv VM_METER +and +.Dv VM_UVMEXP +calls, which return the current load averages, calculates current VM +totals, and returns the uvmexp structure respectively. +The load averages are accessed from userland using the +.Xr getloadavg 3 +function. +The uvmexp structure has all global state of the UVM system, and has +the following members: +.Bd -literal +/* vm_page constants */ +int pagesize; /* size of a page (PAGE_SIZE): must be power of 2 */ +int pagemask; /* page mask */ +int pageshift; /* page shift */ + +/* vm_page counters */ +int npages; /* number of pages we manage */ +int free; /* number of free pages */ +int active; /* number of active pages */ +int inactive; /* number of pages that we free'd but may want back */ +int paging; /* number of pages in the process of being paged out */ +int wired; /* number of wired pages */ + +int zeropages; /* number of zero'd pages */ +int reserve_pagedaemon; /* number of pages reserved for pagedaemon */ +int reserve_kernel; /* number of pages reserved for kernel */ +int unused01; /* formerly anonpages */ +int vnodepages; /* XXX # of pages used by vnode page cache */ +int vtextpages; /* XXX # of pages used by vtext vnodes */ + +/* pageout params */ +int freemin; /* min number of free pages */ +int freetarg; /* target number of free pages */ +int inactarg; /* target number of inactive pages */ +int wiredmax; /* max number of wired pages */ +int anonmin; /* min threshold for anon pages */ +int vtextmin; /* min threshold for vtext pages */ +int vnodemin; /* min threshold for vnode pages */ +int anonminpct; /* min percent anon pages */ +int vtextminpct;/* min percent vtext pages */ +int vnodeminpct;/* min percent vnode pages */ + +/* swap */ +int nswapdev; /* number of configured swap devices in system */ +int swpages; /* number of PAGE_SIZE'ed swap pages */ +int swpginuse; /* number of swap pages in use */ +int swpgonly; /* number of swap pages in use, not also in RAM */ +int nswget; /* number of swap pages moved from disk to RAM */ +int nanon; /* XXX number total of anon's in system */ +int unused05; /* formerly nanonneeded */ +int unused06; /* formerly nfreeanon */ + +/* stat counters */ +int faults; /* page fault count */ +int traps; /* trap count */ +int intrs; /* interrupt count */ +int swtch; /* context switch count */ +int softs; /* software interrupt count */ +int syscalls; /* system calls */ +int pageins; /* pagein operation count */ + /* pageouts are in pdpageouts below */ +int unused07; /* formerly obsolete_swapins */ +int unused08; /* formerly obsolete_swapouts */ +int pgswapin; /* pages swapped in */ +int pgswapout; /* pages swapped out */ +int forks; /* forks */ +int forks_ppwait; /* forks where parent waits */ +int forks_sharevm; /* forks where vmspace is shared */ +int pga_zerohit; /* pagealloc where zero wanted and zero + was available */ +int pga_zeromiss; /* pagealloc where zero wanted and zero + not available */ +int unused09; /* formerly zeroaborts */ + +/* fault subcounters */ +int fltnoram; /* number of times fault was out of ram */ +int fltnoanon; /* number of times fault was out of anons */ +int fltnoamap; /* number of times fault was out of amap chunks */ +int fltpgwait; /* number of times fault had to wait on a page */ +int fltpgrele; /* number of times fault found a released page */ +int fltrelck; /* number of times fault relock called */ +int fltrelckok; /* number of times fault relock is a success */ +int fltanget; /* number of times fault gets anon page */ +int fltanretry; /* number of times fault retrys an anon get */ +int fltamcopy; /* number of times fault clears "needs copy" */ +int fltnamap; /* number of times fault maps a neighbor anon page */ +int fltnomap; /* number of times fault maps a neighbor obj page */ +int fltlget; /* number of times fault does a locked pgo_get */ +int fltget; /* number of times fault does an unlocked get */ +int flt_anon; /* number of times fault anon (case 1a) */ +int flt_acow; /* number of times fault anon cow (case 1b) */ +int flt_obj; /* number of times fault is on object page (2a) */ +int flt_prcopy; /* number of times fault promotes with copy (2b) */ +int flt_przero; /* number of times fault promotes with zerofill (2b) */ + +/* daemon counters */ +int pdwoke; /* number of times daemon woke up */ +int pdrevs; /* number of times daemon rev'd clock hand */ +int pdswout; /* number of times daemon called for swapout */ +int pdfreed; /* number of pages daemon freed since boot */ +int pdscans; /* number of pages daemon scanned since boot */ +int pdanscan; /* number of anonymous pages scanned by daemon */ +int pdobscan; /* number of object pages scanned by daemon */ +int pdreact; /* number of pages daemon reactivated since boot */ +int pdbusy; /* number of times daemon found a busy page */ +int pdpageouts; /* number of times daemon started a pageout */ +int pdpending; /* number of times daemon got a pending pagout */ +int pddeact; /* number of pages daemon deactivates */ +int unused11; /* formerly pdreanon */ +int unused12; /* formerly pdrevnode */ +int unused13; /* formerly pdrevtext */ + +int fpswtch; /* FPU context switches */ +int kmapent; /* number of kernel map entries */ +.Ed +.Pp +The +.Fn uvm_grow +function increases the stack segment of process +.Fa p +to include +.Fa sp . +.Pp +The +.Fn uvm_coredump_walkmap +function supports writing out the memory image of a process in a +core file. +It walks the address space for process +.Fa p +and counts the number of segments necessary to hold the +dumpable memory, +where a segment consists of one or more present pages followed by +zero or more mapped but not present (zero-fill) pages, +or just one or more mapped but not present pages. +It then invokes +.Fa setup +with that segment count and the +.Fa cookie +argument. +.Bd -literal +typedef int uvm_coredump_setup_cb(int nsegment, void *cookie); +.Ed +.Pp +If that returns non-zero then +.Fn uvm_coredump_walkmap +returns that value immediately, +otherwise it invokes +.Fa walk +once for each segment, in ascending address order, +passing it the start of the segment, +the start of the mapped-but-not-present pages, +one past the last address in the segment, +the protection on the segment, +the index of the segment, +and the +.Fa cookie . +.Bd -literal +typedef int uvm_coredump_walk_cb(vaddr_t start, vaddr_t realend, + vaddr_t end, vm_prot_t prot, int nsegment, void *cookie); +.Ed +.Pp +If a call to +.Fa walk +returns non-zero then +.Fa uvm_coredump_walkmap +returns that value immediately. +.Sh NOTES +The structure and types whose names begin with +.Dq vm_ +were named so UVM could coexist with BSD VM during the early +development stages. +.Sh SEE ALSO +.Xr sysctl 2 , +.Xr getloadavg 3 , +.Xr kvm 3 , +.Xr ddb 4 , +.Xr options 4 , +.Xr core 5 , +.Xr pmap 9 +.Rs +.%A Charles D. Cranor +.%D August 1998 +.%C St. Louis, Missouri +.%Q Department of Computer Science, Sever Institute of Technology, Washington University +.%T Design and Implementation of the UVM Virtual Memory System, D.Sc. dissertation +.Re +.Sh HISTORY +The UVM virtual memory system was developed at Washington University in St. Louis. +UVM's roots lie partly in the Mach-based +.Bx 4.4 +VM system, the +.Fx +VM system, and the SunOS4 VM system. +UVM's basic structure is based on the +.Bx 4.4 +VM system. +UVM's new anonymous memory system is based on the +anonymous memory system found in the SunOS4 VM (as described in papers +published by Sun Microsystems, Inc.). +UVM also includes a number of features +new to +.Bx +including page loanout, map entry passing, simplified +copy-on-write, and clustered anonymous memory pageout. +.Pp +UVM appeared in +.Ox 2.9 . +.Sh AUTHORS +.An -nosplit +.An Charles D. Cranor Aq Mt chuck@ccrc.wustl.edu +designed and implemented UVM. +.Pp +.An Matthew Green Aq Mt mrg@eterna.com.au +wrote the swap-space management code. +.Pp +.An Chuck Silvers Aq Mt chuq@chuq.com +implemented the aobj pager, thus allowing +UVM to support System V shared memory and process swapping. +.Pp +.An Artur Grabowski Aq Mt art@openbsd.org +handled the logistical issues involved with merging UVM into the +.Ox +source tree. diff --git a/static/openbsd/man9/uvm_km_alloc.9 b/static/openbsd/man9/uvm_km_alloc.9 new file mode 100644 index 00000000..f40769ac --- /dev/null +++ b/static/openbsd/man9/uvm_km_alloc.9 @@ -0,0 +1,65 @@ +.\" $OpenBSD: uvm_km_alloc.9,v 1.4 2025/11/13 10:59:42 mpi Exp $ +.\" $NetBSD: uvm.9,v 1.14 2000/06/29 06:08:44 mrg Exp $ +.\" +.\" Copyright (c) 1998 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. +.\" +.\" 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 $Mdocdate: November 13 2025 $ +.Dt UVM_KM_SUBALLOC 9 +.Os +.Sh NAME +.Nm uvm_km_suballoc +.Nd raw kernel memory or address space allocator +.Sh SYNOPSIS +.In sys/param.h +.In uvm/uvm.h +.Fn uvm_km_suballoc "vm_map_t map" "vaddr_t *min" "vaddr_t *max " "vsize_t size" "int flags" "boolean_t fixed" "vm_map_t submap" +.Sh DESCRIPTION +The +.Fn uvm_km_suballoc +function allocates submap (with the specified +.Fa flags , +as described above) from +.Fa map , +creating a new map if +.Fa submap +is +.Dv NULL . +The addresses of the submap can be specified exactly by setting the +.Fa fixed +argument to non-zero, which causes the +.Fa min +argument to specify the beginning of the address in the submap. +If +.Fa fixed +is zero, any address of size +.Fa size +will be allocated from +.Fa map +and the start and end addresses returned in +.Fa min +and +.Fa max . +.Sh SEE ALSO +.Xr km_alloc 9 diff --git a/static/openbsd/man9/uvm_map.9 b/static/openbsd/man9/uvm_map.9 new file mode 100644 index 00000000..6afa9f6f --- /dev/null +++ b/static/openbsd/man9/uvm_map.9 @@ -0,0 +1,331 @@ +.\" $OpenBSD: uvm_map.9,v 1.3 2022/12/09 21:19:53 jmc Exp $ +.\" $NetBSD: uvm.9,v 1.14 2000/06/29 06:08:44 mrg Exp $ +.\" +.\" Copyright (c) 1998 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. +.\" +.\" 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 $Mdocdate: December 9 2022 $ +.Dt UVM_MAP 9 +.Os +.Sh NAME +.Nm uvm_map , +.Nm uvm_map_pageable , +.Nm uvm_map_pageable_all , +.Nm uvm_map_checkprot , +.Nm uvm_map_protect , +.Nm uvmspace_alloc , +.Nm uvmspace_exec , +.Nm uvmspace_fork , +.Nm uvmspace_free , +.Nm uvmspace_share , +.Nm uvm_uarea_alloc , +.Nm uvm_uarea_free , +.Nm UVM_MAPFLAG +.Nd virtual address space management interface +.Sh SYNOPSIS +.In sys/param.h +.In uvm/uvm.h +.Ft int +.Fn uvm_map "vm_map_t map" "vaddr_t *startp" "vsize_t size" "struct uvm_object *uobj" "voff_t uoffset" "vsize_t alignment" "unsigned int flags" +.Ft int +.Fn uvm_map_pageable "vm_map_t map" "vaddr_t start" "vaddr_t end" "boolean_t new_pageable" "int lockflags" +.Ft int +.Fn uvm_map_pageable_all "vm_map_t map" "int flags" "vsize_t limit" +.Ft boolean_t +.Fn uvm_map_checkprot "vm_map_t map" "vaddr_t start" "vaddr_t end" "vm_prot_t protection" +.Ft int +.Fn uvm_map_protect "vm_map_t map" "vaddr_t start" "vaddr_t end" "vm_prot_t new_prot" "int et" "boolean_t set_max" "boolean_t checkimmutable" +.Ft struct vmspace * +.Fn uvmspace_alloc "vaddr_t min" "vaddr_t max" "boolean_t pageable" "boolean_t remove_holes" +.Ft void +.Fn uvmspace_exec "struct proc *p" "vaddr_t start" "vaddr_t end" +.Ft struct vmspace * +.Fn uvmspace_fork "struct process *pr" +.Ft void +.Fn uvmspace_free "struct vmspace *vm" +.Ft struct vmspace * +.Fn uvmspace_share "struct process *pr" +.Ft vaddr_t +.Fn uvm_uarea_alloc "void" +.Ft void +.Fn uvm_uarea_free "struct proc *p" +.Ft unsigned int +.Fn UVM_MAPFLAG "vm_prot_t prot" "vm_prot_t maxprot" "vm_inherit_t inh" "int advice" "int flags" +.Sh DESCRIPTION +The +.Fn uvm_map +function establishes a valid mapping in map +.Fa map , +which must be unlocked. +The new mapping has size +.Fa size , +which must be in +.Dv PAGE_SIZE +units. +If +.Fa alignment +is non-zero, it describes the required alignment of the list, in +power-of-two notation. +The +.Fa uobj +and +.Fa uoffset +arguments can have four meanings. +When +.Fa uobj +is +.Dv NULL +and +.Fa uoffset +is +.Dv UVM_UNKNOWN_OFFSET , +.Fn uvm_map +does not use the machine-dependent +.Dv PMAP_PREFER +function. +If +.Fa uoffset +is any other value, it is used as the hint to +.Dv PMAP_PREFER . +When +.Fa uobj +is not +.Dv NULL +and +.Fa uoffset +is +.Dv UVM_UNKNOWN_OFFSET , +.Fn uvm_map +finds the offset based upon the virtual address, passed as +.Fa startp . +If +.Fa uoffset +is any other value, we are doing a normal mapping at this offset. +The start address of the map will be returned in +.Fa startp . +.Pp +.Fa flags +passed to +.Fn uvm_map +are typically created using the +.Fn UVM_MAPFLAG +macro, which uses the following values. +The +.Fa prot +and +.Fa maxprot +can take a mix of the following values: +.Bd -literal +#define PROT_MASK 0x07 /* protection mask */ +#define PROT_NONE 0x00 /* protection none */ +#define PROT_READ 0x01 /* read */ +#define PROT_WRITE 0x02 /* write */ +#define PROT_EXEC 0x04 /* exec */ +.Ed +.Pp +The values that +.Fa inh +can take are: +.Bd -literal +#define MAP_INHERIT_MASK 0x30 /* inherit mask */ +#define MAP_INHERIT_SHARE 0x00 /* "share" */ +#define MAP_INHERIT_COPY 0x10 /* "copy" */ +#define MAP_INHERIT_NONE 0x20 /* "none" */ +#define MAP_INHERIT_ZERO 0x30 /* "zero" */ +.Ed +.Pp +The values that +.Fa advice +can take are: +.Bd -literal +#define MADV_NORMAL 0x0 /* 'normal' */ +#define MADV_RANDOM 0x1 /* 'random' */ +#define MADV_SEQUENTIAL 0x2 /* 'sequential' */ +#define MADV_MASK 0x7 /* mask */ +.Ed +.Pp +The values that +.Fa flags +can take are: +.Bd -literal +#define UVM_FLAG_FIXED 0x0010000 /* find space */ +#define UVM_FLAG_OVERLAY 0x0020000 /* establish overlay */ +#define UVM_FLAG_NOMERGE 0x0040000 /* don't merge map entries */ +#define UVM_FLAG_COPYONW 0x0080000 /* set copy_on_write flag */ +#define UVM_FLAG_TRYLOCK 0x0100000 /* fail if we can not lock map */ +#define UVM_FLAG_HOLE 0x0200000 /* no backend */ +#define UVM_FLAG_QUERY 0x0400000 /* do everything, + except actual execution */ +#define UVM_FLAG_NOFAULT 0x0800000 /* don't fault */ +#define UVM_FLAG_UNMAP 0x1000000 /* unmap to make space */ +#define UVM_FLAG_STACK 0x2000000 /* page may contain a stack */ +.Ed +.Pp +The +.Dv UVM_MAPFLAG +macro arguments can be combined with an or operator. +There are also some additional macros to extract bits from the flags. +The +.Dv UVM_PROTECTION , +.Dv UVM_INHERIT , +.Dv UVM_MAXPROTECTION +and +.Dv UVM_ADVICE +macros return the protection, inheritance, maximum protection and advice, +respectively. +.Fn uvm_map +returns a standard errno. +.Pp +The +.Fn uvm_map_pageable +function changes the pageability of the pages in the range from +.Fa start +to +.Fa end +in map +.Fa map +to +.Fa new_pageable . +The +.Fn uvm_map_pageable_all +function changes the pageability of all mapped regions. +If +.Fa limit +is non-zero and +.Fn pmap_wired_count +is implemented, +.Dv ENOMEM +is returned if the amount of wired pages exceed +.Fa limit . +The map is locked on entry if +.Fa lockflags +contain +.Dv UVM_LK_ENTER , +and locked on exit if +.Fa lockflags +contain +.Dv UVM_LK_EXIT . +.Fn uvm_map_pageable +and +.Fn uvm_map_pageable_all +return a standard errno. +.Pp +The +.Fn uvm_map_checkprot +function checks the protection of the range from +.Fa start +to +.Fa end +in map +.Fa map +against +.Fa protection . +This returns either +.Dv TRUE +or +.Dv FALSE . +.Pp +The +.Fn uvm_map_protect +function changes the protection +.Fa start +to +.Fa end +in map +.Fa map +to +.Fa new_prot , +also setting the maximum protection to the region to +.Fa new_prot +if +.Fa set_max +is non-zero. +The +.Fa et +parameter should be 0, unless a +.Dv PROT_READ | PROT_WRITE +mapping is being changed to extend the stack limit, then it may be +.Dv UVM_ET_STACK . +This function returns a standard errno. +.Pp +The +.Fn uvmspace_alloc +function allocates and returns a new address space, with ranges from +.Fa min +to +.Fa max , +setting the pageability of the address space to +.Fa pageable . +If +.Fa remove_holes +is non-zero, hardware +.Sq holes +in the virtual address space will be removed from the newly allocated +address space. +.Pp +The +.Fn uvmspace_exec +function either reuses the address space of process +.Fa p +if there are no other references to it, or creates +a new one with +.Fn uvmspace_alloc . +The range of valid addresses in the address space is reset to +.Fa start +through +.Fa end . +.Pp +The +.Fn uvmspace_fork +function creates and returns a new address space based upon the +address space of process +.Fa pr +and is typically used when allocating an address space for a +child process. +.Pp +The +.Fn uvmspace_free +function lowers the reference count on the address space +.Fa vm , +freeing the data structures if there are no other references. +.Pp +The +.Fn uvmspace_share +function returns a reference to the address space of process +.Fa pr , +increasing its reference count. +.Pp +The +.Fn uvm_uarea_alloc +function allocates a thread's +.Sq uarea , +the memory where its kernel stack and PCB are stored. +The +.Fn uvm_uarea_free +function frees the uarea for +thread +.Fa p , +which must no longer be running. +.Sh SEE ALSO +.Xr pmap 9 diff --git a/static/openbsd/man9/uvm_pagealloc.9 b/static/openbsd/man9/uvm_pagealloc.9 new file mode 100644 index 00000000..b50a6bac --- /dev/null +++ b/static/openbsd/man9/uvm_pagealloc.9 @@ -0,0 +1,166 @@ +.\" $OpenBSD: uvm_pagealloc.9,v 1.3 2024/08/24 10:47:59 mpi Exp $ +.\" $NetBSD: uvm.9,v 1.14 2000/06/29 06:08:44 mrg Exp $ +.\" +.\" Copyright (c) 1998 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. +.\" +.\" 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 $Mdocdate: August 24 2024 $ +.Dt UVM_PAGEALLOC 9 +.Os +.Sh NAME +.Nm uvm_pagealloc , +.Nm uvm_pagerealloc , +.Nm uvm_pagefree , +.Nm uvm_pglistalloc , +.Nm uvm_pglistfree , +.Nm uvm_page_physload +.Nd physical memory allocator +.Sh SYNOPSIS +.In sys/param.h +.In uvm/uvm.h +.Ft struct vm_page * +.Fn uvm_pagealloc "struct uvm_object *uobj" "voff_t off" "struct vm_anon *anon" "int flags" +.Ft void +.Fn uvm_pagerealloc "struct vm_page *pg" "struct uvm_object *newobj" "voff_t newoff" +.Ft void +.Fn uvm_pagefree "struct vm_page *pg" +.Ft int +.Fn uvm_pglistalloc "psize_t size" "paddr_t low" "paddr_t high" "paddr_t alignment" "paddr_t boundary" "struct pglist *rlist" "int nsegs" "int flags" +.Ft void +.Fn uvm_pglistfree "struct pglist *list" +.Ft void +.Fn uvm_page_physload "paddr_t start" "paddr_t end" "paddr_t avail_start" "paddr_t avail_end" "int free_list" +.Sh DESCRIPTION +The +.Fn uvm_pagealloc +function allocates a page of memory at virtual address +.Fa off +in either the object +.Fa uobj +or the anonymous memory +.Fa anon , +or returns +.Dv NULL +if no pages are free. +Only one of +.Fa anon +and +.Fa uobj +can be non +.Dv NULL . +The +.Fa flags +can be any of: +.Bd -literal +#define UVM_PGA_USERESERVE 0x0001 /* ok to use reserve pages */ +#define UVM_PGA_ZERO 0x0002 /* returned page must be zeroed */ +.Ed +.Pp +The +.Dv UVM_PGA_USERESERVE +flag means to allocate a page even if that will result in the number of +free pages being lower than +.Dv uvmexp.reserve_pagedaemon +(if the current thread is the pagedaemon) or +.Dv uvmexp.reserve_kernel +(if the current thread is not the pagedaemon). +The +.Dv UVM_PGA_ZERO +flag causes the returned page to be filled with zeroes, either by allocating it +from a pool of pre-zeroed pages or by zeroing it in-line as necessary. +.Pp +The +.Fn uvm_pagerealloc +function reallocates page +.Fa pg +to a new object +.Fa newobj , +at a new offset +.Fa newoff . +.Pp +The +.Fn uvm_pagefree +function frees the physical page +.Fa pg . +.Pp +The +.Fn uvm_pglistalloc +function allocates a list of pages for size +.Fa size +byte under various constraints. +.Fa low +and +.Fa high +describe the lowest and highest addresses acceptable for the list. +If +.Fa alignment +is non-zero, it describes the required alignment of the list, in +power-of-two notation. +If +.Fa boundary +is non-zero, no segment of the list may cross this power-of-two +boundary, relative to zero. +.Fa nsegs +is the maximum number of physically contiguous segments. +The allocated memory is returned in the +.Fa rlist +list. +The +.Fa flags +can be any of: +.Bd -literal +#define UVM_PLA_WAITOK 0x0001 /* may sleep */ +#define UVM_PLA_NOWAIT 0x0002 /* can't sleep */ +#define UVM_PLA_ZERO 0x0004 /* zero all pages before returning */ +.Ed +.Pp +The +.Dv UVM_PLA_WAITOK +flag means that the function may sleep while trying to allocate the list of +pages (this is currently ignored). +Conversely, the +.Dv UVM_PLA_NOWAIT +flag signifies that the function may not sleep while allocating. +It is an error not to provide one of the above flags. +Optionally, one may also specify the +.Dv UVM_PLA_ZERO +flag to receive zeroed memory in the page list. +.Pp +The +.Fn uvm_pglistfree +function frees the list of pages pointed to by +.Fa list . +.Pp +The +.Fn uvm_page_physload +function loads physical memory segments into VM space on the specified +.Fa free_list . +.Fn uvm_page_physload +must be called at system boot time to set up physical memory management pages. +The arguments describe the +.Fa start +and +.Fa end +of the physical addresses of the segment, and the available start and end +addresses of pages not already in use. diff --git a/static/openbsd/man9/uvm_vslock.9 b/static/openbsd/man9/uvm_vslock.9 new file mode 100644 index 00000000..b1bbb6d9 --- /dev/null +++ b/static/openbsd/man9/uvm_vslock.9 @@ -0,0 +1,73 @@ +.\" $OpenBSD: uvm_vslock.9,v 1.2 2019/12/06 11:09:47 mpi Exp $ +.\" $NetBSD: uvm.9,v 1.14 2000/06/29 06:08:44 mrg Exp $ +.\" +.\" Copyright (c) 1998 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. +.\" +.\" 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 $Mdocdate: December 6 2019 $ +.Dt UVM_VSLOCK 9 +.Os +.Sh NAME +.Nm uvm_vslock , +.Nm uvm_vsunlock , +.Nm uvm_vslock_device , +.Nm uvm_vsunlock_device +.Nd wire user memory for I/O +.Sh SYNOPSIS +.In uvm/uvm_extern.h +.Ft void +.Fn uvm_vslock "struct proc *p" "caddr_t addr" "size_t len" \ + "vm_prot_t access_type" +.Ft void +.Fn uvm_vsunlock "struct proc *p" "caddr_t addr" "size_t len" +.Ft int +.Fn uvm_vslock_device "struct proc *p" "void *addr" "size_t len" \ + "vm_prot_t access_type" "void **retp" +.Ft void +.Fn uvm_vsunlock_device "struct proc *p" "void *addr" "size_t len" "void *map" +.Sh DESCRIPTION +The +.Fn uvm_vslock +family of functions +control the wiring and unwiring of pages for process +.Fa p +from +.Fa addr +to +.Fa addr + len . +The +.Fa access_type +argument is passed to +.Xr uvm_fault 9 . +.Pp +.Fn uvm_vslock_device +also checks if the pages are DMA reachable. +When they aren't, it bounces their content into a newly created mapping +returned in +.Fa retp . +.Fn uvm_vsunlock_device +will release this memory mapping pointed by +.Fa map . +.Sh SEE ALSO +.Xr uvm_fault 9 diff --git a/static/openbsd/man9/uvn_attach.9 b/static/openbsd/man9/uvn_attach.9 new file mode 100644 index 00000000..0bad650f --- /dev/null +++ b/static/openbsd/man9/uvn_attach.9 @@ -0,0 +1,99 @@ +.\" $OpenBSD: uvn_attach.9,v 1.1 2019/12/05 15:14:28 mpi Exp $ +.\" $NetBSD: uvm.9,v 1.14 2000/06/29 06:08:44 mrg Exp $ +.\" +.\" Copyright (c) 1998 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. +.\" +.\" 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 $Mdocdate: December 5 2019 $ +.Dt UVN_ATTACH 9 +.Os +.Sh NAME +.Nm uvn_attach , +.Nm uvm_vnp_setsize , +.Nm uvm_vnp_sync , +.Nm uvm_vnp_terminate , +.Nm uvm_vnp_uncache +.Nd memory mapping files and devices +.Sh SYNOPSIS +.In sys/param.h +.In uvm/uvm.h +.Ft struct uvm_object * +.Fn uvn_attach "struct vnode *vp" "vm_prot_t accessprot" +.Ft void +.Fn uvm_vnp_setsize "struct vnode *vp" "voff_t newsize" +.Ft void +.Fn uvm_vnp_sync "struct mount *mp" +.Ft void +.Fn uvm_vnp_terminate "struct vnode *vp" +.Ft boolean_t +.Fn uvm_vnp_uncache "struct vnode *vp" +.Sh DESCRIPTION +The +.Fn uvn_attach +function attaches a UVM object to vnode +.Fa vp , +creating the object if necessary. +The object is returned. +.Pp +The +.Fn uvm_vnp_setsize +function sets the size of vnode +.Fa vp +to +.Fa newsize . +Caller must hold a reference to the vnode. +If the vnode shrinks, pages no longer used are discarded. +This function will be removed when the file system and VM buffer caches +are merged. +.Pp +The +.Fn uvm_vnp_sync +function flushes dirty vnodes from either the mount point passed in +.Fa mp , +or all dirty vnodes if +.Fa mp +is +.Dv NULL . +This function will be removed when the file system and VM buffer caches +are merged. +.Pp +The +.Fn uvm_vnp_terminate +function frees all VM resources allocated to vnode +.Fa vp . +If the vnode still has references, it will not be destroyed; however +all future operations using this vnode will fail. +This function will be removed when the file system and VM buffer caches +are merged. +.Pp +The +.Fn uvm_vnp_uncache +function disables vnode +.Fa vp +from persisting when all references are freed. +This function will be removed when the file system and UVM caches +are unified. +Returns true if there is no active vnode. +.Sh SEE ALSO +.Xr uvm_init 9 diff --git a/static/openbsd/man9/vaccess.9 b/static/openbsd/man9/vaccess.9 new file mode 100644 index 00000000..a44d3ff0 --- /dev/null +++ b/static/openbsd/man9/vaccess.9 @@ -0,0 +1,98 @@ +.\" $OpenBSD: vaccess.9,v 1.9 2013/06/04 19:27:15 schwarze Exp $ +.\"- +.\" 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 $Mdocdate: June 4 2013 $ +.Dt VACCESS 9 +.Os +.Sh NAME +.Nm vaccess +.Nd check access permissions based on 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 uid" +.Fa "gid_t gid" +.Fa "mode_t acc_mode" +.Fa "struct ucred *cred" +.Fc +.Sh DESCRIPTION +The +.Fn vaccess +function checks if the credentials described in +.Fa cred +are sufficient to perform the operation described by +.Fa acc_mode , +based on the +.Fa type , +.Fa file_mode , +.Fa uid , +and +.Fa gid +arguments. +These arguments would typically be based on the vnode being +accessed. +.Pp +.Fa file_mode +is the current mode of the file that is having access checked. +The +.Fa uid +and +.Fa gid +arguments are the user id and group id representing the owner of the file. +.Fa acc_mode +describes the operation desired. +It should be one of +.Dv VREAD , +.Dv VWRITE , +or +.Dv VEXEC +representing read, write, and execute, respectively. +.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. +.El +.Sh SEE ALSO +.Xr vnode 9 +.Sh HISTORY +This man page was originally written by +.An Robert Watson +for +.Fx . +It was modified to represent the +.Ox +implementation by +.An Peter Werner . diff --git a/static/openbsd/man9/vclean.9 b/static/openbsd/man9/vclean.9 new file mode 100644 index 00000000..324471a3 --- /dev/null +++ b/static/openbsd/man9/vclean.9 @@ -0,0 +1,80 @@ +.\" $OpenBSD: vclean.9,v 1.11 2020/11/14 10:35:58 jmc Exp $ +.\"- +.\" Copyright (c) 2002 Peter Werner +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd $Mdocdate: November 14 2020 $ +.Dt VCLEAN 9 +.Os +.Sh NAME +.Nm vclean +.Nd disassociate the underlying file system from a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fo vclean +.Fa "struct vnode *vp" +.Fa "int flags" +.Fa "struct proc *p" +.Fc +.Sh DESCRIPTION +The +.Fn vclean +function clears any VM and buffer data associated with the vnode +.Fa vp +and reclaims it from the underlying file system. +.Pp +Its arguments are: +.Bl -tag -width "flags" +.It Fa vp +The vnode to be cleaned. +.It Fa flags +The flags indicating how the vnode should be handled. +.Bl -tag -width "DOCLOSE" +.It Dv DOCLOSE +If this flag is set, +.Fn vclean +will call +.Xr vinvalbuf 9 +on the vnode. +If the vnode is active, it will be closed and inactivated in the +underlying file system. +.El +.It Fa p +The process responsible for this call. +.El +.Pp +On exit, the +.Va v_tag +field of the vnode will be set to +.Dv VT_NON , +and if the vnode was active, it will be placed on the vnode free list. +.Sh SEE ALSO +.Xr vinvalbuf 9 , +.Xr vnode 9 +.Sh HISTORY +This man page was originally written for +.Ox . diff --git a/static/openbsd/man9/vcount.9 b/static/openbsd/man9/vcount.9 new file mode 100644 index 00000000..664d925d --- /dev/null +++ b/static/openbsd/man9/vcount.9 @@ -0,0 +1,61 @@ +.\" $OpenBSD: vcount.9,v 1.7 2013/06/04 19:27:15 schwarze Exp $ +.\" +.\" Copyright (c) 2000 Andrew Stevenson +.\" +.\" 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 this man page travels to places exotic (like projects other than +.\" FreeBSD) I would love to hear about it. +.\" Andrew +.\" +.\" $FreeBSD: src/share/man/man9/vcount.9,v 1.4 2001/12/26 23:14:04 davidc Exp $ +.\" +.Dd $Mdocdate: June 4 2013 $ +.Dt VCOUNT 9 +.Os +.Sh NAME +.Nm vcount +.Nd get total number of references to a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/time.h +.In sys/conf.h +.In sys/vnode.h +.Ft int +.Fn vcount "struct vnode *vp" +.Sh DESCRIPTION +.Fn vcount +is used to get the number of references to a particular device. +It allows for the fact that multiple vnodes may reference the same device. +.Sh RETURN VALUES +.Fn vcount +returns the number of references to the device. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This man page was originally written by +.An Andrew Stevenson +for +.Fx . diff --git a/static/openbsd/man9/vdevgone.9 b/static/openbsd/man9/vdevgone.9 new file mode 100644 index 00000000..22a38f73 --- /dev/null +++ b/static/openbsd/man9/vdevgone.9 @@ -0,0 +1,81 @@ +.\" $OpenBSD: vdevgone.9,v 1.8 2020/11/14 10:35:58 jmc Exp $ +.\"- +.\" Copyright (c) 2002 Peter Werner +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd $Mdocdate: November 14 2020 $ +.Dt VDEVGONE 9 +.Os +.Sh NAME +.Nm vdevgone +.Nd revoke all specified minor numbered vnodes for a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fo vdevgone +.Fa "int maj" +.Fa "int minl" +.Fa "int minh" +.Fa "enum vtype type" +.Fc +.Sh DESCRIPTION +The +.Fn vdevgone +function will revoke all the vnodes corresponding to the specified minor +number range for the device with a major number of +.Fa maj +and of type +.Fa type . +.Pp +Its arguments are: +.Bl -tag -width "type" +.It Fa maj +The major number of the device. +.It Fa minl +The lowest minor number for the device to be revoked. +.It Fa minh +The highest minor number for the device to be revoked. +.It Fa type +The type of the device; this must be one of: +.Bl -tag -width "VBLK" +.It Dv VBLK +Device is a block device +.It Dv VCHR +Device is a character device +.El +.El +.Pp +The endpoints specified by +.Fa minl +and +.Fa minh +are inclusive. +.Sh SEE ALSO +.Xr vfinddev 9 , +.Xr vnode 9 +.Sh HISTORY +This man page was originally written for +.Ox . diff --git a/static/openbsd/man9/vfinddev.9 b/static/openbsd/man9/vfinddev.9 new file mode 100644 index 00000000..1827f815 --- /dev/null +++ b/static/openbsd/man9/vfinddev.9 @@ -0,0 +1,60 @@ +.\" $OpenBSD: vfinddev.9,v 1.7 2013/06/04 19:27:15 schwarze Exp $ +.\"- +.\" Copyright (c) 2002 Peter Werner +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd $Mdocdate: June 4 2013 $ +.Dt VFINDDEV 9 +.Os +.Sh NAME +.Nm vfinddev +.Nd lookup a vnode by device number +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fo vfinddev +.Fa "dev_t dev" +.Fa "enum vtype type" +.Fa "struct vnode **vpp" +.Fc +.Sh DESCRIPTION +The +.Fn vfinddev +function returns a pointer to the vnode of the device represented by the +device number +.Fa dev +and of type +.Fa type +in +.Fa vpp . +.Sh RETURN VALUES +.Fn vfinddev +will return 1 if a corresponding vnode was found, 0 otherwise. +.Sh SEE ALSO +.Xr vnode 9 +.Sh HISTORY +This man page was originally written for +.Ox . diff --git a/static/openbsd/man9/vflush.9 b/static/openbsd/man9/vflush.9 new file mode 100644 index 00000000..cba83401 --- /dev/null +++ b/static/openbsd/man9/vflush.9 @@ -0,0 +1,79 @@ +.\" $OpenBSD: vflush.9,v 1.7 2020/11/14 10:35:58 jmc Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/vflush.9,v 1.2 2001/12/14 09:11:13 ru Exp $ +.\" +.Dd $Mdocdate: November 14 2020 $ +.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" "struct vnode *skipvp" "int flags" +.Sh DESCRIPTION +The +.Fn vflush +function removes any vnodes in the vnode table that belong to the given +mount structure. +.Pp +Its arguments are: +.Bl -tag -width "rootrefs" +.It Fa mp +The mount point whose vnodes should be removed. +.It Fa skipvp +If this is given, the vnode it represents will be skipped. +.It Fa flags +The flags indicating how vnodes should be handled. +.Bl -tag -width "WRITECLOSE" +.It Dv FORCECLOSE +If set, busy vnodes will be forcibly closed. +.It Dv SKIPSYSTEM +If set, vnodes with the +.Dv VSYSTEM +flag set will be skipped. +.It Dv WRITECLOSE +If set, only regular files currently opened for writing will be removed. +.El +.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 vgonel 9 , +.Xr vnode 9 , +.Xr vrele 9 +.Sh AUTHORS +This man page was originally written by +.An Chad David Aq Mt davidc@acns.ab.ca +for +.Fx . diff --git a/static/openbsd/man9/vflushbuf.9 b/static/openbsd/man9/vflushbuf.9 new file mode 100644 index 00000000..80f0492a --- /dev/null +++ b/static/openbsd/man9/vflushbuf.9 @@ -0,0 +1,33 @@ +.\" $OpenBSD: vflushbuf.9,v 1.3 2013/06/04 19:27:16 schwarze Exp $ +.\" Written by Jared Yanovich +.\" This file belongs to the public domain. +.Dd $Mdocdate: June 4 2013 $ +.Dt VFLUSHBUF 9 +.Os +.Sh NAME +.Nm vflushbuf +.Nd flush dirty vnode buffers to disk +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vflushbuf "struct vnode *vp" "int sync" +.Sh DESCRIPTION +The +.Fn vflushbuf +function flushes all dirty buffers associated with the vnode +.Fa vp +to the disk. +If the +.Fa sync +argument is zero, writes to the disk will be asynchronous and +.Fn vflushbuf +returns immediately; otherwise, writes will be synchronous and all +disk blocks associated with the vnode will have been properly +synchronized with the in-core buffers upon return. +.Sh SEE ALSO +.Xr vinvalbuf 9 , +.Xr vnode 9 +.Sh HISTORY +This document first appeared in +.Ox 3.7 . diff --git a/static/openbsd/man9/vfs.9 b/static/openbsd/man9/vfs.9 new file mode 100644 index 00000000..fc4b85be --- /dev/null +++ b/static/openbsd/man9/vfs.9 @@ -0,0 +1,57 @@ +.\" $OpenBSD: vfs.9,v 1.4 2008/06/26 05:42:08 ray Exp $ +.\" $NetBSD: vfs.9,v 1.7 2003/02/25 10:35:34 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 $Mdocdate: June 26 2008 $ +.Dt VFS 9 +.Os +.Sh NAME +.Nm vfs +.Nd kernel interface to file systems +.Sh DESCRIPTION +The virtual file system, +.Nm VFS , +is the kernel interface to file systems. +The interface specifies the calls for the kernel to access file systems. +It also specifies the core functionality that a file system must provide +to the kernel. +.Pp +The focus of +.Nm +activity is the +.Em vnode +and is discussed in +.Xr vnode 9 . +.\" File system operations such as mounting and syncing are discussed in +.\" .Xr vfsops 9 . +.Sh SEE ALSO +.Xr intro 9 , +.\" .Xr vfsops 9 , +.Xr vnode 9 , +.Xr VOP_LOOKUP 9 diff --git a/static/openbsd/man9/vfs_busy.9 b/static/openbsd/man9/vfs_busy.9 new file mode 100644 index 00000000..1b6536ea --- /dev/null +++ b/static/openbsd/man9/vfs_busy.9 @@ -0,0 +1,85 @@ +.\" $OpenBSD: vfs_busy.9,v 1.3 2018/06/04 04:57:09 guenther Exp $ +.\" +.\" Copyright (c) 2006 Nikolay Sturm +.\" +.\" 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: June 4 2018 $ +.Dt VFS_BUSY 9 +.Os +.Sh NAME +.Nm vfs_busy , +.Nm vfs_isbusy , +.Nm vfs_unbusy +.Nd VFS locking API +.Sh SYNOPSIS +.In sys/mount.h +.Pp +.Ft int +.Fn vfs_busy "struct mount *mp" "int flags" +.Ft int +.Fn vfs_isbusy "struct mount *mp" +.Ft void +.Fn vfs_unbusy "struct mount *mp" +.Sh DESCRIPTION +The +.Nm vfs_busy +API is used to lock mount points to ensure consistent access. +A read lock can be shared between multiple processes, while a write lock is +exclusive. +Normally a write lock is only acquired when unmounting. +.Pp +The +.Fn vfs_busy +function locks the mount point pointed to by +.Fa mp , +where +.Fa flags +describes the type of lock to acquire and whether or not to wait for a +conflicting lock to be released. +The following flags are available: +.Pp +.Bl -tag -width "VB_NOWAITXX" -offset indent -compact +.It VB_READ +Acquire a read lock. +.It VB_WRITE +Acquire a write lock. +.It VB_NOWAIT +Return immediately; do not wait for the conflicting lock to be released. +.It VB_WAIT +Wait for the conflicting lock to be released. +.It VB_DUPOK +Prevent +.Xr witness 4 +from logging when this thread already has a mount point locked. +.El +.Pp +If a conflicting lock was encountered, +.Fn vfs_busy +returns an error. +.Pp +The +.Fn vfs_isbusy +function checks whether the given mount point is locked. +.Pp +.Fn vfs_unbusy +unlocks the given mount point. +.Pp +The +.Nm vfs_busy +API is implemented in the file +.Pa sys/kern/vfs_subr.c . +.Sh SEE ALSO +.Xr witness 4 , +.Xr rwlock 9 , +.Xr vfs 9 diff --git a/static/openbsd/man9/vfs_cache.9 b/static/openbsd/man9/vfs_cache.9 new file mode 100644 index 00000000..b6ebe043 --- /dev/null +++ b/static/openbsd/man9/vfs_cache.9 @@ -0,0 +1,179 @@ +.\" $OpenBSD: vfs_cache.9,v 1.4 2018/06/04 19:42:54 kn Exp $ +.\" Written by Jared Yanovich +.\" Public domain, 2005/6/17 +.Dd $Mdocdate: June 4 2018 $ +.Dt VFS_CACHE 9 +.Os +.Sh NAME +.Nm vfs_cache , +.Nm cache_enter , +.Nm cache_lookup , +.Nm cache_purge , +.Nm cache_purgevfs , +.Nm cache_revlookup +.Nd name lookup cache +.Sh SYNOPSIS +.In sys/vnode.h +.In sys/namei.h +.Pp +.Ft int +.Fn cache_lookup "struct vnode *dvp" "struct vnode **vpp" \ + "struct componentname *cnp" +.Ft void +.Fn cache_enter "struct vnode *dvp" "struct vnode *vp" \ + "struct componentname *cnp" +.Ft void +.Fn cache_purge "struct vnode *vp" +.Ft void +.Fn cache_purgevfs "struct mount *mp" +.Ft int +.Fn cache_revlookup "struct vnode *vp" "struct vnode **dvpp" \ + "char **bpp" "char *bufp" +.Sh DESCRIPTION +In order to speed up file name look-up operations (see +.Xr VOP_LOOKUP 9 ) , +the kernel provides an interface for maintaining a cache of the most +recently looked-up file name translations. +Entries in this cache have the following definition: +.Bd -literal +struct namecache { + TAILQ_ENTRY(namecache) nc_lru; /* Regular Entry LRU chain */ + TAILQ_ENTRY(namecache) nc_neg; /* Negative Entry LRU chain */ + RBT_ENTRY(namecache) n_rbcache; /* Namecache rb tree from vnode */ + TAILQ_ENTRY(namecache) nc_me; /* ncp's referring to me */ + struct vnode *nc_dvp; /* vnode of parent of name */ + u_long nc_dvpid; /* capability number of nc_dvp */ + struct vnode *nc_vp; /* vnode the name refers to */ + u_long nc_vpid; /* capability number of nc_vp */ + char nc_nlen; /* length of name */ + char nc_name[NAMECACHE_MAXLEN]; /* segment name */ +}; +.Ed +.Pp +The cache is indexed by a hash value based on the file's base name and +its encompassing directory's vnode generation number. +Negative caching is also performed so that frequently accessed path +names of files that do not exist do not result in expensive lookups. +.Pp +File names with length longer than +.Dv NAMECACHE_MAXLEN +are not cached to simplify lookups and to save space. +Such names are rare and are generally not worth caching. +.Pp +The +.Nm vfs_cache +API contains the following routines: +.Bl -tag -width Ds +.It Fn cache_lookup dvp vpp cnp +Look up the given name in the cache. +.Fa dvp +points to the directory to search, +.Fa vpp +points to a pointer where the vnode of the name being sought will be +stored, and +.Fa cnp +contains the last component of the path name. +.Fa cnp +must have the +.Va cn_nameptr , +.Va cn_namelen , +and +.Va cn_hash +fields filled in. +If no entry is found for the given name, a new one will be created, +even if the path name fails (i.e. it will be negative cached), unless +the +.Xr namei 9 +lookup operation was +.Dv DELETE +or the +.Dv NOCACHE +flag was set for the call to +.Xr namei 9 . +.Pp +Upon success, a pointer to a locked vnode is stored in +.Fa vpp +and a zero value is returned. +If locking the vnode fails, the vnode will remain unlocked, +.Fa *vpp +will be set to +.Dv NULL , +and the corresponding error will be returned. +If the cache entry is negative cached, meaning the name is no longer +valid, +.Er ENOENT +is returned. +Otherwise, the cache lookup has failed and a \-1 value is returned. +.It Fn cache_enter dvp vp cnp +Add a new entry for the translation in the directory +.Fa dvp +for the vnode +.Fa vp +with name +.Fa cnp +to the cache. +.Fa cnp +must have the +.Va cn_nameptr , +.Va cn_namelen , +and +.Va cn_hash +fields filled in. +.It Fn cache_purge vp +Flush all cache entries corresponding with the given vnode +.Fa vp . +This is called after rename operations to hide entries that would no +longer be valid. +.It Fn cache_purgevfs mp +Flush all cache entries for name translations associated with the file +system mount described by +.Fa mp . +This is called when unmounting file systems, which would make all name +translations pertaining to the mount invalid. +.It Fn cache_revlookup vp dvpp bpp bufp +Scan the cache for the name of the directory entry that points to +.Fa vp . +.Fa dvpp +points to where a pointer to the encompassing directory will be stored. +If +.Fa bufp +is not +.Dv NULL , +the name will be written to the end of the space between this pointer +and the value in +.Fa bpp , +and +.Fa bpp +will be updated on return to point to the start of the copied name. +.Pp +On success, +.Fa *dvpp +will be set to point to the encompassing directory and zero will be +returned. +If the cache misses, +.Fa dvpp +will be set to +.Dv NULL +and \-1 will be returned. +Otherwise, failure has occurred, +.Fa dvpp +will be set to +.Dv NULL , +and an appropriate error code will be returned. +.El +.Sh CODE REFERENCES +The +.Nm +API is implemented in the file +.Pa sys/kern/vfs_cache.c . +.Sh SEE ALSO +.Xr vmstat 8 , +.Xr namei 9 , +.Xr vfs 9 , +.Xr vnode 9 , +.Xr VOP_LOOKUP 9 +.Sh HISTORY +The +.Nm +API first appeared in +.Bx 4.2 . diff --git a/static/openbsd/man9/vget.9 b/static/openbsd/man9/vget.9 new file mode 100644 index 00000000..2780acbb --- /dev/null +++ b/static/openbsd/man9/vget.9 @@ -0,0 +1,90 @@ +.\" $OpenBSD: vget.9,v 1.12 2018/05/27 06:02:14 visa Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/vget.9,v 1.7 2001/12/26 23:14:04 davidc Exp $ +.\" +.Dd $Mdocdate: May 27 2018 $ +.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 flags" +.Sh DESCRIPTION +Get a vnode from the free list and increment its reference count. +.Pp +Its arguments are: +.Bl -tag -width flags +.It Fa vp +The vnode to remove from the free list. +.It Fa flags +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 ERRORS +.Bl -tag -width Er +.It Bq Er ENOENT +The vnode +.Fa vp +is in the process of being cleaned out from the underlying +file system. +.It Bq Er EBUSY +The vnode +.Fa vp +is in the process of being cleaned out from the underlying file system, and +it wasn't possible to sleep on it because the +.Dv LK_NOWAIT +flag was specified. +.El +.Sh SEE ALSO +.Xr vnode 9 , +.Xr vput 9 , +.Xr vref 9 , +.Xr vrele 9 +.Sh AUTHORS +This man page was originally written by +.An Doug Rabson +for +.Fx . diff --git a/static/openbsd/man9/vgone.9 b/static/openbsd/man9/vgone.9 new file mode 100644 index 00000000..963b71dc --- /dev/null +++ b/static/openbsd/man9/vgone.9 @@ -0,0 +1,72 @@ +.\" $OpenBSD: vgone.9,v 1.10 2020/08/05 11:10:24 tim Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/vgone.9,v 1.2 2001/12/14 09:11:13 ru Exp $ +.\" +.Dd $Mdocdate: August 5 2020 $ +.Dt VGONE 9 +.Os +.Sh NAME +.Nm vgone , +.Nm vgonel +.Nd prepare a vnode for reuse +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vgone "struct vnode *vp" +.Ft void +.Fn vgonel "struct vnode *vp" "struct proc *p" +.Sh DESCRIPTION +.Fn vgone +and +.Fn vgonel +prepare the vnode +.Fa vp +for reuse by another file system. +The preparation includes the cleaning of all file system specific data and +the removal from its mount point vnode list. +The +.Fa p +argument specifies the process responsible for the call. +.Pp +.Fn vgone +is identical to +.Fn vgonel +with a +.Fa p +value of +.Dv curproc . +.Sh SEE ALSO +.Xr vclean 9 , +.Xr vnode 9 , +.Xr vrecycle 9 +.Sh AUTHORS +This man page was originally written by +.An Chad David Aq Mt davidc@acns.ab.ca +for +.Fx . diff --git a/static/openbsd/man9/vhold.9 b/static/openbsd/man9/vhold.9 new file mode 100644 index 00000000..1eced6f9 --- /dev/null +++ b/static/openbsd/man9/vhold.9 @@ -0,0 +1,74 @@ +.\" $OpenBSD: vhold.9,v 1.9 2013/07/17 20:21:55 schwarze Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/vhold.9,v 1.2 2001/12/14 09:11:13 ru Exp $ +.\" +.Dd $Mdocdate: July 17 2013 $ +.Dt VHOLD 9 +.Os +.Sh NAME +.Nm vhold , +.Nm vdrop +.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 vdrop "struct vnode *vp" +.Sh DESCRIPTION +The +.Fn vhold +function increments the +.Va v_holdcnt +of the given vnode. +If the vnode has already been added to the free list and its +.Va v_holdcnt +and +.Va v_usecount +are both zero, it will be removed from the free list and +added to the vnode hold list. +.Pp +The +.Fn vdrop +function decrements the +.Va v_holdcnt +of the given vnode. +If the vnode is on the vnode hold list and its +.Va v_holdcnt +and +.Va v_usecount +are both zero, it will be removed from the vnode hold list and +added to the freed list. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This man page was originally written by +.An Chad David Aq Mt davidc@acns.ab.ca +for +.Fx . diff --git a/static/openbsd/man9/vinvalbuf.9 b/static/openbsd/man9/vinvalbuf.9 new file mode 100644 index 00000000..f955cbb0 --- /dev/null +++ b/static/openbsd/man9/vinvalbuf.9 @@ -0,0 +1,132 @@ +.\" $OpenBSD: vinvalbuf.9,v 1.13 2020/11/14 10:35:58 jmc Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/vinvalbuf.9,v 1.6 2001/10/06 11:19:41 sheldonh Exp $ +.\" +.Dd $Mdocdate: November 14 2020 $ +.Dt VINVALBUF 9 +.Os +.Sh NAME +.Nm vinvalbuf +.Nd flush and invalidate 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" \ + "struct proc *p" "int slpflag" "uint64_t 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 the +.Dv V_SAVEMETA +flag is set, indirect blocks will not be flushed. +.Pp +Its arguments are: +.Bl -tag -width "slptimeo" +.It Fa vp +A pointer to the vnode whose buffers will be invalidated. +.It Fa flags +The supported flags are +.Dv V_SAVE +and +.Dv V_SAVEMETA . +.Dv V_SAVE +indicates that dirty buffers should be synced with the disk. +.Dv V_SAVEMETA +indicates that indirect blocks should not be flushed. +.It Fa cred +The user credentials that are used to +.Xr VOP_FSYNC 9 +buffers if +.Dv V_SAVE +is set. +.It Fa p +The process responsible for this call. +.It Fa slpflag +The slp flag that will be used in the priority of any calls to +.Xr tsleep_nsec 9 +in the function. +.It Fa slptimeo +The timeout for any calls to +.Xr tsleep_nsec 9 +in the function. +.El +.Sh LOCKS +The vnode is assumed to be locked prior to the call and remains locked upon +return. +.Sh RETURN VALUES +A value of 0 is returned on success. +.Sh PSEUDOCODE +.Bd -literal -offset indent +vn_lock(devvp, LK_EXCLUSIVE | LK_RETRY); +error = vinvalbuf(devvp, V_SAVE, cred, p, 0, 0); +VOP_UNLOCK(devvp); +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 vnode 9 +.Sh AUTHORS +This man page was originally written by +.An Chad David Aq Mt davidc@acns.ab.ca +for +.Fx . diff --git a/static/openbsd/man9/vnode.9 b/static/openbsd/man9/vnode.9 new file mode 100644 index 00000000..033e27b7 --- /dev/null +++ b/static/openbsd/man9/vnode.9 @@ -0,0 +1,416 @@ +.\" $OpenBSD: vnode.9,v 1.36 2025/10/18 10:57:42 mvs Exp $ +.\" +.\" Copyright (c) 2001 Constantine Sapuntzakis +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the 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 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" 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 $Mdocdate: October 18 2025 $ +.Dt VNODE 9 +.Os +.Sh NAME +.Nm vnode +.Nd an overview of vnodes +.Sh DESCRIPTION +A +.Em vnode +is an object in kernel memory that speaks the +.Ux +file interface (open, read, write, close, readdir, etc.). +Vnodes can represent files, directories, FIFOs, domain sockets, block devices, +character devices. +.Pp +Each vnode has a set of methods which start with the string +.Dq VOP_ . +These methods include +.Fn VOP_OPEN , +.Fn VOP_READ , +.Fn VOP_WRITE , +.Fn VOP_RENAME , +.Fn VOP_CLOSE , +and +.Fn VOP_MKDIR . +Many of these methods correspond closely to the equivalent +file system call \- +.Xr open 2 , +.Xr read 2 , +.Xr write 2 , +.Xr rename 2 , +etc. +Each file system (FFS, NFS, etc.) provides implementations for these methods. +.Pp +The Virtual File System library (see +.Xr vfs 9 ) +maintains a pool of vnodes. +File systems cannot allocate their own vnodes; they must use the functions +provided by the VFS to create and manage vnodes. +.Pp +The definition of a vnode is as follows: +.Bd -literal +struct vnode { + struct uvm_vnode *v_uvm; /* uvm data */ + const struct vops *v_op; /* vnode operations vector */ + enum vtype v_type; /* vnode type */ + enum vtagtype v_tag; /* type of underlying data */ + u_int v_flag; /* vnode flags (see below) */ + u_int v_usecount; /* reference count of users */ + u_int v_uvcount; /* unveil references */ + /* reference count of writers */ + u_int v_writecount; + /* Flags that can be read/written in interrupts */ + u_int v_bioflag; + u_int v_holdcnt; /* buffer references */ + u_int v_id; /* capability identifier */ + u_int v_inflight; + struct mount *v_mount; /* ptr to vfs we are in */ + TAILQ_ENTRY(vnode) v_freelist; /* vnode freelist */ + LIST_ENTRY(vnode) v_mntvnodes; /* vnodes for mount point */ + struct buf_rb_bufs v_bufs_tree; /* lookup of all bufs */ + struct buflists v_cleanblkhd; /* clean blocklist head */ + struct buflists v_dirtyblkhd; /* dirty blocklist head */ + u_int v_numoutput; /* num of writes in progress */ + LIST_ENTRY(vnode) v_synclist; /* vnode with dirty buffers */ + union { + struct mount *vu_mountedhere;/* ptr to mounted vfs (VDIR) */ + struct socket *vu_socket; /* unix ipc (VSOCK) */ + struct specinfo *vu_specinfo; /* device (VCHR, VBLK) */ + struct fifoinfo *vu_fifoinfo; /* fifo (VFIFO) */ + } v_un; + + /* VFS namecache */ + struct namecache_rb_cache v_nc_tree; + TAILQ_HEAD(, namecache) v_cache_dst; /* cache entries to us */ + + void *v_data; /* private data for fs */ + struct klist v_klist; /* identity of poller(s) */ +}; +#define v_mountedhere v_un.vu_mountedhere +#define v_socket v_un.vu_socket +#define v_specinfo v_un.vu_specinfo +#define v_fifoinfo v_un.vu_fifoinfo +.Ed +.Ss Vnode life cycle +When a client of the VFS requests a new vnode, the vnode allocation +code can reuse an old vnode object that is no longer in use. +Whether a vnode is in use is tracked by the vnode reference count +.Pq Va v_usecount . +By convention, each open file handle holds a reference +as do VM objects backed by files. +A vnode with a reference count of 1 or more will not be deallocated or +reused to point to a different file. +So, if you want to ensure that your vnode doesn't become a different +file under you, you better be sure you have a reference to it. +A vnode that points to a valid file and has a reference count of 1 or more +is called +.Em active . +.Pp +When a vnode's reference count drops to zero, it becomes +.Em inactive , +that is, a candidate for reuse. +An inactive vnode still refers to a valid file and one can try to +reactivate it using +.Xr vget 9 +(this is used a lot by caches). +.Pp +Before the VFS can reuse an inactive vnode to refer to another file, +it must clean all information pertaining to the old file. +A cleaned out vnode is called a +.Em reclaimed +vnode. +.Pp +To support forceable unmounts and the +.Xr revoke 2 +system call, the VFS may reclaim a vnode with a positive reference +count. +The reclaimed vnode is given to the dead file system, which +returns errors for most operations. +The reclaimed vnode will not be +reused for another file until its reference count hits zero. +.Ss Vnode pool +The +.Xr getnewvnode 9 +call allocates a vnode from the pool, possibly reusing an +inactive vnode, and returns it to the caller. +The vnode returned has a reference count +.Pq Va v_usecount +of 1. +.Pp +The +.Xr vref 9 +call increments the reference count on the vnode. +It may only be on a vnode with reference count of 1 or greater. +The +.Xr vrele 9 +and +.Xr vput 9 +calls decrement the reference count. +In addition, the +.Xr vput 9 +call also releases the vnode lock. +.Pp +The +.Xr vget 9 +call, when used on an inactive vnode, will make the vnode active +by bumping the reference count to one. +When called on an active vnode, +.Fn vget +increases the reference count by one. +However, if the vnode is being reclaimed concurrently, then +.Fn vget +will fail and return an error. +.Pp +The +.Xr vgone 9 +and +.Xr vgonel 9 +calls +orchestrate the reclamation of a vnode. +They can be called on both active and inactive vnodes. +.Pp +When transitioning a vnode to the reclaimed state, the VFS will call the +.Xr VOP_RECLAIM 9 +method. +File systems use this method to free any file-system-specific data +they attached to the vnode. +.Ss Vnode locks +The vnode actually has two different types of locks: the vnode lock +and the vnode reclamation lock +.Pq Dv VXLOCK . +.Ss The vnode lock +The vnode lock and its consistent use accomplishes the following: +.Bl -bullet +.It +It keeps a locked vnode from changing across certain pairs of VOP_ calls, +thus preserving cached data. +For example, it keeps the directory from +changing between a +.Xr VOP_LOOKUP 9 +call and a +.Xr VOP_CREATE 9 . +The +.Fn VOP_LOOKUP +call makes sure the name doesn't already exist in the +directory and finds free room in the directory for the new entry. +The +.Fn VOP_CREATE +call can then go ahead and create the file without checking if +it already exists or looking for free space. +.It +Some file systems rely on it to ensure that only one +.Dq thread +at a time +is calling VOP_ vnode operations on a given file or directory. +Otherwise, the file system's behavior is undefined. +.It +On rare occasions, code will hold the vnode lock so that a series of +VOP_ operations occurs as an atomic unit. +(Of course, this doesn't work with network file systems like NFSv2 that don't +have any notion of bundling a bunch of operations into an atomic unit.) +.It +While the vnode lock is held, the vnode will not be reclaimed. +.El +.Pp +There is a discipline to using the vnode lock. +Some VOP_ operations require that the vnode lock is held before being called. +.Pp +The vnode lock is acquired by calling +.Xr vn_lock 9 +and released by calling +.Xr VOP_UNLOCK 9 . +.Pp +A process is allowed to sleep while holding the vnode lock. +.Pp +The implementation of the vnode lock is the responsibility of the individual +file systems. +Not all file systems implement it. +.Pp +To prevent deadlocks, when acquiring locks on multiple vnodes, the lock +of parent directory must be acquired before the lock on the child directory. +.Ss Other vnode synchronization +The vnode reclamation lock +.Pq Dv VXLOCK +is used to prevent multiple +processes from entering the vnode reclamation code. +It is also used as a flag to indicate that reclamation is in progress. +The +.Dv VXWANT +flag is set by processes that wish to be woken up when reclamation +is finished. +.Pp +The +.Xr vwaitforio 9 +call is used to wait for all outstanding write I/Os associated with a +vnode to complete. +.Ss Version number/capability +The vnode capability, +.Va v_id , +is a 32-bit version number on the vnode. +Every time a vnode is reassigned to a new file, the vnode capability +is changed. +This is used by code that wishes to keep pointers to vnodes but doesn't want +to hold a reference (e.g., caches). +The code keeps both a vnode pointer and a copy of the capability. +The code can later compare the vnode's capability to its copy and see +if the vnode still points to the same file. +.Pp +Note: for this to work, memory assigned to hold a +.Vt struct vnode +can +only be used for another purpose when all pointers to it have disappeared. +Since the vnode pool has no way of knowing when all pointers have +disappeared, it never frees memory it has allocated for vnodes. +.Ss Vnode fields +Most of the fields of the vnode structure should be treated as opaque +and only manipulated through the proper APIs. +This section describes the fields that are manipulated directly. +.Pp +The +.Va v_flag +attribute contains random flags related to various functions. +They are summarized in the following table: +.Pp +.Bl -tag -width 10n -compact -offset indent +.It Dv VROOT +This vnode is the root of its file system. +.It Dv VTEXT +This vnode is a pure text prototype. +.It Dv VSYSTEM +This vnode is being used by kernel. +.It Dv VISTTY +This vnode represents a +.Xr tty 4 . +.It Dv VXLOCK +This vnode is locked to change its underlying type. +.It Dv VXWANT +A process is waiting for this vnode. +.It Dv VALIASED +This vnode has an alias. +.It Dv VLOCKSWORK +This vnode's underlying file system supports locking discipline. +.El +.Pp +The +.Va v_tag +attribute indicates what file system the vnode belongs to. +Very little code actually uses this attribute and its use is deprecated. +Programmers should seriously consider using more object-oriented approaches +(e.g. function tables). +There is no safe way of defining new +.Va v_tag Ns 's +for loadable file systems. +The +.Va v_tag +attribute is read-only. +.Pp +The +.Va v_type +attribute indicates what type of file (e.g. directory, +regular, FIFO) this vnode is. +This is used by the generic code for various checks. +For example, the +.Xr read 2 +system call returns zero when a read is attempted on a directory. +.Pp +Possible types are: +.Pp +.Bl -tag -width 10n -offset indent -compact +.It Dv VNON +This vnode has no type. +.It Dv VREG +This vnode represents a regular file. +.It Dv VDIR +This vnode represents a directory. +.It Dv VBLK +This vnode represents a block device. +.It Dv VCHR +This vnode represents a character device. +.It Dv VLNK +This vnode represents a symbolic link. +.It Dv VSOCK +This vnode represents a socket. +.It Dv VFIFO +This vnode represents a named pipe. +.It Dv VBAD +This vnode represents a bad or dead file. +.El +.Pp +The +.Va v_data +attribute allows a file system to attach a piece of file +system specific memory to the vnode. +This contains information about the file that is specific to +the file system (such as an inode pointer in the case of FFS). +.Pp +The +.Va v_numoutput +attribute indicates the number of pending synchronous +and asynchronous writes on the vnode. +It does not track the number of dirty buffers attached to the vnode. +The attribute is used by code like +.Xr fsync 2 +to wait for all writes +to complete before returning to the user. +This attribute must be manipulated at +.Xr splbio 9 . +.Pp +The +.Va v_writecount +attribute tracks the number of write calls pending +on the vnode. +.Ss Rules +The vast majority of vnode functions may not be called from interrupt +context. +The exceptions are +.Fn bgetvp +and +.Fn brelvp . +The following fields of the vnode are manipulated at interrupt level: +.Va v_numoutput , v_holdcnt , v_dirtyblkhd , +.Va v_cleanblkhd , v_bioflag , v_freelist , +and +.Va v_synclist . +Any access to these fields should be protected by +.Xr splbio 9 . +.Sh SEE ALSO +.Xr uvn_attach 9 , +.Xr vaccess 9 , +.Xr vclean 9 , +.Xr vcount 9 , +.Xr vdevgone 9 , +.Xr vfinddev 9 , +.Xr vflush 9 , +.Xr vflushbuf 9 , +.Xr vfs 9 , +.Xr vget 9 , +.Xr vgone 9 , +.Xr vhold 9 , +.Xr vinvalbuf 9 , +.Xr vn_lock 9 , +.Xr VOP_LOOKUP 9 , +.Xr vput 9 , +.Xr vrecycle 9 , +.Xr vref 9 , +.Xr vrele 9 , +.Xr vwaitforio 9 , +.Xr vwakeup 9 +.Sh HISTORY +This document first appeared in +.Ox 2.9 . diff --git a/static/openbsd/man9/vnsubr.9 b/static/openbsd/man9/vnsubr.9 new file mode 100644 index 00000000..5719e64d --- /dev/null +++ b/static/openbsd/man9/vnsubr.9 @@ -0,0 +1,304 @@ +.\" $OpenBSD: vnsubr.9,v 1.16 2019/10/06 16:32:56 jmc Exp $ +.\" $NetBSD: vnsubr.9,v 1.21 2004/05/25 14:54:56 hannken Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 $Mdocdate: October 6 2019 $ +.Dt VNSUBR 9 +.Os +.Sh NAME +.Nm vnsubr , +.Nm vn_close , +.Nm vn_default_error , +.Nm vn_isunder , +.Nm vn_lock , +.Nm vn_marktext , +.Nm vn_rdwr , +.Nm vn_open , +.Nm vn_stat , +.Nm vn_writechk +.Nd high-level convenience functions for vnode operations +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/vnode.h +.Ft int +.Fn vn_close "struct vnode *vp" "int flags" "struct ucred *cred" "struct proc *p" +.Ft int +.Fn vn_default_error "void *v" +.Ft int +.Fn vn_isunder "struct vnode *dvp" "struct vnode *rvp" "struct proc *p" +.Ft int +.Fn vn_lock "struct vnode *vp" "int flags" +.Ft void +.Fn vn_marktext "struct vnode *vp" +.Ft int +.Fn vn_open "struct nameidata *ndp" "int fmode" "int cmode" +.Ft int +.Fo vn_rdwr +.Fa "enum uio_rw rw" "struct vnode *vp" "caddr_t base" +.Fa "int len" "off_t offset" "enum uio_seg segflg" "int ioflg" +.Fa "struct ucred *cred" "size_t *aresid" "struct proc *p" +.Fc +.Ft int +.Fn vn_stat "struct vnode *vp" "struct stat *sb" "struct proc *p" +.Ft int +.Fn vn_writechk "struct vnode *vp" +.Sh DESCRIPTION +The high-level functions described in this page are convenience +functions for simplified access to the vnode operations described in +.Xr VOP_LOOKUP 9 . +.Bl -tag -width Ds +.It Fn vn_close "vp" "flags" "cred" "p" +Common code for a vnode close. +The argument +.Fa vp +is the unlocked vnode of the vnode to close. +.Fn vn_close +simply locks the vnode, invokes the vnode operation +.Fn VOP_CLOSE +and calls +.Xr vput 9 +to return the vnode to the freelist or holdlist. +Note that +.Fn vn_close +expects an unlocked, referenced vnode and will dereference the vnode +prior to returning. +If the operation is successful, zero is returned; +otherwise an appropriate error is returned. +.It Fn vn_default_error "v" +A generic "default" routine that just returns error. +It is used by a file system to specify unsupported operations in +the vnode operations vector. +.It Fn vn_isunder "dvp" "rvp" "p" +Common code to check if one directory specified by the vnode +.Fa rvp +can be found inside the directory specified by the vnode +.Fa dvp . +The argument +.Fa p +is the calling process. +.Fn vn_isunder +is intended to be used in +.Xr chroot 2 , +.Xr chdir 2 , +.Xr fchdir 2 , +etc., to ensure that +.Xr chroot 2 +actually means something. +If the operation is successful, zero is returned; otherwise 1 is returned. +.It Fn vn_lock "vp" "flags" +Acquire the vnode lock. +Certain file system operations require that +the vnode lock be held when they are called. +.Pp +The +.Fn vn_lock +function must not be called when the vnode's reference count is +zero. +Instead, the +.Xr vget 9 +function should be used. +.Pp +In addition to the +.Fa flags +accepted by +.Xr VOP_LOCK 9 , +the +.Dv LK_RETRY +flag may be used. +.Dv LK_RETRY +causes +.Fn vn_lock +to return the vnode even if it has been reclaimed. +It must not be used with +.Dv LK_NOWAIT . +.Pp +The +.Fn vn_lock +function can sleep. +.It Fn vn_marktext "vp" +Common code to mark the vnode +.Fa vp +as being the text of a running process. +.It Fn vn_open "ndp" "fmode" "cmode" +Common code for vnode open operations. +.Pp +The pathname is described in the +.Vt nameidata +structure pointed to by the +.Fa ndp +argument. +When initializing the nameidata structure for +.Fn vn_open +with +.Xr NDINIT 9 , +the +.Fa op +must be specified as 0, and the +.Fa flags +may only be 0, or +.Dv KERNELPATH . +The lookup mode and flags are set internally +by +.Fn vn_open . +.Pp +The arguments +.Fa fmode +and +.Fa cmode +specify the +.Xr open 2 +file mode and the access permissions for creation. +.Fn vn_open +checks permissions and invokes the +.Xr VOP_OPEN 9 +or +.Xr VOP_CREATE 9 +vnode operations. +If the operation is successful, zero is returned; +otherwise an appropriate error code is returned. +.It Xo +.Fo vn_rdwr +.Fa "rw" "vp" "base" "len" "offset" +.Fa "segflg" "ioflg" "cred" "aresid" "p" +.Fc +.Xc +Common code to package up an I/O request on a vnode into a +.Vt uio +and then perform the I/O. +The argument +.Fa rw +specifies whether the I/O is a read +.Pq Dv UIO_READ +or write +.Pq Dv UIO_WRITE +operation. +The unlocked vnode is specified by +.Fa vp . +The arguments +.Fa p +and +.Fa cred +are the calling process and its credentials. +The remaining arguments specify the +.Vt uio +parameters. +For further information on these parameters, see +.Xr uiomove 9 . +.It Fn vn_stat "vp" "sb" "p" +Common code for a vnode stat operation. +The vnode is specified by the argument +.Fa vp , +and +.Fa sb +is the buffer in which to store the stat information. +The argument +.Fa p +is the calling process. +.Fn vn_stat +basically calls the vnode operation +.Xr VOP_GETATTR 9 +and transfers the contents of a +.Vt vattr +structure into a +.Vt struct stat . +If the operation is successful, zero is returned; otherwise an +appropriate error code is returned. +.It Fn vn_writechk "vp" +Common code to check for write permission on the vnode +.Fa vp . +A vnode is read-only if it is in use as a process's text image. +If the vnode is read-only, +.Er ETXTBSY +is returned; otherwise zero is +returned to indicate that the vnode can be written to. +.El +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ETXTBSY +Cannot write to a vnode since it is a process's text image. +.It Bq Er ENOENT +The vnode has been reclaimed and is dead. +This error is only returned if the +.Dv LK_RETRY +flag is not passed to +.Fn vn_lock . +.It Bq Er EBUSY +The +.Dv LK_NOWAIT +flag was set and +.Fn vn_lock +would have slept. +.El +.Sh CODE REFERENCES +This section describes places within the +.Ox +source tree where actual code implementing or using the vnode +framework can be found. +All pathnames are relative to +.Pa /usr/src . +.Pp +The high-level convenience functions are implemented within the files +.Pa sys/kern/vfs_vnops.c +and +.Pa sys/sys/vnode.h . +.Sh SEE ALSO +.Xr file 9 , +.Xr namei 9 , +.Xr vfs 9 , +.Xr vnode 9 , +.Xr VOP_LOOKUP 9 +.Sh BUGS +The locking discipline is bizarre. +Many vnode operations are passed locked vnodes on entry but release +the lock before they exit. +Discussions with Kirk McKusick indicate that locking +discipline evolved out of the pre-VFS way of doing inode locking. +In addition, the current locking discipline may actually save +lines of code, especially if the number of file systems is fewer +than the number of call sites. +However, the VFS interface would +require less wizardry if the locking discipline were simpler. +.Pp +The locking discipline is used in some places to attempt to make a +series of operations atomic (e.g., permissions check + +operation). +This does not work for non-local file systems that do not +support locking (e.g., NFS). +.Pp +Are vnode locks even necessary? +The security checks can be moved into the individual file systems. +Each file system can have the responsibility of ensuring that vnode +operations are suitably atomic. +.Pp +The +.Dv LK_NOWAIT +flag does prevent the caller from sleeping. +.Pp +The locking discipline as it relates to shared locks has yet to be defined. diff --git a/static/openbsd/man9/vput.9 b/static/openbsd/man9/vput.9 new file mode 100644 index 00000000..b40fcd0f --- /dev/null +++ b/static/openbsd/man9/vput.9 @@ -0,0 +1,62 @@ +.\" $OpenBSD: vput.9,v 1.10 2013/08/14 06:32:32 jmc Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/vput.9,v 1.9 2001/10/01 16:09:25 ru Exp $ +.\" +.Dd $Mdocdate: August 14 2013 $ +.Dt VPUT 9 +.Os +.Sh NAME +.Nm vput +.Nd decrement the reference count for a vnode and unlock it +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vput "struct vnode *vp" +.Sh DESCRIPTION +Decrement the +.Va v_usecount +field of the vnode +.Fa vp +and unlock the vnode. +.Pp +This operation is functionally equivalent to calling +.Xr VOP_UNLOCK 9 +followed by +.Xr vrele 9 . +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_UNLOCK 9 , +.Xr vref 9 , +.Xr vrele 9 +.Sh AUTHORS +This man page was originally written by +.An Doug Rabson +for +.Fx . diff --git a/static/openbsd/man9/vrecycle.9 b/static/openbsd/man9/vrecycle.9 new file mode 100644 index 00000000..4fb02987 --- /dev/null +++ b/static/openbsd/man9/vrecycle.9 @@ -0,0 +1,67 @@ +.\" $OpenBSD: vrecycle.9,v 1.11 2020/08/05 11:10:24 tim Exp $ +.\"- +.\" Copyright (c) 2002 Peter Werner +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd $Mdocdate: August 5 2020 $ +.Dt VRECYCLE 9 +.Os +.Sh NAME +.Nm vrecycle +.Nd recycle a vnode if its reference count is zero +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fo vrecycle +.Fa "struct vnode *vp" +.Fa "struct proc *p" +.Fc +.Sh DESCRIPTION +The +.Fn vrecycle +function places the vnode +.Fa vp +on the free list using +.Xr vgonel 9 +if its +.Va v_usecount +field is zero. +If +.Va v_usecount +is non-zero, it simply returns. +The +.Fa p +argument specifies the process responsible for the call. +.Sh RETURN VALUES +.Fn vrecycle +will return 1 if the vnode was placed on the free list. +It will return 0 if the reference count was non-zero. +.Sh SEE ALSO +.Xr vgonel 9 , +.Xr vnode 9 +.Sh HISTORY +This man page was originally written for +.Ox . diff --git a/static/openbsd/man9/vref.9 b/static/openbsd/man9/vref.9 new file mode 100644 index 00000000..f6bec6e3 --- /dev/null +++ b/static/openbsd/man9/vref.9 @@ -0,0 +1,66 @@ +.\" $OpenBSD: vref.9,v 1.8 2013/06/04 19:27:17 schwarze Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/vref.9,v 1.8 2001/10/01 16:09:25 ru Exp $ +.\" +.Dd $Mdocdate: June 4 2013 $ +.Dt VREF 9 +.Os +.Sh NAME +.Nm vref +.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" +.Sh DESCRIPTION +Increment the +.Va v_usecount +field of the vnode specified by +.Fa vp . +.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 uses a vnode (e.g. during the +operation of some algorithm or to store in a data structure) should +call +.Fn vref . +.Sh SEE ALSO +.Xr vget 9 , +.Xr vnode 9 , +.Xr vput 9 , +.Xr vrele 9 +.Sh AUTHORS +This man page was originally written by +.An Doug Rabson +for +.Fx . diff --git a/static/openbsd/man9/vrele.9 b/static/openbsd/man9/vrele.9 new file mode 100644 index 00000000..1aef1b2e --- /dev/null +++ b/static/openbsd/man9/vrele.9 @@ -0,0 +1,66 @@ +.\" $OpenBSD: vrele.9,v 1.9 2013/06/04 19:27:17 schwarze Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man9/vrele.9,v 1.9 2001/10/01 16:09:25 ru Exp $ +.\" +.Dd $Mdocdate: June 4 2013 $ +.Dt VRELE 9 +.Os +.Sh NAME +.Nm vrele +.Nd decrement the use count for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn vrele "struct vnode *vp" +.Sh DESCRIPTION +Decrement the +.Fa v_usecount +field of the vnode specified by +.Fa vp . +.Pp +Any code in the system which uses a vnode should call +.Fn vrele +when it is finished with the vnode. +If the +.Va v_usecount +field of the vnode reaches zero, the vnode will be placed on the free list. +.Sh RETURN VALUES +.Fn vrele +returns 0 if it can guarantee that it did not sleep. +.Sh SEE ALSO +.Xr vget 9 , +.Xr vnode 9 , +.Xr vput 9 , +.Xr vref 9 +.Sh AUTHORS +This man page was originally written by +.An Doug Rabson +for +.Fx . diff --git a/static/openbsd/man9/vwaitforio.9 b/static/openbsd/man9/vwaitforio.9 new file mode 100644 index 00000000..e7b72526 --- /dev/null +++ b/static/openbsd/man9/vwaitforio.9 @@ -0,0 +1,81 @@ +.\" $OpenBSD: vwaitforio.9,v 1.16 2019/07/19 00:54:58 cheloha Exp $ +.\" +.\" Copyright (c) 2001 Constantine Sapuntzakis +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the 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 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, +.\" 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 $Mdocdate: July 19 2019 $ +.Dt VWAITFORIO 9 +.Os +.Sh NAME +.Nm vwaitforio +.Nd wait for all outstanding asynchronous writes +.Sh SYNOPSIS +.In sys/types.h +.In sys/vnode.h +.Ft int +.Fo vwaitforio +.Fa "struct vnode *vp" +.Fa "int slpflag" +.Fa "char *wmesg" +.Fa "uint64_t slptimeo" +.Fc +.Sh DESCRIPTION +The +.Fn vwaitforio +call sleeps until all asynchronous writes associated with the vnode +.Fa vp +finish. +This is used by functions that need to make sure +that the writes they initiated have completed. +.Pp +The +.Fn vwaitforio +call sleeps at priority +.Dv PRIBIO ++ 1. +The +.Fa slpflag , +.Fa wmesg , +and +.Fa slptimeo +arguments indicate flags to be passed to +.Xr tsleep_nsec 9 . +.Pp +This function must be called at +.Xr splbio 9 . +.Pp +It may be important to ensure that no other process submits asynchronous +writes while a process is waiting for I/O on this vnode. +Otherwise, +.Fn vwaitforio +may never return. +.Sh RETURN VALUES +The +.Fn vwaitforio +function returns 0 on success. +See +.Xr tsleep 9 +for possible error returns. +.Sh SEE ALSO +.Xr tsleep 9 , +.Xr vnode 9 diff --git a/static/openbsd/man9/vwakeup.9 b/static/openbsd/man9/vwakeup.9 new file mode 100644 index 00000000..4ce8a550 --- /dev/null +++ b/static/openbsd/man9/vwakeup.9 @@ -0,0 +1,48 @@ +.\" $OpenBSD: vwakeup.9,v 1.5 2013/08/14 06:32:33 jmc Exp $ +.\" Written by Jared Yanovich +.\" This file belongs to the public domain. +.Dd $Mdocdate: August 14 2013 $ +.Dt VWAKEUP 9 +.Os +.Sh NAME +.Nm vwakeup +.Nd update outstanding I/O count and do wakeup on a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vwakeup "struct vnode *vp" +.Sh DESCRIPTION +The +.Fn vwakeup +function updates the number of outstanding I/O operations on the target +vnode, stored in its +.Va v_numoutput +field. +If the target vnode has the +.Dv VBIOWAIT +flag set in its +.Va v_bioflag +field and has no outstanding I/O operations remaining, a +.Xr wakeup 9 +is performed as well. +.Pp +The +.Fn vwakeup +function must be called at +.Xr splbio 9 . +.Sh SEE ALSO +.Xr panic 9 , +.Xr splbio 9 , +.Xr vnode 9 , +.Xr vwaitforio 9 , +.Xr wakeup 9 +.Sh HISTORY +This document first appeared in +.Ox 3.7 . +.Sh CAVEATS +Calling +.Fn vwakeup +more times than the number of outstanding I/O operations will cause the +system to +.Xr panic 9 . diff --git a/static/openbsd/man9/wdog_register.9 b/static/openbsd/man9/wdog_register.9 new file mode 100644 index 00000000..3d652710 --- /dev/null +++ b/static/openbsd/man9/wdog_register.9 @@ -0,0 +1,66 @@ +.\" $OpenBSD: wdog_register.9,v 1.7 2013/07/17 20:21:56 schwarze Exp $ +.\" +.\" Copyright (c) 2004 Michael Knudsen +.\" +.\" 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: July 17 2013 $ +.Dt WDOG_REGISTER 9 +.Os +.Sh NAME +.Nm wdog_register +.Nd kernel watchdog interface +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn wdog_register "int (*cb)(void *cb_arg, int period)" "void *cb_arg" +.Sh DESCRIPTION +The kernel watchdog interface is used by hardware watchdog drivers and +should be used for all future drivers. +.Pp +.Fn wdog_register +is called by the hardware driver after configuring the hardware watchdog +device. +The +.Fa cb_arg +argument is a pointer to the hardware device control structure. +The +.Fa cb +argument is a pointer to a function supplied by the driver which sets +the timeout in the hardware device. +.Pp +The +.Fa cb_arg +parameter given to +.Fa cb +is a pointer to the device control structure. +The +.Fa period +parameter supplies the desired timeout value in seconds. +A +.Fa period +value of zero disables the watchdog. +Setting the timeout to a nonzero value after disabling the watchdog +will update the timeout value and enable the watchdog. +.Sh CODE REFERENCES +The framework is implemented in the file +.Pa sys/kern/kern_watchdog.c . +.Sh SEE ALSO +.Xr watchdog 4 , +.Xr sysctl_int 9 , +.Xr timeout 9 +.Sh HISTORY +The watchdog timer framework was written by +.An Markus Friedl Aq Mt markus@openbsd.org +and first appeared in +.Ox 3.3 . diff --git a/static/openbsd/man9/wsfont_init.9 b/static/openbsd/man9/wsfont_init.9 new file mode 100644 index 00000000..3cee69f2 --- /dev/null +++ b/static/openbsd/man9/wsfont_init.9 @@ -0,0 +1,188 @@ +.\" $OpenBSD: wsfont_init.9,v 1.2 2019/05/10 17:24:53 schwarze Exp $ +.\" $NetBSD: wsfont.9,v 1.18 2012/01/13 23:09:51 wiz Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Gregory McGarry. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this 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 $Mdocdate: May 10 2019 $ +.Dt WSFONT_INIT 9 +.Os +.Sh NAME +.Nm wsfont_init , +.Nm wsfont_find , +.Nm wsfont_add , +.Nm wsfont_remove , +.Nm wsfont_enum , +.Nm wsfont_lock , +.Nm wsfont_unlock , +.Nm wsfont_map_unichar +.Nd wscons font support +.Sh SYNOPSIS +.In dev/wscons/wsconsio.h +.In dev/wsfont/wsfont.h +.Ft void +.Fn wsfont_init "void" +.Ft int +.Fn wsfont_find "const char *name" "int width" "int height" "int stride" +.Ft int +.Fn wsfont_add "struct wsdisplay_font *font" "int copy" +.Ft int +.Fn wsfont_remove "int cookie" +.Ft void +.Fn wsfont_enum "int (*cb)(void *, struct wsdisplay_font *)" "void *cbarg" +.Ft int +.Fn wsfont_lock "int cookie" "struct wsdisplay_font **ptr" "int bitorder" \ +"int byteorder" +.Ft int +.Fn wsfont_unlock "int cookie" +.Ft int +.Fn wsfont_map_unichar "struct wsdisplay_font *font" "int c" +.Sh DESCRIPTION +The wsfont module is a component of the wscons +.\" .Xr wscons 9 +framework to provide access to display fonts. +Fonts may be loaded dynamically into the kernel or included statically +in the kernel at compile time. +Display drivers which emulate a glass-tty console on a bit-mapped +display can add, remove and find fonts for use by device-dependent +blitter operations. +.Pp +The primary data type for manipulating fonts is the +.Vt wsdisplay_font +structure in +.In dev/wscons/wsconsio.h : +.Bd -literal +struct wsdisplay_font { + char name[WSFONT_NAME_SIZE]; /* font name */ + int index; + int firstchar; + int numchars; /* size of font table */ + int encoding; /* font encoding */ + u_int fontwidth; /* character width */ + u_int fontheight; /* character height */ + u_int stride; + int bitorder; + int byteorder; + void *cookie; + void *data; /* pointer to font table */ +}; +.Ed +.Pp +The maximum font table size is +.Dv WSDISPLAY_MAXFONTSZ . +.Pp +The wsfont framework supports fonts with the following encodings: +.Bl -tag -width compact +.It Dv WSDISPLAY_FONTENC_ISO +ISO-encoded fonts. +.It Dv WSDISPLAY_FONTENC_IBM +IBM-encoded fonts commonly available for IBM CGA, EGA and VGA display +adapters. +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn wsfont_init "void" +Initialise the font list with the built-in fonts. +.It Fn wsfont_find "name" "width" "height" "stride" +Find the font called +.Fa name +from the fonts loaded into the kernel. +The font aspect is specified by +.Fa width , +.Fa height , +and +.Fa stride . +If +.Fn wsfont_find +is called with any of the parameters as 0, it indicates that we don't +care about that aspect of the font. +If the font is found, a (nonnegative-valued) cookie is returned which +can be used with the other functions. +.Pp +When more flexibility is required, +.Fn wsfont_enum +should be used. +.It Fn wsfont_add "font" "copy" +Add a font +.Fa font +to the font list. +If the +.Fa copy +argument is non-zero, then the font is physically copied, otherwise a +reference to the original font is made. +.It Fn wsfont_remove "cookie" +Remove the font specified by +.Fa cookie +from the font list. +The value of cookie was returned by +.Fn wsfont_add . +.It Fn wsfont_enum "callback" "cbarg" +Enumerate the list of fonts. +For each font in the font list, the +.Fa callback +function argument is called with the +.Fa cbarg +argument. +.It Fn wsfont_lock "cookie" "ptr" "bitorder" "byteorder" +Lock access to the font specified by +.Fa cookie +so that it cannot be unloaded from the kernel while it is being used. +If the bit or byte order of the font to be locked differs from what +has been requested via the +.Fa bitorder +and +.Fa byteorder +arguments, then the glyph data will be modified to match. +.Pp +The address of the +.Vt wsdisplay_font +pointer for the specified font is returned in +the +.Fa ptr +argument. +.Pp +.Fn wsfont_lock +returns lockcount on success, or an error code on failure. +.It Fn wsfont_unlock "cookie" +Unlock the font specified by +.Fa cookie . +Returns lockcount on success, or an error code on failure. +.It Fn wsfont_map_unichar "font" "c" +Remap the unicode character +.Fa c +to glyph for font +.Fa font . +Returns the glyph on success or \-1 on error. +.El +.Sh CODE REFERENCES +The wscons subsystem is implemented within the directory +.Pa sys/dev/wscons . +The wsfont subsystem itself is implemented within the file +.Pa sys/dev/wsfont/wsfont.c . +.Sh SEE ALSO +.Xr wsfontload 8 , +.Xr intro 9 -- cgit v1.2.3