Sun Jun 3 10:34:59 2018 UTC ()
Finish documenting the new modules(9) interfaces by adding the module
specificdata routines.


(pgoyette)
diff -r1.425 -r1.426 src/share/man/man9/Makefile
diff -r1.45 -r1.46 src/share/man/man9/module.9
cvs diff -r1.425 -r1.426 src/share/man/man9/Makefile (expand / switch to unified diff)

--- src/share/man/man9/Makefile 2018/06/03 09:22:34 1.425
+++ src/share/man/man9/Makefile 2018/06/03 10:34:59 1.426
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1# $NetBSD: Makefile,v 1.425 2018/06/03 09:22:34 pgoyette Exp $ 1# $NetBSD: Makefile,v 1.426 2018/06/03 10:34:59 pgoyette Exp $
2 2
3# Makefile for section 9 (kernel function and variable) manual pages. 3# Makefile for section 9 (kernel function and variable) manual pages.
4 4
5MAN= accept_filter.9 accf_data.9 accf_http.9 \ 5MAN= accept_filter.9 accf_data.9 accf_http.9 \
6 altq.9 arp.9 audio.9 audio_system.9 autoconf.9 \ 6 altq.9 arp.9 audio.9 audio_system.9 autoconf.9 \
7 bcdtobin.9 bcmp.9 bcopy.9 bintime_add.9 bluetooth.9 boothowto.9 bpf.9 \ 7 bcdtobin.9 bcmp.9 bcopy.9 bintime_add.9 bluetooth.9 boothowto.9 bpf.9 \
8 buffercache.9 bufferio.9 bufq.9 bus_dma.9 bus_space.9 byteorder.9 \ 8 buffercache.9 bufferio.9 bufq.9 bus_dma.9 bus_space.9 byteorder.9 \
9 bzero.9 \ 9 bzero.9 \
10 callback.9 callout.9 cardbus.9 clock.9 cnmagic.9 condvar.9 config.9 \ 10 callback.9 callout.9 cardbus.9 clock.9 cnmagic.9 condvar.9 config.9 \
11 cons.9 copy.9 coredump_write.9 \ 11 cons.9 copy.9 coredump_write.9 \
12 cpu_configure.9 cpu_coredump.9 cpu_dumpconf.9 \ 12 cpu_configure.9 cpu_coredump.9 cpu_dumpconf.9 \
13 cpu_lwp_fork.9 \ 13 cpu_lwp_fork.9 \
14 cpu_idle.9 cpu_initclocks.9 cpu_need_resched.9 \ 14 cpu_idle.9 cpu_initclocks.9 cpu_need_resched.9 \
@@ -512,35 +512,39 @@ MLINKS+=mca.9 mca_intr_establish.9 \ @@ -512,35 +512,39 @@ MLINKS+=mca.9 mca_intr_establish.9 \
512MLINKS+=microtime.9 bintime.9 \ 512MLINKS+=microtime.9 bintime.9 \
513 microtime.9 getbintime.9 \ 513 microtime.9 getbintime.9 \
514 microtime.9 getmicrotime.9 \ 514 microtime.9 getmicrotime.9 \
515 microtime.9 nanotime.9 \ 515 microtime.9 nanotime.9 \
516 microtime.9 getnanotime.9 516 microtime.9 getnanotime.9
517MLINKS+=microuptime.9 binuptime.9 \ 517MLINKS+=microuptime.9 binuptime.9 \
518 microuptime.9 getbinuptime.9 \ 518 microuptime.9 getbinuptime.9 \
519 microuptime.9 getmicrouptime.9 \ 519 microuptime.9 getmicrouptime.9 \
520 microuptime.9 nanouptime.9 \ 520 microuptime.9 nanouptime.9 \
521 microuptime.9 getnanouptime.9 521 microuptime.9 getnanouptime.9
522MLINKS+=module.9 module_autoload.9 \ 522MLINKS+=module.9 module_autoload.9 \
523 module.9 module_builtin_require_force.9 \ 523 module.9 module_builtin_require_force.9 \
524 module.9 module_find_section.9 \ 524 module.9 module_find_section.9 \
 525 module.9 module_getspecific.9 \
525 module.9 module_hold.9 \ 526 module.9 module_hold.9 \
526 module.9 module_init.9 \ 527 module.9 module_init.9 \
527 module.9 module_init_class.9 \ 528 module.9 module_init_class.9 \
528 module.9 module_kernel.9 \ 529 module.9 module_kernel.9 \
529 module.9 module_load.9 \ 530 module.9 module_load.9 \
530 module.9 module_load_vfs_init.9 \ 531 module.9 module_load_vfs_init.9 \
531 module.9 module_name.9 \ 532 module.9 module_name.9 \
532 module.9 module_rele.9 \ 533 module.9 module_rele.9 \
 534 module.9 module_setspecific.9 \
533 module.9 module_source.9 \ 535 module.9 module_source.9 \
 536 module.9 module_specific_key_create.9 \
 537 module.9 module_specific_key_delete.9 \
534 module.9 module_start_unload_thread.9 \ 538 module.9 module_start_unload_thread.9 \
535 module.9 module_unload.9 \ 539 module.9 module_unload.9 \
536 module.9 module_register_callbacks.9 \ 540 module.9 module_register_callbacks.9 \
537 module.9 module_unregister_callbacks.9 541 module.9 module_unregister_callbacks.9
538MLINKS+=mstohz.9 hztoms.9 542MLINKS+=mstohz.9 hztoms.9
539MLINKS+=mutex.9 mutex_init.9 mutex.9 mutex_destroy.9 mutex.9 mutex_enter.9 \ 543MLINKS+=mutex.9 mutex_init.9 mutex.9 mutex_destroy.9 mutex.9 mutex_enter.9 \
540 mutex.9 mutex_exit.9 mutex.9 mutex_tryenter.9 mutex.9 mutex_owned.9 \ 544 mutex.9 mutex_exit.9 mutex.9 mutex_tryenter.9 mutex.9 mutex_owned.9 \
541 mutex.9 mutex_ownable.9 \ 545 mutex.9 mutex_ownable.9 \
542 mutex.9 mutex_spin_enter.9 mutex.9 mutex_spin_exit.9 546 mutex.9 mutex_spin_enter.9 mutex.9 mutex_spin_exit.9
543MLINKS+=m_tag.9 m_tag_copy.9 \ 547MLINKS+=m_tag.9 m_tag_copy.9 \
544 m_tag.9 m_tag_copy_chain.9 \ 548 m_tag.9 m_tag_copy_chain.9 \
545 m_tag.9 m_tag_delete.9 \ 549 m_tag.9 m_tag_delete.9 \
546 m_tag.9 m_tag_delete_chain.9 \ 550 m_tag.9 m_tag_delete_chain.9 \
cvs diff -r1.45 -r1.46 src/share/man/man9/module.9 (expand / switch to unified diff)

--- src/share/man/man9/module.9 2018/06/03 01:52:47 1.45
+++ src/share/man/man9/module.9 2018/06/03 10:34:59 1.46
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: module.9,v 1.45 2018/06/03 01:52:47 pgoyette Exp $ 1.\" $NetBSD: module.9,v 1.46 2018/06/03 10:34:59 pgoyette Exp $
2.\" 2.\"
3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Andrew Doran. 7.\" by Andrew Doran.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
@@ -33,27 +33,31 @@ @@ -33,27 +33,31 @@
33.Sh NAME 33.Sh NAME
34.Nm module , 34.Nm module ,
35.Nm module_load , 35.Nm module_load ,
36.Nm module_autoload , 36.Nm module_autoload ,
37.Nm module_unload , 37.Nm module_unload ,
38.Nm module_init_class , 38.Nm module_init_class ,
39.Nm module_hold , 39.Nm module_hold ,
40.Nm module_rele , 40.Nm module_rele ,
41.Nm module_find_section , 41.Nm module_find_section ,
42.Nm module_kernel , 42.Nm module_kernel ,
43.Nm module_name , 43.Nm module_name ,
44.Nm module_source , 44.Nm module_source ,
45.Nm module_register_callbacks , 45.Nm module_register_callbacks ,
46.Nm module_unregister_callbacks 46.Nm module_unregister_callbacks ,
 47.Nm module_specific_key_create ,
 48.Nm module_specific_key_delete ,
 49.Nm module_getspecific ,
 50.Nm module_setspecific
47.Nd kernel module loader 51.Nd kernel module loader
48.Sh SYNOPSIS 52.Sh SYNOPSIS
49.In sys/module.h 53.In sys/module.h
50.Fn MODULE "class" "name" "required" 54.Fn MODULE "class" "name" "required"
51.Ft int 55.Ft int
52.Fn module_load "const char *name" "int flags" "prop_dictionary_t props" \ 56.Fn module_load "const char *name" "int flags" "prop_dictionary_t props" \
53"modclass_t class" 57"modclass_t class"
54.Ft int 58.Ft int
55.Fn module_autoload "const char *name" "modclass_t class" 59.Fn module_autoload "const char *name" "modclass_t class"
56.Ft int 60.Ft int
57.Fn module_unload "const char *name" 61.Fn module_unload "const char *name"
58.Ft void 62.Ft void
59.Fn module_init_class "modclass_t class" 63.Fn module_init_class "modclass_t class"
@@ -72,26 +76,35 @@ @@ -72,26 +76,35 @@
72.Ft void 76.Ft void
73.Fn module_init "void" 77.Fn module_init "void"
74.Ft void 78.Ft void
75.Fn module_start_unload_thread "void" 79.Fn module_start_unload_thread "void"
76.Ft void 80.Ft void
77.Fn module_builtin_require_force "void" 81.Fn module_builtin_require_force "void"
78.Ft void 82.Ft void
79.Fn module_load_vfs_init "void" 83.Fn module_load_vfs_init "void"
80.Ft "void *" 84.Ft "void *"
81.Fn module_register_callbacks "void (*)(struct module *)" \ 85.Fn module_register_callbacks "void (*)(struct module *)" \
82"void (*unload)(struct module *)" 86"void (*unload)(struct module *)"
83.Ft void 87.Ft void
84.Fn module_unregister_callbacks "void *" 88.Fn module_unregister_callbacks "void *"
 89.Ft specificdata_key_t
 90.Fn module_specific_key_create "specificdata_key_t *keyp" \
 91"specificdata_dtor_t dtor"
 92.Ft void
 93.Fn module_specific_key_delete "specificdata_key_t key"
 94.Ft "void *"
 95.Fn module_getspecific "module_t *mod" "specificdata_key_t key"
 96.Ft "void *"
 97.Fn module_setspecific "module_t *mod" "specificdata_key_t key" "void *data"
85.Sh DESCRIPTION 98.Sh DESCRIPTION
86Modules are sections of code that can be independently linked and selectively 99Modules are sections of code that can be independently linked and selectively
87loaded into or unloaded from a running kernel. 100loaded into or unloaded from a running kernel.
88This provides a mechanism to update the module without having to relink 101This provides a mechanism to update the module without having to relink
89the kernel and reboot. 102the kernel and reboot.
90Modules can be loaded from within the kernel image, provided by the boot 103Modules can be loaded from within the kernel image, provided by the boot
91loader, or loaded from the file system. 104loader, or loaded from the file system.
92.Pp 105.Pp
93The 106The
94.Nm 107.Nm
95subsystem includes two data types: 108subsystem includes two data types:
96.Bl -enum -offset indent 109.Bl -enum -offset indent
97.It 110.It
@@ -469,26 +482,51 @@ successfully loaded; the @@ -469,26 +482,51 @@ successfully loaded; the
469callback is invoked before any module is unloaded. 482callback is invoked before any module is unloaded.
470Each load or unload event can result in multiple invocations of the 483Each load or unload event can result in multiple invocations of the
471callback routines. 484callback routines.
472An opaque cookie is returned which can be passed to 485An opaque cookie is returned which can be passed to
473.Fn module_unregister_callbacks . 486.Fn module_unregister_callbacks .
474.It Fn module_unregister_callbacks "void *opaque" 487.It Fn module_unregister_callbacks "void *opaque"
475Unregister a set of callback routines previously registered with 488Unregister a set of callback routines previously registered with
476.Fn module_register_callbacks . 489.Fn module_register_callbacks .
477The 490The
478.Fa opaque 491.Fa opaque
479argument should be the return value from the previous 492argument should be the return value from the previous
480.Fn module_register_callbacks 493.Fn module_register_callbacks
481call. 494call.
 495.It module_specific_key_create "specificdata_key_t *keyp" \
 496"specificdata_dtor_t dtor"
 497Creates a new specificdata_key for use within the
 498.Nm
 499domain.
 500The key identifier is returned in
 501.Fa keyp .
 502.It module_specific_key_delete "specificdata_key_t key"
 503Deletes the specified specificdata_key
 504.Fa key
 505from the
 506.Nm domain.
 507.It module_getspecific "module_t *mod" "specificdata_key_t key"
 508Retrieves the value associated with
 509.Fa key
 510from module
 511.Fa mod .
 512.It module_setspecific "module_t *mod" "specificdata_key_t key" "void *data"
 513Stores
 514.Fa data
 515as the value associated with
 516.Fa key
 517for module
 518.Fa mod .
 519
482.El 520.El
483.Sh PROGRAMMING CONSIDERATIONS 521.Sh PROGRAMMING CONSIDERATIONS
484The module subsystem is designed to be called recursively, but only within 522The module subsystem is designed to be called recursively, but only within
485a single LWP. 523a single LWP.
486This permits one module's 524This permits one module's
487.Fn modcmd 525.Fn modcmd
488routine to load or unload other modules. 526routine to load or unload other modules.
489.Pp 527.Pp
490Additional considerations: 528Additional considerations:
491.Bl -bullet -offset indent 529.Bl -bullet -offset indent
492.It 530.It
493A module is not permitted to load or unload itself. 531A module is not permitted to load or unload itself.
494Attempts to load or unload a module from within its own 532Attempts to load or unload a module from within its own