Index: head/share/man/man3/bitstring.3 =================================================================== --- head/share/man/man3/bitstring.3 (revision 360602) +++ head/share/man/man3/bitstring.3 (revision 360603) @@ -1,365 +1,365 @@ .\" Copyright (c) 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Paul Vixie. .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" Copyright (c) 2014,2016 Spectra Logic Corporation .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions, and the following disclaimer, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" substantially similar to the "NO WARRANTY" disclaimer below .\" ("Disclaimer") and any redistribution must be conditioned upon .\" including a substantially similar Disclaimer requirement for further .\" binary redistribution. .\" .\" NO WARRANTY .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGES. .\" .\" @(#)bitstring.3 8.1 (Berkeley) 7/19/93 .\" $FreeBSD$ .\" -.Dd Nov 18, 2019 +.Dd November 18, 2019 .Dt BITSTRING 3 .Os .Sh NAME .Nm bit_alloc , .Nm bit_clear , .Nm bit_count , .Nm bit_decl , .Nm bit_ffc , .Nm bit_ffs , .Nm bit_ffc_at , .Nm bit_ffs_at , .Nm bit_ffc_area , .Nm bit_ffs_area , .Nm bit_ffc_area_at , .Nm bit_ffs_area_at , .Nm bit_nclear , .Nm bit_nset , .Nm bit_set , .Nm bit_test , .Nm bitstr_size .Nd bit-string manipulation functions and macros .Sh SYNOPSIS .In bitstring.h .Ft bitstr_t * .Fn bit_alloc "int nbits" .Ft void .Fn bit_decl "bitstr_t *name" "int nbits" .Ft void .Fn bit_clear "bitstr_t *name" "int bit" .Ft void .Fn bit_count "bitstr_t *name" "int count" "int nbits" "int *value" .Ft void .Fn bit_ffc "bitstr_t *name" "int nbits" "int *value" .Ft void .Fn bit_ffs "bitstr_t *name" "int nbits" "int *value" .Ft void .Fn bit_ffc_at "bitstr_t *name" "int start" "int nbits" "int *value" .Ft void .Fn bit_ffs_at "bitstr_t *name" "int start" "int nbits" "int *value" .Ft void .Fn bit_ffc_area "bitstr_t *name" "int nbits" "int size" "int *value" .Ft void .Fn bit_ffs_area "bitstr_t *name" "int nbits" "int size" "int *value" .Ft void .Fn bit_ffc_area_at "bitstr_t *name" "int start" "int nbits" "int size" "int *value" .Ft void .Fn bit_ffs_area_at "bitstr_t *name" "int start" "int nbits" "int size" "int *value" .Ft void .Fn bit_nclear "bitstr_t *name" "int start" "int stop" .Ft void .Fn bit_nset "bitstr_t *name" "int start" "int stop" .Ft void .Fn bit_set "bitstr_t *name" "int bit" .Ft int .Fn bitstr_size "int nbits" .Ft int .Fn bit_test "bitstr_t *name" "int bit" .Sh DESCRIPTION These macros operate on strings of bits. .Pp The function .Fn bit_alloc returns a pointer of type .Dq Fa "bitstr_t *" to sufficient space to store .Fa nbits bits, or .Dv NULL if no space is available. If successful, the returned bit string is initialized with all bits cleared. .Pp The macro .Fn bit_decl declares a bit string with sufficient space to store .Fa nbits bits. .Fn bit_decl may be used to include statically sized bit strings in structure definitions or to create bit strings on the stack. Users of this macro are responsible for initialization of the bit string, typically via a global initialization of the containing struct or use of the .Fn bit_nset or .Fn bin_nclear functions. .Pp The macro .Fn bitstr_size returns the number of bytes necessary to store .Fa nbits bits. This is useful for copying bit strings. .Pp The functions .Fn bit_clear and .Fn bit_set clear or set the zero-based numbered bit .Fa bit , in the bit string .Ar name . .Pp The .Fn bit_nset and .Fn bit_nclear functions set or clear the zero-based numbered bits from .Fa start through .Fa stop in the bit string .Ar name . .Pp The .Fn bit_test function evaluates to non-zero if the zero-based numbered bit .Fa bit of bit string .Fa name is set, and zero otherwise. .Pp The function .Fn bit_ffc stores in the location referenced by .Fa value the zero-based number of the first bit not set in the array of .Fa nbits bits referenced by .Fa name . If all bits are set, the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ffs function stores in the location referenced by .Fa value the zero-based number of the first bit set in the array of .Fa nbits bits referenced by .Fa name . If no bits are set, the location referenced by .Fa value is set to \-1. .Pp The function .Fn bit_ffc_at stores in the location referenced by .Fa value the zero-based number of the first bit not set in the array of .Fa nbits bits referenced by .Fa name , at or after the zero-based bit index .Fa start . If all bits at or after .Fa start are set, the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ffs_at function stores in the location referenced by .Fa value the zero-based number of the first bit set in the array of .Fa nbits bits referenced by .Fa name , at or after the zero-based bit index .Fa start . If no bits are set after .Fa start , the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ffc_area function stores in the location referenced by .Fa value the zero-based number of the first bit beginning a sequence of unset bits of at least .Fa size unset bits in the array of .Fa nbits bits referenced by .Fa name . If no sequence of contiguous unset bits of the specified .Fa size can be found, the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ffs_area function stores in the location referenced by .Fa value the zero-based number of the first bit beginning a sequence of set bits of at least .Fa size set bits in the array of .Fa nbits bits referenced by .Fa name . If no sequence of contiguous set bits of the specified .Fa size can be found, the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ffc_area_at function stores in the location referenced by .Fa value the zero-based number of the first bit beginning a sequence of unset bits of at least .Fa size unset bits in the array of .Fa nbits bits referenced by .Fa name , at or after the zero-based bit index .Fa start . If no sequence of contiguous unset bits of the specified .Fa size can be found at or after .Fa start , the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_ffs_area_at function stores in the location referenced by .Fa value the zero-based number of the first bit beginning a sequence of set bits of at least .Fa size set bits in the array of .Fa nbits bits referenced by .Fa name , at or after the zero-based bit index .Fa start . If no sequence of contiguous set bits of the specified .Fa size can be found at or after .Fa start , the location referenced by .Fa value is set to \-1. .Pp The .Fn bit_count function stores in the location referenced by .Fa value the number of bits set in the array of .Fa nbits bits referenced by .Fa name , at or after the zero-based bit index .Fa start . .Pp The arguments in bit string macros are evaluated only once and may safely have side effects. .Sh EXAMPLES .Bd -literal -offset indent #include #include \&... #define LPR_BUSY_BIT 0 #define LPR_FORMAT_BIT 1 #define LPR_DOWNLOAD_BIT 2 \&... #define LPR_AVAILABLE_BIT 9 #define LPR_MAX_BITS 10 make_lpr_available() { bitstr_t bit_decl(bitlist, LPR_MAX_BITS); ... bit_nclear(bitlist, 0, LPR_MAX_BITS - 1); ... if (!bit_test(bitlist, LPR_BUSY_BIT)) { bit_clear(bitlist, LPR_FORMAT_BIT); bit_clear(bitlist, LPR_DOWNLOAD_BIT); bit_set(bitlist, LPR_AVAILABLE_BIT); } } .Ed .Sh SEE ALSO .Xr malloc 3 , .Xr bitset 9 .Sh HISTORY The .Nm bitstring functions first appeared in .Bx 4.4 . Index: head/share/man/man3/sigevent.3 =================================================================== --- head/share/man/man3/sigevent.3 (revision 360602) +++ head/share/man/man3/sigevent.3 (revision 360603) @@ -1,131 +1,131 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2016 John H. Baldwin .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd February 25, 2020 .Dt SIGEVENT 3 .Os .Sh NAME .Nm sigevent .Nd "asynchronous event notification" .Sh SYNOPSIS .In signal.h .Sh DESCRIPTION Some operations permit threads to request asychronous notification of events via a .Vt struct sigevent structure. This structure contains several fields that describe the requested notification: .Bl -column ".Vt void (*)(union sigval)" ".Va sigev_notify_kevent_flags" .It Sy Type Ta Sy Member Ta Sy Description .It Vt int Ta sigev_notify Ta notification method .It Vt int Ta sigev_signo Ta signal number .It Vt union sigval Ta sigev_value Ta signal value .It Vt int Ta sigev_notify_kqueue Ta .Xr kqueue 2 file descriptor .It Vt unsigned short Ta sigev_notify_kevent_flags Ta kevent flags .It Vt lwpid_t Ta sigev_notify_thread_id Ta LWP ID .It Vt void (*)(union sigval) Ta sigev_notify_function Ta callback function pointer .It Vt pthread_attr_t * Ta sigev_notify_attributes Ta callback thread attributes .El .Pp The .Va sigev_notify field specifies the notification method used when the event triggers: .Bl -tag -width ".Dv SIGEV_THREAD_ID" .It Dv SIGEV_NONE No notification is sent. .It Dv SIGEV_SIGNAL The signal .Va sigev_signo is queued as a real-time signal to the calling process. The value stored in .Va sigev_value will be present in the .Va si_value of the .Vt siginfo_t structure of the queued signal. .It Dv SIGEV_THREAD The notification function in .Va sigev_notify_function is called in a separate thread context. The thread is created with the attributes specified in .Va *sigev_notify_attributes . The value stored in .Va sigev_value is passed as the sole argument to .Va sigev_notify_function . If .Va sigev_notify_attributes is .Dv NULL , the thread is created with default attributes. .It Dv SIGEV_KEVENT A new kevent is posted to the kqueue .Va sigev_notify_kqueue . The .Va udata member of the kevent structure contains the value stored in .Va sigev_value . The meaning of other fields in the kevent are specific to the type of triggered event. .It Dv SIGEV_THREAD_ID The signal .Va sigev_signo is queued to the thread whose LWP ID is .Va sigev_notify_thread_id . The value stored in .Va sigev_value will be present in the .Va si_value of the .Vt siginfo_t structure of the queued signal. .El .Sh NOTES Note that programs wishing to use .Dv SIGEV_THREAD notifications must link against the .Lb librt . .Sh SEE ALSO .Xr aio_read 2 , .Xr mq_notify 2 , .Xr timer_create 2 , .Xr siginfo 3 -.Sh HISTORY -The -.Va sigevent -structure first appeared in -.Fx 3.3 . .Sh STANDARDS The .Vt struct sigevent type conforms to .St -p1003.1-2004 . +.Sh HISTORY +The +.Va sigevent +structure first appeared in +.Fx 3.3 . Index: head/share/man/man3/timeradd.3 =================================================================== --- head/share/man/man3/timeradd.3 (revision 360602) +++ head/share/man/man3/timeradd.3 (revision 360603) @@ -1,165 +1,165 @@ .\" Copyright (c) 1999 Kelly Yancey .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the author nor the names of any co-contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 30, 2018 .Dt TIMERADD 3 .Os .Sh NAME .Nm timeradd , .Nm timersub , .Nm timerclear , .Nm timerisset , .Nm timercmp , .Nm timespecadd , .Nm timespecsub , .Nm timespecclear , .Nm timespecisset , .Nm timespeccmp .Nd operations on timevals and timespecs .Sh SYNOPSIS .In sys/time.h .Ft void .Fn timeradd "struct timeval *a" "struct timeval *b" "struct timeval *res" .Ft void .Fn timersub "struct timeval *a" "struct timeval *b" "struct timeval *res" .Ft void .Fn timerclear "struct timeval *tvp" .Ft int .Fn timerisset "struct timeval *tvp" .Ft int .Fn timercmp "struct timeval *a" "struct timeval *b" CMP .Ft void .Fn timespecadd "struct timespec *a" "struct timespec *b" "struct timespec *res" .Ft void .Fn timespecsub "struct timespec *a" "struct timespec *b" "struct timespec *res" .Ft void .Fn timespecclear "struct timespec *ts" .Ft int .Fn timespecisset "struct timespec *ts" .Ft int .Fn timespeccmp "struct timespec *a" "struct timespec *b" CMP .Sh DESCRIPTION These macros are provided for manipulating .Fa timeval and .Fa timespec structures for use with the .Xr clock_gettime 2 , .Xr clock_settime 2 , .Xr gettimeofday 2 and .Xr settimeofday 2 calls. The .Fa timeval structure is defined in .In sys/time.h as: .Bd -literal struct timeval { long tv_sec; /* seconds since Jan. 1, 1970 */ long tv_usec; /* and microseconds */ }; .Ed And the .Fa timespec structure is defined in .In time.h as: .Bd -literal struct timespec { time_t tv_sec; /* seconds */ long tv_nsec; /* and nanoseconds */ }; .Ed .Pp .Fn timeradd and .Fn timespecadd add the time information stored in .Fa a to .Fa b and store the result in .Fa res . The results are simplified such that the value of .Fa res->tv_usec or .Fa res->tv_nsec is always less than 1 second. .Pp .Fn timersub and .Fn timespecsub subtract the time information stored in .Fa b from .Fa a and store the result in .Fa res . .Pp .Fn timerclear and .Fn timespecclear initialize their argument to midnight (0 hour) January 1st, 1970 (the Epoch). .Pp .Fn timerisset and .Fn timespecisset return true if their argument is set to any time value other than the Epoch. .Pp .Fn timercmp and .Fn timespeccmp compare .Fa a to .Fa b using the comparison operator given in .Fa CMP , and return the result of that comparison. .Sh SEE ALSO -.Xr gettimeofday 2 , -.Xr clock_gettime 2 +.Xr clock_gettime 2 , +.Xr gettimeofday 2 .Sh HISTORY The .Fn timeradd family of macros were imported from .Nx 1.1 , and appeared in .Fx 2.2.6 . The .Fn timespecadd family of macros were imported from .Nx 1.3 into .Fx 3.0 , though they were not exposed to userland until .Fx 12.0 . Index: head/share/man/man5/cd9660.5 =================================================================== --- head/share/man/man5/cd9660.5 (revision 360602) +++ head/share/man/man5/cd9660.5 (revision 360603) @@ -1,81 +1,82 @@ .\" .\" Copyright (c) 2017 Enji Cooper .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission .\" .\" THIS DOCUMENTATION IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 22, 2017 .Dt CD9660 5 .Os .Sh NAME .Nm cd9660 .Nd "ISO-9660 file system" .Sh SYNOPSIS To link into the kernel: .Bd -ragged -offset indent .Cd "options CD9660" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent cd9660_load="YES" +.Ed .Sh DESCRIPTION The .Nm driver will permit the .Fx kernel to access the .Tn cd9660 file system. .Sh EXAMPLES To mount a .Nm volume located on .Pa /dev/cd0 : .Pp .Dl "mount -t cd9660 /dev/cd0 /mnt" .Sh SEE ALSO .Xr nmount 2 , .Xr unmount 2 , .Xr fstab 5 , .Xr mount 8 , .Xr mount_cd9660 8 .Sh HISTORY The .Nm driver first appeared in .Fx 4.4 Lite .Sh AUTHORS .An -nosplit The .Nm kernel implementation was originally written by .An Pace Willisson Aq Mt pace@blitz.com and .An Atsushi Murai Aq Mt amurai@spec.co.jp . .Pp This manual page was written by .An Enji Cooper Aq Mt ngie@FreeBSD.org . Index: head/share/man/man5/elf.5 =================================================================== --- head/share/man/man5/elf.5 (revision 360602) +++ head/share/man/man5/elf.5 (revision 360603) @@ -1,1372 +1,1372 @@ .\" Copyright (c) 1999 Jeroen Ruigrok van der Werven .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 11, 2020 .Dt ELF 5 .Os .Sh NAME .Nm elf .Nd format of ELF executable binary files .Sh SYNOPSIS .In elf.h .Sh DESCRIPTION The header file .In elf.h defines the format of ELF executable binary files. Amongst these files are normal executable files, relocatable object files, core files and shared libraries. .Pp An executable file using the ELF file format consists of an ELF header, followed by a program header table or a section header table, or both. The ELF header is always at offset zero of the file. The program header table and the section header table's offset in the file are defined in the ELF header. The two tables describe the rest of the particularities of the file. .Pp Applications which wish to process ELF binary files for their native architecture only should include .In elf.h in their source code. These applications should need to refer to all the types and structures by their generic names .Dq Elf_xxx and to the macros by .Dq ELF_xxx . Applications written this way can be compiled on any architecture, regardless whether the host is 32-bit or 64-bit. .Pp Should an application need to process ELF files of an unknown architecture then the application needs to include both .In sys/elf32.h and .In sys/elf64.h instead of .In elf.h . Furthermore, all types and structures need to be identified by either .Dq Elf32_xxx or .Dq Elf64_xxx . The macros need to be identified by .Dq ELF32_xxx or .Dq ELF64_xxx . .Pp Whatever the system's architecture is, it will always include .In sys/elf_common.h as well as .In sys/elf_generic.h . .Pp These header files describe the above mentioned headers as C structures and also include structures for dynamic sections, relocation sections and symbol tables. .Pp The following types are being used for 32-bit architectures: .Bd -literal -offset indent Elf32_Addr Unsigned 32-bit program address Elf32_Half Unsigned 16-bit field Elf32_Lword Unsigned 64-bit field Elf32_Off Unsigned 32-bit file offset Elf32_Sword Signed 32-bit field or integer Elf32_Word Unsigned 32-bit field or integer .Ed .Pp For 64-bit architectures we have the following types: .Bd -literal -offset indent Elf64_Addr Unsigned 64-bit program address Elf64_Half Unsigned 16-bit field Elf64_Lword Unsigned 64-bit field Elf64_Off Unsigned 64-bit file offset Elf64_Sword Signed 32-bit field Elf64_Sxword Signed 64-bit field or integer Elf64_Word Unsigned 32-bit field Elf64_Xword Unsigned 64-bit field or integer .Ed .Pp All data structures that the file format defines follow the .Dq natural size and alignment guidelines for the relevant class. If necessary, data structures contain explicit padding to ensure 4-byte alignment for 4-byte objects, to force structure sizes to a multiple of 4, etc. .Pp The ELF header is described by the type Elf32_Ehdr or Elf64_Ehdr: .Bd -literal -offset indent typedef struct { unsigned char e_ident[EI_NIDENT]; Elf32_Half e_type; Elf32_Half e_machine; Elf32_Word e_version; Elf32_Addr e_entry; Elf32_Off e_phoff; Elf32_Off e_shoff; Elf32_Word e_flags; Elf32_Half e_ehsize; Elf32_Half e_phentsize; Elf32_Half e_phnum; Elf32_Half e_shentsize; Elf32_Half e_shnum; Elf32_Half e_shstrndx; } Elf32_Ehdr; .Ed .Bd -literal -offset indent typedef struct { unsigned char e_ident[EI_NIDENT]; Elf64_Half e_type; Elf64_Half e_machine; Elf64_Word e_version; Elf64_Addr e_entry; Elf64_Off e_phoff; Elf64_Off e_shoff; Elf64_Word e_flags; Elf64_Half e_ehsize; Elf64_Half e_phentsize; Elf64_Half e_phnum; Elf64_Half e_shentsize; Elf64_Half e_shnum; Elf64_Half e_shstrndx; } Elf64_Ehdr; .Ed .Pp The fields have the following meanings: .Pp .Bl -tag -width "e_phentsize" -compact -offset indent .It Dv e_ident This array of bytes specifies to interpret the file, independent of the processor or the file's remaining contents. Within this array everything is named by macros, which start with the prefix .Sy EI_ and may contain values which start with the prefix .Sy ELF . The following macros are defined: .Pp .Bl -tag -width "EI_ABIVERSION" -compact .It Dv EI_MAG0 The first byte of the magic number. It must be filled with .Sy ELFMAG0 . .It Dv EI_MAG1 The second byte of the magic number. It must be filled with .Sy ELFMAG1 . .It Dv EI_MAG2 The third byte of the magic number. It must be filled with .Sy ELFMAG2 . .It Dv EI_MAG3 The fourth byte of the magic number. It must be filled with .Sy ELFMAG3 . .It Dv EI_CLASS The fifth byte identifies the architecture for this binary: .Pp .Bl -tag -width "ELFCLASSNONE" -compact .It Dv ELFCLASSNONE This class is invalid. .It Dv ELFCLASS32 This defines the 32-bit architecture. It supports machines with files and virtual address spaces up to 4 Gigabytes. .It Dv ELFCLASS64 This defines the 64-bit architecture. .El .It Dv EI_DATA The sixth byte specifies the data encoding of the processor-specific data in the file. Currently these encodings are supported: .Pp .Bl -tag -width "ELFDATA2LSB" -compact .It Dv ELFDATANONE Unknown data format. .It Dv ELFDATA2LSB Two's complement, little-endian. .It Dv ELFDATA2MSB Two's complement, big-endian. .El .It Dv EI_VERSION The version number of the ELF specification: .Pp .Bl -tag -width "EV_CURRENT" -compact .It Dv EV_NONE Invalid version. .It Dv EV_CURRENT Current version. .El .It Dv EI_OSABI This byte identifies the operating system and ABI to which the object is targeted. Some fields in other ELF structures have flags and values that have platform specific meanings; the interpretation of those fields is determined by the value of this byte. The following values are currently defined: .Pp .Bl -tag -width "ELFOSABI_STANDALONE" -compact .It Dv ELFOSABI_SYSV UNIX System V ABI. .It Dv ELFOSABI_HPUX HP-UX operating system ABI. .It Dv ELFOSABI_NETBSD .Nx operating system ABI. .It Dv ELFOSABI_LINUX GNU/Linux operating system ABI. .It Dv ELFOSABI_HURD GNU/Hurd operating system ABI. .It Dv ELFOSABI_86OPEN 86Open Common IA32 ABI. .It Dv ELFOSABI_SOLARIS Solaris operating system ABI. .It Dv ELFOSABI_MONTEREY Monterey project ABI. .It Dv ELFOSABI_IRIX IRIX operating system ABI. .It Dv ELFOSABI_FREEBSD .Fx operating system ABI. .It Dv ELFOSABI_TRU64 TRU64 UNIX operating system ABI. .It Dv ELFOSABI_ARM ARM architecture ABI. .It Dv ELFOSABI_STANDALONE Standalone (embedded) ABI. .El .It Dv EI_ABIVERSION This byte identifies the version of the ABI to which the object is targeted. This field is used to distinguish among incompatible versions of an ABI. The interpretation of this version number is dependent on the ABI identified by the EI_OSABI field. Applications conforming to this specification use the value 0. .It Dv EI_PAD Start of padding. These bytes are reserved and set to zero. Programs which read them should ignore them. The value for EI_PAD will change in the future if currently unused bytes are given meanings. .It Dv EI_BRAND Start of architecture identification. .It Dv EI_NIDENT The size of the e_ident array. .El .Pp .It Dv e_type This member of the structure identifies the object file type: .Pp .Bl -tag -width "ET_NONE" -compact .It Dv ET_NONE An unknown type. .It Dv ET_REL A relocatable file. .It Dv ET_EXEC An executable file. .It Dv ET_DYN A shared object. .It Dv ET_CORE A core file. .El .Pp .It Dv e_machine This member specifies the required architecture for an individual file: .Pp .Bl -tag -width "EM_MIPS_RS4_BE" -compact .It Dv EM_NONE An unknown machine. .It Dv EM_M32 AT&T WE 32100. .It Dv EM_SPARC Sun Microsystems SPARC. .It Dv EM_386 Intel 80386. .It Dv EM_68K Motorola 68000. .It Dv EM_88K Motorola 88000. .It Dv EM_486 Intel 80486. .It Dv EM_860 Intel 80860. .It Dv EM_MIPS MIPS RS3000 (big-endian only). .It Dv EM_MIPS_RS4_BE MIPS RS4000 (big-endian only). .It Dv EM_SPARC64 SPARC v9 64-bit unofficial. .It Dv EM_PARISC HPPA. .It Dv EM_PPC PowerPC. .It Dv EM_ALPHA Compaq [DEC] Alpha. .El .Pp .It Dv e_version This member identifies the file version: .Pp .Bl -tag -width "EV_CURRENT" -compact .It Dv EV_NONE Invalid version .It Dv EV_CURRENT Current version .El .It Dv e_entry This member gives the virtual address to which the system first transfers control, thus starting the process. If the file has no associated entry point, this member holds zero. .It Dv e_phoff This member holds the program header table's file offset in bytes. If the file has no program header table, this member holds zero. .It Dv e_shoff This member holds the section header table's file offset in bytes. If the file has no section header table this member holds zero. .It Dv e_flags This member holds processor-specific flags associated with the file. Flag names take the form EF_`machine_flag'. Currently no flags have been defined. .It Dv e_ehsize This member holds the ELF header's size in bytes. .It Dv e_phentsize This member holds the size in bytes of one entry in the file's program header table; all entries are the same size. .It Dv e_phnum This member holds the number of entries in the program header table. If the file is using extended program header numbering, then the .Sy e_phnum member will contain the value .Dv PN_XNUM and the actual number of program header table entries will be stored in the .Sy sh_info member of the section header at index .Dv SHN_UNDEF . The product of .Sy e_phentsize and the number of program header table entries gives the program header table's size in bytes. If a file has no program header, .Sy e_phnum holds the value zero. .It Dv e_shentsize This member holds a sections header's size in bytes. A section header is one entry in the section header table; all entries are the same size. .It Dv e_shnum This member holds the number of entries in the section header table. If the file is using extended section numbering, then the .Sy e_shnum member will be zero and the actual section number will be stored in the .Sy sh_size member of the section header at index .Dv SHN_UNDEF . If a file has no section header table, both the .Sy e_shnum and the .Sy e_shoff fields of the ELF header will be zero. The product of .Sy e_shentsize and the number of sections in the file gives the section header table's size in bytes. .It Dv e_shstrndx This member holds the section header table index of the entry associated with the section name string table. If extended section numbering is being used, this field will hold the value .Sy SHN_XINDEX , and the actual section header table index will be present in the .Sy sh_link field of the section header entry at index .Dv SHN_UNDEF . If the file has no section name string table, this member holds the value .Sy SHN_UNDEF . .El .Pp An executable or shared object file's program header table is an array of structures, each describing a segment or other information the system needs to prepare the program for execution. An object file .Em segment contains one or more .Em sections . Program headers are meaningful only for executable and shared object files. A file specifies its own program header size with the ELF header's .Sy e_phentsize and .Sy e_phnum members. As with the Elf executable header, the program header also has different versions depending on the architecture: .Bd -literal -offset indent typedef struct { Elf32_Word p_type; Elf32_Off p_offset; Elf32_Addr p_vaddr; Elf32_Addr p_paddr; Elf32_Word p_filesz; Elf32_Word p_memsz; Elf32_Word p_flags; Elf32_Word p_align; } Elf32_Phdr; .Ed .Bd -literal -offset indent typedef struct { Elf64_Word p_type; Elf64_Word p_flags; Elf64_Off p_offset; Elf64_Addr p_vaddr; Elf64_Addr p_paddr; Elf64_Xword p_filesz; Elf64_Xword p_memsz; Elf64_Xword p_align; } Elf64_Phdr; .Ed .Pp The main difference between the 32-bit and the 64-bit program header lies only in the location of a .Sy p_flags member in the total struct. .Pp .Bl -tag -width "p_offset" -compact -offset indent .It Dv p_type This member of the Phdr struct tells what kind of segment this array element describes or how to interpret the array element's information. .Pp .Bl -tag -width "PT_DYNAMIC" -compact .It Dv PT_NULL The array element is unused and the other members' values are undefined. This lets the program header have ignored entries. .It Dv PT_LOAD The array element specifies a loadable segment, described by .Sy p_filesz and .Sy p_memsz . The bytes from the file are mapped to the beginning of the memory segment. If the segment's memory size .Pq Sy p_memsz is larger than the file size .Pq Sy p_filesz , the .Dq extra bytes are defined to hold the value 0 and to follow the segment's initialized area. The file size may not be larger than the memory size. Loadable segment entries in the program header table appear in ascending order, sorted on the .Sy p_vaddr member. .It Dv PT_DYNAMIC The array element specifies dynamic linking information. .It Dv PT_INTERP The array element specifies the location and size of a null-terminated path name to invoke as an interpreter. This segment type is meaningful only for executable files (though it may occur for shared objects). However it may not occur more than once in a file. If it is present it must precede any loadable segment entry. .It Dv PT_NOTE The array element specifies the location and size for auxiliary information. .It Dv PT_SHLIB This segment type is reserved but has unspecified semantics. Programs that contain an array element of this type do not conform to the ABI. .It Dv PT_PHDR The array element, if present, specifies the location and size of the program header table itself, both in the file and in the memory image of the program. This segment type may not occur more than once in a file. Moreover, it may only occur if the program header table is part of the memory image of the program. If it is present it must precede any loadable segment entry. .It Dv PT_LOPROC This value up to and including .Sy PT_HIPROC are reserved for processor-specific semantics. .It Dv PT_HIPROC This value down to and including .Sy PT_LOPROC are reserved for processor-specific semantics. .El .Pp .It Dv p_offset This member holds the offset from the beginning of the file at which the first byte of the segment resides. .It Dv p_vaddr This member holds the virtual address at which the first byte of the segment resides in memory. .It Dv p_paddr On systems for which physical addressing is relevant, this member is reserved for the segment's physical address. Under .Bx this member is not used and must be zero. .It Dv p_filesz This member holds the number of bytes in the file image of the segment. It may be zero. .It Dv p_memsz This member holds the number of bytes in the memory image of the segment. It may be zero. .It Dv p_flags This member holds flags relevant to the segment: .Pp .Bl -tag -width "PF_X" -compact .It Dv PF_X An executable segment. .It Dv PF_W A writable segment. .It Dv PF_R A readable segment. .El .Pp A text segment commonly has the flags .Sy PF_X and .Sy PF_R . A data segment commonly has .Sy PF_X , .Sy PF_W and .Sy PF_R . .It Dv p_align This member holds the value to which the segments are aligned in memory and in the file. Loadable process segments must have congruent values for .Sy p_vaddr and .Sy p_offset , modulo the page size. Values of zero and one mean no alignment is required. Otherwise, .Sy p_align should be a positive, integral power of two, and .Sy p_vaddr should equal .Sy p_offset , modulo .Sy p_align . .El .Pp An file's section header table lets one locate all the file's sections. The section header table is an array of Elf32_Shdr or Elf64_Shdr structures. The ELF header's .Sy e_shoff member gives the byte offset from the beginning of the file to the section header table. .Sy e_shnum holds the number of entries the section header table contains. .Sy e_shentsize holds the size in bytes of each entry. .Pp A section header table index is a subscript into this array. Some section header table indices are reserved. An object file does not have sections for these special indices: .Pp .Bl -tag -width "SHN_LORESERVE" -compact .It Dv SHN_UNDEF This value marks an undefined, missing, irrelevant, or otherwise meaningless section reference. For example, a symbol .Dq defined relative to section number .Sy SHN_UNDEF is an undefined symbol. .It Dv SHN_LORESERVE This value specifies the lower bound of the range of reserved indices. .It Dv SHN_LOPROC This value up to and including .Sy SHN_HIPROC are reserved for processor-specific semantics. .It Dv SHN_HIPROC This value down to and including .Sy SHN_LOPROC are reserved for processor-specific semantics. .It Dv SHN_ABS This value specifies absolute values for the corresponding reference. For example, symbols defined relative to section number .Sy SHN_ABS have absolute values and are not affected by relocation. .It Dv SHN_COMMON Symbols defined relative to this section are common symbols, such as FORTRAN COMMON or unallocated C external variables. .It Dv SHN_HIRESERVE This value specifies the upper bound of the range of reserved indices. The system reserves indices between .Sy SHN_LORESERVE and .Sy SHN_HIRESERVE , inclusive. The section header table does not contain entries for the reserved indices. .El .Pp The section header has the following structure: .Bd -literal -offset indent typedef struct { Elf32_Word sh_name; Elf32_Word sh_type; Elf32_Word sh_flags; Elf32_Addr sh_addr; Elf32_Off sh_offset; Elf32_Word sh_size; Elf32_Word sh_link; Elf32_Word sh_info; Elf32_Word sh_addralign; Elf32_Word sh_entsize; } Elf32_Shdr; .Ed .Bd -literal -offset indent typedef struct { Elf64_Word sh_name; Elf64_Word sh_type; Elf64_Xword sh_flags; Elf64_Addr sh_addr; Elf64_Off sh_offset; Elf64_Xword sh_size; Elf64_Word sh_link; Elf64_Word sh_info; Elf64_Xword sh_addralign; Elf64_Xword sh_entsize; } Elf64_Shdr; .Ed .Pp .Bl -tag -width "sh_addralign" -compact .It Dv sh_name This member specifies the name of the section. Its value is an index into the section header string table section, giving the location of a null-terminated string. .It Dv sh_type This member categorizes the section's contents and semantics. .Pp .Bl -tag -width "SHT_PROGBITS" -compact .It Dv SHT_NULL This value marks the section header as inactive. It does not have an associated section. Other members of the section header have undefined values. .It Dv SHT_PROGBITS The section holds information defined by the program, whose format and meaning are determined solely by the program. .It Dv SHT_SYMTAB This section holds a symbol table. Typically, .Sy SHT_SYMTAB provides symbols for link editing, though it may also be used for dynamic linking. As a complete symbol table, it may contain many symbols unnecessary for dynamic linking. An object file can also contain a .Sy SHN_DYNSYM section. .It Dv SHT_STRTAB This section holds a string table. An object file may have multiple string table sections. .It Dv SHT_RELA This section holds relocation entries with explicit addends, such as type .Sy Elf32_Rela for the 32-bit class of object files. An object may have multiple relocation sections. .It Dv SHT_HASH This section holds a symbol hash table. All object participating in dynamic linking must contain a symbol hash table. An object file may have only one hash table. .It Dv SHT_DYNAMIC This section holds information for dynamic linking. An object file may have only one dynamic section. .It Dv SHT_NOTE This section holds information that marks the file in some way. .It Dv SHT_NOBITS A section of this type occupies no space in the file but otherwise resembles .Sy SHN_PROGBITS . Although this section contains no bytes, the .Sy sh_offset member contains the conceptual file offset. .It Dv SHT_REL This section holds relocation offsets without explicit addends, such as type .Sy Elf32_Rel for the 32-bit class of object files. An object file may have multiple relocation sections. .It Dv SHT_SHLIB This section is reserved but has unspecified semantics. .It Dv SHT_DYNSYM This section holds a minimal set of dynamic linking symbols. An object file can also contain a .Sy SHN_SYMTAB section. .It Dv SHT_LOPROC This value up to and including .Sy SHT_HIPROC are reserved for processor-specific semantics. .It Dv SHT_HIPROC This value down to and including .Sy SHT_LOPROC are reserved for processor-specific semantics. .It Dv SHT_LOUSER This value specifies the lower bound of the range of indices reserved for application programs. .It Dv SHT_HIUSER This value specifies the upper bound of the range of indices reserved for application programs. Section types between .Sy SHT_LOUSER and .Sy SHT_HIUSER may be used by the application, without conflicting with current or future system-defined section types. .El .Pp .It Dv sh_flags Sections support one-bit flags that describe miscellaneous attributes. If a flag bit is set in .Sy sh_flags , the attribute is .Dq on for the section. Otherwise, the attribute is .Dq off or does not apply. Undefined attributes are set to zero. .Pp .Bl -tag -width "SHF_EXECINSTR" -compact .It Dv SHF_WRITE This section contains data that should be writable during process execution. .It Dv SHF_ALLOC The section occupies memory during process execution. Some control sections do not reside in the memory image of an object file. This attribute is off for those sections. .It Dv SHF_EXECINSTR The section contains executable machine instructions. .It Dv SHF_MASKPROC All bits included in this mask are reserved for processor-specific semantics. .El .Pp .It Dv sh_addr If the section will appear in the memory image of a process, this member holds the address at which the section's first byte should reside. Otherwise, the member contains zero. .It Dv sh_offset This member's value holds the byte offset from the beginning of the file to the first byte in the section. One section type, .Sy SHT_NOBITS , occupies no space in the file, and its .Sy sh_offset member locates the conceptual placement in the file. .It Dv sh_size This member holds the section's size in bytes. Unless the section type is .Sy SHT_NOBITS , the section occupies .Sy sh_size bytes in the file. A section of type .Sy SHT_NOBITS may have a non-zero size, but it occupies no space in the file. .It Dv sh_link This member holds a section header table index link, whose interpretation depends on the section type. .It Dv sh_info This member holds extra information, whose interpretation depends on the section type. .It Dv sh_addralign Some sections have address alignment constraints. If a section holds a doubleword, the system must ensure doubleword alignment for the entire section. That is, the value of .Sy sh_addr must be congruent to zero, modulo the value of .Sy sh_addralign . Only zero and positive integral powers of two are allowed. Values of zero or one mean the section has no alignment constraints. .It Dv sh_entsize Some sections hold a table of fixed-sized entries, such as a symbol table. For such a section, this member gives the size in bytes for each entry. This member contains zero if the section does not hold a table of fixed-size entries. .El .Pp Various sections hold program and control information: .Bl -tag -width ".shstrtab" -compact .It .bss (Block Started by Symbol) This section holds uninitialized data that contributes to the program's memory image. By definition, the system initializes the data with zeros when the program begins to run. This section is of type .Sy SHT_NOBITS . The attributes types are .Sy SHF_ALLOC and .Sy SHF_WRITE . .It .comment This section holds version control information. This section is of type .Sy SHT_PROGBITS . No attribute types are used. .It .data This section holds initialized data that contribute to the program's memory image. This section is of type .Sy SHT_PROGBITS . The attribute types are .Sy SHF_ALLOC and .Sy SHF_WRITE . .It .data1 This section holds initialized data that contribute to the program's memory image. This section is of type .Sy SHT_PROGBITS . The attribute types are .Sy SHF_ALLOC and .Sy SHF_WRITE . .It .debug This section holds information for symbolic debugging. The contents are unspecified. This section is of type .Sy SHT_PROGBITS . No attribute types are used. .It .dynamic This section holds dynamic linking information. The section's attributes will include the .Sy SHF_ALLOC bit. Whether the .Sy SHF_WRITE bit is set is processor-specific. This section is of type .Sy SHT_DYNAMIC . See the attributes above. .It .dynstr This section holds strings needed for dynamic linking, most commonly the strings that represent the names associated with symbol table entries. This section is of type .Sy SHT_STRTAB . The attribute type used is .Sy SHF_ALLOC . .It .dynsym This section holds the dynamic linking symbol table. This section is of type .Sy SHT_DYNSYM . The attribute used is .Sy SHF_ALLOC . .It .fini This section holds executable instructions that contribute to the process termination code. When a program exits normally the system arranges to execute the code in this section. This section is of type .Sy SHT_PROGBITS . The attributes used are .Sy SHF_ALLOC and .Sy SHF_EXECINSTR . .It .got This section holds the global offset table. This section is of type .Sy SHT_PROGBITS . The attributes are processor-specific. .It .hash This section holds a symbol hash table. This section is of type .Sy SHT_HASH . The attribute used is .Sy SHF_ALLOC . .It .init This section holds executable instructions that contribute to the process initialization code. When a program starts to run the system arranges to execute the code in this section before calling the main program entry point. This section is of type .Sy SHT_PROGBITS . The attributes used are .Sy SHF_ALLOC and .Sy SHF_EXECINSTR . .It .interp This section holds the pathname of a program interpreter. If the file has a loadable segment that includes the section, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise, that bit will be off. This section is of type .Sy SHT_PROGBITS . .It .line This section holds line number information for symbolic debugging, which describes the correspondence between the program source and the machine code. The contents are unspecified. This section is of type .Sy SHT_PROGBITS . No attribute types are used. .It .note This section holds information in the .Dq Note Section format described below. This section is of type .Sy SHT_NOTE . No attribute types are used. .It .plt This section holds the procedure linkage table. This section is of type .Sy SHT_PROGBITS . The attributes are processor-specific. .It .relNAME This section holds relocation information as described below. If the file has a loadable segment that includes relocation, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise the bit will be off. By convention, .Dq NAME is supplied by the section to which the relocations apply. Thus a relocation section for .Sy .text normally would have the name .Sy .rel.text . This section is of type .Sy SHT_REL . .It .relaNAME This section holds relocation information as described below. If the file has a loadable segment that includes relocation, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise the bit will be off. By convention, .Dq NAME is supplied by the section to which the relocations apply. Thus a relocation section for .Sy .text normally would have the name .Sy .rela.text . This section is of type .Sy SHT_RELA . .It .rodata This section holds read-only data that typically contributes to a non-writable segment in the process image. This section is of type .Sy SHT_PROGBITS . The attribute used is .Sy SHF_ALLOC . .It .rodata1 This section hold read-only data that typically contributes to a non-writable segment in the process image. This section is of type .Sy SHT_PROGBITS . The attribute used is .Sy SHF_ALLOC . .It .shstrtab This section holds section names. This section is of type .Sy SHT_STRTAB . No attribute types are used. .It .strtab This section holds strings, most commonly the strings that represent the names associated with symbol table entries. If the file has a loadable segment that includes the symbol string table, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise the bit will be off. This section is of type .Sy SHT_STRTAB . .It .symtab This section holds a symbol table. If the file has a loadable segment that includes the symbol table, the section's attributes will include the .Sy SHF_ALLOC bit. Otherwise the bit will be off. This section is of type .Sy SHT_SYMTAB . .It .text This section holds the .Dq text , or executable instructions, of a program. This section is of type .Sy SHT_PROGBITS . The attributes used are .Sy SHF_ALLOC and .Sy SHF_EXECINSTR . .It .jcr This section holds information about Java classes that must be registered. .It .eh_frame This section holds information used for C++ exception-handling. .El .Pp String table sections hold null-terminated character sequences, commonly called strings. The object file uses these strings to represent symbol and section names. One references a string as an index into the string table section. The first byte, which is index zero, is defined to hold a null character. Similarly, a string table's last byte is defined to hold a null character, ensuring null termination for all strings. .Pp An object file's symbol table holds information needed to locate and relocate a program's symbolic definitions and references. A symbol table index is a subscript into this array. .Bd -literal -offset indent typedef struct { Elf32_Word st_name; Elf32_Addr st_value; Elf32_Word st_size; unsigned char st_info; unsigned char st_other; Elf32_Half st_shndx; } Elf32_Sym; .Ed .Bd -literal -offset indent typedef struct { Elf64_Word st_name; unsigned char st_info; unsigned char st_other; Elf64_Half st_shndx; Elf64_Addr st_value; Elf64_Xword st_size; } Elf64_Sym; .Ed .Pp .Bl -tag -width "st_value" -compact .It Dv st_name This member holds an index into the object file's symbol string table, which holds character representations of the symbol names. If the value is non-zero, it represents a string table index that gives the symbol name. Otherwise, the symbol table has no name. .It Dv st_value This member gives the value of the associated symbol. .It Dv st_size Many symbols have associated sizes. This member holds zero if the symbol has no size or an unknown size. .It Dv st_info This member specifies the symbol's type and binding attributes: .Pp .Bl -tag -width "STT_SECTION" -compact .It Dv STT_NOTYPE The symbol's type is not defined. .It Dv STT_OBJECT The symbol is associated with a data object. .It Dv STT_FUNC The symbol is associated with a function or other executable code. .It Dv STT_SECTION The symbol is associated with a section. Symbol table entries of this type exist primarily for relocation and normally have .Sy STB_LOCAL bindings. .It Dv STT_FILE By convention the symbol's name gives the name of the source file associated with the object file. A file symbol has .Sy STB_LOCAL bindings, its section index is .Sy SHN_ABS , and it precedes the other .Sy STB_LOCAL symbols of the file, if it is present. .It Dv STT_LOPROC This value up to and including .Sy STT_HIPROC are reserved for processor-specific semantics. .It Dv STT_HIPROC This value down to and including .Sy STT_LOPROC are reserved for processor-specific semantics. .El .Pp .Bl -tag -width "STB_GLOBAL" -compact .It Dv STB_LOCAL Local symbols are not visible outside the object file containing their definition. Local symbols of the same name may exist in multiple file without interfering with each other. .It Dv STB_GLOBAL Global symbols are visible to all object files being combined. One file's definition of a global symbol will satisfy another file's undefined reference to the same symbol. .It Dv STB_WEAK Weak symbols resemble global symbols, but their definitions have lower precedence. .It Dv STB_LOPROC This value up to and including .Sy STB_HIPROC are reserved for processor-specific semantics. .It Dv STB_HIPROC This value down to and including .Sy STB_LOPROC are reserved for processor-specific semantics. .Pp There are macros for packing and unpacking the binding and type fields: .Pp .Bl -tag -width "ELF32_ST_INFO(bind, type)" -compact .It Xo .Fn ELF32_ST_BIND info .Xc or .Fn ELF64_ST_BIND info extract a binding from an st_info value. .It Xo .Fn ELF64_ST_TYPE info .Xc or .Fn ELF32_ST_TYPE info extract a type from an st_info value. .It Xo .Fn ELF32_ST_INFO bind type .Xc or .Fn ELF64_ST_INFO bind type convert a binding and a type into an st_info value. .El .El .Pp .It Dv st_other This member currently holds zero and has no defined meaning. .It Dv st_shndx Every symbol table entry is .Dq defined in relation to some section. This member holds the relevant section header table index. .El .Pp Relocation is the process of connecting symbolic references with symbolic definitions. Relocatable files must have information that describes how to modify their section contents, thus allowing executable and shared object files to hold the right information for a process' program image. Relocation entries are these data. .Pp Relocation structures that do not need an addend: .Bd -literal -offset indent typedef struct { Elf32_Addr r_offset; Elf32_Word r_info; } Elf32_Rel; .Ed .Bd -literal -offset indent typedef struct { Elf64_Addr r_offset; Elf64_Xword r_info; } Elf64_Rel; .Ed .Pp Relocation structures that need an addend: .Bd -literal -offset indent typedef struct { Elf32_Addr r_offset; Elf32_Word r_info; Elf32_Sword r_addend; } Elf32_Rela; .Ed .Bd -literal -offset indent typedef struct { Elf64_Addr r_offset; Elf64_Xword r_info; Elf64_Sxword r_addend; } Elf64_Rela; .Ed .Pp .Bl -tag -width "r_offset" -compact .It Dv r_offset This member gives the location at which to apply the relocation action. For a relocatable file, the value is the byte offset from the beginning of the section to the storage unit affected by the relocation. For an executable file or shared object, the value is the virtual address of the storage unit affected by the relocation. .It Dv r_info This member gives both the symbol table index with respect to which the relocation must be made and the type of relocation to apply. Relocation types are processor-specific. When the text refers to a relocation entry's relocation type or symbol table index, it means the result of applying .Sy ELF_[32|64]_R_TYPE or .Sy ELF[32|64]_R_SYM , respectively to the entry's .Sy r_info member. .It Dv r_addend This member specifies a constant addend used to compute the value to be stored into the relocatable field. .El .Ss Note Section ELF note sections consist of entries with the following format: .Bl -column -offset indent "namesz" "32 bits" "Null-terminated originator name" .Sy Field Ta Sy Size Ta Sy Description .It Va namesz Ta 32 bits Ta Size of "name" .It Va descsz Ta 32 bits Ta Size of "desc" .It Va type Ta 32 bits Ta OS-dependent note type .It Va name Ta Va namesz Ta Null-terminated originator name .It Va desc Ta Va descsz Ta OS-dependent note data .El .Pp The .Va name and .Va desc fields are padded to ensure 4-byte alignemnt. .Va namesz and .Va descsz specify the unpadded length. .Pp .Fx defines the following ELF note types .Po with corresponding interpretation of .Va desc Pc : .Bl -tag -width 4n .It Dv NT_FREEBSD_ABI_TAG Pq Value: 1 Indicates the OS ABI version in a form of a 32-bit integer containing expected ABI version .Po i.e., .Dv __FreeBSD_version Pc . .It Dv NT_FREEBSD_NOINIT_TAG Pq Value: 2 Indicates that the C startup does not call initialization routines, and thus .Xr rtld 1 must do so. .Va desc is ignored. .It Dv NT_FREEBSD_ARCH_TAG Pq Value: 3 Contains the MACHINE_ARCH that the executable was built for. .It Dv NT_FREEBSD_FEATURE_CTL Pq Value: 4 Contains a bitmask of mitigations and features to enable: .Bl -tag -width 4n .It NT_FREEBSD_FCTL_ASLR_DISABLE Pq Value: 0x01 Request that address randomization (ASLR) not be performed. See .Xr security 7 . .It NT_FREEBSD_FCTL_PROTMAX_DISABLE Pq Value: 0x02 -Request that +Request that .Xr mmap 2 calls not set PROT_MAX to the initial value of the .Fa prot argument. .It NT_FREEBSD_FCTL_STKGAP_DISABLE Pq Value: 0x04 Disable stack gap. .It NT_FREEBSD_FCTL_WXNEEDED Pq Value: 0x08 Indicate that the binary requires mappings that are simultaneously writeable and executable. .El .El .Sh SEE ALSO .Xr as 1 , .Xr gdb 1 , .Xr ld 1 , .Xr objdump 1 , .Xr readelf 1 , .Xr execve 2 , .Xr ar 5 , .Xr core 5 .Rs .%A Hewlett Packard .%B Elf-64 Object File Format .Re .Rs .%A Santa Cruz Operation .%B System V Application Binary Interface .Re .Rs .%A Unix System Laboratories .%T Object Files .%B "Executable and Linking Format (ELF)" .Re .Sh HISTORY The ELF header files made their appearance in .Fx 2.2.6 . ELF in itself first appeared in .At V . The ELF format is an adopted standard. .Sh AUTHORS This manual page was written by .An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org with inspiration from BSDi's .Bsx .Nm manpage. Index: head/share/man/man5/fstab.5 =================================================================== --- head/share/man/man5/fstab.5 (revision 360602) +++ head/share/man/man5/fstab.5 (revision 360603) @@ -1,471 +1,471 @@ .\" Copyright (c) 1980, 1989, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)fstab.5 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" .Dd April 14, 2014 .Dt FSTAB 5 .Os .Sh NAME .Nm fstab .Nd static information about the file systems .Sh SYNOPSIS .In fstab.h .Sh DESCRIPTION The file .Nm contains descriptive information about the various file systems. .Nm is only read by programs, and not written; it is the duty of the system administrator to properly create and maintain this file. Each file system is described on a separate line; fields on each line are separated by tabs or spaces. The order of records in .Nm is important because .Xr fsck 8 , .Xr mount 8 , and .Xr umount 8 sequentially iterate through .Nm doing their thing. .Pp The first field, .Pq Fa fs_spec , describes the special device or remote file system to be mounted. The contents are decoded by the .Xr strunvis 3 function. This allows using spaces or tabs in the device name which would be interpreted as field separators otherwise. .Pp The second field, .Pq Fa fs_file , describes the mount point for the file system. For swap partitions, this field should be specified as .Dq none . The contents are decoded by the .Xr strunvis 3 function, as above. .Pp The third field, .Pq Fa fs_vfstype , describes the type of the file system. The system can support various file system types. Only the root, /usr, and /tmp file systems need be statically compiled into the kernel; everything else will be automatically loaded at mount time. (Exception: the FFS cannot currently be demand-loaded.) Some people still prefer to statically compile other file systems as well. .Pp The fourth field, .Pq Fa fs_mntops , describes the mount options associated with the file system. It is formatted as a comma separated list of options. It contains at least the type of mount (see .Fa fs_type below) plus any additional options appropriate to the file system type. See the options flag .Pq Fl o in the .Xr mount 8 page and the file system specific page, such as .Xr mount_nfs 8 , for additional options that may be specified. All options that can be given to the file system specific mount commands can be used in .Nm as well. They just need to be formatted a bit differently. The arguments of the .Fl o option can be used without the preceding .Fl o flag. Other options need both the file system specific flag and its argument, separated by an equal sign. For example, mounting an .Xr msdosfs 5 filesystem, the options .Bd -literal -offset indent -o sync -o noatime -m 644 -M 755 -u foo -g bar .Ed .Pp should be written as .Bd -literal -offset indent sync,noatime,-m=644,-M=755,-u=foo,-g=bar .Ed .Pp in the option field of .Nm . .Pp If the options .Dq userquota and/or .Dq groupquota are specified, the file system is automatically processed by the .Xr quotacheck 8 command, and user and/or group disk quotas are enabled with .Xr quotaon 8 . By default, file system quotas are maintained in files named .Pa quota.user and .Pa quota.group which are located at the root of the associated file system. These defaults may be overridden by putting an equal sign and an alternative absolute pathname following the quota option. Thus, if the user quota file for .Pa /tmp is stored in .Pa /var/quotas/tmp.user , this location can be specified as: .Bd -literal -offset indent userquota=/var/quotas/tmp.user .Ed .Pp If the option .Dq failok is specified, the system will ignore any error which happens during the mount of that filesystem, which would otherwise cause the system to drop into single user mode. This option is implemented by the .Xr mount 8 command and will not be passed to the kernel. .Pp If the option .Dq noauto is specified, the file system will not be automatically mounted at system startup. Note that, for network file systems of third party types (i.e., types supported by additional software not included in the base system) to be automatically mounted at system startup, the .Va extra_netfs_types .Xr rc.conf 5 variable must be used to extend the .Xr rc 8 startup script's list of network file system types. .Pp If the option .Dq late is specified, the file system will be automatically mounted at a stage of system startup after remote mount points are mounted. For more detail about this option, see the .Xr mount 8 manual page. .Pp If the option .Dq update is specified, it indicates that the status of an already mounted file system should be changed accordingly. This allows, for example, file systems mounted read-only to be upgraded read-write and vice-versa. By default, an entry corresponding to a file systems that is already mounted is going to be skipped over when processing .Nm , unless it's a root file system, in which case logic similar to .Dq update is applied automatically. .Pp The .Dq update option is typically used in conjuction with two .Nm files. The first .Nm file is used to set up the initial set of file systems. The second .Nm file is then run to update the initial set of file systems and to add additional file systems. .Pp The type of the mount is extracted from the .Fa fs_mntops field and stored separately in the .Fa fs_type field (it is not deleted from the .Fa fs_mntops field). If .Fa fs_type is .Dq rw or .Dq ro then the file system whose name is given in the .Fa fs_file field is normally mounted read-write or read-only on the specified special file. .Pp If .Fa fs_type is .Dq sw then the special file is made available as a piece of swap space by the .Xr swapon 8 command at the end of the system reboot procedure. For swap devices, the keyword .Dq trimonce triggers the delivery of a .Dv BIO_DELETE command to the device. This command marks the device's blocks as unused, except those that might store a disk label. This marking can erase a crash dump. To delay .Nm swapon for a device until after .Nm savecore -has copied the crash dump to another location, use the +has copied the crash dump to another location, use the .Dq late option. For vnode-backed swap spaces, .Dq file is supported in the .Fa fs_mntops field. When .Fa fs_spec is an .Xr md 4 device file .Pq Do md Dc or Do md[0-9]* Dc and .Dq file is specified in .Fa fs_mntopts , an .Xr md 4 device is created with the specified file used as backing store, and then the new device is used as swap space. Swap entries on .Pa .eli devices will cause automatic creation of encrypted devices. The .Dq ealgo , .Dq aalgo , .Dq keylen , .Dq notrim , and .Dq sectorsize options may be passed to control those .Xr geli 8 parameters. The fields other than .Fa fs_spec and .Fa fs_type are unused. If .Fa fs_type is specified as .Dq xx the entry is ignored. This is useful to show disk partitions which are currently unused. .Pp The fifth field, .Pq Fa fs_freq , is used for these file systems by the .Xr dump 8 command to determine which file systems need to be dumped. If the fifth field is not present, a value of zero is returned and .Nm dump will assume that the file system does not need to be dumped. If the fifth field is greater than 0, then it specifies the number of days between dumps for this file system. .Pp The sixth field, .Pq Fa fs_passno , is used by the .Xr fsck 8 and .Xr quotacheck 8 programs to determine the order in which file system and quota checks are done at reboot time. The .Fa fs_passno field can be any value between 0 and .Ql INT_MAX Ns -1 . .Pp The root file system should be specified with a .Fa fs_passno of 1, and other file systems should have a .Fa fs_passno of 2 or greater. A file system with a .Fa fs_passno value of 1 is always checked sequentially and be completed before another file system is processed, and it will be processed before all file systems with a larger .Fa fs_passno . .Pp For any given value of .Fa fs_passno , file systems within a drive will be checked sequentially, but file systems on different drives will be checked at the same time to utilize parallelism available in the hardware. Once all file system checks are complete for the current .Fa fs_passno , the same process will start over for the next .Fa fs_passno . .Pp If the sixth field is not present or is zero, a value of zero is returned and .Xr fsck 8 and .Xr quotacheck 8 will assume that the file system does not need to be checked. .Pp The .Fa fs_passno field can be used to implement finer control when the system utilities may determine that the file system resides on a different physical device, when it actually does not, as with a .Xr ccd 4 device. All file systems with a lower .Fa fs_passno value will be completed before starting on file systems with a higher .Fa fs_passno value. E.g. all file systems with a .Fa fs_passno of 2 will be completed before any file systems with a .Fa fs_passno of 3 or greater are started. Gaps are allowed between the different .Fa fs_passno values. E.g. file systems listed in .Pa /etc/fstab may have .Fa fs_passno values such as 0, 1, 2, 15, 100, 200, 300, and may appear in any order within .Pa /etc/fstab . .Bd -literal #define FSTAB_RW "rw" /* read/write device */ #define FSTAB_RQ "rq" /* read/write with quotas */ #define FSTAB_RO "ro" /* read-only device */ #define FSTAB_SW "sw" /* swap device */ #define FSTAB_XX "xx" /* ignore totally */ struct fstab { char *fs_spec; /* block special device name */ char *fs_file; /* file system path prefix */ char *fs_vfstype; /* File system type, ufs, nfs */ char *fs_mntops; /* Mount options ala -o */ char *fs_type; /* FSTAB_* from fs_mntops */ int fs_freq; /* dump frequency, in days */ int fs_passno; /* pass number on parallel fsck */ }; .Ed .Pp The proper way to read records from .Pa fstab is to use the routines .Xr getfsent 3 , .Xr getfsspec 3 , .Xr getfstype 3 , and .Xr getfsfile 3 . .Sh FILES .Bl -tag -width /etc/fstab -compact .It Pa /etc/fstab The file .Nm resides in .Pa /etc . .El .Sh EXAMPLES .Bd -literal # Device Mountpoint FStype Options Dump Pass# # # UFS file system. /dev/da0p2 / ufs rw 1 1 # # Swap space on a block device. /dev/da0p1 none swap sw 0 0 # # Swap space using a block device with GBDE/GELI encyption. # aalgo, ealgo, keylen, sectorsize options are available # for .eli devices. /dev/da1p1.bde none swap sw 0 0 /dev/da1p2.eli none swap sw 0 0 # # tmpfs. tmpfs /tmp tmpfs rw,size=1g,mode=1777 0 0 # # UFS file system on a swap-backed md(4). /dev/md10 is # automatically created. If it is "md", a unit number # will be automatically selected. md10 /scratch mfs rw,-s1g 0 0 # # Swap space on a vnode-backed md(4). md11 none swap sw,file=/swapfile 0 0 # # CDROM. "noauto" option is typically used because the # media is removable. /dev/cd0 /cdrom cd9660 ro,noauto 0 0 # # NFS-exported file system. "serv" is an NFS server name # or IP address. serv:/export /nfs nfs rw,noinet6 0 0 .Ed .Sh SEE ALSO .Xr getfsent 3 , .Xr getvfsbyname 3 , .Xr strunvis 3 , .Xr ccd 4 , .Xr dump 8 , .Xr fsck 8 , .Xr geli 8 , .Xr mount 8 , .Xr quotacheck 8 , .Xr quotaon 8 , .Xr swapon 8 , .Xr umount 8 .Sh HISTORY The .Nm file format appeared in .Bx 4.0 . Index: head/share/man/man7/arch.7 =================================================================== --- head/share/man/man7/arch.7 (revision 360602) +++ head/share/man/man7/arch.7 (revision 360603) @@ -1,488 +1,490 @@ .\" Copyright (c) 2016-2017 The FreeBSD Foundation. All rights reserved. .\" .\" This documentation was created by Ed Maste under sponsorship of .\" The FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 28, 2020 .Dt ARCH 7 .Os .Sh NAME .Nm arch .Nd Architecture-specific details .Sh DESCRIPTION Differences between CPU architectures and platforms supported by .Fx . .Ss Introduction This document is a quick reference of key ABI details of .Fx architecture ports. For full details consult the processor-specific ABI supplement documentation. .Pp If not explicitly mentioned, sizes are in bytes. The architecture details in this document apply to .Fx 11.0 and later, unless otherwise noted. .Pp .Fx uses a flat address space. Variables of types .Vt unsigned long , .Vt uintptr_t , and .Vt size_t and pointers all have the same representation. .Pp In order to maximize compatibility with future pointer integrity mechanisms, manipulations of pointers as integers should be performed via .Vt uintptr_t or .Vt intptr_t and no other types. In particular, .Vt long and .Vt ptrdiff_t should be avoided. .Pp On some architectures, e.g., .Dv powerpc and AIM variants of .Dv powerpc64 , the kernel uses a separate address space. On other architectures, kernel and a user mode process share a single address space. The kernel is located at the highest addresses. .Pp On each architecture, the main user mode thread's stack starts near the highest user address and grows down. .Pp .Fx architecture support varies by release. This table shows the first .Fx release to support each architecture, and, for discontinued architectures, the final release. .Pp .Bl -column -offset indent "Architecture" "Initial Release" "Final Release" .It Sy Architecture Ta Sy Initial Release Ta Sy Final Release .It aarch64 Ta 11.0 .It alpha Ta 3.2 Ta 6.4 .It amd64 Ta 5.1 .It arm Ta 6.0 Ta 12.x .It armeb Ta 8.0 Ta 11.x .It armv6 Ta 10.0 .It armv7 Ta 12.0 .It ia64 Ta 5.0 Ta 10.4 .It i386 Ta 1.0 .It mips Ta 8.0 .It mipsel Ta 9.0 .It mipselhf Ta 12.0 .It mipshf Ta 12.0 .It mipsn32 Ta 9.0 .It mips64 Ta 9.0 .It mips64el Ta 9.0 .It mips64elhf Ta 12.0 .It mips64hf Ta 12.0 .It pc98 Ta 2.2 Ta 11.x .It powerpc Ta 6.0 .It powerpcspe Ta 12.0 .It powerpc64 Ta 6.0 .It riscv64 Ta 12.0 .It riscv64sf Ta 12.0 .It sparc64 Ta 5.0 Ta 12.x .El .Ss Type sizes All .Fx architectures use some variant of the ELF (see .Xr elf 5 ) .Sy Application Binary Interface (ABI) for the machine processor. All supported ABIs can be divided into two groups: .Bl -tag -width "Dv ILP32" .It Dv ILP32 .Vt int , .Vt long , .Vt void * types machine representations all have 4-byte size. .It Dv LP64 .Vt int type machine representation uses 4 bytes, while .Vt long and .Vt void * are 8 bytes. .El .Pp Some machines support more than one .Fx ABI. Typically these are 64-bit machines, where the .Dq native .Dv LP64 execution environment is accompanied by the .Dq legacy .Dv ILP32 environment, which was the historical 32-bit predecessor for 64-bit evolution. Examples are: .Bl -column -offset indent "powerpc64" "ILP32 counterpart" .It Sy LP64 Ta Sy ILP32 counterpart .It Dv amd64 Ta Dv i386 .It Dv powerpc64 Ta Dv powerpc .It Dv mips64* Ta Dv mips* .It Dv aarch64 Ta Dv armv6/armv7 .El .Pp .Dv aarch64 will support execution of .Dv armv6 or .Dv armv7 binaries if the CPU implements .Dv AArch32 execution state, however .Dv armv5 binaries aren't supported. .Pp On all supported architectures: .Bl -column -offset -indent "long long" "Size" .It Sy Type Ta Sy Size .It short Ta 2 .It int Ta 4 .It long Ta sizeof(void*) .It long long Ta 8 .It float Ta 4 .It double Ta 8 .El .Pp Integers are represented in two's complement. Alignment of integer and pointer types is natural, that is, the address of the variable must be congruent to zero modulo the type size. Most ILP32 ABIs, except .Dv arm , require only 4-byte alignment for 64-bit integers. .Pp Machine-dependent type sizes: .Bl -column -offset indent "Architecture" "void *" "long double" "time_t" .It Sy Architecture Ta Sy void * Ta Sy long double Ta Sy time_t .It aarch64 Ta 8 Ta 16 Ta 8 .It amd64 Ta 8 Ta 16 Ta 8 .It armv6 Ta 4 Ta 8 Ta 8 .It armv7 Ta 4 Ta 8 Ta 8 .It i386 Ta 4 Ta 12 Ta 4 .It mips Ta 4 Ta 8 Ta 8 .It mipsel Ta 4 Ta 8 Ta 8 .It mipselhf Ta 4 Ta 8 Ta 8 .It mipshf Ta 4 Ta 8 Ta 8 .It mipsn32 Ta 4 Ta 8 Ta 8 .It mips64 Ta 8 Ta 8 Ta 8 .It mips64el Ta 8 Ta 8 Ta 8 .It mips64elhf Ta 8 Ta 8 Ta 8 .It mips64hf Ta 8 Ta 8 Ta 8 .It powerpc Ta 4 Ta 8 Ta 8 .It powerpcspe Ta 4 Ta 8 Ta 8 .It powerpc64 Ta 8 Ta 8 Ta 8 .It riscv64 Ta 8 Ta 16 Ta 8 .It riscv64sf Ta 8 Ta 16 Ta 8 .El .Pp .Sy time_t is 8 bytes on all supported architectures except i386. .Ss Endianness and Char Signedness .Bl -column -offset indent "Architecture" "Endianness" "char Signedness" .It Sy Architecture Ta Sy Endianness Ta Sy char Signedness .It aarch64 Ta little Ta unsigned .It amd64 Ta little Ta signed .It armv6 Ta little Ta unsigned .It armv7 Ta little Ta unsigned .It i386 Ta little Ta signed .It mips Ta big Ta signed .It mipsel Ta little Ta signed .It mipselhf Ta little Ta signed .It mipshf Ta big Ta signed .It mipsn32 Ta big Ta signed .It mips64 Ta big Ta signed .It mips64el Ta little Ta signed .It mips64elhf Ta little Ta signed .It mips64hf Ta big Ta signed .It powerpc Ta big Ta unsigned .It powerpcspe Ta big Ta unsigned .It powerpc64 Ta big Ta unsigned .It riscv64 Ta little Ta signed .It riscv64sf Ta little Ta signed .El .Ss Page Size .Bl -column -offset indent "Architecture" "Page Sizes" .It Sy Architecture Ta Sy Page Sizes .It aarch64 Ta 4K, 2M, 1G .It amd64 Ta 4K, 2M, 1G .It armv6 Ta 4K, 1M .It armv7 Ta 4K, 1M .It i386 Ta 4K, 2M (PAE), 4M .It mips Ta 4K .It mipsel Ta 4K .It mipselhf Ta 4K .It mipshf Ta 4K .It mipsn32 Ta 4K .It mips64 Ta 4K .It mips64el Ta 4K .It mips64elhf Ta 4K .It mips64hf Ta 4K .It powerpc Ta 4K .It powerpcspe Ta 4K .It powerpc64 Ta 4K .It riscv64 Ta 4K .It riscv64sf Ta 4K .El .Ss Floating Point .Bl -column -offset indent "Architecture" "float, double" "long double" .It Sy Architecture Ta Sy float, double Ta Sy long double .It aarch64 Ta hard Ta soft, quad precision .It amd64 Ta hard Ta hard, 80 bit .It armv6 Ta hard Ta hard, double precision .It armv7 Ta hard Ta hard, double precision .It i386 Ta hard Ta hard, 80 bit .It mips Ta soft Ta identical to double .It mipsel Ta soft Ta identical to double .It mipselhf Ta hard Ta identical to double .It mipshf Ta hard Ta identical to double .It mipsn32 Ta soft Ta identical to double .It mips64 Ta soft Ta identical to double .It mips64el Ta soft Ta identical to double .It mips64elhf Ta hard Ta identical to double .It mips64hf Ta hard Ta identical to double .It powerpc Ta hard Ta hard, double precision .It powerpcspe Ta hard Ta hard, double precision .It powerpc64 Ta hard Ta hard, double precision .It riscv64 Ta hard Ta hard, double precision .It riscv64sf Ta soft Ta soft, double precision .El .Ss Default Tool Chain .Fx uses .Xr clang 1 as the default compiler on all supported CPU architectures, LLVM's .Xr ld.lld 1 as the default linker, and ELF Tool Chain binary utilities such as .Xr objcopy 1 and .Xr readelf 1 . .Ss MACHINE_ARCH vs MACHINE_CPUARCH vs MACHINE .Dv MACHINE_CPUARCH should be preferred in Makefiles when the generic architecture is being tested. .Dv MACHINE_ARCH should be preferred when there is something specific to a particular type of architecture where there is a choice of many, or could be a choice of many. Use .Dv MACHINE when referring to the kernel, interfaces dependent on a specific type of kernel or similar things like boot sequences. .Bl -column -offset indent "Dv MACHINE" "Dv MACHINE_CPUARCH" "Dv MACHINE_ARCH" .It Dv MACHINE Ta Dv MACHINE_CPUARCH Ta Dv MACHINE_ARCH .It arm64 Ta aarch64 Ta aarch64 .It amd64 Ta amd64 Ta amd64 .It arm Ta arm Ta armv6, armv7 .It i386 Ta i386 Ta i386 .It mips Ta mips Ta mips, mipsel, mips64, mips64el, mipshf, mipselhf, mips64elhf, mipsn32 .It powerpc Ta powerpc Ta powerpc, powerpcspe, powerpc64 .It riscv Ta riscv Ta riscv64, riscv64sf .El .Ss Predefined Macros The compiler provides a number of predefined macros. Some of these provide architecture-specific details and are explained below. Other macros, including those required by the language standard, are not included here. .Pp The full set of predefined macros can be obtained with this command: .Bd -literal -offset indent cc -x c -dM -E /dev/null .Ed .Pp Common type size and endianness macros: .Bl -column -offset indent "BYTE_ORDER" "Meaning" .It Sy Macro Ta Sy Meaning .It Dv __LP64__ Ta 64-bit (8-byte) long and pointer, 32-bit (4-byte) int .It Dv __ILP32__ Ta 32-bit (4-byte) int, long and pointer .It Dv BYTE_ORDER Ta Either Dv BIG_ENDIAN or Dv LITTLE_ENDIAN . .Dv PDP11_ENDIAN is not used on .Fx . .El .Pp Architecture-specific macros: .Bl -column -offset indent "Architecture" "Predefined macros" .It Sy Architecture Ta Sy Predefined macros .It aarch64 Ta Dv __aarch64__ .It amd64 Ta Dv __amd64__, Dv __x86_64__ .It armv6 Ta Dv __arm__, Dv __ARM_ARCH >= 6 .It armv7 Ta Dv __arm__, Dv __ARM_ARCH >= 7 .It i386 Ta Dv __i386__ .It mips Ta Dv __mips__, Dv __MIPSEB__, Dv __mips_o32 .It mipsel Ta Dv __mips__, Dv __mips_o32 .It mipselhf Ta Dv __mips__, Dv __mips_o32 .It mipshf Ta Dv __mips__, Dv __MIPSEB__, Dv __mips_o32 .It mipsn32 Ta Dv __mips__, Dv __MIPSEB__, Dv __mips_n32 .It mips64 Ta Dv __mips__, Dv __MIPSEB__, Dv __mips_n64 .It mips64el Ta Dv __mips__, Dv __mips_n64 .It mips64elhf Ta Dv __mips__, Dv __mips_n64 .It mips64hf Ta Dv __mips__, Dv __MIPSEB__, Dv __mips_n64 .It powerpc Ta Dv __powerpc__ .It powerpcspe Ta Dv __powerpc__, Dv __SPE__ .It powerpc64 Ta Dv __powerpc__, Dv __powerpc64__ .It riscv64 Ta Dv __riscv, Dv __riscv_xlen == 64 .It riscv64sf Ta Dv __riscv, Dv __riscv_xlen == 64 .El .Pp Compilers may define additional variants of architecture-specific macros. The macros above are preferred for use in .Fx . .Ss Important Xr make 1 variables Most of the externally settable variables are defined in the .Xr build 7 man page. These variables are not otherwise documented and are used extensively in the build system. .Bl -tag -width "MACHINE_CPUARCH" .It Dv MACHINE Represents the hardware platform. This is the same as the native platform's .Xr uname 1 .Fl m output. It defines both the userland / kernel interface, as well as the bootloader / kernel interface. It should only be used in these contexts. Each CPU architecture may have multiple hardware platforms it supports where .Dv MACHINE differs among them. It is used to collect together all the files from .Xr config 8 to build the kernel. It is often the same as .Dv MACHINE_ARCH just as one CPU architecture can be implemented by many different hardware platforms, one hardware platform may support multiple CPU architecture family members, though with different binaries. For example, .Dv MACHINE of i386 supported the IBM-AT hardware platform while the .Dv MACHINE of pc98 supported the Japanese company NEC's PC-9801 and PC-9821 hardware platforms. Both of these hardware platforms supported only the .Dv MACHINE_ARCH of i386 where they shared a common ABI, except for certain kernel / userland interfaces relating to underlying hardware platform differences in bus architecture, device enumeration and boot interface. Generally, .Dv MACHINE should only be used in src/sys and src/stand or in system imagers or installers. .It Dv MACHINE_ARCH Represents the CPU processor architecture. This is the same as the native platforms .Xr uname 1 .Fl p output. It defines the CPU instruction family supported. It may also encode a variation in the byte ordering of multi-byte integers (endian). It may also encode a variation in the size of the integer or pointer. It may also encode a ISA revision. It may also encode hard versus soft floating point ABI and usage. It may also encode a variant ABI when the other factors do not uniquely define the ABI (e.g., MIPS' n32 ABI). It, along with .Dv MACHINE , defines the ABI used by the system. For example, the MIPS CPU processor family supports 9 different combinations encoding pointer size, endian and hard versus soft float (for 8 combinations) as well as N32 (which only ever had one variation of all these). Generally, the plain CPU name specifies the most common (or at least first) variant of the CPU. This is why mips and mips64 imply 'big endian' while 'armv6' and 'armv7' imply little endian. If we ever were to support the so-called x32 ABI (using 32-bit pointers on the amd64 architecture), it would most likely be encoded as amd64-x32. It is unfortunate that amd64 specifies the 64-bit evolution of the x86 platform (it matches the 'first rule') as everybody else uses x86_64. There is no standard name for the processor: each OS selects its own conventions. .It Dv MACHINE_CPUARCH Represents the source location for a given .Dv MACHINE_ARCH . It is generally the common prefix for all the MACHINE_ARCH that share the same implementation, though 'riscv' breaks this rule. For example, .Dv MACHINE_CPUARCH is defined to be mips for all the flavors of mips that we support since we support them all with a shared set of sources. While amd64 and i386 are closely related, MACHINE_CPUARCH is not x86 for them. -The FreeBSD source base supports amd64 and i386 with two +The +.Fx +source base supports amd64 and i386 with two distinct source bases living in subdirectories named amd64 and i386 (though behind the scenes there's some sharing that fits into this framework). .It Dv CPUTYPE Sets the flavor of .Dv MACHINE_ARCH to build. It is used to optimize the build for a specific CPU / core that the binaries run on. Generally, this does not change the ABI, though it can be a fine line between optimization for specific cases. .It Dv TARGET Used to set .Dv MACHINE in the top level Makefile for cross building. Unused outside of that scope. It is not passed down to the rest of the build. Makefiles outside of the top level should not use it at all (though some have their own private copy for hysterical raisons). .It Dv TARGET_ARCH Used to set .Dv MACHINE_ARCH by the top level Makefile for cross building. Like .Dv TARGET , it is unused outside of that scope. .El .Sh SEE ALSO .Xr src.conf 5 , .Xr build 7 .Sh HISTORY An .Nm manual page appeared in .Fx 11.1 . Index: head/share/man/man9/DECLARE_MODULE.9 =================================================================== --- head/share/man/man9/DECLARE_MODULE.9 (revision 360602) +++ head/share/man/man9/DECLARE_MODULE.9 (revision 360603) @@ -1,128 +1,129 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2000 Alexander Langer .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd February 13, 2018 .Dt DECLARE_MODULE 9 .Os .Sh NAME .Nm DECLARE_MODULE .Nd kernel module declaration macro .Sh SYNOPSIS .In sys/param.h .In sys/kernel.h .In sys/module.h .Fn DECLARE_MODULE "name" "moduledata_t data" "sub" "order" .Fn DECLARE_MODULE_TIED "name" "moduledata_t data" "sub" "order" .Sh DESCRIPTION The .Fn DECLARE_MODULE macro declares a generic kernel module. It is used to register the module with the system, using the .Fn SYSINIT macro. .Fn DECLARE_MODULE is usually used within other macros, such as .Xr DRIVER_MODULE 9 , .Xr DEV_MODULE 9 and .Xr SYSCALL_MODULE 9 . Of course, it can also be called directly, for example in order to implement dynamic sysctls. .Pp A module declared with .Fn DECLARE_MODULE_TIED will load only if the running kernel version (as specified by .Dv __FreeBSD_version ) is identical to that on which it was built. This declaration should be used by modules which depend on interfaces beyond the stable kernel KBI (such as ABI emulators or hypervisors that rely on internal kernel structures). .Fn DECLARE_MODULE -will behave like +will behave like .Fn DECLARE_MODULE_TIED -when compiled with modules built with the kernel. This allows locks and -other synchronization primitives to be inlined safely. +when compiled with modules built with the kernel. +This allows locks and other synchronization primitives +to be inlined safely. .Pp The arguments are: .Bl -tag -width indent .It Fa name The module name, which will be used in the .Fn SYSINIT call to identify the module. .It Fa data A .Vt moduledata_t structure, which contains two main items, the official name of the module name, which will be used in the .Vt module_t structure and a pointer to the event handler function of type .Vt modeventhand_t . .It Fa sub An argument directed to the .Fn SYSINIT macro. Valid values for this are contained in the .Vt sysinit_sub_id enumeration (see .In sys/kernel.h ) and specify the type of system startup interfaces. The .Xr DRIVER_MODULE 9 macro uses a value of .Dv SI_SUB_DRIVERS here for example, since these modules contain a driver for a device. For kernel modules that are loaded at runtime, a value of .Dv SI_SUB_EXEC is common. .It Fa order An argument for .Fn SYSINIT . It represents the KLDs order of initialization within the subsystem. Valid values are defined in the .Vt sysinit_elem_order enumeration .Pq In sys/kernel.h . .El .Sh SEE ALSO .Xr DEV_MODULE 9 , .Xr DRIVER_MODULE 9 , .Xr module 9 , .Xr SYSCALL_MODULE 9 .Pp .Pa /usr/include/sys/kernel.h , .Pa /usr/share/examples/kld .Sh AUTHORS .An -nosplit This manual page was written by .An Alexander Langer Aq Mt alex@FreeBSD.org , inspired by the KLD Facility Programming Tutorial by .An Andrew Reiter Aq Mt arr@watson.org . Index: head/share/man/man9/atomic.9 =================================================================== --- head/share/man/man9/atomic.9 (revision 360602) +++ head/share/man/man9/atomic.9 (revision 360603) @@ -1,601 +1,603 @@ .\" Copyright (c) 2000-2001 John H. Baldwin .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 18, 2019 .Dt ATOMIC 9 .Os .Sh NAME .Nm atomic_add , .Nm atomic_clear , .Nm atomic_cmpset , .Nm atomic_fcmpset , .Nm atomic_fetchadd , .Nm atomic_load , .Nm atomic_readandclear , .Nm atomic_set , .Nm atomic_subtract , .Nm atomic_store , .Nm atomic_thread_fence .Nd atomic operations .Sh SYNOPSIS .In sys/types.h .In machine/atomic.h .Ft void .Fn atomic_add_[acq_|rel_] "volatile *p" " v" .Ft void .Fn atomic_clear_[acq_|rel_] "volatile *p" " v" .Ft int .Fo atomic_cmpset_[acq_|rel_] .Fa "volatile *dst" .Fa " old" .Fa " new" .Fc .Ft int .Fo atomic_fcmpset_[acq_|rel_] .Fa "volatile *dst" .Fa " *old" .Fa " new" .Fc .Ft .Fn atomic_fetchadd_ "volatile *p" " v" .Ft .Fn atomic_load_[acq_] "volatile *p" .Ft .Fn atomic_readandclear_ "volatile *p" .Ft void .Fn atomic_set_[acq_|rel_] "volatile *p" " v" .Ft void .Fn atomic_subtract_[acq_|rel_] "volatile *p" " v" .Ft void .Fn atomic_store_[rel_] "volatile *p" " v" .Ft .Fn atomic_swap_ "volatile *p" " v" .Ft int .Fn atomic_testandclear_ "volatile *p" "u_int v" .Ft int .Fn atomic_testandset_ "volatile *p" "u_int v" .Ft void .Fn atomic_thread_fence_[acq|acq_rel|rel|seq_cst] "void" .Sh DESCRIPTION Atomic operations are commonly used to implement reference counts and as building blocks for synchronization primitives, such as mutexes. .Pp All of these operations are performed .Em atomically across multiple threads and in the presence of interrupts, meaning that they are performed in an indivisible manner from the perspective of concurrently running threads and interrupt handlers. .Pp On all architectures supported by .Fx , ordinary loads and stores of integers in cache-coherent memory are inherently atomic if the integer is naturally aligned and its size does not exceed the processor's word size. However, such loads and stores may be elided from the program by the compiler, whereas atomic operations are always performed. .Pp When atomic operations are performed on cache-coherent memory, all operations on the same location are totally ordered. .Pp When an atomic load is performed on a location in cache-coherent memory, it reads the entire value that was defined by the last atomic store to each byte of the location. An atomic load will never return a value out of thin air. When an atomic store is performed on a location, no other thread or interrupt handler will observe a .Em torn write , or partial modification of the location. .Pp Except as noted below, the semantics of these operations are almost identical to the semantics of similarly named C11 atomic operations. .Ss Types Most atomic operations act upon a specific .Fa type . That type is indicated in the function name. In contrast to C11 atomic operations, .Fx Ns 's atomic operations are performed on ordinary integer types. The available types are: .Pp .Bl -tag -offset indent -width short -compact .It Li int unsigned integer .It Li long unsigned long integer .It Li ptr unsigned integer the size of a pointer .It Li 32 unsigned 32-bit integer .It Li 64 unsigned 64-bit integer .El .Pp For example, the function to atomically add two integers is called .Fn atomic_add_int . .Pp Certain architectures also provide operations for types smaller than .Dq Li int . .Pp .Bl -tag -offset indent -width short -compact .It Li char unsigned character .It Li short unsigned short integer .It Li 8 unsigned 8-bit integer .It Li 16 unsigned 16-bit integer .El .Pp These types must not be used in machine-independent code. .Ss Acquire and Release Operations By default, a thread's accesses to different memory locations might not be performed in .Em program order , that is, the order in which the accesses appear in the source code. To optimize the program's execution, both the compiler and processor might reorder the thread's accesses. However, both ensure that their reordering of the accesses is not visible to the thread. Otherwise, the traditional memory model that is expected by single-threaded programs would be violated. Nonetheless, other threads in a multithreaded program, such as the .Fx kernel, might observe the reordering. Moreover, in some cases, such as the implementation of synchronization between threads, arbitrary reordering might result in the incorrect execution of the program. To constrain the reordering that both the compiler and processor might perform on a thread's accesses, a programmer can use atomic operations with .Em acquire and .Em release semantics. .Pp Atomic operations on memory have up to three variants. The first, or .Em relaxed variant, performs the operation without imposing any ordering constraints on accesses to other memory locations. This variant is the default. The second variant has acquire semantics, and the third variant has release semantics. .Pp When an atomic operation has acquire semantics, the operation must have completed before any subsequent load or store (by program order) is performed. Conversely, acquire semantics do not require that prior loads or stores have completed before the atomic operation is performed. An atomic operation can only have acquire semantics if it performs a load from memory. To denote acquire semantics, the suffix .Dq Li _acq is inserted into the function name immediately prior to the .Dq Li _ Ns Aq Fa type suffix. For example, to subtract two integers ensuring that the subtraction is completed before any subsequent loads and stores are performed, use .Fn atomic_subtract_acq_int . .Pp When an atomic operation has release semantics, all prior loads or stores (by program order) must have completed before the operation is performed. Conversely, release semantics do not require that the atomic operation must have completed before any subsequent load or store is performed. An atomic operation can only have release semantics if it performs a store to memory. To denote release semantics, the suffix .Dq Li _rel is inserted into the function name immediately prior to the .Dq Li _ Ns Aq Fa type suffix. For example, to add two long integers ensuring that all prior loads and stores are completed before the addition is performed, use .Fn atomic_add_rel_long . .Pp When a release operation by one thread .Em synchronizes with an acquire operation by another thread, usually meaning that the acquire operation reads the value written by the release operation, then the effects of all prior stores by the releasing thread must become visible to subsequent loads by the acquiring thread. Moreover, the effects of all stores (by other threads) that were visible to the releasing thread must also become visible to the acquiring thread. These rules only apply to the synchronizing threads. Other threads might observe these stores in a different order. .Pp In effect, atomic operations with acquire and release semantics establish one-way barriers to reordering that enable the implementations of synchronization primitives to express their ordering requirements without also imposing unnecessary ordering. For example, for a critical section guarded by a mutex, an acquire operation when the mutex is locked and a release operation when the mutex is unlocked will prevent any loads or stores from moving outside of the critical section. However, they will not prevent the compiler or processor from moving loads or stores into the critical section, which does not violate the semantics of a mutex. .Ss Thread Fence Operations Alternatively, a programmer can use atomic thread fence operations to constrain the reordering of accesses. In contrast to other atomic operations, fences do not, themselves, access memory. .Pp When a fence has acquire semantics, all prior loads (by program order) must have completed before any subsequent load or store is performed. Thus, an acquire fence is a two-way barrier for load operations. To denote acquire semantics, the suffix .Dq Li _acq is appended to the function name, for example, .Fn atomic_thread_fence_acq . .Pp When a fence has release semantics, all prior loads or stores (by program order) must have completed before any subsequent store operation is performed. Thus, a release fence is a two-way barrier for store operations. To denote release semantics, the suffix .Dq Li _rel is appended to the function name, for example, .Fn atomic_thread_fence_rel . .Pp Although .Fn atomic_thread_fence_acq_rel implements both acquire and release semantics, it is not a full barrier. For example, a store prior to the fence (in program order) may be completed after a load subsequent to the fence. In contrast, .Fn atomic_thread_fence_seq_cst implements a full barrier. Neither loads nor stores may cross this barrier in either direction. .Pp In C11, a release fence by one thread synchronizes with an acquire fence by another thread when an atomic load that is prior to the acquire fence (by program order) reads the value written by an atomic store that is subsequent to the release fence. -In constrast, in FreeBSD, because of the atomicity of ordinary, naturally +In constrast, in +.Fx , +because of the atomicity of ordinary, naturally aligned loads and stores, fences can also be synchronized by ordinary loads and stores. This simplifies the implementation and use of some synchronization primitives in .Fx . .Pp Since neither a compiler nor a processor can foresee which (atomic) load will read the value written by an (atomic) store, the ordering constraints imposed by fences must be more restrictive than acquire loads and release stores. Essentially, this is why fences are two-way barriers. .Pp Although fences impose more restrictive ordering than acquire loads and release stores, by separating access from ordering, they can sometimes facilitate more efficient implementations of synchronization primitives. For example, they can be used to avoid executing a memory barrier until a memory access shows that some condition is satisfied. .Ss Multiple Processors In multiprocessor systems, the atomicity of the atomic operations on memory depends on support for cache coherence in the underlying architecture. In general, cache coherence on the default memory type, .Dv VM_MEMATTR_DEFAULT , is guaranteed by all architectures that are supported by .Fx . For example, cache coherence is guaranteed on write-back memory by the .Tn amd64 and .Tn i386 architectures. However, on some architectures, cache coherence might not be enabled on all memory types. To determine if cache coherence is enabled for a non-default memory type, consult the architecture's documentation. .Ss Semantics This section describes the semantics of each operation using a C like notation. .Bl -hang .It Fn atomic_add p v .Bd -literal -compact *p += v; .Ed .It Fn atomic_clear p v .Bd -literal -compact *p &= ~v; .Ed .It Fn atomic_cmpset dst old new .Bd -literal -compact if (*dst == old) { *dst = new; return (1); } else return (0); .Ed .El .Pp Some architectures do not implement the .Fn atomic_cmpset functions for the types .Dq Li char , .Dq Li short , .Dq Li 8 , and .Dq Li 16 . .Bl -hang .It Fn atomic_fcmpset dst *old new .El .Pp On architectures implementing .Em Compare And Swap operation in hardware, the functionality can be described as .Bd -literal -offset indent -compact if (*dst == *old) { *dst = new; return (1); } else { *old = *dst; return (0); } .Ed On architectures which provide .Em Load Linked/Store Conditional primitive, the write to .Dv *dst might also fail for several reasons, most important of which is a parallel write to .Dv *dst cache line by other CPU. In this case .Fn atomic_fcmpset function also returns .Dv false , despite .Dl *old == *dst . .Pp Some architectures do not implement the .Fn atomic_fcmpset functions for the types .Dq Li char , .Dq Li short , .Dq Li 8 , and .Dq Li 16 . .Bl -hang .It Fn atomic_fetchadd p v .Bd -literal -compact tmp = *p; *p += v; return (tmp); .Ed .El .Pp The .Fn atomic_fetchadd functions are only implemented for the types .Dq Li int , .Dq Li long and .Dq Li 32 and do not have any variants with memory barriers at this time. .Bl -hang .It Fn atomic_load p .Bd -literal -compact return (*p); .Ed .It Fn atomic_readandclear p .Bd -literal -compact tmp = *p; *p = 0; return (tmp); .Ed .El .Pp The .Fn atomic_readandclear functions are not implemented for the types .Dq Li char , .Dq Li short , .Dq Li ptr , .Dq Li 8 , and .Dq Li 16 and do not have any variants with memory barriers at this time. .Bl -hang .It Fn atomic_set p v .Bd -literal -compact *p |= v; .Ed .It Fn atomic_subtract p v .Bd -literal -compact *p -= v; .Ed .It Fn atomic_store p v .Bd -literal -compact *p = v; .Ed .It Fn atomic_swap p v .Bd -literal -compact tmp = *p; *p = v; return (tmp); .Ed .El .Pp The .Fn atomic_swap functions are not implemented for the types .Dq Li char , .Dq Li short , .Dq Li ptr , .Dq Li 8 , and .Dq Li 16 and do not have any variants with memory barriers at this time. .Bl -hang .It Fn atomic_testandclear p v .Bd -literal -compact bit = 1 << (v % (sizeof(*p) * NBBY)); tmp = (*p & bit) != 0; *p &= ~bit; return (tmp); .Ed .El .Bl -hang .It Fn atomic_testandset p v .Bd -literal -compact bit = 1 << (v % (sizeof(*p) * NBBY)); tmp = (*p & bit) != 0; *p |= bit; return (tmp); .Ed .El .Pp The .Fn atomic_testandset and .Fn atomic_testandclear functions are only implemented for the types .Dq Li int , .Dq Li long and .Dq Li 32 and do not have any variants with memory barriers at this time. .Pp The type .Dq Li 64 is currently not implemented for some of the atomic operations on the .Tn arm , .Tn i386 , and .Tn powerpc architectures. .Sh RETURN VALUES The .Fn atomic_cmpset function returns the result of the compare operation. The .Fn atomic_fcmpset function returns .Dv true if the operation succeeded. Otherwise it returns .Dv false and sets .Va *old to the found value. The .Fn atomic_fetchadd , .Fn atomic_load , .Fn atomic_readandclear , and .Fn atomic_swap functions return the value at the specified address. The .Fn atomic_testandset and .Fn atomic_testandclear function returns the result of the test operation. .Sh EXAMPLES This example uses the .Fn atomic_cmpset_acq_ptr and .Fn atomic_set_ptr functions to obtain a sleep mutex and handle recursion. Since the .Va mtx_lock member of a .Vt "struct mtx" is a pointer, the .Dq Li ptr type is used. .Bd -literal /* Try to obtain mtx_lock once. */ #define _obtain_lock(mp, tid) \\ atomic_cmpset_acq_ptr(&(mp)->mtx_lock, MTX_UNOWNED, (tid)) /* Get a sleep lock, deal with recursion inline. */ #define _get_sleep_lock(mp, tid, opts, file, line) do { \\ uintptr_t _tid = (uintptr_t)(tid); \\ \\ if (!_obtain_lock(mp, tid)) { \\ if (((mp)->mtx_lock & MTX_FLAGMASK) != _tid) \\ _mtx_lock_sleep((mp), _tid, (opts), (file), (line));\\ else { \\ atomic_set_ptr(&(mp)->mtx_lock, MTX_RECURSE); \\ (mp)->mtx_recurse++; \\ } \\ } \\ } while (0) .Ed .Sh HISTORY The .Fn atomic_add , .Fn atomic_clear , .Fn atomic_set , and .Fn atomic_subtract operations were introduced in .Fx 3.0 . Initially, these operations were defined on the types .Dq Li char , .Dq Li short , .Dq Li int , and .Dq Li long . .Pp The .Fn atomic_cmpset , .Fn atomic_load_acq , .Fn atomic_readandclear , and .Fn atomic_store_rel operations were added in .Fx 5.0 . Simultaneously, the acquire and release variants were introduced, and support was added for operation on the types .Dq Li 8 , .Dq Li 16 , .Dq Li 32 , .Dq Li 64 , and .Dq Li ptr . .Pp The .Fn atomic_fetchadd operation was added in .Fx 6.0 . .Pp The .Fn atomic_swap and .Fn atomic_testandset operations were added in .Fx 10.0 . .Pp The .Fn atomic_testandclear and .Fn atomic_thread_fence operations were added in .Fx 11.0 . .Pp The relaxed variants of .Fn atomic_load and .Fn atomic_store were added in .Fx 12.0 . Index: head/share/man/man9/bhnd.9 =================================================================== --- head/share/man/man9/bhnd.9 (revision 360602) +++ head/share/man/man9/bhnd.9 (revision 360603) @@ -1,2681 +1,2681 @@ .\" Copyright (c) 2015-2016 Landon Fuller .\" Copyright (c) 2017 The FreeBSD Foundation .\" All rights reserved. .\" .\" Portions of this documentation were written by Landon Fuller .\" under sponsorship from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 26, 2018 .Dt BHND 9 .Os .Sh NAME .Nm bhnd .Nd BHND driver programming interface .Sh SYNOPSIS .In dev/bhnd/bhnd.h .\" .Ss Bus Resource Functions .Ft int .Fo bhnd_activate_resource .Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r" .Fc .Ft "struct bhnd_resource *" .Fo bhnd_alloc_resource .Fa "device_t dev" "int type" "int *rid" "rman_res_t start" "rman_res_t end" .Fa "rman_res_t count" "u_int flags" .Fc .Ft "struct bhnd_resource *" .Fo bhnd_alloc_resource_any .Fa "device_t dev" "int type" "int *rid" "u_int flags" .Fc .Ft int .Fo bhnd_alloc_resources .Fa "device_t dev" "struct resource_spec *rs" "struct bhnd_resource **res" .Fc .Ft int .Fo bhnd_deactivate_resource .Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r" .Fc .Ft int .Fo bhnd_release_resource .Fa "device_t dev" "int type" "int rid" "struct bhnd_resource *r" .Fc .Ft void .Fo bhnd_release_resources .Fa "device_t dev" "const struct resource_spec *rs" .Fa "struct bhnd_resource **res" .Fc .\" .Ss "Bus Space Functions" .Ft void .Fo bhnd_bus_barrier .Fa "struct bhnd_resource *r" "bus_size_t offset" .Fa "bus_size_t length" "int flags" .Fc .Ft uint8_t .Fn bhnd_bus_read_1 "struct bhnd_resource *r" "bus_size_t offset" .Ft uint16_t .Fn bhnd_bus_read_2 "struct bhnd_resource *r" "bus_size_t offset" .Ft uint32_t .Fn bhnd_bus_read_4 "struct bhnd_resource *r" "bus_size_t offset" .Ft void .Fo bhnd_bus_read_multi_1 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_read_multi_2 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_read_multi_4 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_read_multi_stream_1 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_read_multi_stream_2 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_read_multi_stream_4 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_read_region_1 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_read_region_2 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_read_region_4 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_read_region_stream_1 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_read_region_stream_2 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_read_region_stream_4 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fn bhnd_bus_read_stream_1 "struct bhnd_resource *r" "bus_size_t offset" .Ft void .Fn bhnd_bus_read_stream_2 "struct bhnd_resource *r" "bus_size_t offset" .Ft uint32_t .Fn bhnd_bus_read_stream_4 "struct bhnd_resource *r" "bus_size_t offset" .Ft void .Fo bhnd_bus_set_multi_1 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_set_multi_2 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_set_multi_4 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_set_region_1 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_set_region_2 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t value" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_set_region_4 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t value" .Fa "bus_size_t count" .Fc .Ft void .Fn bhnd_bus_write_1 "struct bhnd_resource *r" "uint8_t value" .Ft void .Fn bhnd_bus_write_2 "struct bhnd_resource *r" "uint16_t value" .Ft void .Fn bhnd_bus_write_4 "struct bhnd_resource *r" "uint32_t value" .Ft void .Fo bhnd_bus_write_multi_1 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_write_multi_2 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_write_multi_4 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_write_multi_stream_1 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_write_multi_stream_2 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_write_multi_stream_4 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_write_region_1 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_write_region_2 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_write_region_4 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_write_region_stream_1 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint8_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_write_region_stream_2 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint16_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fo bhnd_bus_write_region_stream_4 .Fa "struct bhnd_resource *r" "bus_size_t offset" "uint32_t *datap" .Fa "bus_size_t count" .Fc .Ft void .Fn bhnd_bus_write_stream_1 "struct bhnd_resource *r" "uint8_t value" .Ft void .Fn bhnd_bus_write_stream_2 "struct bhnd_resource *r" "uint16_t value" .Ft void .Fn bhnd_bus_write_stream_4 "struct bhnd_resource *r" "uint32_t value" .\" .Ss "Device Configuration Functions" .Ft int .Fn bhnd_read_ioctl "device_t dev" "uint16_t *ioctl" .Ft int .Fn bhnd_write_ioctl "device_t dev" "uint16_t value" "uint16_t mask" .Ft int .Fn bhnd_read_iost "device_t dev" "uint16_t *iost" .Ft uint32_t .Fo bhnd_read_config .Fa "device_t dev" "bus_size_t offset" "void *value" "u_int width" .Fc .Ft int .Fo bhnd_write_config .Fa "device_t dev" "bus_size_t offset" "const void *value" "u_int width" .Fc .Ft int .Fn bhnd_reset_hw "device_t dev" "uint16_t ioctl" "uint16_t reset_ioctl" .Ft int .Fn bhnd_suspend_hw "device_t dev" "uint16_t ioctl" .Ft bool .Fn bhnd_is_hw_suspended "device_t dev" .\" .Ss "Device Information Functions" .Ft bhnd_attach_type .Fo bhnd_get_attach_type .Fa "device_t dev" .Fc .Ft "const struct bhnd_chipid *" .Fo bhnd_get_chipid .Fa "device_t dev" .Fc .Ft bhnd_devclass_t .Fo bhnd_get_class .Fa "device_t dev" .Fc .Ft u_int .Fo bhnd_get_core_index .Fa "device_t dev" .Fc .Ft "struct bhnd_core_info" .Fo bhnd_get_core_info .Fa "device_t dev" .Fc .Ft int .Fo bhnd_get_core_unit .Fa "device_t dev" .Fc .Ft uint16_t .Fo bhnd_get_device .Fa "device_t dev" .Fc .Ft const char * .Fo bhnd_get_device_name .Fa "device_t dev" .Fc .Ft uint8_t .Fo bhnd_get_hwrev .Fa "device_t dev" .Fc .Ft uint16_t .Fo bhnd_get_vendor .Fa "device_t dev" .Fc .Ft const char * .Fo bhnd_get_vendor_name .Fa "device_t dev" .Fc .Ft int .Fo bhnd_read_board_info .Fa "device_t dev" "struct bhnd_board_info *info" .Fc .\" .Ss "Device Matching Functions" .Ft bool .Fo bhnd_board_matches .Fa "const struct bhnd_board_info *board" "const struct bhnd_board_match *desc" .Fc .Ft device_t .Fo bhnd_bus_match_child .Fa "device_t bus" "const struct bhnd_core_match *desc" .Fc .Ft bool .Fo bhnd_chip_matches .Fa "const struct bhnd_chipid *chip" "const struct bhnd_chip_match *desc" .Fc .Ft "struct bhnd_core_match" .Fo bhnd_core_get_match_desc .Fa "const struct bhnd_core_info *core" .Fc .Ft bool .Fo bhnd_core_matches .Fa "const struct bhnd_core_info *core" "const struct bhnd_core_match *desc" .Fc .Ft bool .Fo bhnd_cores_equal .Fa "const struct bhnd_core_info *lhs" "const struct bhnd_core_info *rhs" .Fc .Ft bool .Fo bhnd_hwrev_matches .Fa "uint16_t hwrev" "const struct bhnd_hwrev_match *desc" .Fc .Ft "const struct bhnd_core_info *" .Fo bhnd_match_core .Fa "const struct bhnd_core_info *cores" "u_int num_cores" .Fa "const struct bhnd_core_match *desc" .Fc .\" .Ss "Device Table Functions" .Ft "const struct bhnd_device *" .Fo bhnd_device_lookup .Fa "device_t dev" "const struct bhnd_device *table" "size_t entry_size" .Fc .Ft bool .Fo bhnd_device_matches .Fa "device_t dev" "const struct bhnd_device_match *desc" .Fc .Ft uint32_t .Fo bhnd_device_quirks .Fa "device_t dev" "const struct bhnd_device *table" "size_t entry_size" .Fc .Fo BHND_BOARD_QUIRK .Fa "board" "flags" .Fc .Fo BHND_CHIP_QUIRK .Fa "chip" "hwrev" "flags" .Fc .Fo BHND_CORE_QUIRK .Fa "hwrev" "flags" .Fc .Fo BHND_DEVICE .Fa "vendor" "device" "desc" "quirks" "..." .Fc .Fo BHND_DEVICE_IS_END .Fa "struct bhnd_device *d" .Fc .Fo BHND_DEVICE_QUIRK_IS_END .Fa "struct bhnd_device_quirk *q" .Fc .Fo BHND_PKG_QUIRK .Fa "chip" "pkg" "flags" .Fc .Bd -literal struct bhnd_device_quirk { struct bhnd_device_match desc; uint32_t quirks; }; .Ed .Bd -literal struct bhnd_device { const struct bhnd_device_match core; const char *desc; const struct bhnd_device_quirk *quirks_table; uint32_t device_flags; }; .Ed .Bd -literal enum { BHND_DF_ANY = 0, BHND_DF_HOSTB = (1 << 0), BHND_DF_SOC = (1 << 1), BHND_DF_ADAPTER = (1 << 2) }; .Ed .Bd -literal #define BHND_DEVICE_END { { BHND_MATCH_ANY }, NULL, NULL, 0 } .Ed .Bd -literal #define BHND_DEVICE_QUIRK_END { { BHND_MATCH_ANY }, 0 } .Ed .\" .Ss "DMA Address Translation Functions" .Ft int .Fo bhnd_get_dma_translation .Fa "device_t dev" "u_int width" "uint32_t flags" "bus_dma_tag_t *dmat" .Fa "struct bhnd_dma_translation *translation" .Fc .Bd -literal struct bhnd_dma_translation { bhnd_addr_t base_addr; bhnd_addr_t addr_mask; bhnd_addr_t addrext_mask; uint32_t flags; }; .Ed .Bd -literal typedef enum { BHND_DMA_ADDR_30BIT = 30, BHND_DMA_ADDR_32BIT = 32, BHND_DMA_ADDR_64BIT = 64 } bhnd_dma_addrwidth; .Ed .Bd -literal enum bhnd_dma_translation_flags { BHND_DMA_TRANSLATION_PHYSMAP = (1<<0), BHND_DMA_TRANSLATION_BYTESWAPPED = (1<<1) }; .Ed .\" .Ss "Interrupt Functions" .Ft u_int .Fo bhnd_get_intr_count .Fa "device_t dev" .Fc .Ft int .Fo bhnd_get_intr_ivec .Fa "device_t dev" "u_int intr" "u_int *ivec" .Fc .Ft int .Fo bhnd_map_intr .Fa "device_t dev" "u_int intr" "rman_res_t *irq" .Fc .Ft void .Fo bhnd_unmap_intr .Fa "device_t dev" "rman_res_t irq" .Fc .\" .Ss "NVRAM Functions" .Ft int .Fo bhnd_nvram_getvar .Fa "device_t dev" "const char *name" "void *buf" "size_t *len" .Fa "bhnd_nvram_type type" .Fc .Ft int .Fo bhnd_nvram_getvar_array .Fa "device_t dev" "const char *name" "void *buf" "size_t size" .Fa "bhnd_nvram_type type" .Fc .Ft int .Fo bhnd_nvram_getvar_int .Fa "device_t dev" "const char *name" "void *value" "int width" .Fc .Ft int .Fn bhnd_nvram_getvar_int8 "device_t dev" "const char *name" "int8_t *value" .Ft int .Fn bhnd_nvram_getvar_int16 "device_t dev" "const char *name" "int16_t *value" .Ft int .Fn bhnd_nvram_getvar_int32 "device_t dev" "const char *name" "int32_t *value" .Ft int .Fo bhnd_nvram_getvar_uint .Fa "device_t dev" "const char *name" "void *value" "int width" .Fc .Ft int .Fo bhnd_nvram_getvar_uint8 .Fa "device_t dev" "const char *name" "uint8_t *value" .Fc .Ft int .Fo bhnd_nvram_getvar_uint16 .Fa "device_t dev" "const char *name" "uint16_t *value" .Fc .Ft int .Fo bhnd_nvram_getvar_uint32 .Fa "device_t dev" "const char *name" "uint32_t *value" .Fc .Ft int .Fo bhnd_nvram_getvar_str .Fa "device_t dev" "const char *name" "char *buf" "size_t len" "size_t *rlen" .Fc .Ft "const char *" .Fo bhnd_nvram_string_array_next .Fa "const char *inp" "size_t ilen" "const char *prev" "size_t *olen" .Fc .Bd -literal typedef enum { BHND_NVRAM_TYPE_UINT8 = 0, BHND_NVRAM_TYPE_UINT16 = 1, BHND_NVRAM_TYPE_UINT32 = 2, BHND_NVRAM_TYPE_UINT64 = 3, BHND_NVRAM_TYPE_INT8 = 4, BHND_NVRAM_TYPE_INT16 = 5, BHND_NVRAM_TYPE_INT32 = 6, BHND_NVRAM_TYPE_INT64 = 7, BHND_NVRAM_TYPE_CHAR = 8, BHND_NVRAM_TYPE_STRING = 9, BHND_NVRAM_TYPE_BOOL = 10, BHND_NVRAM_TYPE_NULL = 11, BHND_NVRAM_TYPE_DATA = 12 BHND_NVRAM_TYPE_UINT8_ARRAY = 16, BHND_NVRAM_TYPE_UINT16_ARRAY = 17, BHND_NVRAM_TYPE_UINT32_ARRAY = 18, BHND_NVRAM_TYPE_UINT64_ARRAY = 19, BHND_NVRAM_TYPE_INT8_ARRAY = 20, BHND_NVRAM_TYPE_INT16_ARRAY = 21, BHND_NVRAM_TYPE_INT32_ARRAY = 22, BHND_NVRAM_TYPE_INT64_ARRAY = 23, BHND_NVRAM_TYPE_CHAR_ARRAY = 24, BHND_NVRAM_TYPE_STRING_ARRAY = 25, BHND_NVRAM_TYPE_BOOL_ARRAY = 26 } bhnd_nvram_type; .Ed .\" .Ss "Port/Region Functions" .Ft int .Fo bhnd_decode_port_rid .Fa "device_t dev" "int type" "int rid" "bhnd_port_type *port_type" .Fa "u_int *port" "u_int *region" .Fc .Ft u_int .Fo bhnd_get_port_count .Fa "device_t dev" "bhnd_port_type type" .Fc .Ft int .Fo bhnd_get_port_rid .Fa "device_t dev" "bhnd_port_type type" "u_int port" "u_int region" .Fc .Ft int .Fo bhnd_get_region_addr .Fa "device_t dev" "bhnd_port_type port_type" "u_int port" "u_int region" .Fa "bhnd_addr_t *region_addr" "bhnd_size_t *region_size" .Fc .Ft u_int .Fo bhnd_get_region_count .Fa "device_t dev" "bhnd_port_type type" "u_int port" .Fc .Ft bool .Fo bhnd_is_region_valid .Fa "device_t dev" "bhnd_port_type type" "u_int port" "u_int region" .Fc .Bd -literal typedef enum { BHND_PORT_DEVICE = 0, BHND_PORT_BRIDGE = 1, BHND_PORT_AGENT = 2 } bhnd_port_type; .Ed .\" .Ss "Power Management Functions" .Ft int .Fo bhnd_alloc_pmu .Fa "device_t dev" .Fc .Ft int .Fo bhnd_release_pmu .Fa "device_t dev" .Fc .Ft int .Fo bhnd_enable_clocks .Fa "device_t dev" "uint32_t clocks" .Fc .Ft int .Fo bhnd_request_clock .Fa "device_t dev" "bhnd_clock clock" .Fc .Ft int .Fo bhnd_get_clock_freq .Fa "device_t dev" "bhnd_clock clock" "u_int *freq" .Fc .Ft int .Fo bhnd_get_clock_latency .Fa "device_t dev" "bhnd_clock clock" "u_int *latency" .Fc .Ft int .Fo bhnd_request_ext_rsrc .Fa "device_t dev" "u_int rsrc" .Fc .Ft int .Fo bhnd_release_ext_rsrc .Fa "device_t dev" "u_int rsrc" .Fc .Bd -literal typedef enum { BHND_CLOCK_DYN = (1 << 0), BHND_CLOCK_ILP = (1 << 1), BHND_CLOCK_ALP = (1 << 2), BHND_CLOCK_HT = (1 << 3) } bhnd_clock; .Ed .\" .Ss "Service Provider Functions" .Ft int .Fo bhnd_register_provider .Fa "device_t dev" "bhnd_service_t service" .Fc .Ft int .Fo bhnd_deregister_provider .Fa "device_t dev" "bhnd_service_t service" .Fc .Ft device_t .Fo bhnd_retain_provider .Fa "device_t dev" "bhnd_service_t service" .Fc .Ft void .Fo bhnd_release_provider .Fa "device_t dev" "device_t provider" "bhnd_service_t service" .Fc .Bd -literal typedef enum { BHND_SERVICE_CHIPC, BHND_SERVICE_PWRCTL, BHND_SERVICE_PMU, BHND_SERVICE_NVRAM, BHND_SERVICE_GPIO, BHND_SERVICE_ANY = 1000 } bhnd_service_t; .Ed .\" .Ss "Utility Functions" .Ft "bhnd_erom_class_t *" .Fo bhnd_driver_get_erom_class .Fa "driver_t *driver" .Fc .Ft bhnd_devclass_t .Fo bhnd_find_core_class .Fa "uint16_t vendor" "uint16_t device" .Fc .Ft "const char *" .Fo bhnd_find_core_name .Fa "uint16_t vendor" "uint16_t device" .Fc .Ft bhnd_devclass_t .Fo bhnd_core_class .Fa "const struct bhnd_core_info *ci" .Fc .Ft "const char *" .Fo bhnd_core_name .Fa "const struct bhnd_core_info *ci" .Fc .Ft int .Fo bhnd_format_chip_id .Fa "char *buffer" "size_t size" "uint16_t chip_id" .Fc .Ft void .Fo bhnd_set_custom_core_desc .Fa "device_t dev" "const char *dev_name" .Fc .Ft void .Fo bhnd_set_default_core_desc .Fa "device_t dev" .Fc .Ft "const char *" .Fo bhnd_vendor_name .Fa "uint16_t vendor" .Fc .Bd -literal #define BHND_CHIPID_MAX_NAMELEN 32 .Ed .\" .Sh DESCRIPTION .Nm provides a unified bus and driver programming interface for the on-chip interconnects and IP cores found in Broadcom Home Networking Division (BHND) devices. .Pp The BHND device family consists of MIPS/ARM SoCs (System On a Chip) and host-connected chipsets based on a common library of Broadcom IP cores, connected via one of two on-chip backplane (hardware bus) architectures. .Pp Hardware designed prior to 2009 used Broadcom's .Dq SSB backplane architecture, based on Sonics Silicon's interconnect IP. Each core on the Sonics backplane vends a 4 KiB register block, containing both device-specific CSRs, and SSB-specific per-core device management (enable/reset/etc) registers. .Pp Subsequent hardware is based on Broadcom's .Dq BCMA backplane, based on ARM's AMBA IP. The IP cores used in earlier SSB-based devices were adapted for compatibility with the new backplane, with additional .Dq wrapper cores providing per-core device management functions in place of the SSB per-core management registers. .Pp When BHND hardware is used as a host-connected peripheral (e.g., in a PCI Wi-Fi card), the on-chip peripheral controller core is configured to operate as an endpoint device, bridging access to the SoC hardware: .Pp .Bl -dash -offset indent .It Host access to SoC address space is provided via a set of register windows (e.g., a set of configurable windows into SoC address space mapped via PCI BARs) .It DMA is supported by the bridge core's sparse mapping of host address space into the backplane address space. These address regions may be used as a target for the on-chip DMA engine. .It Any backplane interrupt vectors routed to the bridge core may be mapped by the bridge to host interrupts (e.g., PCI INTx/MSI/MSI-X). .El .Pp The .Nm driver programming interface \(em and .Xr bhndb 4 host bridge drivers \(em support the implementation of common drivers for Broadcom IP cores, whether attached via a BHND host bridge, or via the native SoC backplane. .\" .Ss "Bus Resource Functions" The bhnd_resource functions are wrappers for the standard .Vt "struct resource" bus APIs, providing support for .Vt SYS_RES_MEMORY resources that, on .Xr bhndb 4 bridged chipsets, may require on-demand remapping of address windows prior to accessing bus memory. .Pp These functions are primarily used in the implementation of BHND platform device drivers that, on host-connected peripherals, must share a small set of register windows during initial setup and teardown. .Pp BHND peripherals are designed to not require register window remapping during normal operation, and most drivers may safely use the standard .Vt struct resource APIs directly. .Pp The .Fn bhnd_activate_resource function activates a previously allocated resource. .Pp The arguments are as follows: .Bl -tag -width indent .It Fa dev The device holding ownership of the allocated resource. .It Fa type The type of the resource. .It Fa rid The bus-specific handle that identifies the resource being activated. .It Fa r A pointer to the resource returned by .Fn bhnd_alloc_resource . .El .Pp The .Fn bhnd_alloc_resource function allocates a resource from a device's parent .Xr bhnd 4 bus. .Pp The arguments are as follows: .Bl -tag -width indent .It Fa dev The device requesting resource ownership. .It Fa type The type of resource to allocate. This may be any type supported by the standard .Xr bus_alloc_resource 9 function. .It Fa rid The bus-specific handle identifying the resource being allocated. .It Fa start The start address of the resource. .It Fa end The end address of the resource. .It Fa count The size of the resource. .It Fa flags The flags for the resource to be allocated. These may be any values supported by the standard .Xr bus_alloc_resource 9 function. .El .Pp To request that the bus supply the resource's default .Fa start , .Fa end , and .Fa count values, pass .Fa start and .Fa end values of 0ul and ~0ul respectively, and a .Fa count of 1. .Pp The .Fn bhnd_alloc_resource_any function is a convenience wrapper for .Fn bhnd_alloc_resource , using the resource's default .Fa start , .Fa end , and .Fa count values. .Pp The arguments are as follows: .Bl -tag -width indent .It Fa dev The device requesting resource ownership. .It Fa type The type of resource to allocate. This may be any type supported by the standard .Xr bus_alloc_resource 9 function. .It Fa rid The bus-specific handle identifying the resource being allocated. .It Fa flags The flags for the resource to be allocated. These may be any values supported by the standard .Xr bus_alloc_resource 9 function. .El .Pp The .Fn bhnd_alloc_resources function allocates resources defined in resource specification from a device's parent .Xr bhnd 4 bus. .Pp The arguments are as follows: .Bl -tag -width indent .It Fa dev The device requesting ownership of the resources. .It Fa rs -A standard bus resource specification. If all requested resources, are -successfully allocated, this will be updated with the allocated resource -identifiers. +A standard bus resource specification. +If all requested resources, are successfully allocated, +this will be updated with the allocated resource identifiers. .It Fa res If all requested resources are successfully allocated, this will be populated with the allocated .Vt "struct bhnd_resource" instances. .El .Pp The .Fn bhnd_deactivate_resource function deactivates a resource previously activated by. .Fn bhnd_activate_resource . The arguments are as follows: .Bl -tag -width indent .It Fa dev The device holding ownership of the activated resource. .It Fa type The type of the resource. .It Fa rid The bus-specific handle identifying the resource. .It Fa r A pointer to the resource returned by bhnd_alloc_resource. .El .Pp The .Fn bhnd_release_resource function frees a resource previously returned by .Fn bhnd_alloc_resource . The arguments are as follows: .Bl -tag -width indent .It Fa dev The device holding ownership of the resource. .It Fa type The type of the resource. .It Fa rid The bus-specific handle identifying the resource. .It Fa r A pointer to the resource returned by bhnd_alloc_resource. .El .Pp The .Fn bhnd_release_resources function frees resources previously returned by .Fn bhnd_alloc_resources . The arguments are as follows: .Bl -tag -width indent .It Fa dev The device that owns the resources. .It Fa rs A standard bus resource specification previously initialized by .Fn bhnd_alloc_resources . .It Fa res The resources to be released. .El .Pp The .Vt bhnd_resource structure contains the following fields: .Bl -tag -width "direct" .It Fa res A pointer to the bus .Vt struct resource . .It Fa direct If true, the resource requires bus window remapping before it is MMIO accessible. .El .Pp .\" .Ss "Bus Space Functions" The bhnd_bus_space functions wrap their equivalent .Xr bus_space 9 counterparts, and provide support for accessing bus memory via .Vt "struct bhnd_resource". .Pp .Bl -ohang -offset indent -compact .It Fn bhnd_bus_barrier .It Fn bhnd_bus_[read|write]_[1|2|4] .It Fn bhnd_bus_[read_multi|write_multi]_[1|2|4] .It Fn bhnd_bus_[read_multi_stream|write_multi_stream]_[1|2|4] .It Fn bhnd_bus_[read_region|write_region]_[1|2|4] .It Fn bhnd_bus_[read_region_stream|write_region_stream]_[1|2|4] .It Fn bhnd_bus_[read_stream|write_stream]_[1|2|4] .It Fn bhnd_bus_[set_multi|set_stream]_[1|2|4] .El .Pp Drivers that do not rely on .Vt "struct bhnd_resource" should use the standard .Vt struct resource and .Xr bus_space 9 APIs directly. .\" .Ss "Device Configuration Functions" The .Fn bhnd_read_ioctl function is used to read the I/O control register value of device .Fa dev , returning the current value in .Fa ioctl . .Pp The .Fn bhnd_write_ioctl function is used to modify the I/O control register of .Fa dev . The new value of the register is computed by updating any bits set in .Fa mask to .Fa value . The following I/O control flags are supported: .Bl -tag -width ".Dv BHND_IOCTL_CLK_FORCE" -offset indent .It Dv BHND_IOCTL_BIST Initiate a built-in self-test (BIST). Must be cleared after BIST results are read via the IOST (I/O Status) register. .It Dv BHND_IOCTL_PME Enable posting of power management events by the core. .It Dv BHND_IOCTL_CLK_FORCE Force disable of clock gating, resulting in all clocks being distributed within the core. Should be set when asserting/deasserting reset to ensure the reset signal fully propagates to the entire core. .It Dv BHND_IOCTL_CLK_EN If cleared, the core clock will be disabled. Should be set during normal operation, and cleared when the core is held in reset. .It Dv BHND_IOCTL_CFLAGS The mask of IOCTL bits reserved for additional core-specific I/O control flags. .El .Pp The .Fn bhnd_read_iost function is used to read the I/O status register of device .Fa dev , returning the current value in .Fa iost . The following I/O status flags are supported: .Bl -tag -width ".Dv BHND_IOST_BIST_DONE" -offset indent .It Dv BHND_IOST_BIST_DONE Set upon BIST completion. Will be cleared when the .Dv BHND_IOCTL_BIST flag of the I/O control register is cleared using .Fn bhnd_write_ioctl . .It Dv BHND_IOST_BIST_FAIL Set upon detection of a BIST error; the value is unspecified if BIST has not completed and .Dv BHND_IOST_BIST_DONE is not also set. .It Dv BHND_IOST_CLK Set if the core has required that clocked be ungated, or cleared otherwise. The value is undefined if a core does not support clock gating. .It Dv BHND_IOST_DMA64 Set if this core supports 64-bit DMA. .It Dv BHND_IOST_CFLAGS The mask of IOST bits reserved for additional core-specific I/O status flags. .El .Pp The .Fn bhnd_read_config function is used to read a data item of .Fa width bytes at .Fa offset from the backplane-specific agent/config space of the device .Fa dev . .Pp The .Fn bhnd_write_config function is used to write a data item of .Fa width bytes with .Fa value at .Fa offset from the backplane-specific agent/config space of the device .Fa dev . The requested .Fa width must be one of 1, 2, or 4 bytes. .Pp The agent/config space accessible via .Fn bhnd_read_config and .Fn bhnd_write_config is backplane-specific, and these functions should only be used for functionality that is not available via another .Nm function. .Pp The .Fn bhnd_suspend_hw function transitions the device .Fa dev to a low power .Dq RESET state, writing .Fa ioctl to the I/O control flags of .Fa dev . The hardware may be brought out of this state using .Fn bhnd_reset_hw . .Pp The .Fn bhnd_reset_hw function first transitions the device .Fa dev to a low power RESET state, writing .Fa ioctl_reset to the I/O control flags of .Fa dev , and then brings the device out of RESET, writing .Fa ioctl to the device's I/O control flags. .Pp The .Fn bhnd_is_hw_suspended function returns .Dv true if the device .Fa dev is currently held in a RESET state, or is otherwise not clocked. Otherwise, it returns .Dv false . .Pp Any outstanding per-device PMU requests made using .Fn bhnd_enable_clocks , .Fn bhnd_request_clock , or .Fn bhnd_request_ext_rsrc will be released automatically upon placing a device into a RESET state. .Ss "Device Information Functions" The .Fn bhnd_get_attach_type function returns the attachment type of the parent .Xr bhnd 4 bus of device .Fa dev . .Pp The following attachment types are supported: .Bl -hang -width ".Dv BHND_ATTACH_ADAPTER" -offset indent .It Dv BHND_ATTACH_ADAPTER The bus is resident on a bridged adapter, such as a PCI Wi-Fi device. .It Dv BHND_ATTACH_NATIVE The bus is resident on the native host, such as the primary or secondary bus of an embedded SoC. .El .Pp The .Fn bhnd_get_chipid function returns chip information from the parent .Xr bhnd 4 bus of device .Fa dev . The returned .Vt bhnd_chipid struct contains the following fields: .Pp .Bl -tag -width "enum_addr" -offset indent .It Fa chip_id The chip identifier. .It Fa chip_rev The chip's hardware revision. .It Fa chip_pkg The chip's semiconductor package identifier. .Pp Several different physical semiconductor package variants may exist for a given chip, each of which may require driver workarounds for hardware errata, unpopulated components, etc. .It Fa chip_type The interconnect architecture used by this chip. .It Fa chip_caps The .Nm capability flags supported by this chip. .It Fa enum_addr The backplane enumeration address. On SSB devices, this will be the base address of the first SSB core. On BCMA devices, this will be the address of the enumeration ROM (EROM) core. .It Fa ncores The number of cores on the chip backplane, or 0 if unknown. .El .Pp The following constants are defined for known .Fa chip_type values: .Bl -tag -width ".Dv BHND_CHIPTYPE_BCMA_ALT" -offset indent -compact .It Dv BHND_CHIPTYPE_SIBA SSB interconnect. .It Dv BHND_CHIPTYPE_BCMA BCMA interconnect. .It Dv BHND_CHIPTYPE_BCMA_ALT BCMA-compatible variant found in Broadcom Northstar ARM SoCs. .It Dv BHND_CHIPTYPE_UBUS UBUS interconnect. This BCMA-derived interconnect is found in Broadcom BCM33xx DOCSIS SoCs, and BCM63xx xDSL SoCs. UBUS is not currently supported by .Xr bhnd 4 . .El .Pp The following .Fa chip_caps flags are supported: .Bl -tag -width ".Dv BHND_CAP_BP64" -offset indent -compact .It Dv BHND_CAP_BP64 The backplane supports 64-bit addressing. .It Dv BHND_CAP_PMU PMU is present. .El .Pp Additional symbolic constants for known .Fa chip_id , .Fa chip_pkg , and .Fa chip_type values are defined in .In dev/bhnd/bhnd_ids.h . .Pp The .Fn bhnd_get_class function returns the BHND class of device .Fa dev , if the device's .Em vendor and .Em device identifiers are recognized. Otherwise, returns .Dv BHND_DEVCLASS_OTHER . .Pp One of the following device classes will be returned: .Pp .Bl -tag -width ".Dv BHND_DEVCLASS_SOC_ROUTER" -offset indent -compact .It Dv BHND_DEVCLASS_CC ChipCommon I/O Controller .It Dv BHND_DEVCLASS_CC_B ChipCommon Auxiliary Controller .It Dv BHND_DEVCLASS_PMU PMU Controller .It Dv BHND_DEVCLASS_PCI PCI Host/Device Bridge .It Dv BHND_DEVCLASS_PCIE PCIe Host/Device Bridge .It Dv BHND_DEVCLASS_PCCARD PCMCIA Host/Device Bridge .It Dv BHND_DEVCLASS_RAM Internal RAM/SRAM .It Dv BHND_DEVCLASS_MEMC Memory Controller .It Dv BHND_DEVCLASS_ENET IEEE 802.3 MAC/PHY .It Dv BHND_DEVCLASS_ENET_MAC IEEE 802.3 MAC .It Dv BHND_DEVCLASS_ENET_PHY IEEE 802.3 PHY .It Dv BHND_DEVCLASS_WLAN IEEE 802.11 MAC/PHY/Radio .It Dv BHND_DEVCLASS_WLAN_MAC IEEE 802.11 MAC .It Dv BHND_DEVCLASS_WLAN_PHY IEEE 802.11 PHY .It Dv BHND_DEVCLASS_CPU CPU Core .It Dv BHND_DEVCLASS_SOC_ROUTER Interconnect Router .It Dv BHND_DEVCLASS_SOC_BRIDGE Interconnect Host Bridge .It Dv BHND_DEVCLASS_EROM Device Enumeration ROM .It Dv BHND_DEVCLASS_NVRAM NVRAM/Flash Controller .It Dv BHND_DEVCLASS_SOFTMODEM Analog/PSTN SoftModem Codec .It Dv BHND_DEVCLASS_USB_HOST USB Host Controller .It Dv BHND_DEVCLASS_USB_DEV USB Device Controller .It Dv BHND_DEVCLASS_USB_DUAL USB Host/Device Controller .It Dv BHND_DEVCLASS_OTHER Other / Unknown .It Dv BHND_DEVCLASS_INVALID Invalid Class .El .Pp The .Fn bhnd_get_core_info function returns the core information for device .Fa dev . The returned .Vt bhnd_core_info structure contains the following fields: .Pp .Bl -tag -width "core_idx" -offset indent -compact .It Fa vendor Vendor identifier (JEP-106, ARM 4-bit continuation encoded) .It Fa device Device identifier .It Fa hwrev Hardware revision .It Fa core_idx Core index .It Fa unit Core unit .El .Pp Symbolic constants for common vendor and device identifiers are defined in .In dev/bhnd/bhnd_ids.h . Common vendor identifiers include: .Pp .Bl -tag -width ".Dv BHND_MFGID_MIPS" -offset indent -compact .It Dv BHND_MFGID_ARM ARM .It Dv BHND_MFGID_BCM Broadcom .It Dv BHND_MFGID_MIPS MIPS .El .Pp The .Fn bhnd_get_core_index , .Fn bhnd_get_core_unit , .Fn bhnd_get_device , .Fn bhnd_get_hwrev , and .Fn bhnd_get_vendor functions are convenience wrappers for .Fn bhnd_get_core_info , returning, respect the .Fa core_idx , .Fa core_unit , .Fa device , .Fa hwrev , or .Fa vendor field from the .Vt bhnd_core_info structure. .Pp The .Fn bhnd_get_device_name function returns a human readable name for device .Fa dev . .Pp The .Fn bhnd_get_vendor_name function returns a human readable name for the vendor of device .Fa dev . .Pp The .Fn bhnd_read_board_info function attempts to read the board information for device .Fa dev . The board information will be returned in the location pointed to by .Fa info on success. .Pp The .Vt bhnd_board_info structure contains the following fields: .Pp .Bl -tag -width "board_srom_rev" -offset indent .It Fa board_vendor Vendor ID of the board manufacturer (PCI-SIG assigned). .It Fa board_type Board ID. .It Fa board_devid Device ID. .It Fa board_rev Board revision. .It Fa board_srom_rev Board SROM format revision. .It Fa board_flags Board flags (1) .It Fa board_flags2 Board flags (2) .It Fa board_flags3 Board flags (3) .El .Pp The .Fa board_devid field is the Broadcom PCI device ID that most closely matches the capabilities of the BHND device (if any). .Pp On PCI devices, the .Fa board_vendor , .Fa board_type , and .Fa board_devid fields default to the PCI Subsystem Vendor ID, PCI Subsystem ID, and PCI device ID, unless overridden in device NVRAM. .Pp On other devices, including SoCs, the .Fa board_vendor , .Fa board_type , and .Fa board_devid fields will be populated from device NVRAM. .Pp Symbolic constants for common board flags are defined in .In dev/bhnd/bhnd_ids.h . .Pp .Ss "Device Matching Functions" The bhnd device matching functions are used to match against core, chip, and board-level device attributes. Match requirements are specified using the .Vt "struct bhnd_board_match" , .Vt "struct bhnd_chip_match" , .Vt "struct bhnd_core_match" , .Vt "struct bhnd_device_match" , and .Vt "struct bhnd_hwrev_match" match descriptor structures. .Pp The .Fn bhnd_board_matches function returns .Dv true if .Fa board matches the board match descriptor .Fa desc . Otherwise, it returns .Dv false . .Pp The .Fn bhnd_chip_matches function returns .Dv true if .Fa chip matches the chip match descriptor .Fa desc . Otherwise, it returns .Dv false . .Pp The .Fn bhnd_core_matches function returns .Dv true if .Fa core matches the core match descriptor .Fa desc . Otherwise, it returns .Dv false . .Pp The .Fn bhnd_device_matches function returns .Dv true if the device .Fa dev matches the device match descriptor .Fa desc . Otherwise, it returns .Dv false . .Pp The .Fn bhnd_hwrev_matches function returns .Dv true if .Fa hwrev matches the hwrev match descriptor .Fa desc . Otherwise, it returns .Dv false . .Pp The .Fn bhnd_bus_match_child function returns the first child device of .Fa bus that matches the device match descriptor .Fa desc . If no matching child is found, .Dv NULL is returned. .Pp The .Fn bhnd_core_get_match_desc function returns an equality match descriptor for the core info in .Fa core . The returned descriptor will match only on core attributes identical to those defined by .Fa core . .Pp The .Fn bhnd_cores_equal function is a convenience wrapper for .Fn bhnd_core_matches and .Fn bhnd_core_get_match_desc . This function returns .Dv true if the .Vt bhnd_core_info structures .Fa lhs and .Fa rhs are equal. Otherwise, it returns .Dv false . .Pp The .Fn bhnd_match_core function returns a pointer to the first entry in the array .Fa cores of length .Fa num_cores that matches .Fa desc . If no matching core is found, .Dv NULL is returned. .Pp A .Vt bhnd_board_match match descriptor may be initialized using one or more of the following macros: .Pp .Bl -tag -width "Fn BHND_MATCH_BOARD_VENDOR vendor" -offset indent .It Fn BHND_MATCH_BOARD_VENDOR "vendor" Match on boards with a vendor equal to .Fa vendor . .It Fn BHND_MATCH_BOARD_TYPE "type" Match on boards with a type equal to .Dv "BHND_BOARD_ ##" .Fa type .It Fn BHND_MATCH_SROMREV "sromrev" Match on boards with a sromrev that matches .Dv "BHND_HWREV_ ##" .Fa sromrev . .It Fn BHND_MATCH_BOARD_REV "hwrev" Match on boards with hardware revisions that match .Dv "BHND_ ##" .Fa hwrev . .It Fn BHND_MATCH_BOARD "vendor" "type" A convenience wrapper for .Fn BHND_MATCH_BOARD_VENDOR and .Fn BHND_MATCH_BOARD_TYPE . .El .Pp For example: .Bd -literal -offset indent struct bhnd_board_match board_desc = { BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM), BHND_MATCH_BOARD_TYPE(BCM94360X52C), BHND_MATCH_BOARD_REV(HWREV_ANY), BHND_MATCH_SROMREV(RANGE(0, 10)) }; .Ed .Pp A .Vt bhnd_chip_match match descriptor may be initialized using one or more of the following macros: .Pp .Bl -tag -width "Fn BHND_MATCH_CHIP_IPR id pkg hwrev" -offset indent .It Fn BHND_MATCH_CHIP_ID "id" Match on chips with an ID equal to .Dv "BHND_CHIPID_ ##" .Fa id .It Fn BHND_MATCH_CHIP_REV "hwrev" Match on chips with hardware revisions that match .Dv "BHND_ ##" .Fa hwrev . .It Fn BHND_MATCH_CHIP_PKG "pkg" Match on chips with a package ID equal to .Dv "BHND_PKGID_ ##" .Fa pkg .It Fn BHND_MATCH_CHIP_TYPE "type" Match on chips with a chip type equal to .Dv "BHND_CHIPTYPE_ ##" .Fa type .It Fn BHND_MATCH_CHIP_IP "id" "pkg" A convenience wrapper for .Fn BHND_MATCH_CHIP_ID and .Fn BHND_MATCH_CHIP_PKG . .It Fn BHND_MATCH_CHIP_IPR "id" "pkg" "hwrev" A convenience wrapper for .Fn BHND_MATCH_CHIP_ID , .Fn BHND_MATCH_CHIP_PKG , and .Fn BHND_MATCH_CHIP_REV . .It Fn BHND_MATCH_CHIP_IR "id" "hwrev" A convenience wrapper for .Fn BHND_MATCH_CHIP_ID and .Fn BHND_MATCH_CHIP_REV . .El .Pp For example: .Bd -literal -offset indent struct bhnd_chip_match chip_desc = { BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN), BHND_MATCH_CHIP_TYPE(SIBA) }; .Ed .Pp A .Vt bhnd_core_match match descriptor may be initialized using one or more of the following macros: .Pp .Bl -tag -width "Fn BHND_MATCH_CORE_VENDOR vendor" -offset indent .It Fn BHND_MATCH_CORE_VENDOR "vendor" Match on cores with a vendor ID equal to .Fa vendor .It Fn BHND_MATCH_CORE_ID "id" Match on cores with a device ID equal to .Fa id .It Fn BHND_MATCH_CORE_REV "hwrev" Match on cores with hardware revisions that match .Dv "BHND_ ##" .Fa hwrev . .It Fn BHND_MATCH_CORE_CLASS "class" Match on cores with a core device class equal to .Fa class .It Fn BHND_MATCH_CORE_IDX "idx" Match on cores with a core index equal to .Fa idx .It Fn BHND_MATCH_CORE_UNIT "unit" Match on cores with a core unit equal to .Fa unit .It Fn BHND_MATCH_CORE "vendor" "id" A convenience wrapper for .Fn BHND_MATCH_CORE_VENDOR and .Fn BHND_MATCH_CORE_ID . .El .Pp For example: .Bd -literal -offset indent struct bhnd_core_match core_desc = { BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC), BHND_MATCH_CORE_REV(HWREV_RANGE(0, 10)) }; .Ed .Pp The .Vt bhnd_device_match match descriptor supports matching on all board, chip, and core attributes, and may be initialized using any of the .Vt bhnd_board_match , .Vt bhnd_chip_match , or .Vt bhnd_core_match macros. .Pp For example: .Bd -literal -offset indent struct bhnd_device_match device_desc = { BHND_MATCH_CHIP_IP(BCM4329, BCM4329_289PIN), BHND_MATCH_BOARD_VENDOR(BHND_MFGID_BROADCOM), BHND_MATCH_BOARD_TYPE(BCM94329AGB), BHND_MATCH_CORE(BHND_MFGID_BROADCOM, BHND_COREID_CC), }; .Ed .Pp A .Vt bhnd_hwrev_match match descriptor may be initialized using one of the following macros: .Pp .Bl -tag -width "Fn BHND_HWREV_RANGE start end" -offset indent -compact .It Dv BHND_HWREV_ANY Matches any hardware revision. .It Fn BHND_HWREV_EQ "hwrev" Matches any hardware revision equal to .Fa hwrev .It Fn BHND_HWREV_GTE "hwrev" Matches any hardware revision greater than or equal to .Fa hwrev .It Fn BHND_HWREV_LTE "hwrev" Matches any hardware revision less than or equal to .Fa hwrev .It Fn BHND_HWREV_RANGE "start" "end" Matches any hardware revision within an inclusive range. If .Dv BHND_HWREV_INVALID is specified as the .Fa end value, will match on any revision equal to or greater than .Fa start .El .\" .Ss "Device Table Functions" The bhnd device table functions are used to query device and quirk tables. .Pp The .Fn bhnd_device_lookup function returns a pointer to the first entry in device table .Fa table that matches the device .Fa dev . The table entry size is specified by .Fa entry_size . .Pp The .Fn bhnd_device_quirks function scan the device table .Fa table for all quirk entries that match the device .Fa dev , returning the bitwise OR of all matching quirk flags. The table entry size is specified by .Fa entry_size . .Pp The .Vt bhnd_device structure contains the following fields: .Bl -tag -width "quirks_table" -offset indent -compact .It Fa core A .Vt bhnd_device_match descriptor. .It Fa desc A verbose device description suitable for use with .Xr device_set_desc 9 , or .Dv NULL . .It Fa quirks_table The quirks table for this device, or .Dv NULL . .It Fa device_flags The device flags required when matching this entry. .El .Pp The following device flags are supported: .Bl -tag -width ".Dv BHND_DF_ADAPTER" -offset indent -compact .It Dv BHND_DF_ANY Match on any device. .It Dv BHND_DF_HOSTB Match only if the device is the .Xr bhndb 4 host bridge. Implies .Dv BHND_DF_ADAPTER . .It Dv BHND_DF_SOC Match only if the device is attached to a native SoC backplane. .It Dv BHND_DF_ADAPTER Match only if the device is attached to a .Xr bhndb 4 bridged backplane. .El .Pp A .Vt bhnd_device table entry may be initialized using one of the following macros: .Pp .Bl -ohang -offset indent .It Fn BHND_DEVICE "vendor" "device" "desc" "quirks" "flags" Match on devices with a vendor ID equal to .Dv BHND_MFGID_ ## .Fa vendor and a core device ID equal to .Dv BHND_COREID_ ## .Fa device . .Pp The device's verbose description is specified by the .Fa desc argument, a pointer to the device-specific quirks table is specified by the .Fa quirks argument, and any required device flags may be provided in .Fa flags . The optional .Fa flags argument defaults to .Dv BHND_DF_ANY if omitted. .It Dv BHND_DEVICE_END Terminate the .Vt bhnd_device table. .El .Pp For example: .Bd -literal -offset indent struct bhnd_device bhnd_usb11_devices[] = { BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller", bhnd_usb11_quirks), BHND_DEVICE_END }; .Ed .Pp The .Vt bhnd_device_quirk structure contains the following fields: .Bl -tag -width "quirks_table" -offset indent -compact .It Fa desc A .Vt bhnd_device_match descriptor. .It Fa quirks Applicable quirk flags. .El .Pp A bhnd_device_quirk table entry may be initialized using one of the following convenience macros: .Bl -tag -width "Fn BHND_CHIP_QUIRK chip hwrev flags" -offset indent .It Fn BHND_BOARD_QUIRK "board" "flags" Set quirk flags .Fa flags on devices with a board type equal to .Dv BHND_BOARD_ ## .Fa board . .It Fn BHND_CHIP_QUIRK "chip" "hwrev" "flags" Set quirk flags .Fa flags on devices with a chip ID equal to .Dv BHND_CHIPID_BCM ## .Fa chip and chip hardware revision that matches .Dv BHND_ ## .Fa hwrev . .It Fn BHND_PKG_QUIRK "chip" "pkg" flags" Set quirk flags .Fa flags on devices with a chip ID equal to .Dv BHND_CHIPID_BCM ## .Fa chip and chip package equal to .Dv BHND_ ## chip ## .Fa pkg . .It Fn BHND_CORE_QUIRK "hwrev" flags" Set quirk flags .Fa flags on devices with a core hardware revision that matches .Dv BHND_ ## .Fa hwrev . .El For example: .Bd -literal -offset indent struct bhnd_device_quirk bhnd_usb11_quirks[] = { BHND_DEVICE(BCM, USB, "Broadcom USB1.1 Controller", bhnd_usb11_quirks), BHND_DEVICE_END }; .Ed .Ss "DMA Address Translation Functions" The .Fn bhnd_get_dma_translation function is used to request a DMA address translation descriptor suitable for use with a maximum DMA address width of .Fa width , with support for the requested translation .Fa flags . .Pp If a suitable DMA address translation descriptor is found, it will be stored in .Fa translation , and a bus DMA tag specifying the DMA translation's address restrictions will be stored in .Fa dmat . The .Fa translation and .Fa dmat arguments may be .Dv NULL if the translation descriptor or DMA tag are not desired. .Pp The following DMA translation flags are supported: .Bl -ohang -width ".Dv BHND_DMA_TRANSLATION_BYTESWAPPED" -offset indent .It Dv BHND_DMA_TRANSLATION_PHYSMAP The translation remaps the device's physical address space. .Pp This is used in conjunction with .Dv BHND_DMA_TRANSLATION_BYTESWAPPED to define a DMA translation that provides byteswapped access to physical memory on big-endian MIPS SoCs. .It Dv BHND_DMA_TRANSLATION_BYTESWAPPED The translation provides a byte-swapped mapping; write requests will be byte-swapped before being written to memory, and read requests will be byte-swapped before being returned. .Pp This is primarily used to perform efficient byte swapping of DMA data on embedded MIPS SoCs executing in big-endian mode. .El .Pp The following symbolic constants are defined for common DMA address widths: .Pp .Bl -tag -width ".Dv BHND_DMA_ADDR_64BIT" -offset indent -compact .It Dv BHND_DMA_ADDR_30BIT 30-bit DMA .It Dv BHND_DMA_ADDR_32BIT 32-bit DMA .It Dv BHND_DMA_ADDR_64BIT 64-bit DMA .El .Pp The .Vt bhnd_dma_translation structure contains the following fields: .Bl -tag -width "addrext_mask" .It Fa base_addr Host-to-device physical address translation. This may be added to a host physical address to produce a device DMA address. .It Fa addr_mask Device-addressable address mask. This defines the device DMA address range, and excludes any bits reserved for mapping the address within the translation window at .Fa base_addr . .It Fa addrext_mask Device-addressable extended address mask. If a the per-core BHND DMA engine supports the 'addrext' control field, it can be used to provide address bits excluded by .Fa addr_mask . .Pp Support for DMA extended address changes \(em including coordination with the core providing device-to-host DMA address translation \(em is handled transparently by the DMA engine. .Pp For example, on PCI Wi-Fi devices, the Wi-Fi core's DMA engine will (in effect) update the PCI host bridge core's DMA .Dv sbtopcitranslation base address to map the target address prior to performing a DMA transaction. .It Fa flags Translation flags. .El .\" .Ss "Interrupt Functions" The .Fn bhnd_get_intr_count function is used to determine the number of backplane interrupt lines assigned to the device .Fa dev . Interrupt line identifiers are allocated in monotonically increasing order, starting with 0. .Pp The .Fn bhnd_get_intr_ivec function is used to determine the backplane interrupt vector assigned to interrupt line .Fa intr on the device .Fa dev , writing the result to .Fa ivec . Interrupt vector assignments are backplane-specific: On BCMA devices, this function returns the OOB bus line assigned to the interrupt. On SIBA devices, it returns the target OCP slave flag number assigned to the interrupt. .Pp The .Fn bhnd_map_intr function is used to map interrupt line .Fa intr assigned to device .Fa dev to an IRQ number, writing the result to .Fa irq . Until unmapped, this IRQ may be used when allocating a resource of type SYS_RES_IRQ. .Pp Ownership of the interrupt mapping is assumed by the caller, and must be explicitly released using .Fa bhnd_unmap_intr . .Pp The .Fn bhnd_unmap_intr function is used to unmap bus IRQ .Fa irq previously mapped using .Fn bhnd_map_intr by the device .Fa dev . .\" .Ss "NVRAM Functions" The .Fn bhnd_nvram_getvar function is used to read the value of NVRAM variable .Fa name from the NVRAM provider(s) registered with the parent .Xr bhnd 4 bus of device .Fa dev , coerced to the desired data representation .Fa type , written to the buffer specified by .Fa buf . .Pp Before the call, the maximum capacity of .Fa buf is specified by .Fa len . After a successful call \(em or if .Er ENOMEM is returned \(em the size of the available data will be written to .Fa len . The size of the desired data representation can be determined by calling .Fn bhnd_nvram_getvar with a .Dv NULL argument for .Fa buf . .Pp The following NVRAM data types are supported: .Pp .Bl -tag -width ".Dv BHND_NVRAM_TYPE_UINT64_ARRAY" -offset indent -compact .It Dv BHND_NVRAM_TYPE_UINT8 unsigned 8-bit integer .It Dv BHND_NVRAM_TYPE_UINT16 unsigned 16-bit integer .It Dv BHND_NVRAM_TYPE_UINT32 unsigned 32-bit integer .It Dv BHND_NVRAM_TYPE_UINT64 signed 64-bit integer .It Dv BHND_NVRAM_TYPE_INT8 signed 8-bit integer .It Dv BHND_NVRAM_TYPE_INT16 signed 16-bit integer .It Dv BHND_NVRAM_TYPE_INT32 signed 32-bit integer .It Dv BHND_NVRAM_TYPE_INT64 signed 64-bit integer .It Dv BHND_NVRAM_TYPE_CHAR UTF-8 character .It Dv BHND_NVRAM_TYPE_STRING UTF-8 NUL-terminated string .It Dv BHND_NVRAM_TYPE_BOOL uint8 boolean value .It Dv BHND_NVRAM_TYPE_NULL NULL (empty) value .It Dv BHND_NVRAM_TYPE_DATA opaque octet string .It Dv BHND_NVRAM_TYPE_UINT8_ARRAY array of uint8 integers .It Dv BHND_NVRAM_TYPE_UINT16_ARRAY array of uint16 integers .It Dv BHND_NVRAM_TYPE_UINT32_ARRAY array of uint32 integers .It Dv BHND_NVRAM_TYPE_UINT64_ARRAY array of uint64 integers .It Dv BHND_NVRAM_TYPE_INT8_ARRAY array of int8 integers .It Dv BHND_NVRAM_TYPE_INT16_ARRAY array of int16 integers .It Dv BHND_NVRAM_TYPE_INT32_ARRAY array of int32 integers .It Dv BHND_NVRAM_TYPE_INT64_ARRAY array of int64 integers .It Dv BHND_NVRAM_TYPE_CHAR_ARRAY array of UTF-8 characters .It Dv BHND_NVRAM_TYPE_STRING_ARRAY array of UTF-8 NUL-terminated strings .It Dv BHND_NVRAM_TYPE_BOOL_ARRAY array of uint8 boolean values .El .Pp The .Fn bhnd_nvram_getvar_array , .Fn bhnd_nvram_getvar_int , .Fn bhnd_nvram_getvar_int8 , .Fn bhnd_nvram_getvar_int16 , .Fn bhnd_nvram_getvar_int32 , .Fn bhnd_nvram_getvar_uint , .Fn bhnd_nvram_getvar_uint8 , .Fn bhnd_nvram_getvar_uint16 , .Fn bhnd_nvram_getvar_uint32 , and .Fn bhnd_nvram_getvar_str functions are convenience wrappers for .Fn bhnd_nvram_getvar . .Pp The .Fn bhnd_nvram_getvar_array function returns either a value of exactly .Fa size in .Fa buf , or returns an error code of .Er ENXIO if the data representation is not exactly .Fa size in length. .Pp The .Fn bhnd_nvram_getvar_int and .Fn bhnd_nvram_getvar_uint functions return the value of NVRAM variable .Fa name , coerced to a signed or unsigned integer type of .Fa width (1, 2, or 4 bytes). .Pp The .Fn bhnd_nvram_getvar_int8 , .Fn bhnd_nvram_getvar_int16 , .Fn bhnd_nvram_getvar_int32 , .Fn bhnd_nvram_getvar_uint , .Fn bhnd_nvram_getvar_uint8 , .Fn bhnd_nvram_getvar_uint16 , and .Fn bhnd_nvram_getvar_uint32 functions return the value of NVRAM variable .Fa name , coerced to a signed or unsigned 8, 16, or 32-bit integer type. .Pp The .Fn bhnd_nvram_getvar_str functions return the value of NVRAM variable .Fa name , coerced to a NUL-terminated string. .Pp The .Fn bhnd_nvram_string_array_next function iterates over all strings in the .Fa inp .Dv BHND_NVRAM_TYPE_STRING_ARRAY value. The size of .Fa inp , including any terminating NUL character(s), is specified using the .Fa ilen argument. The .Fa prev argument should be either a string pointer previously returned by .Fn bhnd_nvram_string_array_next , or .Dv NULL to begin iteration. If .Fa prev is not .Dv NULL , the .Fa olen argument must be a pointer to the length previously returned by .Fn bhnd_nvram_string_array_next . On success, the next string element's length will be written to this pointer. .\" .Ss "Port/Region Functions" Per-device interconnect memory mappings are identified by a combination of .Em port type , .Em port number , and .Em region number . Port and memory region identifiers are allocated in monotonically increasing order for each .Em port type , starting with 0. .Pp The following port types are supported: .Bl -tag -width ".Dv BHND_PORT_DEVICE" -offset indent .It Dv BHND_PORT_DEVICE Device memory. The device's control/status registers are always mapped by the first device port and region, and will be assigned a .Dv SYS_RES_MEMORY resource ID of 0. .It Dv BHND_PORT_BRIDGE Bridge memory. .It Dv BHND_PORT_AGENT Interconnect agent/wrapper. .El .Pp The .Fn bhnd_decode_port_rid function is used to decode the resource ID .Fa rid assigned to device .Fa dev , of resource type .Fa type , writing the port type to .Fa port_type , port number to .Fa port , and region number to .Fa region . .Pp The .Fn bhnd_get_port_count function returns the number of ports of type .Fa type assigned to device .Fa dev . .Pp The .Fn bhnd_get_port_rid function returns the resource ID for the .Dv SYS_RES_MEMORY resource mapping the .Fa port of .Fa type and .Fa region on device .Fa dev , or -1 if the port or region are invalid, or do not have an assigned resource ID. .Pp The .Fn bhnd_get_region_addr function is used to determine the base address and size of the memory .Fa region on .Fa port of .Fa type assigned to .Fa dev . The region's base device address will be written to .Fa region_addr , and the region size to .Fa region_size . .Pp The .Fn bhnd_get_region_count function returns the number of memory regions mapped to .Fa port of .Fa type on device .Fa dev . .Pp The .Fn bhnd_is_region_valid function returns .Dv true if .Fa region is a valid region mapped by .Fa port of .Fa type on device .Fa dev . .\" .Ss "Power Management Functions" Drivers must ask the parent .Xr bhnd 4 bus to allocate device PMU state using .Fn bhnd_alloc_pmu before calling any another bhnd PMU functions. .Pp The .Fn bhnd_alloc_pmu function is used to allocate per-device PMU state and enable PMU request handling for device .Fa dev . The memory region containing the device's PMU register block must be allocated using .Xr bus_alloc_resource 9 or .Fn bhnd_alloc_resource before calling .Fn bhnd_alloc_pmu , and must not be released until after calling .Fn bhnd_release_pmu . .Pp On all supported BHND hardware, the PMU register block is mapped by the device's control/status registers in the first device port and region. .Pp The .Fn bhnd_release_pmu function releases the per-device PMU state previously allocated for device .Fa dev using .Fn bhnd_alloc_pmu . Any outstanding clock and external resource requests will be discarded upon release of the device PMU state. .Pp The .Fn bhnd_enable_clocks function is used to request that .Fa clocks be powered up and routed to the backplane on behalf of device .Fa dev . This will power any clock sources required (e.g., XTAL, PLL, etc) and wait until the requested clocks are stable. If the request succeeds, any previous clock requests issued by .Fa dev will be discarded. .Pp The following clocks are supported, and may be combined using bitwise OR to request multiple clocks: .Pp .Bl -tag -width ".Dv BHND_CLOCK_DYN" -offset indent .It BHND_CLOCK_DYN Dynamically select an appropriate clock source based on all outstanding clock requests by any device attached to the parent .Xr bhnd 4 bus. .It BHND_CLOCK_ILP Idle Low-Power (ILP) Clock. May be used if no register access is required, or long request latency is acceptable. .It BHND_CLOCK_ALP Active Low-Power (ALP) Clock. Supports low-latency register access and low-rate DMA. .It BHND_CLOCK_HT High Throughput (HT) Clock. Supports high bus throughput and lowest-latency register access. .El .Pp The .Fn bhnd_request_clock function is used to request that .Fa clock (or faster) be powered up and routed to device .Fa dev . .Pp The .Fn bhnd_get_clock_freq function is used to request the current clock frequency of .Fa clock , writing the frequency in Hz to .Fa freq . .Pp The .Fn bhnd_get_clock_latency function is used to determine the transition latency required for .Fa clock , writing the latency in microseconds to .Fa latency . The .Dv BHND_CLOCK_HT latency value is suitable for use as the D11 Wi-Fi core .Em fastpwrup_dly value. .Pp The .Fn bhnd_request_ext_rsrc function is used to request that the external PMU-managed resource assigned to device .Fa dev , identified by device-specific identifier .Fa rsrc , be powered up. .Pp The .Fn bhnd_release_ext_rsrc function releases any outstanding requests by device .Fa dev for the PMU-managed resource identified by device-specific identifier .Fa rsrc . If an external resource is shared by multiple devices, it will not be powered down until all device requests are released. .\" .Ss "Service Provider Functions" The .Fn bhnd_register_provider function is used to register device .Fa dev as a provider for platform .Fa service with the parent .Xr bhnd 4 bus. .Pp The following service types are supported: .Bl -tag -width ".Dv BHND_SERVICE_INVALID" -offset indent .It Dv BHND_SERVICE_CHIPC ChipCommon service. The providing device must implement the bhnd_chipc interface. .It Dv BHND_SERVICE_PWRCTL Legacy PWRCTL service. The providing device must implement the bhnd_pwrctl interface. .It Dv BHND_SERVICE_PMU PMU service. The providing device must implement the bhnd_pmu interface. .It Dv BHND_SERVICE_NVRAM NVRAM service. The providing device must implement the bhnd_nvram interface. .It Dv BHND_SERVICE_GPIO GPIO service. The providing device must implement the standard .Xr gpio 4 interface. .It Dv BHND_SERVICE_ANY Matches on any service type. May be used with .Fn bhnd_deregister_provider to remove all service provider registrations for a device. .El .Pp The .Fn bhnd_deregister_provider function attempts to remove provider registration for the device .Fa dev and .Fa service . If a .Fa service argument of .Dv BHND_SERVICE_ANY is specified, this function will attempt to remove .Em all service provider registrations for .Fa dev . .Pp The .Fn bhnd_retain_provider function retains and returns a reference to the provider registered for .Fa service with the parent .Xr bhnd 4 bus of devce .Fa dev , if available. On success, the caller is responsible for releasing this provider reference using .Fn bhnd_release_provider . The service provider is guaranteed to remain available until the provider reference is released. .Pp The .Fn bhnd_release_provider function releases a reference to a .Fa provider for .Fa service , previously retained by device .Fa dev using .Fn bhnd_retain_provider . .\" .Ss "Utility Functions" The .Fn bhnd_driver_get_erom_class function returns the .Xr bhnd_erom 9 class for the device enumeration table format used by .Xr bhnd 4 bus driver instance .Fa driver . If the driver does not support .Xr bhnd_erom 9 device enumeration, .Dv NULL is returned. .Pp The .Fn bhnd_find_core_class function looks up the BHND class, if known, for the BHND vendor ID .Fa vendor and device ID .Fa device . .Pp The .Fn bhnd_find_core_name function is used to fetch the human-readable name, if known, for the BHND core with a vendor ID of .Fa vendor and device ID of .Fa device . .Pp The .Fn bhnd_core_class and .Fn bhnd_core_name functions are convenience wrappers for .Fn bhnd_find_core_class and .Fn bhnd_find_core_name , that use the .Fa vendor and .Fa device fields of the core info structure .Fa ci . .Pp The .Fn bhnd_format_chip_id function writes a NUL-terminated human-readable representation of the BHND .Fa chip_id value to the specified .Fa buffer with a capacity of .Fa size . No more than .Fa size-1 characters will be written, with the .Fa size'th character set to '\\0'. A buffer size of .Dv BHND_CHIPID_MAX_NAMELEN is sufficient for any string representation produced using .Fn bhnd_format_chip_id . .Pp The .Fn bhnd_set_custom_core_desc function uses the .Xr bhnd 4 device identification of .Fa dev , overriding the core name with the specified .Fa dev_name , to populate the device's verbose description using .Xr device_set_desc . .Pp The .Fn bhnd_set_default_core_desc function uses the .Xr bhnd 4 device identification of .Fa dev to populate the device's verbose description using .Xr device_set_desc . .Pp The .Fn bhnd_vendor_name function returns the human-readable name for the JEP-106, ARM 4-bit continuation encoded manufacturer ID .Fa vendor , if known. .\" .Sh RETURN VALUES .Ss Bus Resource Functions The .Fn bhnd_activate_resource , .Fn bhnd_alloc_resources , .Fn bhnd_deactivate_resource , and .Fn bhnd_release_resource functions return 0 on success, otherwise an appropriate error code is returned. .Pp The .Fn bhnd_alloc_resource and .Fn bhnd_alloc_resource_any functions return a pointer to .Vt "struct resource" on success, a null pointer otherwise. .\" .Ss "Device Configuration Functions" .Pp The .Fn bhnd_read_config and .Fn bhnd_write_config functions return 0 on success, or one of the following values on error: .Bl -tag -width Er .It Bq Er EINVAL The device is not a direct child of the .Xr bhnd 4 bus .It Bq Er EINVAL The requested width is not one of 1, 2, or 4 bytes. .It Bq Er ENODEV Accessing agent/config space for the device is unsupported. .It Bq Er EFAULT The requested offset or width exceeds the bounds of the mapped agent/config space. .El .Pp The .Fn bhnd_read_ioctl , .Fn bhnd_write_ioctl , .Fn bhnd_read_iost , .Fn bhnd_reset_hw , and .Fn bhnd_suspend_hw functions return 0 on success, otherwise an appropriate error code is returned. .\" .Ss "Device Information Functions" .Pp The .Fn bhnd_read_board_info function returns 0 on success, otherwise an appropriate error code is returned. .\" .Ss "DMA Address Translation Functions" The .Fn bhnd_get_dma_translation function returns 0 on success, or one of the following values on error: .Bl -tag -width Er .It Bq Er ENODEV DMA is not supported. .It Bq Er ENOENT No DMA translation matching the requested address width and translation flags is available. .El .Pp If fetching the requested DMA address translation otherwise fails, an appropriate error code will be returned. .\" .Ss "Interrupt Functions" .Pp The .Fn bhnd_get_intr_ivec function returns 0 on success, or .Er ENXIO if the requested interrupt line exceeds the number of interrupt lines assigned to the device. .Pp The .Fn bhnd_map_intr function returns 0 on success, otherwise an appropriate error code is returned. .\" .Ss "NVRAM Functions" The .Fn bhnd_nvram_getvar , .Fn bhnd_nvram_getvar_array , .Fn bhnd_nvram_getvar_int , .Fn bhnd_nvram_getvar_int8 , .Fn bhnd_nvram_getvar_int16 , .Fn bhnd_nvram_getvar_int32 , .Fn bhnd_nvram_getvar_uint , .Fn bhnd_nvram_getvar_uint8 , .Fn bhnd_nvram_getvar_uint16 , and .Fn bhnd_nvram_getvar_uint32 functions return 0 on success, or one of the following values on error: .Bl -tag -width Er .It Bq Er ENODEV If an NVRAM provider has not been registered with the bus. .It Bq Er ENOENT The requested variable was not found. .It Bq Er ENOMEM If the buffer of size is too small to hold the requested value. .It Bq Er EOPNOTSUPP If the value's native type is incompatible with and cannot be coerced to the requested type. .It Bq Er ERANGE If value coercion would overflow (or underflow) the requested type .El .Pp If reading the variable otherwise fails, an appropriate error code will be returned. .\" .Ss "Port/Region Functions" The .Fn bhnd_decode_port_rid function returns 0 on success, or an appropriate error code if no matching port/region is found. .Pp The .Fn bhnd_get_port_rid function returns the resource ID for the requested port and region, or -1 if the port or region are invalid, or do not have an assigned resource ID. .Pp The .Fn bhnd_get_region_addr function returns 0 on success, or an appropriate error code if no matching port/region is found. .\" .Ss "PMU Functions" The .Fn bhnd_alloc_pmu function returns 0 on success, otherwise an appropriate error code is returned. .Pp The .Fn bhnd_release_pmu function returns 0 on success, otherwise an appropriate error code is returned, and the core state will be left unmodified. .Pp The .Fn bhnd_enable_clocks and .Fn bhnd_request_clock functions return 0 on success, or one of the following values on error: .Bl -tag -width Er .It Bq Er ENODEV An unsupported clock was requested. .It Bq Er ENXIO No PMU or PWRCTL provider has been registered with the bus. .El .Pp The .Fn bhnd_get_clock_freq function returns 0 on success, or .Er ENODEV if the frequency for the specified clock is not available. .Pp The .Fn bhnd_get_clock_latency function returns 0 on success, or .Er ENODEV if the transition latency for the specified clock is not available. .Pp The .Fn bhnd_request_ext_rsrc and .Fn bhnd_release_ext_rsrc functions return 0 on success, otherwise an appropriate error code is returned. .Pp .\" .Ss "Service Provider Functions" The .Fn bhnd_register_provider function returns 0 on success, .Er EEXIST if an entry for service already exists, or an appropriate error code if service registration otherwise fails. .Pp The .Fn bhnd_deregister_provider function returns 0 on success, or .Er EBUSY if active references to the service provider exist. .Pp The .Fn bhnd_retain_provider function returns a pointer to .Vt "device_t" on success, a null pointer if the requested provider is not registered. .\" .Ss "Utility Functions" .Pp The .Fn bhnd_format_chip_id function returns the total number of bytes written on success, or a negative integer on failure. .\" .Sh SEE ALSO .Xr bhnd 4 .Xr bhnd_erom 9 .Sh AUTHORS .An -nosplit The .Nm driver programming interface and this manual page were written by .An Landon Fuller Aq Mt landonf@FreeBSD.org . Index: head/share/man/man9/bus_dma.9 =================================================================== --- head/share/man/man9/bus_dma.9 (revision 360602) +++ head/share/man/man9/bus_dma.9 (revision 360603) @@ -1,1277 +1,1277 @@ .\" Copyright (c) 2002, 2003 Hiten M. Pandya. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions, and the following disclaimer, .\" without modification, immediately at the beginning of the file. .\" 2. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR, CONTRIBUTORS OR THE .\" VOICES IN HITEN PANDYA'S HEAD BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED .\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR .\" PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS .\" SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" Copyright (c) 1996, 1997, 1998, 2001 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, .\" NASA Ames Research Center. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $ .\" .Dd April 14, 2020 .Dt BUS_DMA 9 .Os .Sh NAME .Nm bus_dma , .Nm bus_dma_tag_create , .Nm bus_dma_tag_destroy , .Nm bus_dma_template_init , .Nm bus_dma_template_tag , .Nm bus_dma_template_clone , .Nm bus_dmamap_create , .Nm bus_dmamap_destroy , .Nm bus_dmamap_load , .Nm bus_dmamap_load_bio , .Nm bus_dmamap_load_ccb , .Nm bus_dmamap_load_crp , .Nm bus_dmamap_load_mbuf , .Nm bus_dmamap_load_mbuf_sg , .Nm bus_dmamap_load_uio , .Nm bus_dmamap_unload , .Nm bus_dmamap_sync , .Nm bus_dmamem_alloc , .Nm bus_dmamem_free .Nd Bus and Machine Independent DMA Mapping Interface .Sh SYNOPSIS .In machine/bus.h .Ft int .Fn bus_dma_tag_create "bus_dma_tag_t parent" "bus_size_t alignment" \ "bus_addr_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \ "bus_dma_filter_t *filtfunc" "void *filtfuncarg" "bus_size_t maxsize" \ "int nsegments" "bus_size_t maxsegsz" "int flags" "bus_dma_lock_t *lockfunc" \ "void *lockfuncarg" "bus_dma_tag_t *dmat" .Ft int .Fn bus_dma_tag_destroy "bus_dma_tag_t dmat" .Ft void .Fo bus_dma_template_init .Fa "bus_dma_template_t template" .Fa "bus_dma_tag_t parent" .Fc .Ft int .Fo bus_dma_template_tag .Fa "bus_dma_template_t template" .Fa "bus_dma_tag_t *dmat" .Fc .Ft void .Fo bus_dma_template_clone .Fa "bus_dma_template_t template" .Fa "bus_dma_tag_t dmat" .Fc .Ft int .Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp" .Ft int .Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map" .Ft int .Fn bus_dmamap_load "bus_dma_tag_t dmat" "bus_dmamap_t map" "void *buf" \ "bus_size_t buflen" "bus_dmamap_callback_t *callback" "void *callback_arg" \ "int flags" .Ft int .Fn bus_dmamap_load_bio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ "struct bio *bio" "bus_dmamap_callback_t *callback" "void *callback_arg" \ "int flags" .Ft int .Fn bus_dmamap_load_ccb "bus_dma_tag_t dmat" "bus_dmamap_t map" \ "union ccb *ccb" "bus_dmamap_callback_t *callback" "void *callback_arg" \ "int flags" .Ft int .Fn bus_dmamap_load_crp "bus_dma_tag_t dmat" "bus_dmamap_t map" \ "struct crypto *crp" "bus_dmamap_callback_t *callback" "void *callback_arg" \ "int flags" .Ft int .Fn bus_dmamap_load_mbuf "bus_dma_tag_t dmat" "bus_dmamap_t map" \ "struct mbuf *mbuf" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ "int flags" .Ft int .Fn bus_dmamap_load_mbuf_sg "bus_dma_tag_t dmat" "bus_dmamap_t map" \ "struct mbuf *mbuf" "bus_dma_segment_t *segs" "int *nsegs" "int flags" .Ft int .Fn bus_dmamap_load_uio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ "struct uio *uio" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ "int flags" .Ft void .Fn bus_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map" .Ft void .Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \ "op" .Ft int .Fn bus_dmamem_alloc "bus_dma_tag_t dmat" "void **vaddr" \ "int flags" "bus_dmamap_t *mapp" .Ft void .Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \ "bus_dmamap_t map" .Sh DESCRIPTION Direct Memory Access (DMA) is a method of transferring data without involving the CPU, thus providing higher performance. A DMA transaction can be achieved between device to memory, device to device, or memory to memory. .Pp The .Nm API is a bus, device, and machine-independent (MI) interface to DMA mechanisms. It provides the client with flexibility and simplicity by abstracting machine dependent issues like setting up DMA mappings, handling cache issues, bus specific features and limitations. .Sh OVERVIEW A tag structure .Vt ( bus_dma_tag_t ) is used to describe the properties of a group of related DMA transactions. One way to view this is that a tag describes the limitations of a DMA engine. For example, if a DMA engine in a device is limited to 32-bit addresses, that limitation is specified by a parameter when creating the tag for that device. Similarly, a tag can be marked as requiring buffers whose addresses are aligned to a specific boundary. .Pp Some devices may require multiple tags to describe DMA transactions with differing properties. For example, a device might require 16-byte alignment of its descriptor ring while permitting arbitrary alignment of I/O buffers. In this case, the driver must create one tag for the descriptor ring and a separate tag for I/O buffers. If a device has restrictions that are common to all DMA transactions in addition to restrictions that differ between unrelated groups of transactions, the driver can first create a .Dq parent tag that decribes the common restrictions. The per-group tags can then inherit these restrictions from this .Dq parent tag rather than having to list them explicitly when creating the per-group tags. .Pp A mapping structure .Vt ( bus_dmamap_t ) represents a mapping of a memory region for DMA. On systems with I/O MMUs, the mapping structure tracks any I/O MMU entries used by a request. For DMA requests that require bounce pages, the mapping tracks the bounce pages used. .Pp To prepare for one or more DMA transactions, a mapping must be bound to a memory region by calling one of the .Fn bus_dmamap_load functions. These functions configure the mapping which can include programming entries in an I/O MMU and/or allocating bounce pages. An output of these functions (either directly or indirectly by invoking a callback routine) is the list of scatter/gather address ranges a consumer can pass to a DMA engine to access the memory region. When a mapping is no longer needed, the mapping must be unloaded via .Fn bus_dmamap_unload . .Pp Before and after each DMA transaction, .Fn bus_dmamap_sync must be used to ensure that the correct data is used by the DMA engine and the CPU. If a mapping uses bounce pages, the sync operations copy data between the bounce pages and the memory region bound to the mapping. Sync operations also handle architecture-specific details such as CPU cache flushing and CPU memory operation ordering. .Sh STATIC VS DYNAMIC .Nm handles two types of DMA transactions: static and dynamic. Static transactions are used with a long-lived memory region that is reused for many transactions such as a descriptor ring. Dynamic transactions are used for transfers to or from transient buffers such as I/O buffers holding a network packet or disk block. Each transaction type uses a different subset of the .Nm API. .Ss Static Transactions Static transactions use memory regions allocated by .Nm . Each static memory region is allocated by calling .Fn bus_dmamem_alloc . This function requires a valid tag describing the properties of the DMA transactions to this region such as alignment or address restrictions. Multiple regions can share a single tag if they share the same restrictions. .Pp .Fn bus_dmamem_alloc allocates a memory region along with a mapping object. The associated tag, memory region, and mapping object must then be passed to .Fn bus_dmamap_load to bind the mapping to the allocated region and obtain the scatter/gather list. .Pp It is expected that .Fn bus_dmamem_alloc will attempt to allocate memory requiring less expensive sync operations (for example, implementations should not allocate regions requiring bounce pages), but sync operations should still be used. For example, a driver should use .Fn bus_dmamap_sync in an interrupt handler before reading descriptor ring entries written by the device prior to the interrupt. .Pp When a consumer is finished with a memory region, it should unload the mapping via .Fn bus_dmamap_unload and then release the memory region and mapping object via .Fn bus_dmamem_free . .Ss Dynamic Transactions Dynamic transactions map memory regions provided by other parts of the system. A tag must be created via .Fn bus_dma_tag_create to describe the DMA transactions to and from these memory regions, and a pool of mapping objects must be allocated via .Fn bus_dmamap_create to track the mappings of any in-flight transactions. .Pp When a consumer wishes to schedule a transaction for a memory region, the consumer must first obtain an unused mapping object from its pool of mapping objects. The memory region must be bound to the mapping object via one of the .Fn bus_dmamap_load functions. Before scheduling the transaction, the consumer should sync the memory region via .Fn bus_dmamap_sync with one or more of the .Dq PRE flags. After the transaction has completed, the consumer should sync the memory region via .Fn bus_dmamap_sync with one or more of the .Dq POST flags. The mapping can then be unloaded via .Fn bus_dmamap_unload , and the mapping object can be returned to the pool of unused mapping objects. .Pp When a consumer is no longer scheduling DMA transactions, the mapping objects should be freed via .Fn bus_dmamap_destroy , and the tag should be freed via .Fn bus_dma_tag_destroy . .Sh STRUCTURES AND TYPES .Bl -tag -width indent .It Vt bus_dma_tag_t A machine-dependent (MD) opaque type that describes the characteristics of a group of DMA transactions. DMA tags are organized into a hierarchy, with each child tag inheriting the restrictions of its parent. This allows all devices along the path of DMA transactions to contribute to the constraints of those transactions. .It Vt bus_dma_template_t A template structure for creating a .Fa bus_dma_tag_t from a set of defaults. Once initialized with .Fn bus_dma_template_init , a driver can over-ride individual fields to suit its needs. The following fields have the indicated values: .Bd -literal alignment 1 boundary 0 lowaddr BUS_SPACE_MAXADDR highaddr BUS_SPACE_MAXADDR maxsize BUS_SPACE_MAXSIZE nsegments BUS_SPACE_UNRESTRICTED maxsegsize BUS_SPACE_MAXSIZE flags 0 lockfunc NULL lockfuncarg NULL .Ed .Pp Descriptions of each field are documented with .Fn bus_dma_tag_create . Note that the .Fa filtfunc and .Fa filtfuncarg attributes of the DMA tag are not supported with templates. .It Vt bus_dma_filter_t Client specified address filter having the format: .Bl -tag -width indent .It Ft int .Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" .El .Pp Address filters can be specified during tag creation to allow for devices whose DMA address restrictions cannot be specified by a single window. The .Fa filtarg argument is specified by the client during tag creation to be passed to all invocations of the callback. The .Fa testaddr argument contains a potential starting address of a DMA mapping. The filter function operates on the set of addresses from .Fa testaddr to .Ql trunc_page(testaddr) + PAGE_SIZE - 1 , inclusive. The filter function should return zero if any mapping in this range can be accommodated by the device and non-zero otherwise. .It Vt bus_dma_segment_t A machine-dependent type that describes individual DMA segments. It contains the following fields: .Bd -literal bus_addr_t ds_addr; bus_size_t ds_len; .Ed .Pp The .Fa ds_addr field contains the device visible address of the DMA segment, and .Fa ds_len contains the length of the DMA segment. Although the DMA segments returned by a mapping call will adhere to all restrictions necessary for a successful DMA operation, some conversion (e.g.\& a conversion from host byte order to the device's byte order) is almost always required when presenting segment information to the device. .It Vt bus_dmamap_t A machine-dependent opaque type describing an individual mapping. One map is used for each memory allocation that will be loaded. Maps can be reused once they have been unloaded. Multiple maps can be associated with one DMA tag. While the value of the map may evaluate to .Dv NULL on some platforms under certain conditions, it should never be assumed that it will be .Dv NULL in all cases. .It Vt bus_dmamap_callback_t Client specified callback for receiving mapping information resulting from the load of a .Vt bus_dmamap_t via .Fn bus_dmamap_load , .Fn bus_dmamap_load_bio , .Fn bus_dmamap_load_ccb , or .Fn bus_dmamap_load_crp . Callbacks are of the format: .Bl -tag -width indent .It Ft void .Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \ "int nseg" "int error" .El .Pp The .Fa callback_arg is the callback argument passed to dmamap load functions. The .Fa segs and .Fa nseg arguments describe an array of .Vt bus_dma_segment_t structures that represent the mapping. This array is only valid within the scope of the callback function. The success or failure of the mapping is indicated by the .Fa error argument. More information on the use of callbacks can be found in the description of the individual dmamap load functions. .It Vt bus_dmamap_callback2_t Client specified callback for receiving mapping information resulting from the load of a .Vt bus_dmamap_t via .Fn bus_dmamap_load_uio or .Fn bus_dmamap_load_mbuf . .Pp Callback2s are of the format: .Bl -tag -width indent .It Ft void .Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \ "int nseg" "bus_size_t mapsize" "int error" .El .Pp Callback2's behavior is the same as .Vt bus_dmamap_callback_t with the addition that the length of the data mapped is provided via .Fa mapsize . .It Vt bus_dmasync_op_t Memory synchronization operation specifier. Bus DMA requires explicit synchronization of memory with its device visible mapping in order to guarantee memory coherency. The .Vt bus_dmasync_op_t allows the type of DMA operation that will be or has been performed to be communicated to the system so that the correct coherency measures are taken. The operations are represented as bitfield flags that can be combined together, though it only makes sense to combine PRE flags or POST flags, not both. See the .Fn bus_dmamap_sync description below for more details on how to use these operations. .Pp All operations specified below are performed from the host memory point of view, where a read implies data coming from the device to the host memory, and a write implies data going from the host memory to the device. Alternatively, the operations can be thought of in terms of driver operations, where reading a network packet or storage sector corresponds to a read operation in .Nm . .Bl -tag -width ".Dv BUS_DMASYNC_POSTWRITE" .It Dv BUS_DMASYNC_PREREAD Perform any synchronization required prior to an update of host memory by the device. .It Dv BUS_DMASYNC_PREWRITE Perform any synchronization required after an update of host memory by the CPU and prior to device access to host memory. .It Dv BUS_DMASYNC_POSTREAD Perform any synchronization required after an update of host memory by the device and prior to CPU access to host memory. .It Dv BUS_DMASYNC_POSTWRITE Perform any synchronization required after device access to host memory. .El .It Vt bus_dma_lock_t Client specified lock/mutex manipulation method. This will be called from within busdma whenever a client lock needs to be manipulated. In its current form, the function will be called immediately before the callback for a DMA load operation that has been deferred with .Dv BUS_DMA_LOCK and immediately after with .Dv BUS_DMA_UNLOCK . If the load operation does not need to be deferred, then it will not be called since the function loading the map should be holding the appropriate locks. This method is of the format: .Bl -tag -width indent .It Ft void .Fn "lockfunc" "void *lockfunc_arg" "bus_dma_lock_op_t op" .El .Pp The .Fa lockfuncarg argument is specified by the client during tag creation to be passed to all invocations of the callback. The .Fa op argument specifies the lock operation to perform. .Pp Two .Vt lockfunc implementations are provided for convenience. .Fn busdma_lock_mutex performs standard mutex operations on the sleep mutex provided via .Fa lockfuncarg . .Fn dflt_lock will generate a system panic if it is called. It is substituted into the tag when .Fa lockfunc is passed as .Dv NULL to .Fn bus_dma_tag_create and is useful for tags that should not be used with deferred load operations. .It Vt bus_dma_lock_op_t Operations to be performed by the client-specified .Fn lockfunc . .Bl -tag -width ".Dv BUS_DMA_UNLOCK" .It Dv BUS_DMA_LOCK Acquires and/or locks the client locking primitive. .It Dv BUS_DMA_UNLOCK Releases and/or unlocks the client locking primitive. .El .El .Sh FUNCTIONS .Bl -tag -width indent .It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ "highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ "flags" "lockfunc" "lockfuncarg" "*dmat" Allocates a DMA tag, and initializes it according to the arguments provided: .Bl -tag -width ".Fa filtfuncarg" .It Fa parent A parent tag from which to inherit restrictions. The restrictions passed in other arguments can only further tighten the restrictions inherited from the parent tag. .Pp All tags created by a device driver must inherit from the tag returned by .Fn bus_get_dma_tag to honor restrictions between the parent bridge, CPU memory, and the device. .It Fa alignment Alignment constraint, in bytes, of any mappings created using this tag. The alignment must be a power of 2. Hardware that can DMA starting at any address would specify .Em 1 for byte alignment. Hardware requiring DMA transfers to start on a multiple of 4K would specify .Em 4096 . .It Fa boundary Boundary constraint, in bytes, of the target DMA memory region. The boundary indicates the set of addresses, all multiples of the boundary argument, that cannot be crossed by a single .Vt bus_dma_segment_t . The boundary must be a power of 2 and must be no smaller than the maximum segment size. .Ql 0 indicates that there are no boundary restrictions. .It Fa lowaddr , highaddr Bounds of the window of bus address space that .Em cannot be directly accessed by the device. The window contains all addresses greater than .Fa lowaddr and less than or equal to .Fa highaddr . For example, a device incapable of DMA above 4GB, would specify a .Fa highaddr of .Dv BUS_SPACE_MAXADDR and a .Fa lowaddr of .Dv BUS_SPACE_MAXADDR_32BIT . Similarly a device that can only perform DMA to addresses below 16MB would specify a .Fa highaddr of .Dv BUS_SPACE_MAXADDR and a .Fa lowaddr of .Dv BUS_SPACE_MAXADDR_24BIT . Some implementations require that some region of device visible address space, overlapping available host memory, be outside the window. This area of .Ql safe memory is used to bounce requests that would otherwise conflict with the exclusion window. .It Fa filtfunc Optional filter function (may be .Dv NULL ) to be called for any attempt to map memory into the window described by .Fa lowaddr and .Fa highaddr . A filter function is only required when the single window described by .Fa lowaddr and .Fa highaddr cannot adequately describe the constraints of the device. The filter function will be called for every machine page that overlaps the exclusion window. .It Fa filtfuncarg Argument passed to all calls to the filter function for this tag. May be .Dv NULL . .It Fa maxsize Maximum size, in bytes, of the sum of all segment lengths in a given DMA mapping associated with this tag. .It Fa nsegments Number of discontinuities (scatter/gather segments) allowed in a DMA mapped region. .It Fa maxsegsz Maximum size, in bytes, of a segment in any DMA mapped region associated with .Fa dmat . .It Fa flags Are as follows: .Bl -tag -width ".Dv BUS_DMA_ALLOCNOW" .It Dv BUS_DMA_ALLOCNOW Pre-allocate enough resources to handle at least one map load operation on this tag. If sufficient resources are not available, .Er ENOMEM is returned. This should not be used for tags that only describe buffers that will be allocated with .Fn bus_dmamem_alloc . Also, due to resource sharing with other tags, this flag does not guarantee that resources will be allocated or reserved exclusively for this tag. It should be treated only as a minor optimization. .It Dv BUS_DMA_COHERENT Indicate that the DMA engine and CPU are cache-coherent. Cached memory may be used to back allocations created by .Fn bus_dmamem_alloc . For .Fn bus_dma_tag_create , the .Dv BUS_DMA_COHERENT flag is currently implemented on arm64. .El .It Fa lockfunc Optional lock manipulation function (may be .Dv NULL ) to be called when busdma needs to manipulate a lock on behalf of the client. If .Dv NULL is specified, .Fn dflt_lock is used. .It Fa lockfuncarg Optional argument to be passed to the function specified by .Fa lockfunc . .It Fa dmat Pointer to a bus_dma_tag_t where the resulting DMA tag will be stored. .El .Pp Returns .Er ENOMEM if sufficient memory is not available for tag creation or allocating mapping resources. .It Fn bus_dma_tag_destroy "dmat" Deallocate the DMA tag .Fa dmat that was created by .Fn bus_dma_tag_create . .Pp Returns .Er EBUSY if any DMA maps remain associated with .Fa dmat or .Ql 0 on success. .It Fn bus_dma_template_init "*template" "parent" Initializes a .Fa bus_dma_template_t -structure and associates it with an optional +structure and associates it with an optional .Fa parent . The .Fa parent argument may be NULL. .It Fn bus_dma_template_tag "*template" "*dmat" Unpacks a template into a tag, and returns the tag via the .Fa dmat . All return values are identical to .Fn bus_dma_tag_create . .It Fn bus_dma_template_clone "*template" "dmat" Clones the fields from a tag to a template. This is useful for cloning tags when paired with .Fn bus_dma_template_tag . A template that is filled in as a clone does not need to be initialized first. .It Fn bus_dmamap_create "dmat" "flags" "*mapp" Allocates and initializes a DMA map. Arguments are as follows: .Bl -tag -width ".Fa nsegments" .It Fa dmat DMA tag. .It Fa flags Are as follows: .Bl -tag -width ".Dv BUS_DMA_COHERENT" .It Dv BUS_DMA_COHERENT Attempt to map the memory loaded with this map such that cache sync operations are as cheap as possible. This flag is typically set on maps when the memory loaded with these will be accessed by both a CPU and a DMA engine, frequently such as control data and as opposed to streamable data such as receive and transmit buffers. Use of this flag does not remove the requirement of using .Fn bus_dmamap_sync , but it may reduce the cost of performing these operations. .El .It Fa mapp Pointer to a .Vt bus_dmamap_t where the resulting DMA map will be stored. .El .Pp Returns .Er ENOMEM if sufficient memory is not available for creating the map or allocating mapping resources. .It Fn bus_dmamap_destroy "dmat" "map" Frees all resources associated with a given DMA map. Arguments are as follows: .Bl -tag -width ".Fa dmat" .It Fa dmat DMA tag used to allocate .Fa map . .It Fa map The DMA map to destroy. .El .Pp Returns .Er EBUSY if a mapping is still active for .Fa map . .It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" \ "callback_arg" "flags" Creates a mapping in device visible address space of .Fa buflen bytes of .Fa buf , associated with the DMA map .Fa map . This call will always return immediately and will not block for any reason. Arguments are as follows: .Bl -tag -width ".Fa buflen" .It Fa dmat DMA tag used to allocate .Fa map . .It Fa map A DMA map without a currently active mapping. .It Fa buf A kernel virtual address pointer to a contiguous (in KVA) buffer, to be mapped into device visible address space. .It Fa buflen The size of the buffer. .It Fa callback Fa callback_arg The callback function, and its argument. This function is called once sufficient mapping resources are available for the DMA operation. If resources are temporarily unavailable, this function will be deferred until later, but the load operation will still return immediately to the caller. Thus, callers should not assume that the callback will be called before the load returns, and code should be structured appropriately to handle this. See below for specific flags and error codes that control this behavior. .It Fa flags Are as follows: .Bl -tag -width ".Dv BUS_DMA_NOWAIT" .It Dv BUS_DMA_NOWAIT The load should not be deferred in case of insufficient mapping resources, and instead should return immediately with an appropriate error. .It Dv BUS_DMA_NOCACHE The generated transactions to and from the virtual page are non-cacheable. .El .El .Pp Return values to the caller are as follows: .Bl -tag -width ".Er EINPROGRESS" .It 0 The callback has been called and completed. The status of the mapping has been delivered to the callback. .It Er EINPROGRESS The mapping has been deferred for lack of resources. The callback will be called as soon as resources are available. Callbacks are serviced in FIFO order. .Pp Note that subsequent load operations for the same tag that do not require extra resources will still succeed. This may result in out-of-order processing of requests. If the caller requires the order of requests to be preserved, then the caller is required to stall subsequent requests until a pending request's callback is invoked. .It Er ENOMEM The load request has failed due to insufficient resources, and the caller specifically used the .Dv BUS_DMA_NOWAIT flag. .It Er EINVAL The load request was invalid. The callback has been called and has been provided the same error. This error value may indicate that .Fa dmat , .Fa map , .Fa buf , or .Fa callback were invalid, or .Fa buflen was larger than the .Fa maxsize argument used to create the dma tag .Fa dmat . .El .Pp When the callback is called, it is presented with an error value indicating the disposition of the mapping. Error may be one of the following: .Bl -tag -width ".Er EINPROGRESS" .It 0 The mapping was successful and the .Fa dm_segs callback argument contains an array of .Vt bus_dma_segment_t elements describing the mapping. This array is only valid during the scope of the callback function. .It Er EFBIG A mapping could not be achieved within the segment constraints provided in the tag even though the requested allocation size was less than maxsize. .El .It Fn bus_dmamap_load_bio "dmat" "map" "bio" "callback" "callback_arg" "flags" This is a variation of .Fn bus_dmamap_load which maps buffers pointed to by .Fa bio for DMA transfers. .Fa bio may point to either a mapped or unmapped buffer. .It Fn bus_dmamap_load_ccb "dmat" "map" "ccb" "callback" "callback_arg" "flags" This is a variation of .Fn bus_dmamap_load which maps data pointed to by .Fa ccb for DMA transfers. The data for .Fa ccb may be any of the following types: .Bl -tag -width ".Er CAM_DATA_SG_PADDR" .It CAM_DATA_VADDR The data is a single KVA buffer. .It CAM_DATA_PADDR The data is a single bus address range. .It CAM_DATA_SG The data is a scatter/gather list of KVA buffers. .It CAM_DATA_SG_PADDR The data is a scatter/gather list of bus address ranges. .It CAM_DATA_BIO The data is contained in a .Vt struct bio attached to the CCB. .El .Pp .Fn bus_dmamap_load_ccb supports the following CCB XPT function codes: .Pp .Bl -item -offset indent -compact .It XPT_ATA_IO .It XPT_CONT_TARGET_IO .It XPT_SCSI_IO .El .It Fn bus_dmamap_load_crp "dmat" "map" "crp" "callback" "callback_arg" "flags" This is a variation of .Fn bus_dmamap_load which maps buffers pointed to by .Fa crp for DMA transfers. The .Dv BUS_DMA_NOWAIT flag is implied, thus no callback deferral will happen. .It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \ "flags" This is a variation of .Fn bus_dmamap_load which maps mbuf chains for DMA transfers. A .Vt bus_size_t argument is also passed to the callback routine, which contains the mbuf chain's packet header length. The .Dv BUS_DMA_NOWAIT flag is implied, thus no callback deferral will happen. .Pp Mbuf chains are assumed to be in kernel virtual address space. .Pp Beside the error values listed for .Fn bus_dmamap_load , .Er EINVAL will be returned if the size of the mbuf chain exceeds the maximum limit of the DMA tag. .It Fn bus_dmamap_load_mbuf_sg "dmat" "map" "mbuf" "segs" "nsegs" "flags" This is just like .Fn bus_dmamap_load_mbuf except that it returns immediately without calling a callback function. It is provided for efficiency. The scatter/gather segment array .Va segs is provided by the caller and filled in directly by the function. The .Va nsegs argument is returned with the number of segments filled in. Returns the same errors as .Fn bus_dmamap_load_mbuf . .It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags" This is a variation of .Fn bus_dmamap_load which maps buffers pointed to by .Fa uio for DMA transfers. A .Vt bus_size_t argument is also passed to the callback routine, which contains the size of .Fa uio , i.e. .Fa uio->uio_resid . The .Dv BUS_DMA_NOWAIT flag is implied, thus no callback deferral will happen. Returns the same errors as .Fn bus_dmamap_load . .Pp If .Fa uio->uio_segflg is .Dv UIO_USERSPACE , then it is assumed that the buffer, .Fa uio is in .Fa "uio->uio_td->td_proc" Ns 's address space. User space memory must be in-core and wired prior to attempting a map load operation. Pages may be locked using .Xr vslock 9 . .It Fn bus_dmamap_unload "dmat" "map" Unloads a DMA map. Arguments are as follows: .Bl -tag -width ".Fa dmam" .It Fa dmat DMA tag used to allocate .Fa map . .It Fa map The DMA map that is to be unloaded. .El .Pp .Fn bus_dmamap_unload will not perform any implicit synchronization of DMA buffers. This must be done explicitly by a call to .Fn bus_dmamap_sync prior to unloading the map. .It Fn bus_dmamap_sync "dmat" "map" "op" Performs synchronization of a device visible mapping with the CPU visible memory referenced by that mapping. Arguments are as follows: .Bl -tag -width ".Fa dmat" .It Fa dmat DMA tag used to allocate .Fa map . .It Fa map The DMA mapping to be synchronized. .It Fa op Type of synchronization operation to perform. See the definition of .Vt bus_dmasync_op_t for a description of the acceptable values for .Fa op . .El .Pp The .Fn bus_dmamap_sync function is the method used to ensure that CPU's and device's direct memory access (DMA) to shared memory is coherent. For example, the CPU might be used to set up the contents of a buffer that is to be made available to a device. To ensure that the data are visible via the device's mapping of that memory, the buffer must be loaded and a DMA sync operation of .Dv BUS_DMASYNC_PREWRITE must be performed after the CPU has updated the buffer and before the device access is initiated. If the CPU modifies this buffer again later, another .Dv BUS_DMASYNC_PREWRITE sync operation must be performed before an additional device access. Conversely, suppose a device updates memory that is to be read by a CPU. In this case, the buffer must be loaded, and a DMA sync operation of .Dv BUS_DMASYNC_PREREAD must be performed before the device access is initiated. The CPU will only be able to see the results of this memory update once the DMA operation has completed and a .Dv BUS_DMASYNC_POSTREAD sync operation has been performed. .Pp If read and write operations are not preceded and followed by the appropriate synchronization operations, behavior is undefined. .It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "*mapp" Allocates memory that is mapped into KVA at the address returned in .Fa vaddr and that is permanently loaded into the newly created .Vt bus_dmamap_t returned via .Fa mapp . Arguments are as follows: .Bl -tag -width ".Fa alignment" .It Fa dmat DMA tag describing the constraints of the DMA mapping. .It Fa vaddr Pointer to a pointer that will hold the returned KVA mapping of the allocated region. .It Fa flags Flags are defined as follows: .Bl -tag -width ".Dv BUS_DMA_NOWAIT" .It Dv BUS_DMA_WAITOK The routine can safely wait (sleep) for resources. .It Dv BUS_DMA_NOWAIT The routine is not allowed to wait for resources. If resources are not available, .Dv ENOMEM is returned. .It Dv BUS_DMA_COHERENT Attempt to map this memory in a coherent fashion. See .Fn bus_dmamap_create above for a description of this flag. For .Fn bus_dmamem_alloc , the .Dv BUS_DMA_COHERENT flag is currently implemented on arm and arm64. .It Dv BUS_DMA_ZERO Causes the allocated memory to be set to all zeros. .It Dv BUS_DMA_NOCACHE The allocated memory will not be cached in the processor caches. All memory accesses appear on the bus and are executed without reordering. For .Fn bus_dmamem_alloc , the .Dv BUS_DMA_NOCACHE flag is currently implemented on amd64 and i386 where it results in the Strong Uncacheable PAT to be set for the allocated virtual address range. .El .It Fa mapp Pointer to a .Vt bus_dmamap_t where the resulting DMA map will be stored. .El .Pp The size of memory to be allocated is .Fa maxsize as specified in the call to .Fn bus_dma_tag_create for .Fa dmat . .Pp The current implementation of .Fn bus_dmamem_alloc will allocate all requests as a single segment. .Pp An initial load operation is required to obtain the bus address of the allocated memory, and an unload operation is required before freeing the memory, as described below in .Fn bus_dmamem_free . Maps are automatically handled by this function and should not be explicitly allocated or destroyed. .Pp Although an explicit load is not required for each access to the memory referenced by the returned map, the synchronization requirements as described in the .Fn bus_dmamap_sync section still apply and should be used to achieve portability on architectures without coherent buses. .Pp Returns .Er ENOMEM if sufficient memory is not available for completing the operation. .It Fn bus_dmamem_free "dmat" "*vaddr" "map" Frees memory previously allocated by .Fn bus_dmamem_alloc . Any mappings will be invalidated. Arguments are as follows: .Bl -tag -width ".Fa vaddr" .It Fa dmat DMA tag. .It Fa vaddr Kernel virtual address of the memory. .It Fa map DMA map to be invalidated. .El .El .Sh RETURN VALUES Behavior is undefined if invalid arguments are passed to any of the above functions. If sufficient resources cannot be allocated for a given transaction, .Er ENOMEM is returned. All routines that are not of type .Vt void will return 0 on success or an error code on failure as discussed above. .Pp All .Vt void routines will succeed if provided with valid arguments. .Sh LOCKING Two locking protocols are used by .Nm . The first is a private global lock that is used to synchronize access to the bounce buffer pool on the architectures that make use of them. This lock is strictly a leaf lock that is only used internally to .Nm and is not exposed to clients of the API. .Pp The second protocol involves protecting various resources stored in the tag. Since almost all .Nm operations are done through requests from the driver that created the tag, the most efficient way to protect the tag resources is through the lock that the driver uses. In cases where .Nm acts on its own without being called by the driver, the lock primitive specified in the tag is acquired and released automatically. An example of this is when the .Fn bus_dmamap_load callback function is called from a deferred context instead of the driver context. This means that certain .Nm functions must always be called with the same lock held that is specified in the tag. These functions include: .Pp .Bl -item -offset indent -compact .It .Fn bus_dmamap_load .It .Fn bus_dmamap_load_bio .It .Fn bus_dmamap_load_ccb .It .Fn bus_dmamap_load_mbuf .It .Fn bus_dmamap_load_mbuf_sg .It .Fn bus_dmamap_load_uio .It .Fn bus_dmamap_unload .It .Fn bus_dmamap_sync .El .Pp There is one exception to this rule. It is common practice to call some of these functions during driver start-up without any locks held. So long as there is a guarantee of no possible concurrent use of the tag by different threads during this operation, it is safe to not hold a lock for these functions. .Pp Certain .Nm operations should not be called with the driver lock held, either because they are already protected by an internal lock, or because they might sleep due to memory or resource allocation. The following functions must not be called with any non-sleepable locks held: .Pp .Bl -item -offset indent -compact .It .Fn bus_dma_tag_create .It .Fn bus_dmamap_create .It .Fn bus_dmamem_alloc .El .Pp All other functions do not have a locking protocol and can thus be called with or without any system or driver locks held. .Sh SEE ALSO .Xr devclass 9 , .Xr device 9 , .Xr driver 9 , .Xr rman 9 , .Xr vslock 9 .Pp .Rs .%A "Jason R. Thorpe" .%T "A Machine-Independent DMA Framework for NetBSD" .%J "Proceedings of the Summer 1998 USENIX Technical Conference" .%Q "USENIX Association" .%D "June 1998" .Re .Sh HISTORY The .Nm interface first appeared in .Nx 1.3 . .Pp The .Nm API was adopted from .Nx for use in the CAM SCSI subsystem. The alterations to the original API were aimed to remove the need for a .Vt bus_dma_segment_t array stored in each .Vt bus_dmamap_t while allowing callers to queue up on scarce resources. .Sh AUTHORS The .Nm interface was designed and implemented by .An Jason R. Thorpe of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. Additional input on the .Nm design was provided by .An -nosplit .An Chris Demetriou , .An Charles Hannum , .An Ross Harvey , .An Matthew Jacob , .An Jonathan Stone , and .An Matt Thomas . .Pp The .Nm interface in .Fx benefits from the contributions of .An Justin T. Gibbs , .An Peter Wemm , .An Doug Rabson , .An Matthew N. Dodd , .An Sam Leffler , .An Maxime Henrion , .An Jake Burkholder , .An Takahashi Yoshihiro , .An Scott Long and many others. .Pp This manual page was written by .An Hiten M. Pandya and .An Justin T. Gibbs . Index: head/share/man/man9/dpcpu.9 =================================================================== --- head/share/man/man9/dpcpu.9 (revision 360602) +++ head/share/man/man9/dpcpu.9 (revision 360603) @@ -1,165 +1,165 @@ .\"- .\" Copyright (c) 2017 Robert N. M. Watson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 5, 2018 .Dt DPCPU 9 .Os .Sh NAME .Nm dpcpu .Nd Kernel Dynamic Per-CPU Memory Allocator .Sh SYNOPSIS .In sys/pcpu.h .Ss Per-CPU Variable Definition and Declaration .Fn DPCPU_DEFINE "type" "name" .Fn DPCPU_DEFINE_STATIC "type" "name" .Fn DPCPU_DECLARE "type" "name" .Ss Current CPU Accessor Functions .Fn DPCPU_PTR "name" .Fn DPCPU_GET "name" .Fn DPCPU_SET "name" "value" .Ss Named CPU Accessor Functions .Fn DPCPU_ID_PTR "cpu" "name" .Fn DPCPU_ID_GET "cpu" "name" .Fn DPCPU_ID_SET "cpu" "name" "value" .Sh DESCRIPTION .Nm instantiates one instance of a global variable with each CPU in the system. Dynamically allocated per-CPU variables are defined using .Fn DPCPU_DEFINE , which defines a variable of name .Ar name and type .Ar type . Arbitrary C types may be used, including structures and arrays. If no initialization is provided, then each per-CPU instance of the variable will be zero-filled (i.e., as though allocated in BSS): .Bd -literal -offset 1234 DPCPU_DEFINE(int, foo_int); .Ed .Pp Values may also be initialized statically with the definition, causing each per-CPU instance to be initialized with the value: .Bd -literal -offset 1234 DPCPU_DEFINE(int, foo_int) = 1; .Ed .Pp Values that can be defined as .Dv static must use .Fn DPCPU_DEFINE_STATIC : .Bd -literal -offset 1234 DPCPU_DEFINE_STATIC(int, foo_int); .Ed .Pp .Fn DPCPU_DECLARE produces a declaration of the per-CPU variable suitable for use in header files. .Pp The current CPU's variable instance can be accessed via .Nm DPCPU_PTR (which returns a pointer to the per-CPU instance), .Nm DPCPU_GET (which retrieves the value of the per-CPU instance), and .Nm DPCPU_SET (which sets the value of the per-CPU instance). .Pp Instances of variables associated with specific CPUs can be accessed via the .Nm DPCPU_ID_PTR , .Nm DPCPU_ID_GET , and .Nm DPGPU_ID_SET accessor functions, which accept an additional CPU ID argument, .Ar cpu . .Ss Synchronization In addition to the ordinary synchronization concerns associated with global variables, which may imply the use of .Xr atomic 9 , .Xr mutex 9 , or other kernel synchronization primitives, it is further the case that thread migration could dynamically change the instance of a variable being accessed by a thread between operations. This requires additional care when reasoning about and protecting per-CPU variables. .Pp For example, it may be desirable to protect access using .Xr critical_section 9 to prevent both preemption and migration during use. Alternatively, it may be desirable to cache the CPU ID at the start of a sequence of accesses, using suitable synchronization to make non-atomic sequences safe in the presence of migration. .Bd -literal -offset 1234 DPCPU_DEFINE_STATIC(int, foo_int); DPCPU_DEFINE_STATIC(struct mutex, foo_lock); void foo_int_increment(void) { int cpu, value; /* Safe as atomic access. */ atomic_add_int(DPCPU_PTR(foo_int), 1); /* * Protect with a critical section, which prevents preemption * and migration. However, access to instances from remote CPUs * is not safe, as critical sections prevent concurrent access * only from the current CPU. */ critical_enter(); value = DPCPU_GET(foo_int); value++; DPCPU_SET(foo_int, value); critical_exit(); /* * Protect with a per-CPU mutex, tolerating migration, but * potentially accessing the variable from multiple CPUs if * migration occurs after reading curcpu. Remote access to a * per-CPU variable is safe as long as the correct mutex is * acquired. */ cpu = curcpu; mtx_lock(DPCPU_ID_PTR(cpu, foo_lock)); value = DPCPU_ID_GET(cpu, foo_int); value++; DPCPU_ID_SET(cpu, foo_int); mtx_unlock(DPCPU_ID_PTR(cpu, foo_lock)); } .Ed .Sh SEE ALSO .Xr atomic 9 , .Xr critical_enter 9 , .Xr mutex 9 .Sh HISTORY .Nm was first introduced by .An Jeff Roberson in .Fx 8.0 . This manual page was written by -.An Robert N. M. Watson. +.An Robert N. M. Watson . Index: head/share/man/man9/getenv.9 =================================================================== --- head/share/man/man9/getenv.9 (revision 360602) +++ head/share/man/man9/getenv.9 (revision 360603) @@ -1,222 +1,222 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2013 Hudson River Trading LLC .\" Written by: John H. Baldwin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 1, 2017 .Dt GETENV 9 .Os .Sh NAME .Nm freeenv , .Nm kern_getenv , .Nm getenv_int , .Nm getenv_long , .Nm getenv_string , .Nm getenv_quad , .Nm getenv_uint , .Nm getenv_ulong , .Nm kern_setenv , .Nm testenv , .Nm kern_unsetenv .Nd kernel environment variable functions .Sh SYNOPSIS .In sys/param.h .In sys/systm.h .Ft void .Fn freeenv "char *env" .Ft char * .Fn kern_getenv "const char *name" .Ft int .Fn getenv_int "const char *name" "int *data" .Ft int .Fn getenv_long "const char *name" "long *data" .Ft int .Fn getenv_string "const char *name" "char *data" "int size" .Ft int .Fn getenv_quad "const char *name" "quad_t *data" .Ft int .Fn getenv_uint "const char *name" "unsigned int *data" .Ft int .Fn getenv_ulong "const char *name" "unsigned long *data" .Ft int .Fn kern_setenv "const char *name" "const char *value" .Ft int .Fn testenv "const char *name" .Ft int .Fn kern_unsetenv "const char *name" .Sh DESCRIPTION These functions set, unset, fetch, and parse variables from the kernel's environment. .Pp The .Fn kern_getenv function obtains the current value of the kernel environment variable .Fa name and returns a pointer to the string value. The caller should not modify the string pointed to by the return value. The .Fn kern_getenv function may allocate temporary storage, so the .Fn freeenv function must be called to release any allocated resources when the value returned by .Fn kern_getenv is no longer needed. .Pp The .Fn freeenv function is used to release the resources allocated by a previous call to .Fn kern_getenv . The .Fa env argument passed to .Fn freeenv is the pointer returned by the earlier call to .Fn kern_getenv . Like .Xr free 3 , the .Fa env argument can be .Va NULL , in which case no action occurs. .Pp The .Fn kern_setenv function inserts or resets the kernel environment variable .Fa name to .Fa value . If the variable .Fa name already exists, its value is replaced. This function can fail if an internal limit on the number of environment variables is exceeded. .Pp The .Fn kern_unsetenv function deletes the kernel environment variable .Fa name . .Pp The .Fn testenv function is used to determine if a kernel environment variable exists. It returns a non-zero value if the variable .Fa name exists and zero if it does not. .Pp The .Fn getenv_int , .Fn getenv_long , .Fn getenv_quad , .Fn getenv_uint , and .Fn getenv_ulong functions look for a kernel environment variable .Fa name and parse it as a signed integer, long integer, signed 64-bit integer, unsigned integer, or an unsigned long integer, respectively. These functions fail and return zero if .Fa name does not exist or if any invalid characters are present in its value. On success, these function store the parsed value in the integer variable pointed to by .Fa data . If the parsed value overflows the integer type, a truncated value is stored in .Fa data and zero is returned. If the value begins with a prefix of .Dq 0x it is interpreted as hexadecimal. If it begins with a prefix of .Dq 0 it is interpreted as octal. Otherwise, the value is interpreted as decimal. The value may contain a single character suffix specifying a unit for the value. The interpreted value is multiplied by the unit's magnitude before being returned. The following unit suffixes are supported: .Bl -column -offset indent ".Sy Unit" ".Sy Magnitude" .It Sy Unit Ta Sy Magnitude .It k Ta 2^10 .It m Ta 2^20 .It g Ta 2^30 .It t Ta 2^40 .El .Pp The .Fn getenv_string function stores a copy of the kernel environment variable .Fa name in the buffer described by .Fa data and -.Fa size. +.Fa size . If the variable does not exist, zero is returned. If the variable exists, up to .Fa size - 1 characters of its value are copied to the buffer pointed to by .Fa data followed by a null character and a non-zero value is returned. .Sh RETURN VALUES The .Fn kern_getenv function returns a pointer to an environment variable's value on success or .Dv NULL if the variable does not exist. .Pp The .Fn kern_setenv and .Fn kern_unsetenv functions return zero on success and -1 on failure. .Pp The .Fn testenv function returns zero if the specified environment variable does not exist and a non-zero value if it does exist. The .Fn getenv_int , .Fn getenv_long , .Fn getenv_string , .Fn getenv_quad , .Fn getenv_uint , and .Fn getenv_ulong functions return a non-zero value on success and zero on failure. Index: head/share/man/man9/iflib.9 =================================================================== --- head/share/man/man9/iflib.9 (revision 360602) +++ head/share/man/man9/iflib.9 (revision 360603) @@ -1,42 +1,42 @@ .\" $FreeBSD$ .Dd September 20, 2018 .Dt IFLIB 9 .Os .Sh NAME .Nm iflib .Nd Network Interface Driver Framework .Sh DESCRIPTION .Nm -is a framework for writing network interface drivers for FreeBSD. +is a framework for writing network interface drivers for +.Fx . It is designed to remove a large amount of the boilerplate that is often needed for modern network interface devices, allowing driver authors to focus on the specific code needed for their hardware. .Pp There are three logical components to .Nm each of which is described in its own manual page. These are: .Bl -tag -width ".Xr iflibtxrx 9" .It Xr iflibdi 9 Device-independent functions, used to integrate .Nm into the rest of the .Fx networking stack. .It Xr iflibdd 9 Device-dependent functions, used when writing new .Nm based drivers. .It Xr iflibtxrx 9 Device-dependent transmit and receive functions, used when writing new .Nm based drivers. .Sh SEE ALSO .Xr iflib 4 , .Xr iflibdd 9 , .Xr iflibdi 9 , .Xr iflibtxrx 9 , .Xr ifnet 9 .Sh AUTHORS .An Benno Rice Aq Mt benno@FreeBSD.org - Index: head/share/man/man9/kern_testfrwk.9 =================================================================== --- head/share/man/man9/kern_testfrwk.9 (revision 360602) +++ head/share/man/man9/kern_testfrwk.9 (revision 360603) @@ -1,193 +1,195 @@ .\" .\" Copyright (c) 2015 Netflix, Inc. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd November 12, 2015 .Dt KERN_TESTFRWK 9 .Os .Sh NAME .Nm kern_testfrwk .Nd A kernel testing framework .Sh SYNOPSIS kld_load kern_testfrwk .Sh DESCRIPTION .\" This whole section is not written in manual page style and should be ripped .\" out and replaced. -CEM So what is this sys/tests directory in the kernel all about? .Pp -Have you ever wanted to test a part of the FreeBSD kernel in some way and you +Have you ever wanted to test a part of the +.Fx +kernel in some way and you had no real way from user-land to make what you want to occur happen? Say an error path or situation where locking occurs in a particular manner that happens only once in a blue moon? .Pp If so, then the kernel test framework is just what you are looking for. It is designed to help you create the situation you want. .Pp There are two components to the system: the test framework and your test. This document will describe both components and use the test submitted with the initial commit of this code to discuss the test .Xr ( callout_test 4 ) . All of the tests become kernel loadable modules. The test you write should have a dependency on the test framework. That way it will be loaded automatically with your test. For example, you can see how to do this in the bottom of callout_test.c in .Pa sys/tests/callout_test/callout_test.c . .Pp The framework itself is in .Pa sys/tests/framework/kern_testfrwk.c . Its job is to manage the tests that are loaded. (More than one can be loaded.) The idea is pretty simple; you load the test framework and then load your test. .Pp When your test loads, you register your tests with the kernel test framework. You do that through a call to .Fn kern_testframework_register . Usually this is done at the module load event as shown below: .Bd -literal -offset indent switch (type) { case MOD_LOAD: err = kern_testframework_register("callout_test", run_callout_test); .Ed .Pp Here the test is "callout_test" and it is registered to run the function .Fn run_callout_test passing it a .Fa struct kern_test *ptr . The .Vt kern_test structure is defined in .Pa kern_testfrwk.h . .Bd -literal -offset indent struct kern_test { char name[TEST_NAME_LEN]; int num_threads; /* Fill in how many threads you want */ int tot_threads_running; /* Private to framework */ uint8_t test_options[TEST_OPTION_SPACE]; }; .Ed .Pp The user sends this structure down via a sysctl to start your test. He or she places the same name you registered ("callout_test" in our example) in the .Va name field. The user can also set the number of threads to run with .Va num_threads . .Pp The framework will start the requested number of kernel threads, all running your test at the same time. The user does not specify anything in .Va tot_threads_running ; it is private to the framework. As the framework calls each of your tests, it will set the .Va tot_threads_running to the index of the thread that your call is made from. For example, if the user sets .Va num_threads to 2, then the function .Fn run_callout_test will be called once with .Va tot_threads_running to 0, and a second time with .Va tot_threads_running set to 1. .Pp The .Va test_options field is a test-specific set of information that is an opaque blob. It is passed in from user space and has a maximum size of 256 bytes. You can pass arbitrary test input in the space. In the case of callout_test we reshape that to: .Bd -literal -offset indent struct callout_test { int number_of_callouts; int test_number; }; .Ed .Pp So the first lines of .Fn run_callout_test does the following to get at the user specific data: .\" This is a bad example and violates strict aliasing. It should be replaced. .Bd -literal -offset indent struct callout_test *u; size_t sz; int i; struct callout_run *rn; int index = test->tot_threads_running; u = (struct callout_test *)test->test_options; .Ed .Pp That way it can access: .Va u->test_number (there are two types of tests provided with this test) and .Va u->number_of_callouts (how many simultaneous callouts to run). .Pp Your test can do anything with these bytes. So the callout_test in question wants to create a situation where multiple callouts are all run, that is the .Va number_of_callouts , and it tries to cancel the callout with the new .Fn callout_async_drain . The threads do this by acquiring the lock in question, and then starting each of the callouts. It waits for the callouts to all go off (the executor spins waits). This forces the situation that the callouts have expired and are all waiting on the lock that the executor holds. After the callouts are all blocked, the executor calls .Fn callout_async_drain on each callout and releases the lock. .Pp .\" callout_test(4) specific documentation should probably be moved to its own .\" page. After all the callouts are done, a total status is printed showing the results via .Xr printf 9 . The human tester can run .Xr dmesg 8 to see the results. In this case it is expected that if you are running test 0, all the callouts expire on the same CPU so only one callout_drain function would have been called. the number of zero_returns should match the number of callout_drains that were called, i.e., 1. The one_returns should be the remainder of the callouts. If the test number was 1, the callouts were spread across all CPUs. The number of zero_returns will again match the number of drain calls made which matches the number of CPUs that were put in use. .Pp More than one thread can be used with this test, though in the example case it is probably not necessary. .Pp You should not need to change the framework. Just add tests and register them after loading. .Sh AUTHORS The kernel test framework was written by .An Randall Stewart Aq Mt rrs@FreeBSD.org with help from .An John Mark Gurney Aq Mt jmg@FreeBSD.org . Index: head/share/man/man9/ofw_graph.9 =================================================================== --- head/share/man/man9/ofw_graph.9 (revision 360602) +++ head/share/man/man9/ofw_graph.9 (revision 360603) @@ -1,106 +1,108 @@ .\" Copyright (c) 2019 Emmanuel Vadot .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 10, 2019 .Dt ofw_graph 9 .Os .Sh NAME .Nm ofw_graph , .Nm ofw_graph_get_port_by_idx , .Nm ofw_graph_port_get_num_endpoints , .Nm ofw_graph_get_endpoint_by_idx , .Nm ofw_graph_get_remote_endpoint , .Nm ofw_graph_get_remote_parent , .Nm ofw_graph_get_device_by_port_ep , .Nd Helpers for the graph bindings .Sh SYNOPSIS .In dev/ofw/openfirm.h .In dev/ofw/ofw_graph.h .Ft phandle_t .Fn ofw_graph_get_port_by_idx "phandle_t node" "uint32_t idx" .Ft size_t .Fn ofw_graph_port_get_num_endpoints "phandle_t port" .Ft phandle_t .Fn ofw_graph_get_endpoint_by_idx "phandle_t port" "uint32_t idx" .Ft phandle_t .Fn ofw_graph_get_remote_endpoint "phandle_t endpoint" .Ft phandle_t .Fn ofw_graph_get_remote_parent "phandle_t remote" .Ft device_t .Fn ofw_graph_get_device_by_port_ep "phandle_t node" "uint32_t port_id" "uin32_t ep_id" .Sh DESCRIPTION .Pp The ofw_graph functions are helpers to parse the DTS graph bindings .Pp .Fn ofw_graph_get_port_by_idx return the port with id .Fa idx . It will first check node named .Fa port@idx and then fallback on checking the .Fa ports -child for a child node matching the id. If no ports matching +child for a child node matching the id. +If no ports matching .Fa idx is found the function return 0. .Pp .Fn ofw_graph_port_get_num_endpoints returns the number of endpoints a port node have. .Pp .Fn ofw_graph_get_endpoint_by_idx return the endpoint with id .Fa idx . It will first check if there is a single child named .Fa endpoint -and returns it if there is. If there is multiple endpoints it will check -the +and returns it if there is. +If there is multiple endpoints it will check the .Fa reg property and returns the correct .Fa phandle_t or 0 if none match. .Pp .Fn ofw_graph_get_remote_endpoint returns the .Fa remote-endpoint property if it exists or 0. .Pp .Fn ofw_graph_get_remote_parent returns the device node corresponding to the .Fa remote-endpoint phandle or 0 if none. .Fn ofw_graph_get_device_by_port_ep returns the device associated with the port and endpoint or .Fa NULL -if none. The device driver should have called +if none. +The device driver should have called .Fn OF_device_register_xref before. -.Fn +.Fn .Sh HISTORY The .Nm ofw_graph functions first appeared in .Fx 13.0 . The .Nm ofw_graph functions and manual page were written by .An Emmanuel Vadot Aq Mt manu@FreeBSD.org .