1*9da20b8aSRobert Mustacchi.\" 2*9da20b8aSRobert Mustacchi.\" This file and its contents are supplied under the terms of the 3*9da20b8aSRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 4*9da20b8aSRobert Mustacchi.\" You may only use this file in accordance with the terms of version 5*9da20b8aSRobert Mustacchi.\" 1.0 of the CDDL. 6*9da20b8aSRobert Mustacchi.\" 7*9da20b8aSRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 8*9da20b8aSRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 9*9da20b8aSRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 10*9da20b8aSRobert Mustacchi.\" 11*9da20b8aSRobert Mustacchi.\" 12*9da20b8aSRobert Mustacchi.\" Copyright 2023 Oxide Computer Company 13*9da20b8aSRobert Mustacchi.\" 14*9da20b8aSRobert Mustacchi.Dd January 26, 2023 15*9da20b8aSRobert Mustacchi.Dt INTRO 9F 16*9da20b8aSRobert Mustacchi.Os 17*9da20b8aSRobert Mustacchi.Sh NAME 18*9da20b8aSRobert Mustacchi.Nm Intro 19*9da20b8aSRobert Mustacchi.Nd Introduction to kernel and device driver functions 20*9da20b8aSRobert Mustacchi.Sh SYNOPSIS 21*9da20b8aSRobert Mustacchi.In sys/ddi.h 22*9da20b8aSRobert Mustacchi.In sys/sunddi.h 23*9da20b8aSRobert Mustacchi.Sh DESCRIPTION 24*9da20b8aSRobert MustacchiSection 9F of the manual page describes functions that are used for device 25*9da20b8aSRobert Mustacchidrivers, kernel modules, and the implementation of the kernel itself. 26*9da20b8aSRobert MustacchiThis first provides an overview for the use of kernel functions and portions of 27*9da20b8aSRobert Mustacchithe manual that are specific to the kernel. 28*9da20b8aSRobert MustacchiAfter that, we have grouped together most functions that are available by use, 29*9da20b8aSRobert Mustacchiwith some brief commentary and introduction. 30*9da20b8aSRobert Mustacchi.Pp 31*9da20b8aSRobert MustacchiMost manual pages are similar to those in other sections. 32*9da20b8aSRobert MustacchiThey have common fields such as the NAME, a SYNOPSIS to show which header files 33*9da20b8aSRobert Mustacchito include and prototypes, an extended DESCRIPTION discussing its use, and the 34*9da20b8aSRobert Mustacchicommon combination of RETURN VALUES and ERRORS. 35*9da20b8aSRobert MustacchiSome manuals will have examples and additional manuals to reference in the SEE 36*9da20b8aSRobert MustacchiALSO section. 37*9da20b8aSRobert Mustacchi.Ss RETURN VALUES and ERRORS 38*9da20b8aSRobert MustacchiOne major difference when programming in the kernel versus userland is that 39*9da20b8aSRobert Mustacchithere is no equivalent to 40*9da20b8aSRobert Mustacchi.Va errno . 41*9da20b8aSRobert MustacchiInstead, there are a few common patterns that are used throughout the kernel 42*9da20b8aSRobert Mustacchithat we'll discuss. 43*9da20b8aSRobert MustacchiWhile there are common patterns, please be aware that due to the natural 44*9da20b8aSRobert Mustacchievolution of the system, you will need to read the specifics of the 45*9da20b8aSRobert Mustacchisection. 46*9da20b8aSRobert Mustacchi.Bl -bullet 47*9da20b8aSRobert Mustacchi.It 48*9da20b8aSRobert MustacchiMany functions will return a specific DDI 49*9da20b8aSRobert Mustacchi.Pq Device Driver Interface 50*9da20b8aSRobert Mustacchivalue, which is commonly one of 51*9da20b8aSRobert Mustacchi.Dv DDI_SUCCESS 52*9da20b8aSRobert Mustacchior 53*9da20b8aSRobert Mustacchi.Dv DDI_FAILURE , 54*9da20b8aSRobert Mustacchiindicating success and failure respectively. 55*9da20b8aSRobert MustacchiSome functions will return additional error codes to indicate why something 56*9da20b8aSRobert Mustacchifailed. 57*9da20b8aSRobert MustacchiIn general, when checking a response code is always preferred to compare that 58*9da20b8aSRobert Mustacchisomething equals or does not equal 59*9da20b8aSRobert Mustacchi.Dv DDI_SUCCESS 60*9da20b8aSRobert Mustacchias there can be many different error cases and additional ones can be added over 61*9da20b8aSRobert Mustacchitime. 62*9da20b8aSRobert Mustacchi.It 63*9da20b8aSRobert MustacchiMany routines explicitly return 64*9da20b8aSRobert Mustacchi.Sy 0 65*9da20b8aSRobert Mustacchion success and will return an explicit error number. 66*9da20b8aSRobert Mustacchi.Xr Intro 2 67*9da20b8aSRobert Mustacchihas a list of error numbers. 68*9da20b8aSRobert Mustacchi.It 69*9da20b8aSRobert MustacchiThere are classes of functions that return either a pointer or a boolean type, 70*9da20b8aSRobert Mustacchieither the C99 71*9da20b8aSRobert Mustacchi.Vt bool 72*9da20b8aSRobert Mustacchior the system's traditional type 73*9da20b8aSRobert Mustacchi.Vt boolean_t . 74*9da20b8aSRobert MustacchiIn these cases, sometimes a more detailed error is provided via an additional 75*9da20b8aSRobert Mustacchiargument such as a 76*9da20b8aSRobert Mustacchi.Vt "int *" . 77*9da20b8aSRobert MustacchiAbsent such an argument, there is generally no more detailed information 78*9da20b8aSRobert Mustacchiavailable. 79*9da20b8aSRobert Mustacchi.El 80*9da20b8aSRobert Mustacchi.Ss CONTEXT 81*9da20b8aSRobert MustacchiThe CONTEXT section of a manual page describes the times in which this function 82*9da20b8aSRobert Mustacchimay be called. 83*9da20b8aSRobert MustacchiIn generally there are three different contexts that come up: 84*9da20b8aSRobert Mustacchi.Bl -tag -width Ds 85*9da20b8aSRobert Mustacchi.It Sy User 86*9da20b8aSRobert MustacchiUser context implies that the thread of execution is operating because a user 87*9da20b8aSRobert Mustacchithread has entered the kernel for an operation. 88*9da20b8aSRobert MustacchiWhen an application issues a system call such as 89*9da20b8aSRobert Mustacchi.Xr open 2 , 90*9da20b8aSRobert Mustacchi.Xr read 2 , 91*9da20b8aSRobert Mustacchi.Xr write 2 , 92*9da20b8aSRobert Mustacchior 93*9da20b8aSRobert Mustacchi.Xr ioctl 2 94*9da20b8aSRobert Mustacchithen we are said to be in user context. 95*9da20b8aSRobert MustacchiWhen in user context, one can copy in or out data from a user's address space. 96*9da20b8aSRobert MustacchiWhen writing a character or block device driver, the majority of the time that a 97*9da20b8aSRobert Mustacchicharacter device operation such as the corresponding 98*9da20b8aSRobert Mustacchi.Xr open 9E , 99*9da20b8aSRobert Mustacchi.Xr read 9E , 100*9da20b8aSRobert Mustacchi.Xr write 9E , 101*9da20b8aSRobert Mustacchiand 102*9da20b8aSRobert Mustacchi.Xr ioctl 9E 103*9da20b8aSRobert Mustacchientry point being called, it is executing in user context. 104*9da20b8aSRobert MustacchiIt is possible to call those entry points through the kernel's layered device 105*9da20b8aSRobert Mustacchiinterface, so drivers cannot assume those entry points will always have a user 106*9da20b8aSRobert Mustacchiprocess present, strictly speaking. 107*9da20b8aSRobert Mustacchi.It Sy Interrupt 108*9da20b8aSRobert MustacchiInterrupt context refers to when the operating system is handling an interrupt 109*9da20b8aSRobert Mustacchi.Po 110*9da20b8aSRobert MustacchiSee 111*9da20b8aSRobert Mustacchi.Sx Interrupt Related Functions 112*9da20b8aSRobert Mustacchi.Pc 113*9da20b8aSRobert Mustacchiand executing a registered interrupt handler. 114*9da20b8aSRobert MustacchiInterrupt context is split into two different sets: high-level and low-level 115*9da20b8aSRobert Mustacchiinterrupts. 116*9da20b8aSRobert MustacchiMost device drivers are always going to be executing low-level interrupts. 117*9da20b8aSRobert MustacchiTo determine whether an interrupt is considered high level or not, you should 118*9da20b8aSRobert Mustacchipass the interrupt handle to the 119*9da20b8aSRobert Mustacchi.Xr ddi_intr_get_pri 9F 120*9da20b8aSRobert Mustacchifunction and compare the resulting priority with 121*9da20b8aSRobert Mustacchi.Xr ddi_intr_get_hilevel_pri 9F . 122*9da20b8aSRobert Mustacchi.Pp 123*9da20b8aSRobert MustacchiWhen executing high-level interrupts, the thread may only execute a limited 124*9da20b8aSRobert Mustacchinumber of functions. 125*9da20b8aSRobert MustacchiIn particular, it may call 126*9da20b8aSRobert Mustacchi.Xr ddi_intr_trigger_softint 9F , 127*9da20b8aSRobert Mustacchi.Xr mutex_enter 9F , 128*9da20b8aSRobert Mustacchiand 129*9da20b8aSRobert Mustacchi.Xr mutex_exit 9F . 130*9da20b8aSRobert MustacchiIt is critical that the mutex being used be properly initialized with the 131*9da20b8aSRobert Mustacchidriver's interrupt priority. 132*9da20b8aSRobert MustacchiThe system will transparently pick the correct implementation of a mutex based 133*9da20b8aSRobert Mustacchion the interrupt type. 134*9da20b8aSRobert MustacchiAside from the above, one must not block while in high-level interrupt context. 135*9da20b8aSRobert Mustacchi.Pp 136*9da20b8aSRobert MustacchiOn the other hand, when a thread is not in high-level interrupt context, most of 137*9da20b8aSRobert Mustacchithese restrictions are lifted. 138*9da20b8aSRobert MustacchiKernel memory may be allocated 139*9da20b8aSRobert Mustacchi.Po 140*9da20b8aSRobert Mustacchiif using a non-blocking allocation such as 141*9da20b8aSRobert Mustacchi.Dv KM_NOSLEEP 142*9da20b8aSRobert Mustacchior 143*9da20b8aSRobert Mustacchi.Dv KM_NOSLEEP_LAZY 144*9da20b8aSRobert Mustacchi.Pc , 145*9da20b8aSRobert Mustacchiand many of the other documented functions may be called. 146*9da20b8aSRobert Mustacchi.Pp 147*9da20b8aSRobert MustacchiRegardless of whether a thread is in high-level or low-level interrupt context, 148*9da20b8aSRobert Mustacchiit will never have a user context associated with it and therefore cannot use 149*9da20b8aSRobert Mustacchiroutines like 150*9da20b8aSRobert Mustacchi.Xr ddi_copyin 9F 151*9da20b8aSRobert Mustacchior 152*9da20b8aSRobert Mustacchi.Xr ddi_copyout 9F . 153*9da20b8aSRobert Mustacchi.It Sy Kernel 154*9da20b8aSRobert MustacchiKernel context refers to all other times in the kernel. 155*9da20b8aSRobert MustacchiWhenever the kernel is executing something on a thread that is not associated 156*9da20b8aSRobert Mustacchiwith a user process, then one is in kernel context. 157*9da20b8aSRobert MustacchiThe most common situation for writers of kernel modules are things like timeout 158*9da20b8aSRobert Mustacchicallbacks, such as 159*9da20b8aSRobert Mustacchi.Xr timeout 9F 160*9da20b8aSRobert Mustacchior 161*9da20b8aSRobert Mustacchi.Xr ddi_periodic_add 9F , 162*9da20b8aSRobert Mustacchicases where the kernel is invoking a driver's device operation routines such as 163*9da20b8aSRobert Mustacchi.Xr attach 9E 164*9da20b8aSRobert Mustacchiand 165*9da20b8aSRobert Mustacchi.Xr detach 9E , 166*9da20b8aSRobert Mustacchior many of the device driver's registered callbacks from frameworks such as the 167*9da20b8aSRobert Mustacchi.Xr mac 9E , 168*9da20b8aSRobert Mustacchi.Xr usba_hcdi 9E , 169*9da20b8aSRobert Mustacchiand various portions of SCSI, USB, and block devices. 170*9da20b8aSRobert Mustacchi.It Sy Framework-specific Contexts 171*9da20b8aSRobert MustacchiSome manuals will discuss more specific constraints about when they can be used. 172*9da20b8aSRobert MustacchiFor example, some functions may only be called while executing a specific entry 173*9da20b8aSRobert Mustacchipoint like 174*9da20b8aSRobert Mustacchi.Xr attach 9E . 175*9da20b8aSRobert MustacchiAnother example of this is that the 176*9da20b8aSRobert Mustacchi.Xr mac_transceiver_info_set_present 9F 177*9da20b8aSRobert Mustacchifunction is only meant to be used while executing a networking driver's 178*9da20b8aSRobert Mustacchi.Xr mct_info 9E 179*9da20b8aSRobert Mustacchientry point. 180*9da20b8aSRobert Mustacchi.El 181*9da20b8aSRobert Mustacchi.Ss PARAMETERS 182*9da20b8aSRobert MustacchiIn kernel manual pages 183*9da20b8aSRobert Mustacchi.Pq section 9 , 184*9da20b8aSRobert Mustacchieach function and entry point description generally has a separate list 185*9da20b8aSRobert Mustacchiof parameters which are arguments to the function. 186*9da20b8aSRobert MustacchiThe parameters section describes the basic purpose of each argument and 187*9da20b8aSRobert Mustacchishould explain where such things often come from and any constraints on 188*9da20b8aSRobert Mustacchitheir values. 189*9da20b8aSRobert Mustacchi.Sh INTERFACES 190*9da20b8aSRobert MustacchiFunctions below are organized into categories that describe their purpose. 191*9da20b8aSRobert MustacchiIndividual functions are documented in their own manual pages. 192*9da20b8aSRobert MustacchiFor each of these areas, we discuss high-level concepts behind each area and 193*9da20b8aSRobert Mustacchiprovide a brief discussion of how to get started with it. 194*9da20b8aSRobert MustacchiNote, some deprecated functions or older frameworks are not listed here. 195*9da20b8aSRobert Mustacchi.Pp 196*9da20b8aSRobert MustacchiEvery function listed below has its own manual page in section 9F and 197*9da20b8aSRobert Mustacchican be read with 198*9da20b8aSRobert Mustacchi.Xr man 1 . 199*9da20b8aSRobert MustacchiIn addition, some corresponding concepts are documented in section 9 and 200*9da20b8aSRobert Mustacchisome groups of functions are present to support a specific type of 201*9da20b8aSRobert Mustacchidevice driver, which is discussed more in section 9E . 202*9da20b8aSRobert Mustacchi.Ss Logging Functions 203*9da20b8aSRobert MustacchiThrough the kernel there are often needs to log messages that either 204*9da20b8aSRobert Mustacchimake it into the system log or on the console. 205*9da20b8aSRobert MustacchiThese kinds of messages can be performed with the 206*9da20b8aSRobert Mustacchi.Xr cmn_err 9F 207*9da20b8aSRobert Mustacchifunction or one of its more specific variants that operate in the 208*9da20b8aSRobert Mustacchicontext of a device 209*9da20b8aSRobert Mustacchi.Po 210*9da20b8aSRobert Mustacchi.Xr dev_err 9F 211*9da20b8aSRobert Mustacchi.Pc 212*9da20b8aSRobert Mustacchior a zone 213*9da20b8aSRobert Mustacchi.Po 214*9da20b8aSRobert Mustacchi.Xr zcmn_err 9F 215*9da20b8aSRobert Mustacchi.Pc . 216*9da20b8aSRobert Mustacchi.Pp 217*9da20b8aSRobert MustacchiThe console should be used sparingly. 218*9da20b8aSRobert MustacchiWhile a notice may be found there, one should assume that it may be 219*9da20b8aSRobert Mustacchimissed either due to overflow, not being connected to say a serial 220*9da20b8aSRobert Mustacchiconsole at the time, or some other reason. 221*9da20b8aSRobert MustacchiWhile the system log is better than the console, folks need to take care 222*9da20b8aSRobert Mustacchinot to spam the log. 223*9da20b8aSRobert MustacchiImagine if someone logged every time a network packet was generated or 224*9da20b8aSRobert Mustacchireceived, you'd quickly potentially run out of space and make it harder 225*9da20b8aSRobert Mustacchito find useful messages for bizarre behavior. 226*9da20b8aSRobert MustacchiIt's also important to remember that only system administrators and 227*9da20b8aSRobert Mustacchiprivileged users can actually see this log. 228*9da20b8aSRobert MustacchiWhere possible and appropriate use programmatic errors in routines that 229*9da20b8aSRobert Mustacchiallow it. 230*9da20b8aSRobert Mustacchi.Pp 231*9da20b8aSRobert MustacchiThe system also supports a structured event log called a system event 232*9da20b8aSRobert Mustacchithat is processed by 233*9da20b8aSRobert Mustacchi.Xr syseventd 8 . 234*9da20b8aSRobert MustacchiThis is used by the OS to provide notifications for things like device 235*9da20b8aSRobert Mustacchiinsertion and removal or the change of a data link. 236*9da20b8aSRobert MustacchiThese are driven by the 237*9da20b8aSRobert Mustacchi.Xr ddi_log_sysevent 9F 238*9da20b8aSRobert Mustacchifunction and allow arbitrary additional structured metadata in the form 239*9da20b8aSRobert Mustacchiof a 240*9da20b8aSRobert Mustacchi.Vt nvlist_t . 241*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 242*9da20b8aSRobert Mustacchi.It Xr cmn_err 9F Ta Xr dev_err 9F 243*9da20b8aSRobert Mustacchi.It Xr vcmn_err 9F Ta Xr vzcmn_err 9F 244*9da20b8aSRobert Mustacchi.It Xr zcmn_err 9F Ta Xr ddi_log_sysevent 9F 245*9da20b8aSRobert Mustacchi.El 246*9da20b8aSRobert Mustacchi.Ss Memory Allocation 247*9da20b8aSRobert MustacchiAt the heart of most device drivers is memory allocation. 248*9da20b8aSRobert MustacchiThe primary kernel allocator is called 249*9da20b8aSRobert Mustacchi.Qq kmem 250*9da20b8aSRobert Mustacchi.Pq kernel memory 251*9da20b8aSRobert Mustacchiand it is based on the 252*9da20b8aSRobert Mustacchi.Qq vmem 253*9da20b8aSRobert Mustacchi.Pq virtual memory 254*9da20b8aSRobert Mustacchisubsystem. 255*9da20b8aSRobert MustacchiMost of the time, device drivers should use 256*9da20b8aSRobert Mustacchi.Xr kmem_alloc 9F 257*9da20b8aSRobert Mustacchiand 258*9da20b8aSRobert Mustacchi.Xr kmem_zalloc 9F 259*9da20b8aSRobert Mustacchito allocate memory and free it with 260*9da20b8aSRobert Mustacchi.Xr kmem_free 9F . 261*9da20b8aSRobert MustacchiBased on the original kmem and subsequent vmem papers, the kernel is 262*9da20b8aSRobert Mustacchiinternally using object caches and magazines to allow high-throughput 263*9da20b8aSRobert Mustacchiallocation in a multi-CPU environment. 264*9da20b8aSRobert Mustacchi.Pp 265*9da20b8aSRobert MustacchiWhen allocating memory, an important choice must be made: whether or not 266*9da20b8aSRobert Mustacchito block for memory. 267*9da20b8aSRobert MustacchiIf one opts to perform a sleeping allocation, then the caller can be 268*9da20b8aSRobert Mustacchiguaranteed that the allocation will succeed, but it may take some time 269*9da20b8aSRobert Mustacchiand the thread will be blocked during that entire duration. 270*9da20b8aSRobert MustacchiThis is the 271*9da20b8aSRobert Mustacchi.Dv KM_SLEEP 272*9da20b8aSRobert Mustacchiflag. 273*9da20b8aSRobert MustacchiOn the other hand, there are many circumstances where this is not 274*9da20b8aSRobert Mustacchiappropriate, especially because a thread that is inside a memory 275*9da20b8aSRobert Mustacchiallocation function cannot currently be cancelled. 276*9da20b8aSRobert MustacchiIf the thread corresponds to a user process, then it will not be 277*9da20b8aSRobert Mustacchikillable. 278*9da20b8aSRobert Mustacchi.Pp 279*9da20b8aSRobert MustacchiGiven that there are many situations where this is not appropriate, the 280*9da20b8aSRobert Mustacchikernel offers an allocation mode where it will not block for memory to 281*9da20b8aSRobert Mustacchibe available: 282*9da20b8aSRobert Mustacchi.Dv KM_NOSLEEP 283*9da20b8aSRobert Mustacchiand 284*9da20b8aSRobert Mustacchi.Dv KM_NOSLEEP_LAZY . 285*9da20b8aSRobert MustacchiThese allocations can fail and return 286*9da20b8aSRobert Mustacchi.Dv NULL 287*9da20b8aSRobert Mustacchiwhen they do fail. 288*9da20b8aSRobert MustacchiEven though these are said to be no sleep operations, that does not mean 289*9da20b8aSRobert Mustacchithat the caller may not end up temporarily blocked due to mutex 290*9da20b8aSRobert Mustacchicontention or due to trying a bit more aggressively to reclaim memory in 291*9da20b8aSRobert Mustacchithe case of 292*9da20b8aSRobert Mustacchi.Dv KM_NOSLEEP . 293*9da20b8aSRobert MustacchiUnless operating in special circumstances, using 294*9da20b8aSRobert Mustacchi.Dv KM_NOSLEEP_LAZY 295*9da20b8aSRobert Mustacchishould be preferred to 296*9da20b8aSRobert Mustacchi.Dv KM_NOSLEEP . 297*9da20b8aSRobert Mustacchi.Pp 298*9da20b8aSRobert MustacchiIf a device driver has its own complex object that has more significant 299*9da20b8aSRobert Mustacchiset up and tear down costs, then the kmem cache function family should 300*9da20b8aSRobert Mustacchibe considered. 301*9da20b8aSRobert MustacchiTo use a kmem cache, it must first be created using the 302*9da20b8aSRobert Mustacchi.Xr kmem_cache_create 9F 303*9da20b8aSRobert Mustacchifunction, which requires specifying the size, alignment, and 304*9da20b8aSRobert Mustacchiconstructors and destructors. 305*9da20b8aSRobert MustacchiIndividual objects are allocated from the cache with the 306*9da20b8aSRobert Mustacchi.Xr kmem_cache_alloc 9F 307*9da20b8aSRobert Mustacchifunction. 308*9da20b8aSRobert MustacchiAn important constraint when using the caches is that when an object is 309*9da20b8aSRobert Mustacchifreed with 310*9da20b8aSRobert Mustacchi.Xr kmem_cache_free 9F , 311*9da20b8aSRobert Mustacchiit is the callers responsibility to ensure that the object is returned 312*9da20b8aSRobert Mustacchito its constructed state prior to freeing it. 313*9da20b8aSRobert MustacchiIf the object is reused, prior to the kernel reclaiming the memory for 314*9da20b8aSRobert Mustacchiother uses, then the constructor will not be called again. 315*9da20b8aSRobert MustacchiMost device drivers do not need to create a kmem cache for their 316*9da20b8aSRobert Mustacchiown allocations. 317*9da20b8aSRobert Mustacchi.Pp 318*9da20b8aSRobert MustacchiIf you are writing a device driver that is trying to interact with the 319*9da20b8aSRobert Mustacchinetworking, STREAMS, or USB subsystems, then they are generally using 320*9da20b8aSRobert Mustacchithe 321*9da20b8aSRobert Mustacchi.Vt mblk_t 322*9da20b8aSRobert Mustacchidata structure which is managed through a different set of APIs, though 323*9da20b8aSRobert Mustacchithey are leveraging kmem under the hood. 324*9da20b8aSRobert Mustacchi.Pp 325*9da20b8aSRobert MustacchiThe vmem set of interfaces allows for the management of abstract regions 326*9da20b8aSRobert Mustacchiof integers, generally representing memory or some other object, each 327*9da20b8aSRobert Mustacchiwith an offset and length. 328*9da20b8aSRobert MustacchiWhile it is not common that a device driver needs to do their own such 329*9da20b8aSRobert Mustacchimanagement, 330*9da20b8aSRobert Mustacchi.Xr vmem_create 9F 331*9da20b8aSRobert Mustacchiand 332*9da20b8aSRobert Mustacchi.Xr vmem_alloc 9F 333*9da20b8aSRobert Mustacchiare what to reach for when the need arises. 334*9da20b8aSRobert MustacchiRather than using vmem, if one needs to model a set of integers where 335*9da20b8aSRobert Mustacchieach is a valid identifier, that is you need to allocate every integer 336*9da20b8aSRobert Mustacchibetween 0 and 1000 as a distinct identifier, instead use 337*9da20b8aSRobert Mustacchi.Xr id_space_create 9F 338*9da20b8aSRobert Mustacchiwhich is discussed in 339*9da20b8aSRobert Mustacchi.Sx Identifier Management . 340*9da20b8aSRobert MustacchiFor more information on vmem, see 341*9da20b8aSRobert Mustacchi.Xr vmem 9 . 342*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 343*9da20b8aSRobert Mustacchi.It Xr kmem_alloc 9F Ta Xr kmem_cache_alloc 9F 344*9da20b8aSRobert Mustacchi.It Xr kmem_cache_create 9F Ta Xr kmem_cache_destroy 9F 345*9da20b8aSRobert Mustacchi.It Xr kmem_cache_free 9F Ta Xr kmem_cache_set_move 9F 346*9da20b8aSRobert Mustacchi.It Xr kmem_free 9F Ta Xr kmem_zalloc 9F 347*9da20b8aSRobert Mustacchi.It Xr vmem_add 9F Ta Xr vmem_alloc 9F 348*9da20b8aSRobert Mustacchi.It Xr vmem_contains 9F Ta Xr vmem_create 9F 349*9da20b8aSRobert Mustacchi.It Xr vmem_destroy 9F Ta Xr vmem_free 9F 350*9da20b8aSRobert Mustacchi.It Xr vmem_size 9F Ta Xr vmem_walk 9F 351*9da20b8aSRobert Mustacchi.It Xr vmem_xalloc 9F Ta Xr vmem_xcreate 9F 352*9da20b8aSRobert Mustacchi.It Xr vmem_xfree 9F Ta Xr bufcall 9F 353*9da20b8aSRobert Mustacchi.It Xr esbbcall 9F Ta Xr qbufcall 9F 354*9da20b8aSRobert Mustacchi.It Xr qunbufcall 9F Ta Xr unbufcall 9F 355*9da20b8aSRobert Mustacchi.El 356*9da20b8aSRobert Mustacchi.Ss String and libc Analogues 357*9da20b8aSRobert MustacchiThe kernel has many analogues for classic libc functions that deal with 358*9da20b8aSRobert Mustacchistring processing, memory copying, and related. 359*9da20b8aSRobert MustacchiFor the most part, these behave similarly to their userland analogues, 360*9da20b8aSRobert Mustacchibut there can be some differences in return values and for example, in 361*9da20b8aSRobert Mustacchithe set of supported format characters in the case of 362*9da20b8aSRobert Mustacchi.Xr snprintf 9F 363*9da20b8aSRobert Mustacchiand related. 364*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 365*9da20b8aSRobert Mustacchi.It Xr ASSERT 9F Ta Xr bcmp 9F 366*9da20b8aSRobert Mustacchi.It Xr bzero 9F Ta Xr bcopy 9F 367*9da20b8aSRobert Mustacchi.It Xr ddi_strdup 9F Ta Xr ddi_strtol 9F 368*9da20b8aSRobert Mustacchi.It Xr ddi_strtoll 9F Ta Xr ddi_strtoul 9F 369*9da20b8aSRobert Mustacchi.It Xr ddi_strtoull 9F Ta Xr ddi_ffs 9F 370*9da20b8aSRobert Mustacchi.It Xr ddi_fls 9F Ta Xr max 9F 371*9da20b8aSRobert Mustacchi.It Xr memchr 9F Ta Xr memcmp 9F 372*9da20b8aSRobert Mustacchi.It Xr memcpy 9F Ta Xr memmove 9F 373*9da20b8aSRobert Mustacchi.It Xr memset 9F Ta Xr min 9F 374*9da20b8aSRobert Mustacchi.It Xr numtos 9F Ta Xr snprintf 9F 375*9da20b8aSRobert Mustacchi.It Xr sprintf 9F Ta Xr stoi 9F 376*9da20b8aSRobert Mustacchi.It Xr strcasecmp 9F Ta Xr strcat 9F 377*9da20b8aSRobert Mustacchi.It Xr strchr 9F Ta Xr strcmp 9F 378*9da20b8aSRobert Mustacchi.It Xr strcpy 9F Ta Xr strdup 9F 379*9da20b8aSRobert Mustacchi.It Xr strfree 9F Ta Xr string 9F 380*9da20b8aSRobert Mustacchi.It Xr strlcat 9F Ta Xr strlcpy 9F 381*9da20b8aSRobert Mustacchi.It Xr strlen 9F Ta Xr strlog 9F 382*9da20b8aSRobert Mustacchi.It Xr strncasecmp 9F Ta Xr strncat 9F 383*9da20b8aSRobert Mustacchi.It Xr strncmp 9F Ta Xr strncpy 9F 384*9da20b8aSRobert Mustacchi.It Xr strnlen 9F Ta Xr strqget 9F 385*9da20b8aSRobert Mustacchi.It Xr strqset 9F Ta Xr strrchr 9F 386*9da20b8aSRobert Mustacchi.It Xr strspn 9F Ta Xr swab 9F 387*9da20b8aSRobert Mustacchi.It Xr vsnprintf 9F Ta Xr va_arg 9F 388*9da20b8aSRobert Mustacchi.It Xr va_copy 9F Ta Xr va_end 9F 389*9da20b8aSRobert Mustacchi.It Xr va_start 9F Ta Xr vsprintf 9F 390*9da20b8aSRobert Mustacchi.El 391*9da20b8aSRobert Mustacchi.Ss Tree Data Structures 392*9da20b8aSRobert MustacchiThese functions provide access to an intrusive self-balancing binary 393*9da20b8aSRobert Mustacchitree that is generally used throughout illumos. 394*9da20b8aSRobert MustacchiThe primary type here is the 395*9da20b8aSRobert Mustacchi.Vt avl_tree_t . 396*9da20b8aSRobert MustacchiStructures can be present in multiple trees and there are built-in 397*9da20b8aSRobert Mustacchiwalkers for the data structure in 398*9da20b8aSRobert Mustacchi.Xr mdb 1 . 399*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 400*9da20b8aSRobert Mustacchi.It Xr avl_add 9F Ta Xr avl_create 9F 401*9da20b8aSRobert Mustacchi.It Xr avl_destroy_nodes 9F Ta Xr avl_destroy 9F 402*9da20b8aSRobert Mustacchi.It Xr avl_find 9F Ta Xr avl_first 9F 403*9da20b8aSRobert Mustacchi.It Xr avl_insert_here 9F Ta Xr avl_insert 9F 404*9da20b8aSRobert Mustacchi.It Xr avl_is_empty 9F Ta Xr avl_last 9F 405*9da20b8aSRobert Mustacchi.It Xr avl_nearest 9F Ta Xr AVL_NEXT 9F 406*9da20b8aSRobert Mustacchi.It Xr avl_numnodes 9F Ta Xr AVL_PREV 9F 407*9da20b8aSRobert Mustacchi.It Xr avl_remove 9F Ta Xr avl_swap 9F 408*9da20b8aSRobert Mustacchi.El 409*9da20b8aSRobert Mustacchi.Ss Linked Lists 410*9da20b8aSRobert MustacchiThese functions provide a standard, intrusive doubly-linked list whose 411*9da20b8aSRobert Mustacchitype is the 412*9da20b8aSRobert Mustacchi.Vt list_t . 413*9da20b8aSRobert MustacchiThis list implementation is used extensively throughout illumos, has 414*9da20b8aSRobert Mustacchidebugging support through 415*9da20b8aSRobert Mustacchi.Xr mdb 1 416*9da20b8aSRobert Mustacchiwalkers, and is generally recommended rather than creating your own 417*9da20b8aSRobert Mustacchilist. 418*9da20b8aSRobert MustacchiDue to its intrusive nature, a given structure can be present on 419*9da20b8aSRobert Mustacchimultiple lists. 420*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 421*9da20b8aSRobert Mustacchi.It Xr list_create 9F Ta Xr list_destroy 9F 422*9da20b8aSRobert Mustacchi.It Xr list_head 9F Ta Xr list_insert_after 9F 423*9da20b8aSRobert Mustacchi.It Xr list_insert_before 9F Ta Xr list_insert_head 9F 424*9da20b8aSRobert Mustacchi.It Xr list_insert_tail 9F Ta Xr list_is_empty 9F 425*9da20b8aSRobert Mustacchi.It Xr list_link_active 9F Ta Xr list_link_init 9F 426*9da20b8aSRobert Mustacchi.It Xr list_link_replace 9F Ta Xr list_move_tail 9F 427*9da20b8aSRobert Mustacchi.It Xr list_next 9F Ta Xr list_prev 9F 428*9da20b8aSRobert Mustacchi.It Xr list_remove_head 9F Ta Xr list_remove_tail 9F 429*9da20b8aSRobert Mustacchi.It Xr list_remove 9F Ta Xr list_tail 9F 430*9da20b8aSRobert Mustacchi.El 431*9da20b8aSRobert Mustacchi.Ss Name-Value Pairs 432*9da20b8aSRobert MustacchiThe kernel often uses the 433*9da20b8aSRobert Mustacchi.Vt nvlist_t 434*9da20b8aSRobert Mustacchidata structure to pass around a list of typed name-value pairs. 435*9da20b8aSRobert MustacchiThis data structure is used in diverse areas, particularly because of 436*9da20b8aSRobert Mustacchiits ability to be serialized in different formats that are suitable not 437*9da20b8aSRobert Mustacchionly for use between userland and the kernel, but also persistently to a 438*9da20b8aSRobert Mustacchifile. 439*9da20b8aSRobert Mustacchi.Pp 440*9da20b8aSRobert MustacchiA 441*9da20b8aSRobert Mustacchi.Vt nvlist_t 442*9da20b8aSRobert Mustacchistructure is initialized with the 443*9da20b8aSRobert Mustacchi.Xr nvlist_alloc 9F 444*9da20b8aSRobert Mustacchifunction and can operate with two different degrees of uniqueness: a 445*9da20b8aSRobert Mustacchimode where only names are unique or that every name is qualified to a 446*9da20b8aSRobert Mustacchitype. 447*9da20b8aSRobert MustacchiThe former means that if I have an integer name 448*9da20b8aSRobert Mustacchi.Dq foo 449*9da20b8aSRobert Mustacchiand then add a string, array, or any other value with the same name, it 450*9da20b8aSRobert Mustacchiwill be replaced. 451*9da20b8aSRobert MustacchiHowever, if were using the name and type as unique, then the value would 452*9da20b8aSRobert Mustacchionly be replaced if both the pair's type and the name 453*9da20b8aSRobert Mustacchi.Dq foo 454*9da20b8aSRobert Mustacchimatched a pair that was already present. 455*9da20b8aSRobert MustacchiOtherwise, the two different entries would co-exist. 456*9da20b8aSRobert Mustacchi.Pp 457*9da20b8aSRobert MustacchiWhen constructing an nvlist, it is normally backed by the normal kmem 458*9da20b8aSRobert Mustacchiallocator and may either use sleeping or non-sleeping allocations. 459*9da20b8aSRobert MustacchiIt is also possible to use a custom allocator, though that generally has 460*9da20b8aSRobert Mustacchinot been necessary in the kernel. 461*9da20b8aSRobert Mustacchi.Pp 462*9da20b8aSRobert MustacchiSpecific keys and values can be looked up directly with the 463*9da20b8aSRobert Mustacchinvlist_lookup family of functions, but the entire list can be iterated 464*9da20b8aSRobert Mustacchias well, which is especially useful when trying to validate that no 465*9da20b8aSRobert Mustacchiunknown keys are present in the list. 466*9da20b8aSRobert MustacchiThe iteration API 467*9da20b8aSRobert Mustacchi.Xr nvlist_next_nvpair 9F 468*9da20b8aSRobert Mustacchiallows one to then get both the key's name, the type of value of the 469*9da20b8aSRobert Mustacchipair, and then the value itself. 470*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 471*9da20b8aSRobert Mustacchi.It Xr nv_alloc_fini 9F Ta Xr nv_alloc_init 9F 472*9da20b8aSRobert Mustacchi.It Xr nvlist_add_boolean_array 9F Ta Xr nvlist_add_boolean_value 9F 473*9da20b8aSRobert Mustacchi.It Xr nvlist_add_boolean 9F Ta Xr nvlist_add_byte_array 9F 474*9da20b8aSRobert Mustacchi.It Xr nvlist_add_byte 9F Ta Xr nvlist_add_int16_array 9F 475*9da20b8aSRobert Mustacchi.It Xr nvlist_add_int16 9F Ta Xr nvlist_add_int32_array 9F 476*9da20b8aSRobert Mustacchi.It Xr nvlist_add_int32 9F Ta Xr nvlist_add_int64_array 9F 477*9da20b8aSRobert Mustacchi.It Xr nvlist_add_int64 9F Ta Xr nvlist_add_int8_array 9F 478*9da20b8aSRobert Mustacchi.It Xr nvlist_add_int8 9F Ta Xr nvlist_add_nvlist_array 9F 479*9da20b8aSRobert Mustacchi.It Xr nvlist_add_nvlist 9F Ta Xr nvlist_add_nvpair 9F 480*9da20b8aSRobert Mustacchi.It Xr nvlist_add_string_array 9F Ta Xr nvlist_add_string 9F 481*9da20b8aSRobert Mustacchi.It Xr nvlist_add_uint16_array 9F Ta Xr nvlist_add_uint16 9F 482*9da20b8aSRobert Mustacchi.It Xr nvlist_add_uint32_array 9F Ta Xr nvlist_add_uint32 9F 483*9da20b8aSRobert Mustacchi.It Xr nvlist_add_uint64_array 9F Ta Xr nvlist_add_uint64 9F 484*9da20b8aSRobert Mustacchi.It Xr nvlist_add_uint8_array 9F Ta Xr nvlist_add_uint8 9F 485*9da20b8aSRobert Mustacchi.It Xr nvlist_alloc 9F Ta Xr nvlist_dup 9F 486*9da20b8aSRobert Mustacchi.It Xr nvlist_exists 9F Ta Xr nvlist_free 9F 487*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_boolean_array 9F Ta Xr nvlist_lookup_boolean_value 9F 488*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_boolean 9F Ta Xr nvlist_lookup_byte_array 9F 489*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_byte 9F Ta Xr nvlist_lookup_int16_array 9F 490*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_int16 9F Ta Xr nvlist_lookup_int32_array 9F 491*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_int32 9F Ta Xr nvlist_lookup_int64_array 9F 492*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_int64 9F Ta Xr nvlist_lookup_int8_array 9F 493*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_int8 9F Ta Xr nvlist_lookup_nvlist_array 9F 494*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_nvlist 9F Ta Xr nvlist_lookup_nvpair 9F 495*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_pairs 9F Ta Xr nvlist_lookup_string_array 9F 496*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_string 9F Ta Xr nvlist_lookup_uint16_array 9F 497*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_uint16 9F Ta Xr nvlist_lookup_uint32_array 9F 498*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_uint32 9F Ta Xr nvlist_lookup_uint64_array 9F 499*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_uint64 9F Ta Xr nvlist_lookup_uint8_array 9F 500*9da20b8aSRobert Mustacchi.It Xr nvlist_lookup_uint8 9F Ta Xr nvlist_merge 9F 501*9da20b8aSRobert Mustacchi.It Xr nvlist_next_nvpair 9F Ta Xr nvlist_pack 9F 502*9da20b8aSRobert Mustacchi.It Xr nvlist_remove_all 9F Ta Xr nvlist_remove 9F 503*9da20b8aSRobert Mustacchi.It Xr nvlist_size 9F Ta Xr nvlist_t 9F 504*9da20b8aSRobert Mustacchi.It Xr nvlist_unpack 9F Ta Xr nvlist_xalloc 9F 505*9da20b8aSRobert Mustacchi.It Xr nvlist_xdup 9F Ta Xr nvlist_xpack 9F 506*9da20b8aSRobert Mustacchi.It Xr nvlist_xunpack 9F Ta Xr nvpair_name 9F 507*9da20b8aSRobert Mustacchi.It Xr nvpair_type 9F Ta Xr nvpair_value_boolean_array 9F 508*9da20b8aSRobert Mustacchi.It Xr nvpair_value_byte_array 9F Ta Xr nvpair_value_byte 9F 509*9da20b8aSRobert Mustacchi.It Xr nvpair_value_int16_array 9F Ta Xr nvpair_value_int16 9F 510*9da20b8aSRobert Mustacchi.It Xr nvpair_value_int32_array 9F Ta Xr nvpair_value_int32 9F 511*9da20b8aSRobert Mustacchi.It Xr nvpair_value_int64_array 9F Ta Xr nvpair_value_int64 9F 512*9da20b8aSRobert Mustacchi.It Xr nvpair_value_int8_array 9F Ta Xr nvpair_value_int8 9F 513*9da20b8aSRobert Mustacchi.It Xr nvpair_value_nvlist_array 9F Ta Xr nvpair_value_nvlist 9F 514*9da20b8aSRobert Mustacchi.It Xr nvpair_value_string_array 9F Ta Xr nvpair_value_string 9F 515*9da20b8aSRobert Mustacchi.It Xr nvpair_value_uint16_array 9F Ta Xr nvpair_value_uint16 9F 516*9da20b8aSRobert Mustacchi.It Xr nvpair_value_uint32_array 9F Ta Xr nvpair_value_uint32 9F 517*9da20b8aSRobert Mustacchi.It Xr nvpair_value_uint64_array 9F Ta Xr nvpair_value_uint64 9F 518*9da20b8aSRobert Mustacchi.It Xr nvpair_value_uint8_array 9F Ta Xr nvpair_value_uint8 9F 519*9da20b8aSRobert Mustacchi.El 520*9da20b8aSRobert Mustacchi.Ss Identifier Management 521*9da20b8aSRobert MustacchiA common challenge in the kernel is the management of a series of 522*9da20b8aSRobert Mustacchidifferent IDs. 523*9da20b8aSRobert MustacchiThere are three different families of routines for managing identifiers 524*9da20b8aSRobert Mustacchipresented here, but we recommend the use of the 525*9da20b8aSRobert Mustacchi.Xr id_space_create 9F 526*9da20b8aSRobert Mustacchiand 527*9da20b8aSRobert Mustacchi.Xr id_alloc 9F 528*9da20b8aSRobert Mustacchifamily for new use cases. 529*9da20b8aSRobert MustacchiThe ID space can cover all or a subset of the 32-bit integer space and 530*9da20b8aSRobert Mustacchiprovides different allocation strategies for this. 531*9da20b8aSRobert Mustacchi.Pp 532*9da20b8aSRobert MustacchiDue to the current implementation, callers should generally prefer the 533*9da20b8aSRobert Mustacchinon-sleeping variants because the sleeping ones are not cancellable 534*9da20b8aSRobert Mustacchi.Po 535*9da20b8aSRobert Mustacchicurrently this is backed by vmem, but this should not be assumed and may 536*9da20b8aSRobert Mustacchichange in the future 537*9da20b8aSRobert Mustacchi.Pc . 538*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 539*9da20b8aSRobert Mustacchi.It Xr id_alloc_nosleep 9F Ta Xr id_alloc_specific_nosleep 9F 540*9da20b8aSRobert Mustacchi.It Xr id_alloc 9F Ta Xr id_allocff_nosleep 9F 541*9da20b8aSRobert Mustacchi.It Xr id_allocff 9F Ta Xr id_free 9F 542*9da20b8aSRobert Mustacchi.It Xr id_space_create 9F Ta Xr id_space_destroy 9F 543*9da20b8aSRobert Mustacchi.It Xr id_space_extend 9F Ta Xr id_space 9F 544*9da20b8aSRobert Mustacchi.It Xr id32_alloc 9F Ta Xr id32_free 9F 545*9da20b8aSRobert Mustacchi.It Xr id32_lookup 9F Ta Xr rmalloc_wait 9F 546*9da20b8aSRobert Mustacchi.It Xr rmalloc 9F Ta Xr rmallocmap_wait 9F 547*9da20b8aSRobert Mustacchi.It Xr rmallocmap 9F Ta Xr rmfree 9F 548*9da20b8aSRobert Mustacchi.It Xr rmfreemap 9F Ta 549*9da20b8aSRobert Mustacchi.El 550*9da20b8aSRobert Mustacchi.Ss Bit Manipulation Routines 551*9da20b8aSRobert MustacchiMany device drivers that are working with registers often need to get a 552*9da20b8aSRobert Mustacchispecific range of bits out of an integer. 553*9da20b8aSRobert MustacchiThese functions provide safe ways to set 554*9da20b8aSRobert Mustacchi.Pq bitset 555*9da20b8aSRobert Mustacchiand extract 556*9da20b8aSRobert Mustacchi.Pq bitx 557*9da20b8aSRobert Mustacchibit ranges, as well 558*9da20b8aSRobert Mustacchias modify an integer to remove a set of bits entirely 559*9da20b8aSRobert Mustacchi.Pq bitdel . 560*9da20b8aSRobert MustacchiUsing these functions is preferred to constructing manual masks and 561*9da20b8aSRobert Mustacchishifts particularly when a programming manual for a device is specified 562*9da20b8aSRobert Mustacchiin ranges of bits. 563*9da20b8aSRobert MustacchiOn debug builds, these provide extra checking to try and catch 564*9da20b8aSRobert Mustacchiprogrammer error. 565*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 566*9da20b8aSRobert Mustacchi.It Xr bitdel64 9F Ta Xr bitset8 9F 567*9da20b8aSRobert Mustacchi.It Xr bitset16 9F Ta Xr bitset32 9F 568*9da20b8aSRobert Mustacchi.It Xr bitset64 9F Ta Xr bitx8 9F 569*9da20b8aSRobert Mustacchi.It Xr bitx16 9F Ta Xr bitx32 9F 570*9da20b8aSRobert Mustacchi.It Xr bitx64 9F Ta 571*9da20b8aSRobert Mustacchi.El 572*9da20b8aSRobert Mustacchi.Ss Synchronization Primitives 573*9da20b8aSRobert MustacchiThe kernel provides a set of basic synchronization primitives that can 574*9da20b8aSRobert Mustacchibe used by the system. 575*9da20b8aSRobert MustacchiThese include mutexes, condition variables, reader/writer locks, and 576*9da20b8aSRobert Mustacchisemaphores. 577*9da20b8aSRobert MustacchiWhen creating mutexes and reader/writer locks, the kernel requires that 578*9da20b8aSRobert Mustacchione pass in the interrupt priority of a mutex if it will be used in 579*9da20b8aSRobert Mustacchiinterrupt context. 580*9da20b8aSRobert MustacchiThis is required so the kernel can determine the correct underlying type 581*9da20b8aSRobert Mustacchiof lock to use. 582*9da20b8aSRobert MustacchiThis ensures that if for some reason a mutex needs to be used in 583*9da20b8aSRobert Mustacchihigh-level interrupt context, the kernel will use a spin lock, but 584*9da20b8aSRobert Mustacchiotherwise can use the standard adaptive mutex that might block. 585*9da20b8aSRobert MustacchiFor developers familiar with other operating systems, this is somewhat 586*9da20b8aSRobert Mustacchidifferent in that the consumer does not need to generally figure out 587*9da20b8aSRobert Mustacchithis level of detail and this is why this is not present. 588*9da20b8aSRobert Mustacchi.Pp 589*9da20b8aSRobert MustacchiIn addition, condition variables provide means for waiting and detecting 590*9da20b8aSRobert Mustacchithat a signal has been delivered. 591*9da20b8aSRobert MustacchiThese variants are particularly useful when writing character device 592*9da20b8aSRobert Mustacchioperations for device drivers as it allows users the chance to cancel an 593*9da20b8aSRobert Mustacchioperation and not be blocked indefinitely on something that may not 594*9da20b8aSRobert Mustacchioccur. 595*9da20b8aSRobert MustacchiThese _sig variants should generally be preferred where applicable. 596*9da20b8aSRobert Mustacchi.Pp 597*9da20b8aSRobert MustacchiThe kernel also provides memory barrier primitives. 598*9da20b8aSRobert MustacchiSee the 599*9da20b8aSRobert Mustacchi.Sx Memory Barriers 600*9da20b8aSRobert Mustacchisection for more information. 601*9da20b8aSRobert MustacchiThere is no need to use manual memory barriers when using the 602*9da20b8aSRobert Mustacchisynchronization primitives. 603*9da20b8aSRobert MustacchiThe synchronization primitives contain that the appropriate barriers are 604*9da20b8aSRobert Mustacchipresent to ensure coherency while the lock is held. 605*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 606*9da20b8aSRobert Mustacchi.It Xr cv_broadcast 9F Ta Xr cv_destroy 9F 607*9da20b8aSRobert Mustacchi.It Xr cv_init 9F Ta Xr cv_reltimedwait_sig 9F 608*9da20b8aSRobert Mustacchi.It Xr cv_reltimedwait 9F Ta Xr cv_signal 9F 609*9da20b8aSRobert Mustacchi.It Xr cv_timedwait_sig 9F Ta Xr cv_timedwait 9F 610*9da20b8aSRobert Mustacchi.It Xr cv_wait_sig 9F Ta Xr cv_wait 9F 611*9da20b8aSRobert Mustacchi.It Xr ddi_enter_critical 9F Ta Xr ddi_exit_critical 9F 612*9da20b8aSRobert Mustacchi.It Xr mutex_destroy 9F Ta Xr mutex_enter 9F 613*9da20b8aSRobert Mustacchi.It Xr mutex_exit 9F Ta Xr mutex_init 9F 614*9da20b8aSRobert Mustacchi.It Xr mutex_owned 9F Ta Xr mutex_tryenter 9F 615*9da20b8aSRobert Mustacchi.It Xr rw_destroy 9F Ta Xr rw_downgrade 9F 616*9da20b8aSRobert Mustacchi.It Xr rw_enter 9F Ta Xr rw_exit 9F 617*9da20b8aSRobert Mustacchi.It Xr rw_init 9F Ta Xr rw_read_locked 9F 618*9da20b8aSRobert Mustacchi.It Xr rw_tryenter 9F Ta Xr rw_tryupgrade 9F 619*9da20b8aSRobert Mustacchi.It Xr sema_destroy 9F Ta Xr sema_init 9F 620*9da20b8aSRobert Mustacchi.It Xr sema_p_sig 9F Ta Xr sema_p 9F 621*9da20b8aSRobert Mustacchi.It Xr sema_tryp 9F Ta Xr sema_v 9F 622*9da20b8aSRobert Mustacchi.It Xr semaphore 9F Ta 623*9da20b8aSRobert Mustacchi.El 624*9da20b8aSRobert Mustacchi.Ss Atomic Operations 625*9da20b8aSRobert MustacchiThis group of functions provides a general way to perform atomic 626*9da20b8aSRobert Mustacchioperations on integers of different sizes and explicit types. 627*9da20b8aSRobert MustacchiThe 628*9da20b8aSRobert Mustacchi.Xr atomic_ops 9F 629*9da20b8aSRobert Mustacchimanual page describes the different classes of functions in more detail, 630*9da20b8aSRobert Mustacchibut there are functions that take care of using the CPU's instructions 631*9da20b8aSRobert Mustacchifor addition, compare and swap, and more. 632*9da20b8aSRobert MustacchiIf data is being protected and only accessed under a synchronization 633*9da20b8aSRobert Mustacchiprimitive such as a mutex or reader-writer lock, then there isn't a 634*9da20b8aSRobert Mustacchireason to use an atomic operation for that data, generally speaking. 635*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 636*9da20b8aSRobert Mustacchi.It Xr atomic_add_8_nv 9F Ta Xr atomic_add_8 9F 637*9da20b8aSRobert Mustacchi.It Xr atomic_add_16_nv 9F Ta Xr atomic_add_16 9F 638*9da20b8aSRobert Mustacchi.It Xr atomic_add_32_nv 9F Ta Xr atomic_add_32 9F 639*9da20b8aSRobert Mustacchi.It Xr atomic_add_64_nv 9F Ta Xr atomic_add_64 9F 640*9da20b8aSRobert Mustacchi.It Xr atomic_add_char_nv 9F Ta Xr atomic_add_char 9F 641*9da20b8aSRobert Mustacchi.It Xr atomic_add_int_nv 9F Ta Xr atomic_add_int 9F 642*9da20b8aSRobert Mustacchi.It Xr atomic_add_long_nv 9F Ta Xr atomic_add_long 9F 643*9da20b8aSRobert Mustacchi.It Xr atomic_add_ptr_nv 9F Ta Xr atomic_add_ptr 9F 644*9da20b8aSRobert Mustacchi.It Xr atomic_add_short_nv 9F Ta Xr atomic_add_short 9F 645*9da20b8aSRobert Mustacchi.It Xr atomic_and_8_nv 9F Ta Xr atomic_and_8 9F 646*9da20b8aSRobert Mustacchi.It Xr atomic_and_16_nv 9F Ta Xr atomic_and_16 9F 647*9da20b8aSRobert Mustacchi.It Xr atomic_and_32_nv 9F Ta Xr atomic_and_32 9F 648*9da20b8aSRobert Mustacchi.It Xr atomic_and_64_nv 9F Ta Xr atomic_and_64 9F 649*9da20b8aSRobert Mustacchi.It Xr atomic_and_uchar_nv 9F Ta Xr atomic_and_uchar 9F 650*9da20b8aSRobert Mustacchi.It Xr atomic_and_uint_nv 9F Ta Xr atomic_and_uint 9F 651*9da20b8aSRobert Mustacchi.It Xr atomic_and_ulong_nv 9F Ta Xr atomic_and_ulong 9F 652*9da20b8aSRobert Mustacchi.It Xr atomic_and_ushort_nv 9F Ta Xr atomic_and_ushort 9F 653*9da20b8aSRobert Mustacchi.It Xr atomic_cas_16 9F Ta Xr atomic_cas_32 9F 654*9da20b8aSRobert Mustacchi.It Xr atomic_cas_64 9F Ta Xr atomic_cas_8 9F 655*9da20b8aSRobert Mustacchi.It Xr atomic_cas_ptr 9F Ta Xr atomic_cas_uchar 9F 656*9da20b8aSRobert Mustacchi.It Xr atomic_cas_uint 9F Ta Xr atomic_cas_ulong 9F 657*9da20b8aSRobert Mustacchi.It Xr atomic_cas_ushort 9F Ta Xr atomic_clear_long_excl 9F 658*9da20b8aSRobert Mustacchi.It Xr atomic_dec_8_nv 9F Ta Xr atomic_dec_8 9F 659*9da20b8aSRobert Mustacchi.It Xr atomic_dec_16_nv 9F Ta Xr atomic_dec_16 9F 660*9da20b8aSRobert Mustacchi.It Xr atomic_dec_32_nv 9F Ta Xr atomic_dec_32 9F 661*9da20b8aSRobert Mustacchi.It Xr atomic_dec_64_nv 9F Ta Xr atomic_dec_64 9F 662*9da20b8aSRobert Mustacchi.It Xr atomic_dec_ptr_nv 9F Ta Xr atomic_dec_ptr 9F 663*9da20b8aSRobert Mustacchi.It Xr atomic_dec_uchar_nv 9F Ta Xr atomic_dec_uchar 9F 664*9da20b8aSRobert Mustacchi.It Xr atomic_dec_uint_nv 9F Ta Xr atomic_dec_uint 9F 665*9da20b8aSRobert Mustacchi.It Xr atomic_dec_ulong_nv 9F Ta Xr atomic_dec_ulong 9F 666*9da20b8aSRobert Mustacchi.It Xr atomic_dec_ushort_nv 9F Ta Xr atomic_dec_ushort 9F 667*9da20b8aSRobert Mustacchi.It Xr atomic_inc_8_nv 9F Ta Xr atomic_inc_8 9F 668*9da20b8aSRobert Mustacchi.It Xr atomic_inc_16_nv 9F Ta Xr atomic_inc_16 9F 669*9da20b8aSRobert Mustacchi.It Xr atomic_inc_32_nv 9F Ta Xr atomic_inc_32 9F 670*9da20b8aSRobert Mustacchi.It Xr atomic_inc_64_nv 9F Ta Xr atomic_inc_64 9F 671*9da20b8aSRobert Mustacchi.It Xr atomic_inc_ptr_nv 9F Ta Xr atomic_inc_ptr 9F 672*9da20b8aSRobert Mustacchi.It Xr atomic_inc_uchar_nv 9F Ta Xr atomic_inc_uchar 9F 673*9da20b8aSRobert Mustacchi.It Xr atomic_inc_uint_nv 9F Ta Xr atomic_inc_uint 9F 674*9da20b8aSRobert Mustacchi.It Xr atomic_inc_ulong_nv 9F Ta Xr atomic_inc_ulong 9F 675*9da20b8aSRobert Mustacchi.It Xr atomic_inc_ushort_nv 9F Ta Xr atomic_inc_ushort 9F 676*9da20b8aSRobert Mustacchi.It Xr atomic_or_8_nv 9F Ta Xr atomic_or_8 9F 677*9da20b8aSRobert Mustacchi.It Xr atomic_or_16_nv 9F Ta Xr atomic_or_16 9F 678*9da20b8aSRobert Mustacchi.It Xr atomic_or_32_nv 9F Ta Xr atomic_or_32 9F 679*9da20b8aSRobert Mustacchi.It Xr atomic_or_64_nv 9F Ta Xr atomic_or_64 9F 680*9da20b8aSRobert Mustacchi.It Xr atomic_or_uchar_nv 9F Ta Xr atomic_or_uchar 9F 681*9da20b8aSRobert Mustacchi.It Xr atomic_or_uint_nv 9F Ta Xr atomic_or_uint 9F 682*9da20b8aSRobert Mustacchi.It Xr atomic_or_ulong_nv 9F Ta Xr atomic_or_ulong 9F 683*9da20b8aSRobert Mustacchi.It Xr atomic_or_ushort_nv 9F Ta Xr atomic_or_ushort 9F 684*9da20b8aSRobert Mustacchi.It Xr atomic_set_long_excl 9F Ta Xr atomic_swap_8 9F 685*9da20b8aSRobert Mustacchi.It Xr atomic_swap_16 9F Ta Xr atomic_swap_32 9F 686*9da20b8aSRobert Mustacchi.It Xr atomic_swap_64 9F Ta Xr atomic_swap_ptr 9F 687*9da20b8aSRobert Mustacchi.It Xr atomic_swap_uchar 9F Ta Xr atomic_swap_uint 9F 688*9da20b8aSRobert Mustacchi.It Xr atomic_swap_ulong 9F Ta Xr atomic_swap_ushort 9F 689*9da20b8aSRobert Mustacchi.El 690*9da20b8aSRobert Mustacchi.Ss Memory Barriers 691*9da20b8aSRobert MustacchiThe kernel provides general purpose memory barriers that can be used 692*9da20b8aSRobert Mustacchiwhen required. 693*9da20b8aSRobert MustacchiIn general, when using items described in the 694*9da20b8aSRobert Mustacchi.Sx Synchronization Primitives 695*9da20b8aSRobert Mustacchisection, these are not required. 696*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 697*9da20b8aSRobert Mustacchi.It Xr membar_consumer 9F Ta Xr membar_enter 9F 698*9da20b8aSRobert Mustacchi.It Xr membar_exit 9F Ta Xr membar_producer 9F 699*9da20b8aSRobert Mustacchi.El 700*9da20b8aSRobert Mustacchi.Ss Virtual Memory and Pages 701*9da20b8aSRobert MustacchiAll platforms that the operating system supports have some form of 702*9da20b8aSRobert Mustacchivirtual memory which is managed in units of pages. 703*9da20b8aSRobert MustacchiThe page size varies between architectures and platforms. 704*9da20b8aSRobert MustacchiFor example, the smallest x86 page size is 4 KiB while SPARC 705*9da20b8aSRobert Mustacchitraditionally used 8 KiB pages. 706*9da20b8aSRobert MustacchiThese functions can be used to convert between pages and bytes. 707*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 708*9da20b8aSRobert Mustacchi.It Xr btop 9F Ta Xr btopr 9F 709*9da20b8aSRobert Mustacchi.It Xr ddi_btop 9F Ta Xr ddi_btopr 9F 710*9da20b8aSRobert Mustacchi.It Xr ddi_ptob 9F Ta Xr ptob 9F 711*9da20b8aSRobert Mustacchi.El 712*9da20b8aSRobert Mustacchi.Ss Module and Device Framework 713*9da20b8aSRobert MustacchiThese functions are used as part of implementing kernel modules and 714*9da20b8aSRobert Mustacchiregister device drivers with the various kernel frameworks. 715*9da20b8aSRobert MustacchiThere are also functions here that are satiable for use in the 716*9da20b8aSRobert Mustacchi.Xr dev_ops 9F , 717*9da20b8aSRobert Mustacchi.Xr cb_ops 9F , 718*9da20b8aSRobert Mustacchietc. 719*9da20b8aSRobert Mustacchistructures and for interrogating module information. 720*9da20b8aSRobert Mustacchi.Pp 721*9da20b8aSRobert MustacchiThe 722*9da20b8aSRobert Mustacchi.Xr mod_install 9F 723*9da20b8aSRobert Mustacchiand 724*9da20b8aSRobert Mustacchi.Xr mod_remove 9F 725*9da20b8aSRobert Mustacchifunctions are used during a driver's 726*9da20b8aSRobert Mustacchi.Xr _init 9E 727*9da20b8aSRobert Mustacchiand 728*9da20b8aSRobert Mustacchi.Xr _fini 9E 729*9da20b8aSRobert Mustacchifunctions. 730*9da20b8aSRobert Mustacchi.Pp 731*9da20b8aSRobert MustacchiThere are two different ways that drivers often manage their instance 732*9da20b8aSRobert Mustacchistate which is created during 733*9da20b8aSRobert Mustacchi.Xr attach 9E . 734*9da20b8aSRobert MustacchiThe first is the use of 735*9da20b8aSRobert Mustacchi.Xr ddi_set_driver_private 9F 736*9da20b8aSRobert Mustacchiand 737*9da20b8aSRobert Mustacchi.Xr ddi_get_driver_private 9F . 738*9da20b8aSRobert MustacchiThis stores a driver-specific value on the 739*9da20b8aSRobert Mustacchi.Vt dev_info_t 740*9da20b8aSRobert Mustacchistructure which allows it to be used during other operations. 741*9da20b8aSRobert MustacchiSome device driver frameworks may use this themselves, making this 742*9da20b8aSRobert Mustacchiunavailable to the driver. 743*9da20b8aSRobert Mustacchi.Pp 744*9da20b8aSRobert MustacchiThe other path is to use the soft state suite of functions which 745*9da20b8aSRobert Mustacchidynamically grows to cover the number of instances of a device that 746*9da20b8aSRobert Mustacchiexist. 747*9da20b8aSRobert MustacchiThe soft state is generally initialized in the 748*9da20b8aSRobert Mustacchi.Xr _init 9E 749*9da20b8aSRobert Mustacchientry point with 750*9da20b8aSRobert Mustacchi.Xr ddi_soft_state_init 9F 751*9da20b8aSRobert Mustacchiand then instances are allocated and freed during 752*9da20b8aSRobert Mustacchi.Xr attach 9E 753*9da20b8aSRobert Mustacchiand 754*9da20b8aSRobert Mustacchi.Xr detach 9E 755*9da20b8aSRobert Mustacchiwith 756*9da20b8aSRobert Mustacchi.Xr ddi_soft_state_zalloc 9F 757*9da20b8aSRobert Mustacchiand 758*9da20b8aSRobert Mustacchi.Xr ddi_soft_state_free 9F , 759*9da20b8aSRobert Mustacchiand then retrieved with 760*9da20b8aSRobert Mustacchi.Xr ddi_get_soft_state 9F . 761*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 762*9da20b8aSRobert Mustacchi.It Xr ddi_get_driver_private 9F Ta Xr ddi_get_soft_state 9F 763*9da20b8aSRobert Mustacchi.It Xr ddi_modclose 9F Ta Xr ddi_modopen 9F 764*9da20b8aSRobert Mustacchi.It Xr ddi_modsym 9F Ta Xr ddi_no_info 9F 765*9da20b8aSRobert Mustacchi.It Xr ddi_report_dev 9F Ta Xr ddi_set_driver_private 9F 766*9da20b8aSRobert Mustacchi.It Xr ddi_soft_state_fini 9F Ta Xr ddi_soft_state_free 9F 767*9da20b8aSRobert Mustacchi.It Xr ddi_soft_state_init 9F Ta Xr ddi_soft_state_zalloc 9F 768*9da20b8aSRobert Mustacchi.It Xr mod_info 9F Ta Xr mod_install 9F 769*9da20b8aSRobert Mustacchi.It Xr mod_modname 9F Ta Xr mod_remove 9F 770*9da20b8aSRobert Mustacchi.It Xr nochpoll 9F Ta Xr nodev 9F 771*9da20b8aSRobert Mustacchi.It Xr nulldev 9F Ta 772*9da20b8aSRobert Mustacchi.El 773*9da20b8aSRobert Mustacchi.Ss Device Tree Information 774*9da20b8aSRobert MustacchiDevices are organized into a tree that is partially seeded by the 775*9da20b8aSRobert Mustacchiplatform based on information discovered at boot and augmented with 776*9da20b8aSRobert Mustacchiadditional information at runtime. 777*9da20b8aSRobert MustacchiEvery instance of a device driver is given a 778*9da20b8aSRobert Mustacchi.Vt "dev_info_t *" 779*9da20b8aSRobert Mustacchi.Pq device information 780*9da20b8aSRobert Mustacchidata structure which corresponds to information about an instance and 781*9da20b8aSRobert Mustacchihas a place in the tree. 782*9da20b8aSRobert MustacchiWhen a driver requests operations like to allocate memory for DMA, that 783*9da20b8aSRobert Mustacchirequest is passed up the tree and modified. 784*9da20b8aSRobert MustacchiThe same is true for other things like interrupts, event notifications, 785*9da20b8aSRobert Mustacchior properties. 786*9da20b8aSRobert Mustacchi.Pp 787*9da20b8aSRobert MustacchiThere are many different informational properties about a device driver. 788*9da20b8aSRobert MustacchiFor example, 789*9da20b8aSRobert Mustacchi.Xr ddi_driver_name 9F 790*9da20b8aSRobert Mustacchireturns the name of the device driver, 791*9da20b8aSRobert Mustacchi.Xr ddi_get_name 9F 792*9da20b8aSRobert Mustacchireturns the name of the node in the tree, 793*9da20b8aSRobert Mustacchi.Xr ddi_get_parent 9F 794*9da20b8aSRobert Mustacchireturns a node's parent, and 795*9da20b8aSRobert Mustacchi.Xr ddi_get_instance 9F 796*9da20b8aSRobert Mustacchireturns the instance number of a specific driver. 797*9da20b8aSRobert Mustacchi.Pp 798*9da20b8aSRobert MustacchiThere are a series of properties that exist on the tree, the exact set 799*9da20b8aSRobert Mustacchiof which depend on the class of the device and are often documented in a 800*9da20b8aSRobert Mustacchispecific device class's manual. 801*9da20b8aSRobert MustacchiFor example, the 802*9da20b8aSRobert Mustacchi.Dq reg 803*9da20b8aSRobert Mustacchiproperty is used for PCI and PCIe devices to describe the various base 804*9da20b8aSRobert Mustacchiaddress registers, their types, and related, which are documented in 805*9da20b8aSRobert Mustacchi.Xr pci 5 . 806*9da20b8aSRobert Mustacchi.Pp 807*9da20b8aSRobert MustacchiWhen getting a property one can constrain it to the current instance or 808*9da20b8aSRobert Mustacchiyou can ask for a parent to try to look up the property. 809*9da20b8aSRobert MustacchiWhich mode is appropriate depends on the specific class of driver, its 810*9da20b8aSRobert Mustacchiparent, and the property. 811*9da20b8aSRobert Mustacchi.Pp 812*9da20b8aSRobert MustacchiUsing a 813*9da20b8aSRobert Mustacchi.Vt "dev_info_t *" 814*9da20b8aSRobert Mustacchipointer has to be done carefully. 815*9da20b8aSRobert MustacchiWhen a device driver is in any of its 816*9da20b8aSRobert Mustacchi.Xr dev_ops 9S , 817*9da20b8aSRobert Mustacchi.Xr cb_ops 9S , 818*9da20b8aSRobert Mustacchior similar callback functions that it has registered with the kernel, 819*9da20b8aSRobert Mustacchithen it can always safely use its own 820*9da20b8aSRobert Mustacchi.Vt "dev_info_t" 821*9da20b8aSRobert Mustacchiand those of any parents it discovers through 822*9da20b8aSRobert Mustacchi.Xr ddi_get_parent 9F . 823*9da20b8aSRobert MustacchiHowever, it cannot assume the validity of any siblings or children 824*9da20b8aSRobert Mustacchiunless there are other circumstances that guarantee that they will not 825*9da20b8aSRobert Mustacchidisappear. 826*9da20b8aSRobert MustacchiIn the broader kernel, one should not assume that it is safe to use a 827*9da20b8aSRobert Mustacchigiven 828*9da20b8aSRobert Mustacchi.Vt "dev_info_t *" 829*9da20b8aSRobert Mustacchistructure without the appropriate NDI 830*9da20b8aSRobert Mustacchi.Pq nexus driver interface 831*9da20b8aSRobert Mustacchihold having been applied. 832*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 833*9da20b8aSRobert Mustacchi.It Xr ddi_binding_name 9F Ta Xr ddi_dev_is_sid 9F 834*9da20b8aSRobert Mustacchi.It Xr ddi_driver_major 9F Ta Xr ddi_driver_name 9F 835*9da20b8aSRobert Mustacchi.It Xr ddi_get_devstate 9F Ta Xr ddi_get_instance 9F 836*9da20b8aSRobert Mustacchi.It Xr ddi_get_name 9F Ta Xr ddi_get_parent 9F 837*9da20b8aSRobert Mustacchi.It Xr ddi_getlongprop_buf 9F Ta Xr ddi_getlongprop 9F 838*9da20b8aSRobert Mustacchi.It Xr ddi_getprop 9F Ta Xr ddi_getproplen 9F 839*9da20b8aSRobert Mustacchi.It Xr ddi_node_name 9F Ta Xr ddi_prop_create 9F 840*9da20b8aSRobert Mustacchi.It Xr ddi_prop_exists 9F Ta Xr ddi_prop_free 9F 841*9da20b8aSRobert Mustacchi.It Xr ddi_prop_get_int 9F Ta Xr ddi_prop_get_int64 9F 842*9da20b8aSRobert Mustacchi.It Xr ddi_prop_lookup_byte_array 9F Ta Xr ddi_prop_lookup_int_array 9F 843*9da20b8aSRobert Mustacchi.It Xr ddi_prop_lookup_int64_array 9F Ta Xr ddi_prop_lookup_string_array 9F 844*9da20b8aSRobert Mustacchi.It Xr ddi_prop_lookup_string 9F Ta Xr ddi_prop_lookup 9F 845*9da20b8aSRobert Mustacchi.It Xr ddi_prop_modify 9F Ta Xr ddi_prop_op 9F 846*9da20b8aSRobert Mustacchi.It Xr ddi_prop_remove_all 9F Ta Xr ddi_prop_remove 9F 847*9da20b8aSRobert Mustacchi.It Xr ddi_prop_undefine 9F Ta Xr ddi_prop_update_byte_array 9F 848*9da20b8aSRobert Mustacchi.It Xr ddi_prop_update_int_array 9F Ta Xr ddi_prop_update_int 9F 849*9da20b8aSRobert Mustacchi.It Xr ddi_prop_update_int64_array 9F Ta Xr ddi_prop_update_int64 9F 850*9da20b8aSRobert Mustacchi.It Xr ddi_prop_update_string_array 9F Ta Xr ddi_prop_update_string 9F 851*9da20b8aSRobert Mustacchi.It Xr ddi_prop_update 9F Ta Xr ddi_root_node 9F 852*9da20b8aSRobert Mustacchi.It Xr ddi_slaveonly 9F Ta 853*9da20b8aSRobert Mustacchi.El 854*9da20b8aSRobert Mustacchi.Ss Copying Data to and from Userland 855*9da20b8aSRobert MustacchiThe kernel operates in a different context from userland. 856*9da20b8aSRobert MustacchiOne does not simply access user memory. 857*9da20b8aSRobert MustacchiThis is enforced either by the architecture's memory model, where user 858*9da20b8aSRobert Mustacchiaddress space isn't even present in the kernel's virtual address space 859*9da20b8aSRobert Mustacchior by architectural mechanisms such as Supervisor Mode Access Protect 860*9da20b8aSRobert Mustacchi.Pq SMAP 861*9da20b8aSRobert Mustacchion x86. 862*9da20b8aSRobert Mustacchi.Pp 863*9da20b8aSRobert MustacchiTo facilitate accessing memory, the kernel provides a few routines that 864*9da20b8aSRobert Mustacchican be used. 865*9da20b8aSRobert MustacchiIn most contexts the main thing to use is 866*9da20b8aSRobert Mustacchi.Xr ddi_copyin 9F 867*9da20b8aSRobert Mustacchiand 868*9da20b8aSRobert Mustacchi.Xr ddi_copyout 9F . 869*9da20b8aSRobert MustacchiThese will safely dereference addresses and ensure that the address is 870*9da20b8aSRobert Mustacchiappropriate depending on whether this is coming from the user or kernel. 871*9da20b8aSRobert MustacchiWhen operating with the kernel's 872*9da20b8aSRobert Mustacchi.Vt uio_t 873*9da20b8aSRobert Mustacchistructure which is for mostly used when processing read and write 874*9da20b8aSRobert Mustacchirequests, instead 875*9da20b8aSRobert Mustacchi.Xr uiomove 9F 876*9da20b8aSRobert Mustacchiis the goto function. 877*9da20b8aSRobert Mustacchi.Pp 878*9da20b8aSRobert MustacchiWhen reading data from userland into the kernel, there is another 879*9da20b8aSRobert Mustacchiconcern: the data model. 880*9da20b8aSRobert MustacchiThe most common place this comes up is in an 881*9da20b8aSRobert Mustacchi.Xr ioctl 9E 882*9da20b8aSRobert Mustacchihandler or other places where the kernel is operating on data that isn't 883*9da20b8aSRobert Mustacchifixed size. 884*9da20b8aSRobert MustacchiParticularly in C, though this applies to other languages, structures 885*9da20b8aSRobert Mustacchiand unions vary in the size and alignment requirements between 32-bit 886*9da20b8aSRobert Mustacchiand 64-bit processes. 887*9da20b8aSRobert MustacchiThe same even applies if one uses pointers or the 888*9da20b8aSRobert Mustacchi.Vt long , 889*9da20b8aSRobert Mustacchi.Vt size_t , 890*9da20b8aSRobert Mustacchior similar types in C. 891*9da20b8aSRobert MustacchiIn supported 32-bit and 64-bit environments these types are 4 and 8 892*9da20b8aSRobert Mustacchibytes respectively. 893*9da20b8aSRobert MustacchiTo account for this, when data is not fixed size between all data 894*9da20b8aSRobert Mustacchimodels, the driver must look at the data model of the process it is 895*9da20b8aSRobert Mustacchicopying data from. 896*9da20b8aSRobert Mustacchi.Pp 897*9da20b8aSRobert MustacchiThe simplest way to solve this problem is to try to make the data 898*9da20b8aSRobert Mustacchistructure the same across the different models. 899*9da20b8aSRobert MustacchiIt's not sufficient to just use the same structure definition and fixed 900*9da20b8aSRobert Mustacchisize types as the alignment and padding between the two can vary. 901*9da20b8aSRobert MustacchiFor example, the alignment of a 64-bit integer like a 902*9da20b8aSRobert Mustacchi.Vt uint64_t 903*9da20b8aSRobert Mustacchican change between a 32-bit and 64-bit data model. 904*9da20b8aSRobert MustacchiOne way to check for the data structures being identical is to leverage 905*9da20b8aSRobert Mustacchithe 906*9da20b8aSRobert Mustacchi.Xr ctfdiff 1 907*9da20b8aSRobert Mustacchiprogram, generally with the 908*9da20b8aSRobert Mustacchi.Fl I 909*9da20b8aSRobert Mustacchioption. 910*9da20b8aSRobert Mustacchi.Pp 911*9da20b8aSRobert MustacchiHowever, there are times when a structure simply can't be the same, such 912*9da20b8aSRobert Mustacchias when we're encoding a pointer into the structure or a type like the 913*9da20b8aSRobert Mustacchi.Vt size_t . 914*9da20b8aSRobert MustacchiWhen this happens, the most natural way to accomplish this is to use the 915*9da20b8aSRobert Mustacchi.Xr ddi_model_convert_from 9F 916*9da20b8aSRobert Mustacchifunction which can determine the appropriate model from the ioctl's 917*9da20b8aSRobert Mustacchiarguments. 918*9da20b8aSRobert MustacchiThis provides a natural way to copy a structure in and out in the 919*9da20b8aSRobert Mustacchiappropriate data model and convert it at those points to the kernel's 920*9da20b8aSRobert Mustacchinative form. 921*9da20b8aSRobert Mustacchi.Pp 922*9da20b8aSRobert MustacchiAn alternate way to approach the data model is to use the 923*9da20b8aSRobert Mustacchi.Xr STRUCT_DECL 9F 924*9da20b8aSRobert Mustacchifunctions, but as this requires wrapping every access to every member, 925*9da20b8aSRobert Mustacchioften times the 926*9da20b8aSRobert Mustacchi.Xr ddi_model_convert_from 9F 927*9da20b8aSRobert Mustacchiapproach and taking care of converting values and ensuring that limits 928*9da20b8aSRobert Mustacchiaren't exceeded at the end is preferred. 929*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 930*9da20b8aSRobert Mustacchi.It Xr bp_copyin 9F Ta Xr bp_copyout 9F 931*9da20b8aSRobert Mustacchi.It Xr copyin 9F Ta Xr copyout 9F 932*9da20b8aSRobert Mustacchi.It Xr ddi_copyin 9F Ta Xr ddi_copyout 9F 933*9da20b8aSRobert Mustacchi.It Xr ddi_model_convert_from 9F Ta Xr SIZEOF_PTR 9F 934*9da20b8aSRobert Mustacchi.It Xr SIZEOF_STRUCT 9F Ta Xr STRUCT_BUF 9F 935*9da20b8aSRobert Mustacchi.It Xr STRUCT_DECL 9F Ta Xr STRUCT_FADDR 9F 936*9da20b8aSRobert Mustacchi.It Xr STRUCT_FGET 9F Ta Xr STRUCT_FGETP 9F 937*9da20b8aSRobert Mustacchi.It Xr STRUCT_FSET 9F Ta Xr STRUCT_FSETP 9F 938*9da20b8aSRobert Mustacchi.It Xr STRUCT_HANDLE 9F Ta Xr STRUCT_INIT 9F 939*9da20b8aSRobert Mustacchi.It Xr STRUCT_SET_HANDLE 9F Ta Xr STRUCT_SIZE 9F 940*9da20b8aSRobert Mustacchi.It Xr uiomove 9F Ta Xr ureadc 9F 941*9da20b8aSRobert Mustacchi.It Xr uwritec 9F Ta 942*9da20b8aSRobert Mustacchi.El 943*9da20b8aSRobert Mustacchi.Ss Device Register Setup and Access 944*9da20b8aSRobert MustacchiThe kernel abstracts out accessing registers on a device on behalf of 945*9da20b8aSRobert Mustacchidrivers. 946*9da20b8aSRobert MustacchiThis allows a similar set of interfaces to be used whether the registers 947*9da20b8aSRobert Mustacchiare found within a PCI BAR, utilizing I/O ports, memory mapped 948*9da20b8aSRobert Mustacchiregisters, or some other scheme. 949*9da20b8aSRobert MustacchiDevices with registers all have a 950*9da20b8aSRobert Mustacchi.Dq regs 951*9da20b8aSRobert Mustacchiproperty that is set up by their parent device, generally a kernel 952*9da20b8aSRobert Mustacchiframework as is the case for PCIe devices, and the meaning is a contract 953*9da20b8aSRobert Mustacchibetween the two. 954*9da20b8aSRobert MustacchiRegister sets are identified by a numeric ID, which varies on the device 955*9da20b8aSRobert Mustacchitype. 956*9da20b8aSRobert MustacchiFor example, the first BAR of a PCI device is defined as register set 1. 957*9da20b8aSRobert MustacchiOn the other hand, the AMD GPIO controller might have three register sets 958*9da20b8aSRobert Mustacchibecause of how the hardware design splits them up. 959*9da20b8aSRobert MustacchiThe meaning of the registers and their semantics is still 960*9da20b8aSRobert Mustacchidevice-specific. 961*9da20b8aSRobert MustacchiThe kernel doesn't know how to interpret the actual registers of a PCIe 962*9da20b8aSRobert Mustacchidevice say, just that they exist. 963*9da20b8aSRobert Mustacchi.Pp 964*9da20b8aSRobert MustacchiTo begin with register setup, one often first looks at the number of 965*9da20b8aSRobert Mustacchiregister sets that exist and their size. 966*9da20b8aSRobert MustacchiMost PCI-based device drivers will skip calling 967*9da20b8aSRobert Mustacchi.Xr ddi_dev_nregs 9F 968*9da20b8aSRobert Mustacchiand will just move straight to calling 969*9da20b8aSRobert Mustacchi.Xr ddi_dev_regsize 9F 970*9da20b8aSRobert Mustacchito determine the size of a register set that they are interested in. 971*9da20b8aSRobert MustacchiTo actually map the registers, a device driver will call 972*9da20b8aSRobert Mustacchi.Xr ddi_regs_map_setup 9F 973*9da20b8aSRobert Mustacchiwhich requires both a register set and a series of attributes and 974*9da20b8aSRobert Mustacchireturns an access handle that is used to actually read and write the 975*9da20b8aSRobert Mustacchiregisters. 976*9da20b8aSRobert MustacchiWhen setting up registers, one must have a corresponding 977*9da20b8aSRobert Mustacchi.Vt ddi_device_acc_attr_t 978*9da20b8aSRobert Mustacchistructure which is used to define what endianness the register set is 979*9da20b8aSRobert Mustacchiin, whether any kind of reordering is allowed 980*9da20b8aSRobert Mustacchi.Po 981*9da20b8aSRobert Mustacchiif in doubt specify 982*9da20b8aSRobert Mustacchi.Dv DDI_STRICTORDER_ACC 983*9da20b8aSRobert Mustacchi.Pc , 984*9da20b8aSRobert Mustacchiand whether any particular error handling is being used. 985*9da20b8aSRobert MustacchiThe structure and all of its different options are described in 986*9da20b8aSRobert Mustacchi.Xr ddi_device_acc_attr 9S . 987*9da20b8aSRobert Mustacchi.Pp 988*9da20b8aSRobert MustacchiOnce a register handle is obtained, then it's easy to read and write the 989*9da20b8aSRobert Mustacchiregister space. 990*9da20b8aSRobert MustacchiFunctions are organized based on the size of the access. 991*9da20b8aSRobert MustacchiFor the most part, most situations call for the use of the 992*9da20b8aSRobert Mustacchi.Xr ddi_get8 9F , 993*9da20b8aSRobert Mustacchi.Xr ddi_get16 9F , 994*9da20b8aSRobert Mustacchi.Xr ddi_get32 9F , 995*9da20b8aSRobert Mustacchiand 996*9da20b8aSRobert Mustacchi.Xr ddi_get64 9F 997*9da20b8aSRobert Mustacchifunctions to read a register and the 998*9da20b8aSRobert Mustacchi.Xr ddi_put8 9F , 999*9da20b8aSRobert Mustacchi.Xr ddi_put16 9F , 1000*9da20b8aSRobert Mustacchi.Xr ddi_put32 9F , 1001*9da20b8aSRobert Mustacchiand 1002*9da20b8aSRobert Mustacchi.Xr ddi_put64 9F 1003*9da20b8aSRobert Mustacchifunctions to set a register value. 1004*9da20b8aSRobert MustacchiWhile there are the ddi_io_ and ddi_mem_ families of functions below, 1005*9da20b8aSRobert Mustacchithese are not generally needed and are generally present for 1006*9da20b8aSRobert Mustacchicompatibility. 1007*9da20b8aSRobert MustacchiThe kernel will automatically perform the appropriate type of register 1008*9da20b8aSRobert Mustacchiread for the device type in question. 1009*9da20b8aSRobert Mustacchi.Pp 1010*9da20b8aSRobert MustacchiOnce a register set is no longer being used, the 1011*9da20b8aSRobert Mustacchi.Xr ddi_regs_map_free 9F 1012*9da20b8aSRobert Mustacchifunction should be used to release resources. 1013*9da20b8aSRobert MustacchiIn most cases, this happens while executing the 1014*9da20b8aSRobert Mustacchi.Xr detach 9E 1015*9da20b8aSRobert Mustacchientry point. 1016*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1017*9da20b8aSRobert Mustacchi.It Xr ddi_dev_nregs 9F Ta Xr ddi_dev_regsize 9F 1018*9da20b8aSRobert Mustacchi.It Xr ddi_device_copy 9F Ta Xr ddi_device_zero 9F 1019*9da20b8aSRobert Mustacchi.It Xr ddi_regs_map_free 9F Ta Xr ddi_regs_map_setup 9F 1020*9da20b8aSRobert Mustacchi.It Xr ddi_get8 9F Ta Xr ddi_get16 9F 1021*9da20b8aSRobert Mustacchi.It Xr ddi_get32 9F Ta Xr ddi_get64 9F 1022*9da20b8aSRobert Mustacchi.It Xr ddi_io_get8 9F Ta Xr ddi_io_get16 9F 1023*9da20b8aSRobert Mustacchi.It Xr ddi_io_get32 9F Ta Xr ddi_io_put8 9F 1024*9da20b8aSRobert Mustacchi.It Xr ddi_io_put16 9F Ta Xr ddi_io_put32 9F 1025*9da20b8aSRobert Mustacchi.It Xr ddi_io_rep_get8 9F Ta Xr ddi_io_rep_get16 9F 1026*9da20b8aSRobert Mustacchi.It Xr ddi_io_rep_get32 9F Ta Xr ddi_io_rep_put8 9F 1027*9da20b8aSRobert Mustacchi.It Xr ddi_io_rep_put16 9F Ta Xr ddi_io_rep_put32 9F 1028*9da20b8aSRobert Mustacchi.It Xr ddi_map_regs 9F Ta Xr ddi_mem_get8 9F 1029*9da20b8aSRobert Mustacchi.It Xr ddi_mem_get16 9F Ta Xr ddi_mem_get32 9F 1030*9da20b8aSRobert Mustacchi.It Xr ddi_mem_get64 9F Ta Xr ddi_mem_put8 9F 1031*9da20b8aSRobert Mustacchi.It Xr ddi_mem_put16 9F Ta Xr ddi_mem_put32 9F 1032*9da20b8aSRobert Mustacchi.It Xr ddi_mem_put64 9F Ta Xr ddi_mem_rep_get8 9F 1033*9da20b8aSRobert Mustacchi.It Xr ddi_mem_rep_get16 9F Ta Xr ddi_mem_rep_get32 9F 1034*9da20b8aSRobert Mustacchi.It Xr ddi_mem_rep_get64 9F Ta Xr ddi_mem_rep_put8 9F 1035*9da20b8aSRobert Mustacchi.It Xr ddi_mem_rep_put16 9F Ta Xr ddi_mem_rep_put32 9F 1036*9da20b8aSRobert Mustacchi.It Xr ddi_mem_rep_put64 9F Ta Xr ddi_peek8 9F 1037*9da20b8aSRobert Mustacchi.It Xr ddi_peek16 9F Ta Xr ddi_peek32 9F 1038*9da20b8aSRobert Mustacchi.It Xr ddi_peek64 9F Ta Xr ddi_poke8 9F 1039*9da20b8aSRobert Mustacchi.It Xr ddi_poke16 9F Ta Xr ddi_poke32 9F 1040*9da20b8aSRobert Mustacchi.It Xr ddi_poke64 9F Ta Xr ddi_put8 9F 1041*9da20b8aSRobert Mustacchi.It Xr ddi_put16 9F Ta Xr ddi_put32 9F 1042*9da20b8aSRobert Mustacchi.It Xr ddi_put64 9F Ta Xr ddi_rep_get8 9F 1043*9da20b8aSRobert Mustacchi.It Xr ddi_rep_get16 9F Ta Xr ddi_rep_get32 9F 1044*9da20b8aSRobert Mustacchi.It Xr ddi_rep_get64 9F Ta Xr ddi_rep_put8 9F 1045*9da20b8aSRobert Mustacchi.It Xr ddi_rep_put16 9F Ta Xr ddi_rep_put32 9F 1046*9da20b8aSRobert Mustacchi.It Xr ddi_rep_put64 9F Ta 1047*9da20b8aSRobert Mustacchi.El 1048*9da20b8aSRobert Mustacchi.Ss DMA Related Functions 1049*9da20b8aSRobert MustacchiMost high-performance devices provide first-class support for DMA 1050*9da20b8aSRobert Mustacchi.Pq direct memory access . 1051*9da20b8aSRobert MustacchiDMA allows a transfer between a device and memory to occur 1052*9da20b8aSRobert Mustacchiasynchronously and generally without a thread's specific involvement. 1053*9da20b8aSRobert MustacchiToday, most DMA is provided directly by devices and the corresponding 1054*9da20b8aSRobert Mustacchidevice scheme. 1055*9da20b8aSRobert MustacchiTake PCI and PCI Express for example. 1056*9da20b8aSRobert MustacchiThe idea of DMA is built into the PCIe standard and therefore basic 1057*9da20b8aSRobert Mustacchisupport for it exists and therefore there isn't a lot of special 1058*9da20b8aSRobert Mustacchiprogramming required. 1059*9da20b8aSRobert MustacchiHowever, this hasn't always been true and still exists in some cases 1060*9da20b8aSRobert Mustacchiwhere there is a 3rd party DMA engine. 1061*9da20b8aSRobert MustacchiIf we consider the PCIe example, the PCIe device directly performs reads 1062*9da20b8aSRobert Mustacchiand writes to main memory on its own. 1063*9da20b8aSRobert MustacchiHowever, in the 3rd party case, there is a distinct controller that is 1064*9da20b8aSRobert Mustacchineither the device nor memory that facilitates this, which is called a 1065*9da20b8aSRobert MustacchiDMA engine. 1066*9da20b8aSRobert MustacchiFor most part, DMA engines are not something that needs to be thought 1067*9da20b8aSRobert Mustacchiabout for most platforms that illumos is present on; however, they still 1068*9da20b8aSRobert Mustacchiexist in some embedded and related contexts. 1069*9da20b8aSRobert Mustacchi.Pp 1070*9da20b8aSRobert MustacchiThe first thing that a driver needs to do to set up DMA is to understand 1071*9da20b8aSRobert Mustacchithe constraints of the device and bus. 1072*9da20b8aSRobert MustacchiThese constraints are described in a series of attributes in the 1073*9da20b8aSRobert Mustacchi.Vt ddi_dma_attr_t 1074*9da20b8aSRobert Mustacchistructure which is defined in 1075*9da20b8aSRobert Mustacchi.Xr ddi_dma_attr 9S . 1076*9da20b8aSRobert MustacchiThe reason that attributes exist is because different devices, and 1077*9da20b8aSRobert Mustacchisometimes different memory uses with a device, have different 1078*9da20b8aSRobert Mustacchirequirements for memory. 1079*9da20b8aSRobert MustacchiA simple example of this is that not all devices can accept memory 1080*9da20b8aSRobert Mustacchiaddresses that are 64-bits wide and may have to be constrained to the 1081*9da20b8aSRobert Mustacchilower 32-bits of memory. 1082*9da20b8aSRobert MustacchiAnother common constraint is how this memory is chunked up. 1083*9da20b8aSRobert MustacchiSome devices may require that all of the DMA memory be contiguous, while 1084*9da20b8aSRobert Mustacchiothers can allow that to be broken up into say up to 4 or 8 different 1085*9da20b8aSRobert Mustacchiregions. 1086*9da20b8aSRobert Mustacchi.Pp 1087*9da20b8aSRobert MustacchiWhen memory is allocated for DMA it isn't immediately mapped into the 1088*9da20b8aSRobert Mustacchikernel's address space. 1089*9da20b8aSRobert MustacchiThe addresses that describe a DMA address are defined in a DMA cookie, 1090*9da20b8aSRobert Mustacchiseveral of which may make up a request. 1091*9da20b8aSRobert MustacchiHowever, those addresses are always physical addresses or addresses that 1092*9da20b8aSRobert Mustacchiare virtualized by an IOMMU. 1093*9da20b8aSRobert MustacchiThere are some cases were the kernel or a driver needs to be able to 1094*9da20b8aSRobert Mustacchiaccess that memory, such as memory that represents a networking packet. 1095*9da20b8aSRobert MustacchiThe IP stack will expect to be able to actually read the data it's 1096*9da20b8aSRobert Mustacchigiven. 1097*9da20b8aSRobert Mustacchi.Pp 1098*9da20b8aSRobert MustacchiTo begin with allocating DMA memory, a driver first fills out its 1099*9da20b8aSRobert Mustacchiattribute structure. 1100*9da20b8aSRobert MustacchiOnce that's ready, the DMA allocation process can begin. 1101*9da20b8aSRobert MustacchiThis starts off by a driver calling 1102*9da20b8aSRobert Mustacchi.Xr ddi_dma_alloc_handle 9F . 1103*9da20b8aSRobert MustacchiThis handle is used through the lifetime of a given DMA memory buffer, 1104*9da20b8aSRobert Mustacchibut it can be used across multiple operations that a device or the 1105*9da20b8aSRobert Mustacchikernel may perform. 1106*9da20b8aSRobert MustacchiThe next step is to actually request that the kernel allocate some 1107*9da20b8aSRobert Mustacchiamount of memory in the kernel for this DMA request. 1108*9da20b8aSRobert MustacchiThis phase actually allocates addresses in virtual address space for the 1109*9da20b8aSRobert Mustacchiactivity and also requires a register attribute object that is discussed 1110*9da20b8aSRobert Mustacchiin 1111*9da20b8aSRobert Mustacchi.Sx Device Register Setup and Access . 1112*9da20b8aSRobert MustacchiArmed with this a driver can now call 1113*9da20b8aSRobert Mustacchi.Xr ddi_dma_mem_alloc 9F 1114*9da20b8aSRobert Mustacchito specify how much memory they are looking for. 1115*9da20b8aSRobert MustacchiIf this is successful, a virtual address, the actual length of the 1116*9da20b8aSRobert Mustacchiregion, and an access handle will be returned. 1117*9da20b8aSRobert Mustacchi.Pp 1118*9da20b8aSRobert MustacchiAt this point, the virtual address region is present. 1119*9da20b8aSRobert MustacchiMost drivers will access this virtual address range directly and will 1120*9da20b8aSRobert Mustacchiignore the register access handle. 1121*9da20b8aSRobert MustacchiThe side effect of this is that they will handle all endianness issues 1122*9da20b8aSRobert Mustacchiwith the memory region themselves. 1123*9da20b8aSRobert MustacchiIf the driver would prefer to go through the handle, then it can use the 1124*9da20b8aSRobert Mustacchiregister access functions discussed earlier. 1125*9da20b8aSRobert Mustacchi.Pp 1126*9da20b8aSRobert MustacchiBefore the memory can be programmed into the device, it must be bound to 1127*9da20b8aSRobert Mustacchia series of physical addresses or addresses virtualized by an IOMMU. 1128*9da20b8aSRobert MustacchiWhile the kernel presents the illusion of a single consistent virtual 1129*9da20b8aSRobert Mustacchiaddress range for applications, the physical reality can be quite 1130*9da20b8aSRobert Mustacchidifferent. 1131*9da20b8aSRobert MustacchiWhen the driver is ready it calls 1132*9da20b8aSRobert Mustacchi.Xr ddi_dma_addr_bind_handle 9F 1133*9da20b8aSRobert Mustacchito create the mapping to well known physical addresses. 1134*9da20b8aSRobert Mustacchi.Pp 1135*9da20b8aSRobert MustacchiThese addresses are stored in a series of cookies. 1136*9da20b8aSRobert MustacchiA driver can determine the number of cookies for a given request by 1137*9da20b8aSRobert Mustacchiutilizing its DMA handle and calling 1138*9da20b8aSRobert Mustacchi.Xr ddi_dma_ncookies 9F 1139*9da20b8aSRobert Mustacchiand then pairing that with 1140*9da20b8aSRobert Mustacchi.Xr ddi_dma_cookie_get 9F . 1141*9da20b8aSRobert MustacchiThese DMA cookies will not change and can be used time and time again 1142*9da20b8aSRobert Mustacchiuntil 1143*9da20b8aSRobert Mustacchi.Xr ddi_dma_unbind_handle 9F 1144*9da20b8aSRobert Mustacchiis called. 1145*9da20b8aSRobert MustacchiWith this information in hand, a physical device can be programmed with 1146*9da20b8aSRobert Mustacchithese addresses and let loose to perform I/O. 1147*9da20b8aSRobert Mustacchi.Pp 1148*9da20b8aSRobert MustacchiWhen performing I/O to and from a device, synchronization is a vitally 1149*9da20b8aSRobert Mustacchiimportant thing which ensures that the actual state in memory is 1150*9da20b8aSRobert Mustacchicoherent with the rest of the CPU's internal structures such as caches. 1151*9da20b8aSRobert MustacchiIn general, a given DMA request is only going in one direction: for a 1152*9da20b8aSRobert Mustacchidevice or for the local CPU. 1153*9da20b8aSRobert MustacchiIn either case, the 1154*9da20b8aSRobert Mustacchi.Xr ddi_dma_sync 9F 1155*9da20b8aSRobert Mustacchifunction must be called after the kernel is done writing to a region of 1156*9da20b8aSRobert MustacchiDMA memory and before it triggers the device or the kernel must call it 1157*9da20b8aSRobert Mustacchiafter the device has told it that some activity has completed that it is 1158*9da20b8aSRobert Mustacchigoing to check. 1159*9da20b8aSRobert Mustacchi.Pp 1160*9da20b8aSRobert MustacchiSome DMA operations utilize what are called DMA windows. 1161*9da20b8aSRobert MustacchiThe most common consumer is something like a disk device where DMA 1162*9da20b8aSRobert Mustacchioperations to a given series of sectors can be split up into different 1163*9da20b8aSRobert Mustacchichunks where as long as all the transfers are performed, the 1164*9da20b8aSRobert Mustacchiintermediate states are acceptable. 1165*9da20b8aSRobert MustacchiPut another way, because of how SCSI and SAS commands are designed, 1166*9da20b8aSRobert Mustacchiblock devices can basically take a given I/O request and break it into 1167*9da20b8aSRobert Mustacchimultiple independent I/Os that will equate to the same final item. 1168*9da20b8aSRobert Mustacchi.Pp 1169*9da20b8aSRobert MustacchiWhen a device supports this mode of operation and it is opted into, then 1170*9da20b8aSRobert Mustacchia DMA allocation may result in the use of DMA windows. 1171*9da20b8aSRobert MustacchiThis allows for cases where the kernel can't perform a DMA allocation 1172*9da20b8aSRobert Mustacchifor the entire request, but instead can allocate a partial region and 1173*9da20b8aSRobert Mustacchithen walk through each part one at a time. 1174*9da20b8aSRobert MustacchiThis is uncommon outside of block devices and usually also is related to 1175*9da20b8aSRobert Mustacchicalling 1176*9da20b8aSRobert Mustacchi.Xr ddi_dma_buf_bind_handle 9F . 1177*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1178*9da20b8aSRobert Mustacchi.It Xr ddi_dma_addr_bind_handle 9F Ta Xr ddi_dma_alloc_handle 9F 1179*9da20b8aSRobert Mustacchi.It Xr ddi_dma_buf_bind_handle 9F Ta Xr ddi_dma_burstsizes 9F 1180*9da20b8aSRobert Mustacchi.It Xr ddi_dma_cookie_get 9F Ta Xr ddi_dma_cookie_iter 9F 1181*9da20b8aSRobert Mustacchi.It Xr ddi_dma_cookie_one 9F Ta Xr ddi_dma_free_handle 9F 1182*9da20b8aSRobert Mustacchi.It Xr ddi_dma_getwin 9F Ta Xr ddi_dma_mem_alloc 9F 1183*9da20b8aSRobert Mustacchi.It Xr ddi_dma_mem_free 9F Ta Xr ddi_dma_ncookies 9F 1184*9da20b8aSRobert Mustacchi.It Xr ddi_dma_nextcookie 9F Ta Xr ddi_dma_numwin 9F 1185*9da20b8aSRobert Mustacchi.It Xr ddi_dma_set_sbus64 9F Ta Xr ddi_dma_sync 9F 1186*9da20b8aSRobert Mustacchi.It Xr ddi_dma_unbind_handle 9F Ta Xr ddi_dmae_1stparty 9F 1187*9da20b8aSRobert Mustacchi.It Xr ddi_dmae_alloc 9F Ta Xr ddi_dmae_disable 9F 1188*9da20b8aSRobert Mustacchi.It Xr ddi_dmae_enable 9F Ta Xr ddi_dmae_getattr 9F 1189*9da20b8aSRobert Mustacchi.It Xr ddi_dmae_getcnt 9F Ta Xr ddi_dmae_prog 9F 1190*9da20b8aSRobert Mustacchi.It Xr ddi_dmae_release 9F Ta Xr ddi_dmae_stop 9F 1191*9da20b8aSRobert Mustacchi.It Xr ddi_dmae 9F Ta 1192*9da20b8aSRobert Mustacchi.El 1193*9da20b8aSRobert Mustacchi.Ss Interrupt Handler Related Functions 1194*9da20b8aSRobert MustacchiInterrupts are a central part of the role of device drivers and one of 1195*9da20b8aSRobert Mustacchithe things that's important to get right. 1196*9da20b8aSRobert MustacchiInterrupts come in different types: fixed, MSI, and MSI-X. 1197*9da20b8aSRobert MustacchiThe kinds that are available depend on the device and the rest of the 1198*9da20b8aSRobert Mustacchisystem. 1199*9da20b8aSRobert MustacchiFor example, MSI and MSI-X interrupts are generally specific to PCI and 1200*9da20b8aSRobert MustacchiPCI Express devices. 1201*9da20b8aSRobert MustacchiTo begin the interrupt allocation process, the first thing a driver 1202*9da20b8aSRobert Mustacchineeds to do is to discover what type of interrupts it supports with 1203*9da20b8aSRobert Mustacchi.Xr ddi_intr_get_supported_types 9F . 1204*9da20b8aSRobert MustacchiThen, the driver should work through the supported types, preferring 1205*9da20b8aSRobert MustacchiMSI-X, then MSI, and finally fixed interrupts, and try to allocate 1206*9da20b8aSRobert Mustacchiinterrupts. 1207*9da20b8aSRobert Mustacchi.Pp 1208*9da20b8aSRobert MustacchiDrivers first need to know how many interrupts that they require. 1209*9da20b8aSRobert MustacchiFor example, a networking driver may want to have an interrupt made 1210*9da20b8aSRobert Mustacchiavailable for each ring that it has. 1211*9da20b8aSRobert MustacchiTo discover the number of interrupts available, the driver should call 1212*9da20b8aSRobert Mustacchi.Xr ddi_intr_get_navail 9F . 1213*9da20b8aSRobert MustacchiIf there are sufficient interrupts, it can proceed to actually 1214*9da20b8aSRobert Mustacchiallocate the interrupts with 1215*9da20b8aSRobert Mustacchi.Xr ddi_intr_alloc 9F . 1216*9da20b8aSRobert MustacchiWhen allocating interrupts, callers need to check to see how many 1217*9da20b8aSRobert Mustacchiinterrupts the system actually gave them. 1218*9da20b8aSRobert MustacchiJust because an interrupt is allocated does not mean that it will fire 1219*9da20b8aSRobert Mustacchior be ready to use, there are a series of additional steps that the 1220*9da20b8aSRobert Mustacchidriver must take. 1221*9da20b8aSRobert Mustacchi.Pp 1222*9da20b8aSRobert MustacchiTo go through and enable the interrupt, the driver should go through and 1223*9da20b8aSRobert Mustacchiget the interrupt capabilities with 1224*9da20b8aSRobert Mustacchi.Xr ddi_intr_get_cap 9F 1225*9da20b8aSRobert Mustacchiand the priority of the interrupt with 1226*9da20b8aSRobert Mustacchi.Xr ddi_intr_get_pri 9F . 1227*9da20b8aSRobert MustacchiThe priority must be used while creating mutexes and related 1228*9da20b8aSRobert Mustacchisynchronization primitives that will be used during the interrupt 1229*9da20b8aSRobert Mustacchihandler. 1230*9da20b8aSRobert MustacchiAt this point, the driver can go ahead and register the functions that 1231*9da20b8aSRobert Mustacchiwill be called with each allocated interrupt with the 1232*9da20b8aSRobert Mustacchi.Xr ddi_intr_add_handler 9F 1233*9da20b8aSRobert Mustacchifunction. 1234*9da20b8aSRobert MustacchiThe arguments can vary for each allocated interrupt. 1235*9da20b8aSRobert MustacchiIt is common to have an interrupt-specific data structure passed in one 1236*9da20b8aSRobert Mustacchiof the arguments or an interrupt number, while the other argument is 1237*9da20b8aSRobert Mustacchigenerally the driver's instance-specific data structure. 1238*9da20b8aSRobert Mustacchi.Pp 1239*9da20b8aSRobert MustacchiAt this point, the last step for the interrupt to be made active from 1240*9da20b8aSRobert Mustacchithe kernel's perspective is to enable it. 1241*9da20b8aSRobert MustacchiThis will use either the 1242*9da20b8aSRobert Mustacchi.Xr ddi_intr_block_enable 9F 1243*9da20b8aSRobert Mustacchior 1244*9da20b8aSRobert Mustacchi.Xr ddi_intr_enable 9F 1245*9da20b8aSRobert Mustacchifunctions depending on the interrupt's capabilities. 1246*9da20b8aSRobert MustacchiThe reason that these are different is because some interrupt types 1247*9da20b8aSRobert Mustacchi.Pq MSI 1248*9da20b8aSRobert Mustacchirequire that all interrupts in a group be enabled and disabled at the 1249*9da20b8aSRobert Mustacchisame time. 1250*9da20b8aSRobert MustacchiThis is indicated with the 1251*9da20b8aSRobert Mustacchi.Dv DDI_INTR_FLAG_BLOCK 1252*9da20b8aSRobert Mustacchiflag found in the interrupt's capabilities. 1253*9da20b8aSRobert MustacchiOnce that is called, interrupts that are generated by a device will be 1254*9da20b8aSRobert Mustacchidelivered to the registered function. 1255*9da20b8aSRobert Mustacchi.Pp 1256*9da20b8aSRobert MustacchiIt's important to note that there is often device-specific interrupt 1257*9da20b8aSRobert Mustacchisetup that is required. 1258*9da20b8aSRobert MustacchiWhile the kernel takes care of updating any pieces of the processor's 1259*9da20b8aSRobert Mustacchiinterrupt controller, I/O crossbar, or the PCI MSI and MSI-X 1260*9da20b8aSRobert Mustacchicapabilities, many devices have device-specific registers that are used 1261*9da20b8aSRobert Mustacchito manage, set up, and acknowledge interrupts. 1262*9da20b8aSRobert MustacchiThese registers or other controls are often capable of separately 1263*9da20b8aSRobert Mustacchimasking interrupts and are generally what should be used if there are 1264*9da20b8aSRobert Mustacchitimes that you need to separately enable or disable interrupts such as 1265*9da20b8aSRobert Mustacchito poll an I/O ring. 1266*9da20b8aSRobert Mustacchi.Pp 1267*9da20b8aSRobert MustacchiWhen unwinding interrupts, one needs to work in the reverse order here. 1268*9da20b8aSRobert MustacchiUntil 1269*9da20b8aSRobert Mustacchi.Xr ddi_intr_block_disable 9F 1270*9da20b8aSRobert Mustacchior 1271*9da20b8aSRobert Mustacchi.Xr ddi_intr_disable 9F 1272*9da20b8aSRobert Mustacchiis called, one should assume that their interrupt handler will be 1273*9da20b8aSRobert Mustacchicalled. 1274*9da20b8aSRobert MustacchiDue to cases where an interrupt is shared between multiple devices, this 1275*9da20b8aSRobert Mustacchican happen even if the device is quiesced! 1276*9da20b8aSRobert MustacchiOnly after that is done is it safe to then free the interrupts with a 1277*9da20b8aSRobert Mustacchicall to 1278*9da20b8aSRobert Mustacchi.Xr ddi_intr_free 9F . 1279*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1280*9da20b8aSRobert Mustacchi.It Xr ddi_add_intr 9F Ta Xr ddi_add_softintr 9F 1281*9da20b8aSRobert Mustacchi.It Xr ddi_get_iblock_cookie 9F Ta Xr ddi_get_soft_iblock_cookie 9F 1282*9da20b8aSRobert Mustacchi.It Xr ddi_intr_add_handler 9F Ta Xr ddi_intr_add_softint 9F 1283*9da20b8aSRobert Mustacchi.It Xr ddi_intr_alloc 9F Ta Xr ddi_intr_block_disable 9F 1284*9da20b8aSRobert Mustacchi.It Xr ddi_intr_block_enable 9F Ta Xr ddi_intr_clr_mask 9F 1285*9da20b8aSRobert Mustacchi.It Xr ddi_intr_disable 9F Ta Xr ddi_intr_dup_handler 9F 1286*9da20b8aSRobert Mustacchi.It Xr ddi_intr_enable 9F Ta Xr ddi_intr_free 9F 1287*9da20b8aSRobert Mustacchi.It Xr ddi_intr_get_cap 9F Ta Xr ddi_intr_get_hilevel_pri 9F 1288*9da20b8aSRobert Mustacchi.It Xr ddi_intr_get_navail 9F Ta Xr ddi_intr_get_nintrs 9F 1289*9da20b8aSRobert Mustacchi.It Xr ddi_intr_get_pending 9F Ta Xr ddi_intr_get_pri 9F 1290*9da20b8aSRobert Mustacchi.It Xr ddi_intr_get_softint_pri 9F Ta Xr ddi_intr_get_supported_types 9F 1291*9da20b8aSRobert Mustacchi.It Xr ddi_intr_hilevel 9F Ta Xr ddi_intr_remove_handler 9F 1292*9da20b8aSRobert Mustacchi.It Xr ddi_intr_remove_softint 9F Ta Xr ddi_intr_set_cap 9F 1293*9da20b8aSRobert Mustacchi.It Xr ddi_intr_set_mask 9F Ta Xr ddi_intr_set_nreq 9F 1294*9da20b8aSRobert Mustacchi.It Xr ddi_intr_set_pri 9F Ta Xr ddi_intr_set_softint_pri 9F 1295*9da20b8aSRobert Mustacchi.It Xr ddi_intr_trigger_softint 9F Ta Xr ddi_remove_intr 9F 1296*9da20b8aSRobert Mustacchi.It Xr ddi_remove_softintr 9F Ta Xr ddi_trigger_softintr 9F 1297*9da20b8aSRobert Mustacchi.El 1298*9da20b8aSRobert Mustacchi.Ss Minor Nodes 1299*9da20b8aSRobert MustacchiFor a device driver to be accessed by a program in user space 1300*9da20b8aSRobert Mustacchi.Pq or with the kernel layered device interface 1301*9da20b8aSRobert Mustacchithen it must create a minor node. 1302*9da20b8aSRobert MustacchiMinor nodes are created under 1303*9da20b8aSRobert Mustacchi.Pa /devices 1304*9da20b8aSRobert Mustacchi.Pq Xr devfs 4FS 1305*9da20b8aSRobert Mustacchiand are tied to the instance of a device driver via its 1306*9da20b8aSRobert Mustacchi.Vt dev_info_t . 1307*9da20b8aSRobert MustacchiThe 1308*9da20b8aSRobert Mustacchi.Xr devfsadm 8 1309*9da20b8aSRobert Mustacchidaemon and the 1310*9da20b8aSRobert Mustacchi.Pa /dev 1311*9da20b8aSRobert Mustacchifile system 1312*9da20b8aSRobert Mustacchi.Po 1313*9da20b8aSRobert Mustacchisdev, 1314*9da20b8aSRobert Mustacchi.Xr dev 4FS 1315*9da20b8aSRobert Mustacchi.Pc 1316*9da20b8aSRobert Mustacchiare responsible for creating a coherent set of names that user programs 1317*9da20b8aSRobert Mustacchiaccess. 1318*9da20b8aSRobert MustacchiDrivers create these minor nodes using the 1319*9da20b8aSRobert Mustacchi.Xr ddi_create_minor_node 9F 1320*9da20b8aSRobert Mustacchifunction listed below. 1321*9da20b8aSRobert Mustacchi.Pp 1322*9da20b8aSRobert MustacchiIn UNIX tradition, character, block, and STREAMS device special files 1323*9da20b8aSRobert Mustacchiare identified by a major and minor number. 1324*9da20b8aSRobert MustacchiAll instances of a given driver share the same major number, which means 1325*9da20b8aSRobert Mustacchithat a device driver must coordinate the minor number space across 1326*9da20b8aSRobert Mustacchi.Em all 1327*9da20b8aSRobert Mustacchiinstances. 1328*9da20b8aSRobert MustacchiWhile a minor node is created with a fixed minor number, it is possible 1329*9da20b8aSRobert Mustacchito change the minor number while processing an 1330*9da20b8aSRobert Mustacchi.Xr open 9E 1331*9da20b8aSRobert Mustacchicall, allowing subsequent character device operations to uniquely 1332*9da20b8aSRobert Mustacchiidentify a particular caller. 1333*9da20b8aSRobert MustacchiThis is usually referred to as a driver that 1334*9da20b8aSRobert Mustacchi.Dq clones . 1335*9da20b8aSRobert Mustacchi.Pp 1336*9da20b8aSRobert MustacchiWhen drivers aren't performing cloning, then usually the minor number 1337*9da20b8aSRobert Mustacchiused when creating the minor node is some fixed offset or multiple of 1338*9da20b8aSRobert Mustacchithe driver's instance number. 1339*9da20b8aSRobert MustacchiWhen cloning and a driver needs to allocate and manage a minor number 1340*9da20b8aSRobert Mustacchispace, usually an ID space is leveraged whose IDs are usually in the 1341*9da20b8aSRobert Mustacchirange from 0 through 1342*9da20b8aSRobert Mustacchi.Dv MAXMIN32 . 1343*9da20b8aSRobert MustacchiThere are severa different strategies for tracking data structures as 1344*9da20b8aSRobert Mustacchithey relate to minor numbers. 1345*9da20b8aSRobert MustacchiSometimes, the soft state functionality is used. 1346*9da20b8aSRobert MustacchiOthers might keep an AVL tree around or tie the data to some other data 1347*9da20b8aSRobert Mustacchistructure. 1348*9da20b8aSRobert MustacchiThe method chosen often varies on the specifics of the implementation 1349*9da20b8aSRobert Mustacchiand its broader context. 1350*9da20b8aSRobert Mustacchi.Pp 1351*9da20b8aSRobert MustacchiThe 1352*9da20b8aSRobert Mustacchi.Vt dev_t 1353*9da20b8aSRobert Mustacchistructure represents the combined major and minor number. 1354*9da20b8aSRobert MustacchiIt can be taken apart with the 1355*9da20b8aSRobert Mustacchi.Xr getmajor 9F 1356*9da20b8aSRobert Mustacchiand 1357*9da20b8aSRobert Mustacchi.Xr getminor 9F 1358*9da20b8aSRobert Mustacchifunctions and then reconstructed with the 1359*9da20b8aSRobert Mustacchi.Xr makedevice 9F 1360*9da20b8aSRobert Mustacchifunction. 1361*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1362*9da20b8aSRobert Mustacchi.It Xr ddi_create_minor_node 9F Ta Xr ddi_remove_minor_node 9F 1363*9da20b8aSRobert Mustacchi.It Xr getmajor 9F Ta Xr getminor 9F 1364*9da20b8aSRobert Mustacchi.It Xr devfs_clean 9F Ta Xr makedevice 9F 1365*9da20b8aSRobert Mustacchi.El 1366*9da20b8aSRobert Mustacchi.Ss Accessing Time, Delays, and Periodic Events 1367*9da20b8aSRobert MustacchiThe kernel provides a number of ways to understand time in the system. 1368*9da20b8aSRobert MustacchiIn particular it provides a few different clocks and time measurements: 1369*9da20b8aSRobert Mustacchi.Bl -tag -width Ds 1370*9da20b8aSRobert Mustacchi.It High-resolution monotonic time 1371*9da20b8aSRobert MustacchiThe kernel provides access to a high-resolution monotonic clock that is 1372*9da20b8aSRobert Mustacchitracked in nanoseconds. 1373*9da20b8aSRobert MustacchiThis clock is perfect for measuring durations and is accessed via 1374*9da20b8aSRobert Mustacchi.Xr gethrtime 9F . 1375*9da20b8aSRobert MustacchiUnlike the real-time clock, this clock is not subject to adjustments by 1376*9da20b8aSRobert Mustacchia time synchronization daemon and is the preferred clock that drivers 1377*9da20b8aSRobert Mustacchishould be using for tracking events. 1378*9da20b8aSRobert MustacchiThe high-resolution clock is consistent across CPUs, meaning that you 1379*9da20b8aSRobert Mustacchimay call 1380*9da20b8aSRobert Mustacchi.Xr gethrtime 9F 1381*9da20b8aSRobert Mustacchion one CPU and the value will be consistent with what is returned, even 1382*9da20b8aSRobert Mustacchiif a thread is migrated to another CPU. 1383*9da20b8aSRobert Mustacchi.Pp 1384*9da20b8aSRobert MustacchiThe high-resolution clock is implemented using an architecture and 1385*9da20b8aSRobert Mustacchiplatform-specific means. 1386*9da20b8aSRobert MustacchiFor example, on x86 it is generally backed by the TSC 1387*9da20b8aSRobert Mustacchi.Pq time stamp counter . 1388*9da20b8aSRobert Mustacchi.It Real-time 1389*9da20b8aSRobert MustacchiThe real-time clock tracks time as humans perceive it. 1390*9da20b8aSRobert MustacchiThis clock is accessed using 1391*9da20b8aSRobert Mustacchi.Xr ddi_get_time 9F . 1392*9da20b8aSRobert MustacchiIf the system is running a time synchronization daemon that leverages 1393*9da20b8aSRobert Mustacchithe network time protocol, then this time may be in sync with other 1394*9da20b8aSRobert Mustacchisystems 1395*9da20b8aSRobert Mustacchi.Pq subject to some amount of variance ; 1396*9da20b8aSRobert Mustacchihowever, it is critical that this is not assumed. 1397*9da20b8aSRobert Mustacchi.Pp 1398*9da20b8aSRobert MustacchiIn general, this time should not be used by drivers for any purpose. 1399*9da20b8aSRobert MustacchiIt can jump around, drift, and most aspects in the kernel are not based 1400*9da20b8aSRobert Mustacchion the real-time clock. 1401*9da20b8aSRobert MustacchiFor any device timing activities, the high-resolution clock should be 1402*9da20b8aSRobert Mustacchiused. 1403*9da20b8aSRobert Mustacchi.It Tick-based monotonic time 1404*9da20b8aSRobert MustacchiThe kernel has a running periodic function that fires based on the rate 1405*9da20b8aSRobert Mustacchidictated by the 1406*9da20b8aSRobert Mustacchi.Va hz 1407*9da20b8aSRobert Mustacchivariable, generally operating at 100 or 1000 kHz. 1408*9da20b8aSRobert MustacchiThe current number of ticks since boot is accessible through the 1409*9da20b8aSRobert Mustacchi.Xr ddi_get_lbolt 9F 1410*9da20b8aSRobert Mustacchifunction. 1411*9da20b8aSRobert MustacchiWhen functions operate in units of ticks, this is what they are 1412*9da20b8aSRobert Mustacchitracking. 1413*9da20b8aSRobert MustacchiThis value can be converted to and from microseconds using the 1414*9da20b8aSRobert Mustacchi.Xr drv_usectohz 9F 1415*9da20b8aSRobert Mustacchiand 1416*9da20b8aSRobert Mustacchi.Xr drv_hztousec 9F 1417*9da20b8aSRobert Mustacchifunctions. 1418*9da20b8aSRobert Mustacchi.Pp 1419*9da20b8aSRobert MustacchiIn general, drivers should prefer the high-resolution monotonic clock 1420*9da20b8aSRobert Mustacchifor tracking events internally. 1421*9da20b8aSRobert Mustacchi.El 1422*9da20b8aSRobert Mustacchi.Pp 1423*9da20b8aSRobert MustacchiWith these different timing mechanisms, the kernel provides a few 1424*9da20b8aSRobert Mustacchidifferent ways to delay execution or to get a callback after some 1425*9da20b8aSRobert Mustacchiamount of time passes. 1426*9da20b8aSRobert Mustacchi.Pp 1427*9da20b8aSRobert MustacchiThe 1428*9da20b8aSRobert Mustacchi.Xr delay 9F 1429*9da20b8aSRobert Mustacchiand 1430*9da20b8aSRobert Mustacchi.Xr drv_usecwait 9F 1431*9da20b8aSRobert Mustacchifunctions are used to block the execution of the current thread. 1432*9da20b8aSRobert Mustacchi.Xr delay 9F 1433*9da20b8aSRobert Mustacchican be used in conditions where sleeping and blocking is allowed where 1434*9da20b8aSRobert Mustacchias 1435*9da20b8aSRobert Mustacchi.Xr drv_usecwait 9F 1436*9da20b8aSRobert Mustacchiis a busy-wait, which is appropriate for some device drivers, 1437*9da20b8aSRobert Mustacchiparticularly when in high-level interrupt context. 1438*9da20b8aSRobert Mustacchi.Pp 1439*9da20b8aSRobert MustacchiThe kernel also allows a function to be called after some time has 1440*9da20b8aSRobert Mustacchielapsed. 1441*9da20b8aSRobert MustacchiThis callback occurs on a different thread and will be executed in 1442*9da20b8aSRobert Mustacchi.Sy kernel 1443*9da20b8aSRobert Mustacchicontext. 1444*9da20b8aSRobert MustacchiA timeout can be scheduled in the future with the 1445*9da20b8aSRobert Mustacchi.Xr timeout 9F 1446*9da20b8aSRobert Mustacchifunction and cancelled with the 1447*9da20b8aSRobert Mustacchi.Xr untimeout 9F 1448*9da20b8aSRobert Mustacchifunction. 1449*9da20b8aSRobert MustacchiThere is also a STREAMs-specific version that can be used if the 1450*9da20b8aSRobert Mustacchicircumstances are required with the 1451*9da20b8aSRobert Mustacchi.Xr qtimeout 9F 1452*9da20b8aSRobert Mustacchifunction. 1453*9da20b8aSRobert Mustacchi.Pp 1454*9da20b8aSRobert MustacchiThese are all considered one-shot events. 1455*9da20b8aSRobert MustacchiThat is, they will only happen once after being scheduled. 1456*9da20b8aSRobert MustacchiIf instead, a driver requires periodic behavior, such as needing 1457*9da20b8aSRobert Mustacchisomething to occur every second, then it should use the 1458*9da20b8aSRobert Mustacchi.Xr ddi_periodic_add 9F 1459*9da20b8aSRobert Mustacchifunction to establish that. 1460*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1461*9da20b8aSRobert Mustacchi.It Xr delay 9F Ta Xr ddi_get_lbolt 9F 1462*9da20b8aSRobert Mustacchi.It Xr ddi_get_lbolt64 9F Ta Xr ddi_get_time 9F 1463*9da20b8aSRobert Mustacchi.It Xr ddi_periodic_add 9F Ta Xr ddi_periodic_delete 9F 1464*9da20b8aSRobert Mustacchi.It Xr drv_hztousec 9F Ta Xr drv_usectohz 9F 1465*9da20b8aSRobert Mustacchi.It Xr drv_usecwait 9F Ta Xr gethrtime 9F 1466*9da20b8aSRobert Mustacchi.It Xr qtimeout 9F Ta Xr quntimeout 9F 1467*9da20b8aSRobert Mustacchi.It Xr timeout 9F Ta Xr untimeout 9F 1468*9da20b8aSRobert Mustacchi.El 1469*9da20b8aSRobert Mustacchi.Ss Task Queues 1470*9da20b8aSRobert MustacchiA task queue provides an asynchronous processing mechanism that can be 1471*9da20b8aSRobert Mustacchiused by drivers and the broader system. 1472*9da20b8aSRobert MustacchiA task queue can be created with 1473*9da20b8aSRobert Mustacchi.Xr ddi_taskq_create 9F 1474*9da20b8aSRobert Mustacchiand sized with a given number of threads and a relative priority of those 1475*9da20b8aSRobert Mustacchithreads. 1476*9da20b8aSRobert MustacchiOnce created, tasks can be dispatched to the queue with 1477*9da20b8aSRobert Mustacchi.Xr ddi_taskq_dispatch 9F . 1478*9da20b8aSRobert MustacchiThe different functions and arguments dispatched do not need to be the 1479*9da20b8aSRobert Mustacchisame and can vary from invocation to invocation. 1480*9da20b8aSRobert MustacchiHowever, it is the caller's responsibility to ensure that any reference 1481*9da20b8aSRobert Mustacchimemory is valid until the task queue is done processing. 1482*9da20b8aSRobert MustacchiIt is possible to create a barrier for a task queue by using the 1483*9da20b8aSRobert Mustacchi.Xr ddi_taskq_wait 9F 1484*9da20b8aSRobert Mustacchifunction. 1485*9da20b8aSRobert Mustacchi.Pp 1486*9da20b8aSRobert MustacchiWhile task queues are a flexible mechanism for handling and processing 1487*9da20b8aSRobert Mustacchievents that occur in a well defined context, they do not have an 1488*9da20b8aSRobert Mustacchiinherent backpressure mechanism built in. 1489*9da20b8aSRobert MustacchiThis means it is possible to add events to a task queue faster than they 1490*9da20b8aSRobert Mustacchican be processed. 1491*9da20b8aSRobert MustacchiFor high-volume events, this must be considered before just dispatching 1492*9da20b8aSRobert Mustacchian event. 1493*9da20b8aSRobert MustacchiDo not rely on a non-sleeping allocation in the task queue dispatch 1494*9da20b8aSRobert Mustacchicontext. 1495*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1496*9da20b8aSRobert Mustacchi.It Xr ddi_taskq_create 9F Ta Xr ddi_taskq_destroy 9F 1497*9da20b8aSRobert Mustacchi.It Xr ddi_taskq_dispatch 9F Ta Xr ddi_taskq_resume 9F 1498*9da20b8aSRobert Mustacchi.It Xr ddi_taskq_suspend 9F Ta Xr ddi_taskq_suspended 9F 1499*9da20b8aSRobert Mustacchiddi_taskq_wait 1500*9da20b8aSRobert Mustacchi.El 1501*9da20b8aSRobert Mustacchi.Ss Credential Management and Privileges 1502*9da20b8aSRobert MustacchiNot everything in the system has the same power to impact it. 1503*9da20b8aSRobert MustacchiTo determine the permissions and context of a caller, the 1504*9da20b8aSRobert Mustacchi.Vt cred_t 1505*9da20b8aSRobert Mustacchidata structure encapsulates a number of different things including the 1506*9da20b8aSRobert Mustacchitraditional user and group IDs, but also the zone that one is operating 1507*9da20b8aSRobert Mustacchiin the context of and the associated privileges that the caller has. 1508*9da20b8aSRobert MustacchiWhile this concept is more often thought of due to userland processes being 1509*9da20b8aSRobert Mustacchiassociated with specific users, these same principles apply to different 1510*9da20b8aSRobert Mustacchithreads in the kernel. 1511*9da20b8aSRobert MustacchiNot all kernel threads are allowed to indiscriminately do what they 1512*9da20b8aSRobert Mustacchiwant, they can be constrained by the same privilege model that processes 1513*9da20b8aSRobert Mustacchiare, which is discussed in 1514*9da20b8aSRobert Mustacchi.Xr privileges 7 . 1515*9da20b8aSRobert Mustacchi.Pp 1516*9da20b8aSRobert MustacchiMost operations that device drivers implement are given a credential. 1517*9da20b8aSRobert MustacchiHowever, from within the kernel, a credential can be obtained that 1518*9da20b8aSRobert Mustacchirefers to a specific zone, the current process, or a generic kernel 1519*9da20b8aSRobert Mustacchicredential. 1520*9da20b8aSRobert Mustacchi.Pp 1521*9da20b8aSRobert MustacchiIt is up to drivers and the kernel writ-large to check whether a given 1522*9da20b8aSRobert Mustacchicredential is authorized to perform a given operation. 1523*9da20b8aSRobert MustacchiThis is encapsulated by the various privilege checks that exist. 1524*9da20b8aSRobert MustacchiThe most common check used is 1525*9da20b8aSRobert Mustacchi.Xr drv_priv 9F 1526*9da20b8aSRobert Mustacchiwhich checks for 1527*9da20b8aSRobert Mustacchi.Dv PRIV_SYS_DEVICES . 1528*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1529*9da20b8aSRobert Mustacchi.It Xr CRED 9F Ta Xr crdup 9F 1530*9da20b8aSRobert Mustacchi.It Xr crfree 9F Ta Xr crget 9F 1531*9da20b8aSRobert Mustacchi.It Xr crgetgid 9F Ta Xr crgetgroups 9F 1532*9da20b8aSRobert Mustacchi.It Xr crgetngroups 9F Ta Xr crgetrgid 9F 1533*9da20b8aSRobert Mustacchi.It Xr crgetruid 9F Ta Xr crgetsgid 9F 1534*9da20b8aSRobert Mustacchi.It Xr crgetsuid 9F Ta Xr crgetuid 9F 1535*9da20b8aSRobert Mustacchi.It Xr crgetzoneid 9F Ta Xr crhold 9F 1536*9da20b8aSRobert Mustacchi.It Xr ddi_get_cred 9F Ta Xr drv_priv 9F 1537*9da20b8aSRobert Mustacchi.It Xr kcred 9F Ta Xr priv_getbyname 9F 1538*9da20b8aSRobert Mustacchi.It Xr priv_policy_choice 9F Ta Xr priv_policy_only 9F 1539*9da20b8aSRobert Mustacchi.It Xr priv_policy 9F Ta Xr zone_kcred 9F 1540*9da20b8aSRobert Mustacchi.El 1541*9da20b8aSRobert Mustacchi.Ss Device ID Management 1542*9da20b8aSRobert MustacchiDevice IDs are a means of establishing a unique ID for a device in the 1543*9da20b8aSRobert Mustacchikernel. 1544*9da20b8aSRobert MustacchiThese unique IDs are generally tied to something from the device's 1545*9da20b8aSRobert Mustacchihardware such as a serial number or related, but can also be fabricated 1546*9da20b8aSRobert Mustacchiand stored on the device. 1547*9da20b8aSRobert MustacchiThese device IDs are used by other subsystems like ZFS to record 1548*9da20b8aSRobert Mustacchiinformation about a device as the actual 1549*9da20b8aSRobert Mustacchi.Pa /devices 1550*9da20b8aSRobert Mustacchipath that a device resides at may change because it is moved around in 1551*9da20b8aSRobert Mustacchithe system. 1552*9da20b8aSRobert Mustacchi.Pp 1553*9da20b8aSRobert MustacchiFor device drivers, particularly those that represent block devices, 1554*9da20b8aSRobert Mustacchithey should first call 1555*9da20b8aSRobert Mustacchi.Xr ddi_devid_init 9F 1556*9da20b8aSRobert Mustacchito initialize the device ID data structure. 1557*9da20b8aSRobert MustacchiAfter that is done, it is then safe to call 1558*9da20b8aSRobert Mustacchi.Xr ddi_devid_register 9F 1559*9da20b8aSRobert Mustacchito notify the kernel about the ID. 1560*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1561*9da20b8aSRobert Mustacchi.It Xr ddi_devid_compare 9F Ta Xr ddi_devid_free 9F 1562*9da20b8aSRobert Mustacchi.It Xr ddi_devid_get 9F Ta Xr ddi_devid_init 9F 1563*9da20b8aSRobert Mustacchi.It Xr ddi_devid_register 9F Ta Xr ddi_devid_sizeof 9F 1564*9da20b8aSRobert Mustacchi.It Xr ddi_devid_str_decode 9F Ta Xr ddi_devid_str_encode 9F 1565*9da20b8aSRobert Mustacchi.It Xr ddi_devid_str_free 9F Ta Xr ddi_devid_unregister 9F 1566*9da20b8aSRobert Mustacchi.It Xr ddi_devid_valid 9F Ta 1567*9da20b8aSRobert Mustacchi.El 1568*9da20b8aSRobert Mustacchi.Ss Message Block Functions 1569*9da20b8aSRobert MustacchiThe 1570*9da20b8aSRobert Mustacchi.Vt "mblk_t" 1571*9da20b8aSRobert Mustacchidata structure is used to chain together messages which are used through 1572*9da20b8aSRobert Mustacchithe kernel for different subsystems including all of networking, 1573*9da20b8aSRobert Mustacchiterminals, STREAMS, USB, and more. 1574*9da20b8aSRobert Mustacchi.Pp 1575*9da20b8aSRobert MustacchiMessage blocks are chained together by a series of two different 1576*9da20b8aSRobert Mustacchipointers: 1577*9da20b8aSRobert Mustacchi.Fa b_cont 1578*9da20b8aSRobert Mustacchiand 1579*9da20b8aSRobert Mustacchi.Fa b_next . 1580*9da20b8aSRobert MustacchiWhen a message is split across multiple data buffers, they are linked by 1581*9da20b8aSRobert Mustacchithe 1582*9da20b8aSRobert Mustacchi.Fa b_cont 1583*9da20b8aSRobert Mustacchipointer. 1584*9da20b8aSRobert MustacchiHowever, multiple distinct messages can be chained together and linked 1585*9da20b8aSRobert Mustacchiby the 1586*9da20b8aSRobert Mustacchi.Fa b_next 1587*9da20b8aSRobert Mustacchipointer. 1588*9da20b8aSRobert MustacchiLet's look at this in the context of a series of networking packets. 1589*9da20b8aSRobert MustacchiIf we had a chain of say 10 UDP packets that we were given, each UDP 1590*9da20b8aSRobert Mustacchipacket is considered an independent message and would be linked from one 1591*9da20b8aSRobert Mustacchito the next based on the order they should be transmitted with the 1592*9da20b8aSRobert Mustacchi.Fa b_next 1593*9da20b8aSRobert Mustacchipointer. 1594*9da20b8aSRobert MustacchiHowever, an individual message may be entirely in one message block, in 1595*9da20b8aSRobert Mustacchiwhich case its 1596*9da20b8aSRobert Mustacchi.Fa b_cont 1597*9da20b8aSRobert Mustacchipointer would be 1598*9da20b8aSRobert Mustacchi.Dv NULL , 1599*9da20b8aSRobert Mustacchibut if say the packet were split into a 100 byte data buffer that 1600*9da20b8aSRobert Mustacchicontained the headers and then a 1000 byte data buffer that contained 1601*9da20b8aSRobert Mustacchithe actual packet data, those two would be linked together by 1602*9da20b8aSRobert Mustacchi.Fa b_cont . 1603*9da20b8aSRobert MustacchiA continued message would never have its next pointer used to link it to 1604*9da20b8aSRobert Mustacchia wholly different message. 1605*9da20b8aSRobert MustacchiVisually you might see this as: 1606*9da20b8aSRobert Mustacchi.Bd -literal 1607*9da20b8aSRobert Mustacchi +---------------+ 1608*9da20b8aSRobert Mustacchi | UDP Message 0 | 1609*9da20b8aSRobert Mustacchi | Bytes 0-1100 | 1610*9da20b8aSRobert Mustacchi | b_cont ---+--> NULL 1611*9da20b8aSRobert Mustacchi | b_next + | 1612*9da20b8aSRobert Mustacchi +---------|-----+ 1613*9da20b8aSRobert Mustacchi | 1614*9da20b8aSRobert Mustacchi v 1615*9da20b8aSRobert Mustacchi +---------------+ +----------------+ 1616*9da20b8aSRobert Mustacchi | UDP Message 1 | | UDP Message 1+ | 1617*9da20b8aSRobert Mustacchi | Bytes 0-100 | | Bytes 100-1100 | 1618*9da20b8aSRobert Mustacchi | b_cont ---+--> | b_cont ----+->NULL 1619*9da20b8aSRobert Mustacchi | b_next + | | b_next ----+->NULL 1620*9da20b8aSRobert Mustacchi +---------|-----+ +----------------+ 1621*9da20b8aSRobert Mustacchi | 1622*9da20b8aSRobert Mustacchi ... 1623*9da20b8aSRobert Mustacchi | 1624*9da20b8aSRobert Mustacchi v 1625*9da20b8aSRobert Mustacchi +---------------+ 1626*9da20b8aSRobert Mustacchi | UDP Message 9 | 1627*9da20b8aSRobert Mustacchi | Bytes 0-1100 | 1628*9da20b8aSRobert Mustacchi | b_cont ---+--> NULL 1629*9da20b8aSRobert Mustacchi | b_next ---+--> NULL 1630*9da20b8aSRobert Mustacchi +---------------+ 1631*9da20b8aSRobert Mustacchi.Ed 1632*9da20b8aSRobert Mustacchi.Pp 1633*9da20b8aSRobert MustacchiMessage blocks all have an associated data block which contains the 1634*9da20b8aSRobert Mustacchiactual data that is present. 1635*9da20b8aSRobert MustacchiMultiple message blocks can share the same data block as well. 1636*9da20b8aSRobert MustacchiThe data block has a notion of a type, which is generally 1637*9da20b8aSRobert Mustacchi.Dv M_DATA 1638*9da20b8aSRobert Mustacchiwhich signifies that they operate on data. 1639*9da20b8aSRobert Mustacchi.Pp 1640*9da20b8aSRobert MustacchiTo allocate message blocks, one generally uses the 1641*9da20b8aSRobert Mustacchi.Xr allocb 9F 1642*9da20b8aSRobert Mustacchifunction to create one; however, you can also create message blocks 1643*9da20b8aSRobert Mustacchiusing your own source of data through functions like 1644*9da20b8aSRobert Mustacchi.Xr desballoc 9F . 1645*9da20b8aSRobert MustacchiThis is generally used when one wants to use memory that was originally 1646*9da20b8aSRobert Mustacchiused for DMA to pass data back into the kernel, such as in a networking 1647*9da20b8aSRobert Mustacchidevice driver. 1648*9da20b8aSRobert MustacchiWhen this happens, a callback function will be called once the last user 1649*9da20b8aSRobert Mustacchiof the data block is done with it. 1650*9da20b8aSRobert Mustacchi.Pp 1651*9da20b8aSRobert MustacchiThe functions listed below often end in either 1652*9da20b8aSRobert Mustacchi.Dq msg 1653*9da20b8aSRobert Mustacchior 1654*9da20b8aSRobert Mustacchi.Dq b 1655*9da20b8aSRobert Mustacchito indicate that they will operate on an entire message and follow the 1656*9da20b8aSRobert Mustacchi.Fa b_cont 1657*9da20b8aSRobert Mustacchipointer or they will not respectively. 1658*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1659*9da20b8aSRobert Mustacchi.It Xr adjmsg 9F Ta Xr allocb 9F 1660*9da20b8aSRobert Mustacchi.It Xr copyb 9F Ta Xr copymsg 9F 1661*9da20b8aSRobert Mustacchi.It Xr datamsg 9F Ta Xr desballoc 9F 1662*9da20b8aSRobert Mustacchi.It Xr desballoca 9F Ta Xr dupb 9F 1663*9da20b8aSRobert Mustacchi.It Xr dupmsg 9F Ta Xr esballoc 9F 1664*9da20b8aSRobert Mustacchi.It Xr esballoca 9F Ta Xr freeb 9F 1665*9da20b8aSRobert Mustacchi.It Xr freemsg 9F Ta Xr linkb 9F 1666*9da20b8aSRobert Mustacchi.It Xr mcopymsg 9F Ta Xr msgdsize 9F 1667*9da20b8aSRobert Mustacchi.It Xr msgpullup 9F Ta Xr msgsize 9F 1668*9da20b8aSRobert Mustacchi.It Xr pullupmsg 9F Ta Xr rmvb 9F 1669*9da20b8aSRobert Mustacchi.It Xr testb 9F Ta Xr unlinkb 9F 1670*9da20b8aSRobert Mustacchi.El 1671*9da20b8aSRobert Mustacchi.Ss Upgradable Firmware Modules 1672*9da20b8aSRobert MustacchiThe UFM 1673*9da20b8aSRobert Mustacchi.Pq Upgradable Firmware Module 1674*9da20b8aSRobert Mustacchisubsystem is used to grant the system observability into firmware that 1675*9da20b8aSRobert Mustacchiexists persistently on a device. 1676*9da20b8aSRobert MustacchiThese functions are intended for use by drivers that are participating in 1677*9da20b8aSRobert Mustacchithe kernel's UFM framework, which is discussed in 1678*9da20b8aSRobert Mustacchi.Xr ddi_ufm 9E . 1679*9da20b8aSRobert Mustacchi.Pp 1680*9da20b8aSRobert MustacchiThe 1681*9da20b8aSRobert Mustacchi.Xr ddi_ufm_init 9E 1682*9da20b8aSRobert Mustacchiand 1683*9da20b8aSRobert Mustacchi.Xr ddi_ufm_fini 9E 1684*9da20b8aSRobert Mustacchifunctions are used to indicate support of the subsystem to the kernel. 1685*9da20b8aSRobert MustacchiThe driver is required to use the 1686*9da20b8aSRobert Mustacchi.Xr ddi_ufm_update 9F 1687*9da20b8aSRobert Mustacchifunction to indicate both that it is ready to receive UFM requests and 1688*9da20b8aSRobert Mustacchito indicate that any data that the kernel may have previously received 1689*9da20b8aSRobert Mustacchihas changed. 1690*9da20b8aSRobert MustacchiOnce that's completed, then the other functions listed here are 1691*9da20b8aSRobert Mustacchigenerally used as part of implementing specific callback functions that 1692*9da20b8aSRobert Mustacchiare registered. 1693*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1694*9da20b8aSRobert Mustacchi.It Xr ddi_ufm_fini 9F Ta Xr ddi_ufm_image_set_desc 9F 1695*9da20b8aSRobert Mustacchi.It Xr ddi_ufm_image_set_misc 9F Ta Xr ddi_ufm_image_set_nslots 9F 1696*9da20b8aSRobert Mustacchi.It Xr ddi_ufm_init 9F Ta Xr ddi_ufm_slot_set_attrs 9F 1697*9da20b8aSRobert Mustacchi.It Xr ddi_ufm_slot_set_imgsize 9F Ta Xr ddi_ufm_slot_set_misc 9F 1698*9da20b8aSRobert Mustacchi.It Xr ddi_ufm_slot_set_version 9F Ta Xr ddi_ufm_update 9F 1699*9da20b8aSRobert Mustacchi.El 1700*9da20b8aSRobert Mustacchi.Ss Firmware Loading 1701*9da20b8aSRobert MustacchiSome hardware devices have firmware that is not stored as part of the 1702*9da20b8aSRobert Mustacchidevice itself and must instead be sent to the device each time it is 1703*9da20b8aSRobert Mustacchipowered on. 1704*9da20b8aSRobert MustacchiThese routines help drivers that need to perform this read such data 1705*9da20b8aSRobert Mustacchifrom the file system from well-known locations in the operating system. 1706*9da20b8aSRobert MustacchiTo begin with, a driver should call 1707*9da20b8aSRobert Mustacchi.Xr firmware_open 9F 1708*9da20b8aSRobert Mustacchito open a handle to the firmware file. 1709*9da20b8aSRobert MustacchiAt that point, one can determine the size of the file with the 1710*9da20b8aSRobert Mustacchi.Xr firmware_get_size 9F 1711*9da20b8aSRobert Mustacchifunction and allocate the appropriate sized memory buffer to read it in. 1712*9da20b8aSRobert MustacchiCallers should always check what the size of the returned file is and 1713*9da20b8aSRobert Mustacchishould not just blindly pass that size off to the kernel memory 1714*9da20b8aSRobert Mustacchiallocator. 1715*9da20b8aSRobert MustacchiFor example, if a file was over 100 MiB in size, then one should not 1716*9da20b8aSRobert Mustacchiassume that they're going to just blindly allocate 100 MiB of kernel 1717*9da20b8aSRobert Mustacchimemory and should instead perform incremental reads and sends to a 1718*9da20b8aSRobert Mustacchidevice that are smaller in size. 1719*9da20b8aSRobert Mustacchi.Pp 1720*9da20b8aSRobert MustacchiA driver can then go through and perform arbitrary reads of the firmware 1721*9da20b8aSRobert Mustacchifile through the 1722*9da20b8aSRobert Mustacchi.Xr firmware_read 9F 1723*9da20b8aSRobert Mustacchiinterface until they have read everything that they need. 1724*9da20b8aSRobert MustacchiOnce complete, the corresponding handle needs to be released through the 1725*9da20b8aSRobert Mustacchi.Xr firmware_close 9F 1726*9da20b8aSRobert Mustacchifunction. 1727*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1728*9da20b8aSRobert Mustacchi.It Xr firmware_close 9F Ta Xr firmware_get_size 9F 1729*9da20b8aSRobert Mustacchi.It Xr firmware_open 9F Ta Xr firmware_read 9F 1730*9da20b8aSRobert Mustacchi.El 1731*9da20b8aSRobert Mustacchi.Ss Fault Management Handling 1732*9da20b8aSRobert MustacchiThese functions allow device drivers to harden themselves against errors 1733*9da20b8aSRobert Mustacchithat might occur while interfacing with devices and tie into the broader 1734*9da20b8aSRobert Mustacchifault management architecture. 1735*9da20b8aSRobert Mustacchi.Pp 1736*9da20b8aSRobert MustacchiTo begin, a driver must declare which capabilities it implements during 1737*9da20b8aSRobert Mustacchiits 1738*9da20b8aSRobert Mustacchi.Xr attach 9E 1739*9da20b8aSRobert Mustacchifunction by calling 1740*9da20b8aSRobert Mustacchi.Xr ddi_fm_init 9F . 1741*9da20b8aSRobert MustacchiThe set of capabilities it receives back may be less than what was 1742*9da20b8aSRobert Mustacchirequested because the capabilities are dependent on the overall chain of 1743*9da20b8aSRobert Mustacchidrivers present. 1744*9da20b8aSRobert Mustacchi.Pp 1745*9da20b8aSRobert MustacchiIf 1746*9da20b8aSRobert Mustacchi.Dv DDI_FM_EREPORT_CAPABLE 1747*9da20b8aSRobert Mustacchiwas negotiated, then the driver is expected to generate error events 1748*9da20b8aSRobert Mustacchiwhen certain conditions occur using the 1749*9da20b8aSRobert Mustacchi.Xr ddi_fm_ereport_post 9F 1750*9da20b8aSRobert Mustacchifunction or the more specific 1751*9da20b8aSRobert Mustacchi.Xr pci_ereport_post 9F 1752*9da20b8aSRobert Mustacchifunction. 1753*9da20b8aSRobert MustacchiIf a caller has negotiated 1754*9da20b8aSRobert Mustacchi.Dv DDI_FM_ACCCHK_CAPABLE , 1755*9da20b8aSRobert Mustacchithen it is allowed to set up its register attributes to indicate that it 1756*9da20b8aSRobert Mustacchiwill check for errors on the register handle after using functions like 1757*9da20b8aSRobert Mustacchi.Xr ddi_get8 9F 1758*9da20b8aSRobert Mustacchiand 1759*9da20b8aSRobert Mustacchi.Xr ddi_set8 9F 1760*9da20b8aSRobert Mustacchiby calling 1761*9da20b8aSRobert Mustacchi.Xr ddi_fm_acc_err_get 9F 1762*9da20b8aSRobert Mustacchiand reacting accordingly. 1763*9da20b8aSRobert MustacchiSimilarly, if a driver has negotiated 1764*9da20b8aSRobert Mustacchi.Dv DDI_FM_DMACHK_CAPABLE , 1765*9da20b8aSRobert Mustacchithen it will use 1766*9da20b8aSRobert Mustacchi.Xr ddi_check_dma_handle 9F 1767*9da20b8aSRobert Mustacchito check the results of DMA activity and handle the results 1768*9da20b8aSRobert Mustacchiappropriately. 1769*9da20b8aSRobert MustacchiSimilar to register accesses, the DMA attributes must be updated to set 1770*9da20b8aSRobert Mustacchithat error handling is anticipated on this handle. 1771*9da20b8aSRobert MustacchiThe 1772*9da20b8aSRobert Mustacchi.Xr ddi_fm_init 9F 1773*9da20b8aSRobert Mustacchimanual page has an overview of the other types of flags that can be 1774*9da20b8aSRobert Mustacchinegotiated and how they are used. 1775*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1776*9da20b8aSRobert Mustacchi.It Xr ddi_check_acc_handle 9F Ta Xr ddi_check_dma_handle 9F 1777*9da20b8aSRobert Mustacchi.It Xr ddi_dev_report_fault 9F Ta Xr ddi_fm_acc_err_clear 9F 1778*9da20b8aSRobert Mustacchi.It Xr ddi_fm_acc_err_get 9F Ta Xr ddi_fm_capable 9F 1779*9da20b8aSRobert Mustacchi.It Xr ddi_fm_dma_err_clear 9F Ta Xr ddi_fm_dma_err_get 9F 1780*9da20b8aSRobert Mustacchi.It Xr ddi_fm_ereport_post 9F Ta Xr ddi_fm_fini 9F 1781*9da20b8aSRobert Mustacchi.It Xr ddi_fm_handler_register 9F Ta Xr ddi_fm_handler_unregister 9F 1782*9da20b8aSRobert Mustacchi.It Xr ddi_fm_init 9F Ta Xr ddi_fm_service_impact 9F 1783*9da20b8aSRobert Mustacchi.It Xr pci_ereport_post 9F Ta Xr pci_ereport_setup 9F 1784*9da20b8aSRobert Mustacchi.It Xr pci_ereport_teardown 9F Ta 1785*9da20b8aSRobert Mustacchi.El 1786*9da20b8aSRobert Mustacchi.Ss SCSI and SAS Device Driver Functions 1787*9da20b8aSRobert MustacchiThese functions are for use by SCSI and SAS device drivers that leverage 1788*9da20b8aSRobert Mustacchithe kernel's frameworks. 1789*9da20b8aSRobert MustacchiOther device drivers should not use these. 1790*9da20b8aSRobert MustacchiFor more background on these, some of the general concepts are discussed 1791*9da20b8aSRobert Mustacchiin 1792*9da20b8aSRobert Mustacchi.Xr iport 9 , 1793*9da20b8aSRobert Mustacchi.Xr phymap 9 , 1794*9da20b8aSRobert Mustacchiand 1795*9da20b8aSRobert Mustacchi.Xr tgtmap 9 . 1796*9da20b8aSRobert Mustacchi.Pp 1797*9da20b8aSRobert MustacchiDevice drivers register initially with the kernel by using the 1798*9da20b8aSRobert Mustacchi.Xr scsi_ha_init 9F 1799*9da20b8aSRobert Mustacchifunction and then, in their attach routine, register specific instances, 1800*9da20b8aSRobert Mustacchiusing functions like 1801*9da20b8aSRobert Mustacchi.Xr scsi_hba_iport_register 9F 1802*9da20b8aSRobert Mustacchior instead 1803*9da20b8aSRobert Mustacchi.Xr scsi_hba_tran_alloc 9F 1804*9da20b8aSRobert Mustacchiand 1805*9da20b8aSRobert Mustacchi.Xr scsi_hba_attach_setup 9F . 1806*9da20b8aSRobert MustacchiNew drivers are encouraged to use the target map and iports framework to 1807*9da20b8aSRobert Mustacchisimplify the device driver writing process. 1808*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1809*9da20b8aSRobert Mustacchi.It Xr makecom_g0_s 9F Ta Xr makecom_g0 9F 1810*9da20b8aSRobert Mustacchi.It Xr makecom_g1 9F Ta Xr makecom_g5 9F 1811*9da20b8aSRobert Mustacchi.It Xr makecom 9F Ta Xr sas_phymap_create 9F 1812*9da20b8aSRobert Mustacchi.It Xr sas_phymap_destroy 9F Ta Xr sas_phymap_lookup_ua 9F 1813*9da20b8aSRobert Mustacchi.It Xr sas_phymap_lookup_uapriv 9F Ta Xr sas_phymap_phy_add 9F 1814*9da20b8aSRobert Mustacchi.It Xr sas_phymap_phy_rem 9F Ta Xr sas_phymap_phy2ua 9F 1815*9da20b8aSRobert Mustacchi.It Xr sas_phymap_phys_free 9F Ta Xr sas_phymap_phys_next 9F 1816*9da20b8aSRobert Mustacchi.It Xr sas_phymap_ua_free 9F Ta Xr sas_phymap_ua2phys 9F 1817*9da20b8aSRobert Mustacchi.It Xr sas_phymap_uahasphys 9F Ta Xr scsi_abort 9F 1818*9da20b8aSRobert Mustacchi.It Xr scsi_address_device 9F Ta Xr scsi_alloc_consistent_buf 9F 1819*9da20b8aSRobert Mustacchi.It Xr scsi_cname 9F Ta Xr scsi_destroy_pkt 9F 1820*9da20b8aSRobert Mustacchi.It Xr scsi_device_hba_private_get 9F Ta Xr scsi_device_hba_private_set 9F 1821*9da20b8aSRobert Mustacchi.It Xr scsi_device_unit_address 9F Ta Xr scsi_dmafree 9F 1822*9da20b8aSRobert Mustacchi.It Xr scsi_dmaget 9F Ta Xr scsi_dname 9F 1823*9da20b8aSRobert Mustacchi.It Xr scsi_errmsg 9F Ta Xr scsi_ext_sense_fields 9F 1824*9da20b8aSRobert Mustacchi.It Xr scsi_find_sense_descr 9F Ta Xr scsi_free_consistent_buf 9F 1825*9da20b8aSRobert Mustacchi.It Xr scsi_free_wwnstr 9F Ta Xr scsi_get_device_type_scsi_options 9F 1826*9da20b8aSRobert Mustacchi.It Xr scsi_get_device_type_string 9F Ta Xr scsi_hba_attach_setup 9F 1827*9da20b8aSRobert Mustacchi.It Xr scsi_hba_detach 9F Ta Xr scsi_hba_fini 9F 1828*9da20b8aSRobert Mustacchi.It Xr scsi_hba_init 9F Ta Xr scsi_hba_iport_exist 9F 1829*9da20b8aSRobert Mustacchi.It Xr scsi_hba_iport_find 9F Ta Xr scsi_hba_iport_register 9F 1830*9da20b8aSRobert Mustacchi.It Xr scsi_hba_iport_unit_address 9F Ta Xr scsi_hba_iportmap_create 9F 1831*9da20b8aSRobert Mustacchi.It Xr scsi_hba_iportmap_destroy 9F Ta Xr scsi_hba_iportmap_iport_add 9F 1832*9da20b8aSRobert Mustacchi.It Xr scsi_hba_iportmap_iport_remove 9F Ta Xr scsi_hba_lookup_capstr 9F 1833*9da20b8aSRobert Mustacchi.It Xr scsi_hba_pkt_alloc 9F Ta Xr scsi_hba_pkt_comp 9F 1834*9da20b8aSRobert Mustacchi.It Xr scsi_hba_pkt_free 9F Ta Xr scsi_hba_probe 9F 1835*9da20b8aSRobert Mustacchi.It Xr scsi_hba_tgtmap_create 9F Ta Xr scsi_hba_tgtmap_destroy 9F 1836*9da20b8aSRobert Mustacchi.It Xr scsi_hba_tgtmap_scan_luns 9F Ta Xr scsi_hba_tgtmap_set_add 9F 1837*9da20b8aSRobert Mustacchi.It Xr scsi_hba_tgtmap_set_begin 9F Ta Xr scsi_hba_tgtmap_set_end 9F 1838*9da20b8aSRobert Mustacchi.It Xr scsi_hba_tgtmap_set_flush 9F Ta Xr scsi_hba_tgtmap_tgt_add 9F 1839*9da20b8aSRobert Mustacchi.It Xr scsi_hba_tgtmap_tgt_remove 9F Ta Xr scsi_hba_tran_alloc 9F 1840*9da20b8aSRobert Mustacchi.It Xr scsi_hba_tran_free 9F Ta Xr scsi_ifgetcap 9F 1841*9da20b8aSRobert Mustacchi.It Xr scsi_ifsetcap 9F Ta Xr scsi_init_pkt 9F 1842*9da20b8aSRobert Mustacchi.It Xr scsi_log 9F Ta Xr scsi_mname 9F 1843*9da20b8aSRobert Mustacchi.It Xr scsi_pktalloc 9F Ta Xr scsi_pktfree 9F 1844*9da20b8aSRobert Mustacchi.It Xr scsi_poll 9F Ta Xr scsi_probe 9F 1845*9da20b8aSRobert Mustacchi.It Xr scsi_resalloc 9F Ta Xr scsi_reset_notify 9F 1846*9da20b8aSRobert Mustacchi.It Xr scsi_reset 9F Ta Xr scsi_resfree 9F 1847*9da20b8aSRobert Mustacchi.It Xr scsi_rname 9F Ta Xr scsi_sense_asc 9F 1848*9da20b8aSRobert Mustacchi.It Xr scsi_sense_ascq 9F Ta Xr scsi_sense_cmdspecific_uint64 9F 1849*9da20b8aSRobert Mustacchi.It Xr scsi_sense_info_uint64 9F Ta Xr scsi_sense_key 9F 1850*9da20b8aSRobert Mustacchi.It Xr scsi_setup_cdb 9F Ta Xr scsi_slave 9F 1851*9da20b8aSRobert Mustacchi.It Xr scsi_sname 9F Ta Xr scsi_sync_pkt 9F 1852*9da20b8aSRobert Mustacchi.It Xr scsi_transport 9F Ta Xr scsi_unprobe 9F 1853*9da20b8aSRobert Mustacchi.It Xr scsi_unslave 9F Ta Xr scsi_validate_sense 9F 1854*9da20b8aSRobert Mustacchi.It Xr scsi_vu_errmsg 9F Ta Xr scsi_wwn_to_wwnstr 9F 1855*9da20b8aSRobert Mustacchiscsi_wwnstr_to_wwn 1856*9da20b8aSRobert Mustacchi.El 1857*9da20b8aSRobert Mustacchi.Ss Block Device Buffer Handling 1858*9da20b8aSRobert MustacchiBlock devices operate with a data structure called the 1859*9da20b8aSRobert Mustacchi.Vt struct buf 1860*9da20b8aSRobert Mustacchiwhich is described in 1861*9da20b8aSRobert Mustacchi.Xr buf 9S . 1862*9da20b8aSRobert MustacchiThis structure is used to represent a given block request and is used 1863*9da20b8aSRobert Mustacchiheavily in block devices, the SCSI/SAS framework, and the blkdev 1864*9da20b8aSRobert Mustacchiframework. 1865*9da20b8aSRobert MustacchiThe functions described here are used to manipulate these structures in 1866*9da20b8aSRobert Mustacchivarious ways such as copying them around, indicating error conditions, 1867*9da20b8aSRobert Mustacchior indicating when the I/O operation is done. 1868*9da20b8aSRobert MustacchiBy default, this memory is not mapped into the kernel's address space so 1869*9da20b8aSRobert Mustacchiseveral functions such as 1870*9da20b8aSRobert Mustacchi.Xr bp_mapin 9F 1871*9da20b8aSRobert Mustacchiare present to allow for that to happen when required. 1872*9da20b8aSRobert Mustacchi.Pp 1873*9da20b8aSRobert MustacchiTo initially obtain a 1874*9da20b8aSRobert Mustacchi.Vt struct buf , 1875*9da20b8aSRobert Mustacchidrivers should begin by calling 1876*9da20b8aSRobert Mustacchi.Xr getrbuf 9S 1877*9da20b8aSRobert Mustacchiat which point, the caller can fill in the structure. 1878*9da20b8aSRobert MustacchiOnce that's done, the 1879*9da20b8aSRobert Mustacchi.Xr physio 9F 1880*9da20b8aSRobert Mustacchifunction can be used to actually perform the I/O and wait until it's 1881*9da20b8aSRobert Mustacchicomplete. 1882*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1883*9da20b8aSRobert Mustacchi.It Xr bioclone 9F Ta Xr biodone 9F 1884*9da20b8aSRobert Mustacchi.It Xr bioerror 9F Ta Xr biofini 9F 1885*9da20b8aSRobert Mustacchi.It Xr bioinit 9F Ta Xr biomodified 9F 1886*9da20b8aSRobert Mustacchi.It Xr bioreset 9F Ta Xr biosize 9F 1887*9da20b8aSRobert Mustacchi.It Xr biowait 9F Ta Xr bp_mapin 9F 1888*9da20b8aSRobert Mustacchi.It Xr bp_mapout 9F Ta Xr clrbuf 9F 1889*9da20b8aSRobert Mustacchi.It Xr disksort 9F Ta Xr freerbuf 9F 1890*9da20b8aSRobert Mustacchi.It Xr geterror 9F Ta Xr getrbuf 9F 1891*9da20b8aSRobert Mustacchi.It Xr minphys 9F Ta Xr physio 9F 1892*9da20b8aSRobert Mustacchi.El 1893*9da20b8aSRobert Mustacchi.Ss Networking Device Driver Functions 1894*9da20b8aSRobert MustacchiThese functions are for networking device drivers that implant the MAC, 1895*9da20b8aSRobert MustacchiGLDv3 interfaces. 1896*9da20b8aSRobert MustacchiThe full framework and how to use it is described in 1897*9da20b8aSRobert Mustacchi.Xr mac 9E . 1898*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1899*9da20b8aSRobert Mustacchi.It Xr mac_alloc 9F Ta Xr mac_fini_ops 9F 1900*9da20b8aSRobert Mustacchi.It Xr mac_free 9F Ta Xr mac_hcksum_get 9F 1901*9da20b8aSRobert Mustacchi.It Xr mac_hcksum_set 9F Ta Xr mac_init_ops 9F 1902*9da20b8aSRobert Mustacchi.It Xr mac_link_update 9F Ta Xr mac_lso_get 9F 1903*9da20b8aSRobert Mustacchi.It Xr mac_maxsdu_update 9F Ta Xr mac_prop_info_set_default_fec 9F 1904*9da20b8aSRobert Mustacchi.It Xr mac_prop_info_set_default_link_flowctrl 9F Ta Xr mac_prop_info_set_default_str 9F 1905*9da20b8aSRobert Mustacchi.It Xr mac_prop_info_set_default_uint32 9F Ta Xr mac_prop_info_set_default_uint64 9F 1906*9da20b8aSRobert Mustacchi.It Xr mac_prop_info_set_default_uint8 9F Ta Xr mac_prop_info_set_perm 9F 1907*9da20b8aSRobert Mustacchi.It Xr mac_prop_info_set_range_uint32 9F Ta Xr mac_prop_info 9F 1908*9da20b8aSRobert Mustacchi.It Xr mac_register 9F Ta Xr mac_ring_rx 9F 1909*9da20b8aSRobert Mustacchi.It Xr mac_rx 9F Ta Xr mac_transceiver_info_set_present 9F 1910*9da20b8aSRobert Mustacchi.It Xr mac_transceiver_info_set_usable 9F Ta Xr mac_transceiver_info 9F 1911*9da20b8aSRobert Mustacchi.It Xr mac_tx_ring_update 9F Ta Xr mac_tx_update 9F 1912*9da20b8aSRobert Mustacchi.It Xr mac_unregister 9F Ta 1913*9da20b8aSRobert Mustacchi.El 1914*9da20b8aSRobert Mustacchi.Ss USB Device Driver Functions 1915*9da20b8aSRobert MustacchiThese functions are designed for USB device drivers. 1916*9da20b8aSRobert MustacchiTo first initialize with the kernel, a device driver must call 1917*9da20b8aSRobert Mustacchi.Xr usb_client_attach 9F 1918*9da20b8aSRobert Mustacchiand then 1919*9da20b8aSRobert Mustacchi.Xr usb_get_dev_data 9F . 1920*9da20b8aSRobert MustacchiThe latter call is required to get access to the USB-level 1921*9da20b8aSRobert Mustacchidescriptors about the device which describe what kinds of USB endpoints 1922*9da20b8aSRobert Mustacchi.Pq control, bulk, interrupt, or isochronous 1923*9da20b8aSRobert Mustacchiexist on the device as well as how many different interfaces and 1924*9da20b8aSRobert Mustacchiconfigurations are present. 1925*9da20b8aSRobert Mustacchi.Pp 1926*9da20b8aSRobert MustacchiOnce a given configuration, sometimes the default, is selected, then the 1927*9da20b8aSRobert Mustacchidriver can proceed to opening up what the USB architecture calls a pipe, 1928*9da20b8aSRobert Mustacchiwhich provides a way to send requests to a specific USB endpoint. 1929*9da20b8aSRobert MustacchiFirst, specific endpoints can be looked up using the 1930*9da20b8aSRobert Mustacchi.Xr usb_lookup_ep_data 9F 1931*9da20b8aSRobert Mustacchifunction which gets information from the parsed descriptors and then 1932*9da20b8aSRobert Mustacchithat gets filled into an extended descriptor with 1933*9da20b8aSRobert Mustacchi.Xr usb_ep_xdescr_fill 9F . 1934*9da20b8aSRobert MustacchiWith that in hand, a pipe can be opened with 1935*9da20b8aSRobert Mustacchi.Xr usb_pipe_xopen 9F . 1936*9da20b8aSRobert Mustacchi.Pp 1937*9da20b8aSRobert MustacchiOnce a pipe has been opened, which most often happens in a driver's 1938*9da20b8aSRobert Mustacchi.Xr attach 9E 1939*9da20b8aSRobert Mustacchientry point, then requests can be allocated and submitted. 1940*9da20b8aSRobert MustacchiThere is a different allocation for each type of request 1941*9da20b8aSRobert Mustacchi.Po 1942*9da20b8aSRobert Mustacchie.g. 1943*9da20b8aSRobert Mustacchi.Xr usb_alloc_bulk_req 9F 1944*9da20b8aSRobert Mustacchi.Pc 1945*9da20b8aSRobert Mustacchiand a different submission function for each type as well. 1946*9da20b8aSRobert MustacchiEach request structure has a corresponding page in section 9S that 1947*9da20b8aSRobert Mustacchidescribes the structure, its members, and how to work with it. 1948*9da20b8aSRobert Mustacchi.Pp 1949*9da20b8aSRobert MustacchiOne other major concern for USB devices, which isn't as common with 1950*9da20b8aSRobert Mustacchiother types of devices, is that they can be yanked out and reinserted 1951*9da20b8aSRobert Mustacchiat any time. 1952*9da20b8aSRobert MustacchiTo help determine when this happens, the kernel offers the 1953*9da20b8aSRobert Mustacchi.Xr usb_register_event_cbs 9F 1954*9da20b8aSRobert Mustacchifunction which allows a driver to register for callbacks when a device 1955*9da20b8aSRobert Mustacchiis disconnected, reconnected, or around checkpoint suspend/resume 1956*9da20b8aSRobert Mustacchibehavior. 1957*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 1958*9da20b8aSRobert Mustacchi.It Xr usb_alloc_bulk_req 9F Ta Xr usb_alloc_ctrl_req 9F 1959*9da20b8aSRobert Mustacchi.It Xr usb_alloc_intr_req 9F Ta Xr usb_alloc_isoc_req 9F 1960*9da20b8aSRobert Mustacchi.It Xr usb_alloc_request 9F Ta Xr usb_client_attach 9F 1961*9da20b8aSRobert Mustacchi.It Xr usb_client_detach 9F Ta Xr usb_clr_feature 9F 1962*9da20b8aSRobert Mustacchi.It Xr usb_create_pm_components 9F Ta Xr usb_ep_xdescr_fill 9F 1963*9da20b8aSRobert Mustacchi.It Xr usb_free_bulk_req 9F Ta Xr usb_free_ctrl_req 9F 1964*9da20b8aSRobert Mustacchi.It Xr usb_free_descr_tree 9F Ta Xr usb_free_dev_data 9F 1965*9da20b8aSRobert Mustacchi.It Xr usb_free_intr_req 9F Ta Xr usb_free_isoc_req 9F 1966*9da20b8aSRobert Mustacchi.It Xr usb_get_addr 9F Ta Xr usb_get_alt_if 9F 1967*9da20b8aSRobert Mustacchi.It Xr usb_get_cfg 9F Ta Xr usb_get_current_frame_number 9F 1968*9da20b8aSRobert Mustacchi.It Xr usb_get_dev_data 9F Ta Xr usb_get_if_number 9F 1969*9da20b8aSRobert Mustacchi.It Xr usb_get_max_pkts_per_isoc_request 9F Ta Xr usb_get_status 9F 1970*9da20b8aSRobert Mustacchi.It Xr usb_get_string_descr 9F Ta Xr usb_handle_remote_wakeup 9F 1971*9da20b8aSRobert Mustacchi.It Xr usb_lookup_ep_data 9F Ta Xr usb_owns_device 9F 1972*9da20b8aSRobert Mustacchi.It Xr usb_parse_data 9F Ta Xr usb_pipe_bulk_xfer 9F 1973*9da20b8aSRobert Mustacchi.It Xr usb_pipe_close 9F Ta Xr usb_pipe_ctrl_xfer_wait 9F 1974*9da20b8aSRobert Mustacchi.It Xr usb_pipe_ctrl_xfer 9F Ta Xr usb_pipe_drain_reqs 9F 1975*9da20b8aSRobert Mustacchi.It Xr usb_pipe_get_max_bulk_transfer_size 9F Ta Xr usb_pipe_get_private 9F 1976*9da20b8aSRobert Mustacchi.It Xr usb_pipe_get_state 9F Ta Xr usb_pipe_intr_xfer 9F 1977*9da20b8aSRobert Mustacchi.It Xr usb_pipe_isoc_xfer 9F Ta Xr usb_pipe_open 9F 1978*9da20b8aSRobert Mustacchi.It Xr usb_pipe_reset 9F Ta Xr usb_pipe_set_private 9F 1979*9da20b8aSRobert Mustacchi.It Xr usb_pipe_stop_intr_polling 9F Ta Xr usb_pipe_stop_isoc_polling 9F 1980*9da20b8aSRobert Mustacchi.It Xr usb_pipe_xopen 9F Ta Xr usb_print_descr_tree 9F 1981*9da20b8aSRobert Mustacchi.It Xr usb_register_hotplug_cbs 9F Ta Xr usb_reset_device 9F 1982*9da20b8aSRobert Mustacchi.It Xr usb_set_alt_if 9F Ta Xr usb_set_cfg 9F 1983*9da20b8aSRobert Mustacchi.It Xr usb_unregister_hotplug_cbs 9F Ta 1984*9da20b8aSRobert Mustacchi.El 1985*9da20b8aSRobert Mustacchi.Ss PCI Device Driver Functions 1986*9da20b8aSRobert MustacchiThese functions are specific for PCI and PCI Express based device 1987*9da20b8aSRobert Mustacchidrivers and are intended to be used to get access to PCI configuration 1988*9da20b8aSRobert Mustacchispace. 1989*9da20b8aSRobert MustacchiFor normal PCI base address registers 1990*9da20b8aSRobert Mustacchi.Pq BARs 1991*9da20b8aSRobert Mustacchiinstead see 1992*9da20b8aSRobert Mustacchi.Sx Register Setup and Access . 1993*9da20b8aSRobert Mustacchi.Pp 1994*9da20b8aSRobert MustacchiTo access PCI configuration space, a device driver should first call 1995*9da20b8aSRobert Mustacchi.Xr pci_config_setup 9F . 1996*9da20b8aSRobert MustacchiGenerally, drivers will call this in their 1997*9da20b8aSRobert Mustacchi.Xr attach 9E 1998*9da20b8aSRobert Mustacchientry point and then tear down the configuration space access with the 1999*9da20b8aSRobert Mustacchi.Xr pci_config_teardown 9F 2000*9da20b8aSRobert Mustacchientry point in 2001*9da20b8aSRobert Mustacchi.Xr detach 9E . 2002*9da20b8aSRobert MustacchiAfter setting up access to configuration space, the returned handle can 2003*9da20b8aSRobert Mustacchibe used in all of the various configuration space routines to get and 2004*9da20b8aSRobert Mustacchiset specific sized values in configuration space. 2005*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2006*9da20b8aSRobert Mustacchi.It Xr pci_config_get8 9F Ta Xr pci_config_get16 9F 2007*9da20b8aSRobert Mustacchi.It Xr pci_config_get32 9F Ta Xr pci_config_get64 9F 2008*9da20b8aSRobert Mustacchi.It Xr pci_config_put8 9F Ta Xr pci_config_put16 9F 2009*9da20b8aSRobert Mustacchi.It Xr pci_config_put32 9F Ta Xr pci_config_put64 9F 2010*9da20b8aSRobert Mustacchi.It Xr pci_config_setup 9F Ta Xr pci_config_teardown 9F 2011*9da20b8aSRobert Mustacchi.It Xr pci_report_pmcap 9F Ta Xr pci_restore_config_regs 9F 2012*9da20b8aSRobert Mustacchi.It Xr pci_save_config_regs 9F Ta 2013*9da20b8aSRobert Mustacchi.El 2014*9da20b8aSRobert Mustacchi.Ss USB Host Controller Interface Functions 2015*9da20b8aSRobert MustacchiThese routines are used for device drivers which implement the USB 2016*9da20b8aSRobert Mustacchihost controller interfaces described in 2017*9da20b8aSRobert Mustacchi.Xr usba_hcdi 9E . 2018*9da20b8aSRobert MustacchiOther types of devices drivers and modules should not call these 2019*9da20b8aSRobert Mustacchifunctions. 2020*9da20b8aSRobert MustacchiIn particular, if one is writing a device driver for a USB device, these 2021*9da20b8aSRobert Mustacchiare not the routines you're looking for and you want to see 2022*9da20b8aSRobert Mustacchi.Sx USB Device Driver Functions . 2023*9da20b8aSRobert MustacchiThese are what the 2024*9da20b8aSRobert Mustacchi.Xr ehci 4D 2025*9da20b8aSRobert Mustacchior 2026*9da20b8aSRobert Mustacchi.Xr xhci 4D 2027*9da20b8aSRobert Mustacchidrivers use to provide services that USB drivers use via the kernel USB 2028*9da20b8aSRobert Mustacchiarchitecture. 2029*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2030*9da20b8aSRobert Mustacchi.It Xr usba_alloc_hcdi_ops 9F Ta Xr usba_free_hcdi_ops 9F 2031*9da20b8aSRobert Mustacchi.It Xr usba_hcdi_cb 9F Ta Xr usba_hcdi_dup_intr_req 9F 2032*9da20b8aSRobert Mustacchi.It Xr usba_hcdi_dup_isoc_req 9F Ta Xr usba_hcdi_get_device_private 9F 2033*9da20b8aSRobert Mustacchi.It Xr usba_hcdi_register 9F Ta Xr usba_hcdi_unregister 9F 2034*9da20b8aSRobert Mustacchi.It Xr usba_hubdi_bind_root_hub 9F Ta Xr usba_hubdi_cb_ops 9F 2035*9da20b8aSRobert Mustacchi.It Xr usba_hubdi_close 9F Ta Xr usba_hubdi_dev_ops 9F 2036*9da20b8aSRobert Mustacchi.It Xr usba_hubdi_ioctl 9F Ta Xr usba_hubdi_open 9F 2037*9da20b8aSRobert Mustacchi.It Xr usba_hubdi_root_hub_power 9F Ta Xr usba_hubdi_unbind_root_hub 9F 2038*9da20b8aSRobert Mustacchi.El 2039*9da20b8aSRobert Mustacchi.Ss Functions for PCMCIA Drivers 2040*9da20b8aSRobert MustacchiThese functions exist for older PCMCIA device drivers. 2041*9da20b8aSRobert MustacchiThese should not otherwise be used by the system. 2042*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2043*9da20b8aSRobert Mustacchi.It Xr csx_AccessConfigurationRegister 9F Ta Xr csx_ConvertSize 9F 2044*9da20b8aSRobert Mustacchi.It Xr csx_ConvertSpeed 9F Ta Xr csx_CS_DDI_Info 9F 2045*9da20b8aSRobert Mustacchi.It Xr csx_DeregisterClient 9F Ta Xr csx_DupHandle 9F 2046*9da20b8aSRobert Mustacchi.It Xr csx_Error2Text 9F Ta Xr csx_Event2Text 9F 2047*9da20b8aSRobert Mustacchi.It Xr csx_FreeHandle 9F Ta Xr csx_Get16 9F 2048*9da20b8aSRobert Mustacchi.It Xr csx_Get32 9F Ta Xr csx_Get64 9F 2049*9da20b8aSRobert Mustacchi.It Xr csx_Get8 9F Ta Xr csx_GetEventMask 9F 2050*9da20b8aSRobert Mustacchi.It Xr csx_GetFirstClient 9F Ta Xr csx_GetFirstTuple 9F 2051*9da20b8aSRobert Mustacchi.It Xr csx_GetHandleOffset 9F Ta Xr csx_GetMappedAddr 9F 2052*9da20b8aSRobert Mustacchi.It Xr csx_GetNextClient 9F Ta Xr csx_GetNextTuple 9F 2053*9da20b8aSRobert Mustacchi.It Xr csx_GetStatus 9F Ta Xr csx_GetTupleData 9F 2054*9da20b8aSRobert Mustacchi.It Xr csx_MakeDeviceNode 9F Ta Xr csx_MapLogSocket 9F 2055*9da20b8aSRobert Mustacchi.It Xr csx_MapMemPage 9F Ta Xr csx_ModifyConfiguration 9F 2056*9da20b8aSRobert Mustacchi.It Xr csx_ModifyWindow 9F Ta Xr csx_Parse_CISTPL_BATTERY 9F 2057*9da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_BYTEORDER 9F Ta Xr csx_Parse_CISTPL_CFTABLE_ENTRY 9F 2058*9da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_CONFIG 9F Ta Xr csx_Parse_CISTPL_DATE 9F 2059*9da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_DEVICE_A 9F Ta Xr csx_Parse_CISTPL_DEVICE_OA 9F 2060*9da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_DEVICE_OC 9F Ta Xr csx_Parse_CISTPL_DEVICE 9F 2061*9da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_DEVICEGEO_A 9F Ta Xr csx_Parse_CISTPL_DEVICEGEO 9F 2062*9da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_FORMAT 9F Ta Xr csx_Parse_CISTPL_FUNCE 9F 2063*9da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_FUNCID 9F Ta Xr csx_Parse_CISTPL_GEOMETRY 9F 2064*9da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_JEDEC_A 9F Ta Xr csx_Parse_CISTPL_JEDEC_C 9F 2065*9da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_LINKTARGET 9F Ta Xr csx_Parse_CISTPL_LONGLINK_A 9F 2066*9da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_LONGLINK_C 9F Ta Xr csx_Parse_CISTPL_LONGLINK_MFC 9F 2067*9da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_MANFID 9F Ta Xr csx_Parse_CISTPL_ORG 9F 2068*9da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_SPCL 9F Ta Xr csx_Parse_CISTPL_SWIL 9F 2069*9da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_VERS_1 9F Ta Xr csx_Parse_CISTPL_VERS_2 9F 2070*9da20b8aSRobert Mustacchi.It Xr csx_ParseTuple 9F Ta Xr csx_Put16 9F 2071*9da20b8aSRobert Mustacchi.It Xr csx_Put32 9F Ta Xr csx_Put64 9F 2072*9da20b8aSRobert Mustacchi.It Xr csx_Put8 9F Ta Xr csx_RegisterClient 9F 2073*9da20b8aSRobert Mustacchi.It Xr csx_ReleaseConfiguration 9F Ta Xr csx_ReleaseIO 9F 2074*9da20b8aSRobert Mustacchi.It Xr csx_ReleaseIRQ 9F Ta Xr csx_ReleaseSocketMask 9F 2075*9da20b8aSRobert Mustacchi.It Xr csx_ReleaseWindow 9F Ta Xr csx_RemoveDeviceNode 9F 2076*9da20b8aSRobert Mustacchi.It Xr csx_RepGet16 9F Ta Xr csx_RepGet32 9F 2077*9da20b8aSRobert Mustacchi.It Xr csx_RepGet64 9F Ta Xr csx_RepGet8 9F 2078*9da20b8aSRobert Mustacchi.It Xr csx_RepPut16 9F Ta Xr csx_RepPut32 9F 2079*9da20b8aSRobert Mustacchi.It Xr csx_RepPut64 9F Ta Xr csx_RepPut8 9F 2080*9da20b8aSRobert Mustacchi.It Xr csx_RequestConfiguration 9F Ta Xr csx_RequestIO 9F 2081*9da20b8aSRobert Mustacchi.It Xr csx_RequestIRQ 9F Ta Xr csx_RequestSocketMask 9F 2082*9da20b8aSRobert Mustacchi.It Xr csx_RequestWindow 9F Ta Xr csx_ResetFunction 9F 2083*9da20b8aSRobert Mustacchi.It Xr csx_SetEventMask 9F Ta Xr csx_SetHandleOffset 9F 2084*9da20b8aSRobert Mustacchi.It Xr csx_ValidateCIS 9F Ta 2085*9da20b8aSRobert Mustacchi.El 2086*9da20b8aSRobert Mustacchi.Ss STREAMS related functions 2087*9da20b8aSRobert MustacchiThese functions are meant to be used when interacting with STREAMS 2088*9da20b8aSRobert Mustacchidevices or when implementing one. 2089*9da20b8aSRobert MustacchiWhen a STREAMS driver is opened, it receives messages on a queue which 2090*9da20b8aSRobert Mustacchiare then processed and can be sent back. 2091*9da20b8aSRobert MustacchiAs different queues are often linked together, the most common thing is 2092*9da20b8aSRobert Mustacchito process a message and then pass the message onto the next queue using 2093*9da20b8aSRobert Mustacchithe 2094*9da20b8aSRobert Mustacchi.Xr putnext 9F 2095*9da20b8aSRobert Mustacchifunction. 2096*9da20b8aSRobert Mustacchi.Pp 2097*9da20b8aSRobert MustacchiSTREAMS messages are passed around using message blocks, which use the 2098*9da20b8aSRobert Mustacchi.Vt mblk_t 2099*9da20b8aSRobert Mustacchitype. 2100*9da20b8aSRobert MustacchiSee 2101*9da20b8aSRobert Mustacchi.Sx Message Block Functions 2102*9da20b8aSRobert Mustacchifor more about how the data structure and functions that manipulate 2103*9da20b8aSRobert Mustacchimessage blocks. 2104*9da20b8aSRobert Mustacchi.Pp 2105*9da20b8aSRobert MustacchiThese functions should generally not be used when implementing a 2106*9da20b8aSRobert Mustacchinetworking device driver today. 2107*9da20b8aSRobert MustacchiSee 2108*9da20b8aSRobert Mustacchi.Xr mac 9E 2109*9da20b8aSRobert Mustacchiinstead. 2110*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2111*9da20b8aSRobert Mustacchi.It Xr backq 9F Ta Xr bcanput 9F 2112*9da20b8aSRobert Mustacchi.It Xr bcanputnext 9F Ta Xr canput 9F 2113*9da20b8aSRobert Mustacchi.It Xr canputnext 9F Ta Xr enableok 9F 2114*9da20b8aSRobert Mustacchi.It Xr flushband 9F Ta Xr flushq 9F 2115*9da20b8aSRobert Mustacchi.It Xr freezestr 9F Ta Xr getq 9F 2116*9da20b8aSRobert Mustacchi.It Xr insq 9F Ta Xr merror 9F 2117*9da20b8aSRobert Mustacchi.It Xr mexchange 9F Ta Xr noenable 9F 2118*9da20b8aSRobert Mustacchi.It Xr put 9F Ta Xr putbq 9F 2119*9da20b8aSRobert Mustacchi.It Xr putctl 9F Ta Xr putctl1 9F 2120*9da20b8aSRobert Mustacchi.It Xr putnext 9F Ta Xr putnextctl 9F 2121*9da20b8aSRobert Mustacchi.It Xr putnextctl1 9F Ta Xr putq 9F 2122*9da20b8aSRobert Mustacchi.It Xr mt-streams 9F Ta Xr qassociate 9F 2123*9da20b8aSRobert Mustacchi.It Xr qenable 9F Ta Xr qprocsoff 9F 2124*9da20b8aSRobert Mustacchi.It Xr qprocson 9F Ta Xr qreply 9F 2125*9da20b8aSRobert Mustacchi.It Xr qsize 9F Ta Xr qwait_sig 9F 2126*9da20b8aSRobert Mustacchi.It Xr qwait 9F Ta Xr qwriter 9F 2127*9da20b8aSRobert Mustacchi.It Xr OTHERQ 9F Ta Xr RD 9F 2128*9da20b8aSRobert Mustacchi.It Xr rmvq 9F Ta Xr SAMESTR 9F 2129*9da20b8aSRobert Mustacchi.It Xr unfreezestr 9F Ta Xr WR 9F 2130*9da20b8aSRobert Mustacchi.El 2131*9da20b8aSRobert Mustacchi.Ss STREAMS ioctls 2132*9da20b8aSRobert MustacchiThe following functions are used when a STREAMS-based device driver is 2133*9da20b8aSRobert Mustacchiprocessing its 2134*9da20b8aSRobert Mustacchi.Xr ioctl 9E 2135*9da20b8aSRobert Mustacchientry point. 2136*9da20b8aSRobert MustacchiUnlike character and block devices, STREAMS ioctls are passed around in 2137*9da20b8aSRobert Mustacchimessage blocks and copying data in and out of userland as STREAMS 2138*9da20b8aSRobert Mustacchiioctls are generally always processed in 2139*9da20b8aSRobert Mustacchi.Sy kernel 2140*9da20b8aSRobert Mustacchicontext. 2141*9da20b8aSRobert MustacchiThis means that the normal functions like 2142*9da20b8aSRobert Mustacchi.Xr ddi_copyin 9F 2143*9da20b8aSRobert Mustacchiand 2144*9da20b8aSRobert Mustacchi.Xr ddi_copyout 9F 2145*9da20b8aSRobert Mustacchicannot be used. 2146*9da20b8aSRobert MustacchiInstead, when a message block has a type of 2147*9da20b8aSRobert Mustacchi.Dv M_IOCTL , 2148*9da20b8aSRobert Mustacchithen these routines can often be used to convert the structure into one 2149*9da20b8aSRobert Mustacchithat asks for data to be copied in, copied out, or to finally 2150*9da20b8aSRobert Mustacchiacknowledge the ioctl as successful or to terminate the processing in 2151*9da20b8aSRobert Mustacchierror. 2152*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2153*9da20b8aSRobert Mustacchi.It Xr mcopyin 9F Ta Xr mcopyout 9F 2154*9da20b8aSRobert Mustacchi.It Xr mioc2ack 9F Ta Xr miocack 9F 2155*9da20b8aSRobert Mustacchi.It Xr miocnak 9F Ta Xr miocpullup 9F 2156*9da20b8aSRobert Mustacchi.It Xr mkiocb 9F Ta 2157*9da20b8aSRobert Mustacchi.El 2158*9da20b8aSRobert Mustacchi.Ss chpoll(9E) Related Functions 2159*9da20b8aSRobert MustacchiThese functions are present in service of the 2160*9da20b8aSRobert Mustacchi.Xr chpoll 9E 2161*9da20b8aSRobert Mustacchiinterface which is used to support the traditional 2162*9da20b8aSRobert Mustacchi.Xr poll 2 , 2163*9da20b8aSRobert Mustacchiand 2164*9da20b8aSRobert Mustacchi.Xr select 3C 2165*9da20b8aSRobert Mustacchiinterfaces as well as event ports through the 2166*9da20b8aSRobert Mustacchi.Xr port_get 3C 2167*9da20b8aSRobert Mustacchiinterface. 2168*9da20b8aSRobert MustacchiSee 2169*9da20b8aSRobert Mustacchi.Xr chpoll 9E 2170*9da20b8aSRobert Mustacchifor the specific cases this should be called. 2171*9da20b8aSRobert MustacchiIf a device driver does not implement the 2172*9da20b8aSRobert Mustacchi.Xr chpoll 9E 2173*9da20b8aSRobert Mustacchicharacter device entry point, then these functions should not be used. 2174*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2175*9da20b8aSRobert Mustacchi.It Xr pollhead_clean 9F Ta Xr pollwakeup 9F 2176*9da20b8aSRobert Mustacchi.El 2177*9da20b8aSRobert Mustacchi.Ss Kernel Statistics 2178*9da20b8aSRobert MustacchiThe kernel statistics or kstat framework provides an easy way of 2179*9da20b8aSRobert Mustacchiexporting statistic information to be consumed outside of the kernel. 2180*9da20b8aSRobert MustacchiUsers can interface with this data via 2181*9da20b8aSRobert Mustacchi.Xr kstat 8 2182*9da20b8aSRobert Mustacchiand the corresponding kstat library discussed in 2183*9da20b8aSRobert Mustacchi.Xr kstat 3KSTAT . 2184*9da20b8aSRobert Mustacchi.Pp 2185*9da20b8aSRobert MustacchiKernel statistics are grouped using a tuple of four identifiers, 2186*9da20b8aSRobert Mustacchiseparated by colons when using 2187*9da20b8aSRobert Mustacchi.Xr kstat 8 . 2188*9da20b8aSRobert MustacchiThese are, in order, the statistic module name, instance, a name 2189*9da20b8aSRobert Mustacchiwhich covers a group of statistics, and an individual name for a 2190*9da20b8aSRobert Mustacchistatistic. 2191*9da20b8aSRobert MustacchiIn addition, kernel statistics have a class which is used to group 2192*9da20b8aSRobert Mustacchisimilar named groups of statistics together across devices. 2193*9da20b8aSRobert MustacchiWhen using 2194*9da20b8aSRobert Mustacchi.Xr kstat_create 9F , 2195*9da20b8aSRobert Mustacchidrivers specify the first three parts of the tuple and the class. 2196*9da20b8aSRobert MustacchiThe naming of individual statistics, the last part of the tuple, varies 2197*9da20b8aSRobert Mustacchibased upon the type of the statistic. 2198*9da20b8aSRobert MustacchiFor the most part, drivers will use the kstat type 2199*9da20b8aSRobert Mustacchi.Dv KSTAT_TYPE_NAMED , 2200*9da20b8aSRobert Mustacchiwhich allows multiple name-value pairs to exist within the statistic. 2201*9da20b8aSRobert MustacchiFor example, the kernel's layer 2 networking framework, 2202*9da20b8aSRobert Mustacchi.Xr mac 9E , 2203*9da20b8aSRobert Mustacchicreates a kstat with the driver's name and instance and names it 2204*9da20b8aSRobert Mustacchi.Dq mac . 2205*9da20b8aSRobert MustacchiWithin this named group, there are statistics for all of the different 2206*9da20b8aSRobert Mustacchiindividual stats that the kernel and devices track such as bytes 2207*9da20b8aSRobert Mustacchitransmitted and received, the state and speed of the link, and 2208*9da20b8aSRobert Mustacchiadvertised and enabled capabilities. 2209*9da20b8aSRobert Mustacchi.Pp 2210*9da20b8aSRobert MustacchiA device driver can initialize a kstat with the 2211*9da20b8aSRobert Mustacchi.Xr kstat_create 9F 2212*9da20b8aSRobert Mustacchifunction. 2213*9da20b8aSRobert MustacchiIt will not be made accessible to users until the 2214*9da20b8aSRobert Mustacchi.Xr kstat_install 9F 2215*9da20b8aSRobert Mustacchifunction is called. 2216*9da20b8aSRobert MustacchiThe device driver must perform additional initialization of the kstat 2217*9da20b8aSRobert Mustacchibefore proceeding and calling 2218*9da20b8aSRobert Mustacchi.Xr kstat_install 9F . 2219*9da20b8aSRobert MustacchiThe kstat structure that drivers see is discussed in 2220*9da20b8aSRobert Mustacchi.Xr kstat 9S . 2221*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2222*9da20b8aSRobert Mustacchi.It Xr kstat_create 9F Ta Xr kstat_delete 9F 2223*9da20b8aSRobert Mustacchi.It Xr kstat_install 9F Ta Xr kstat_named_init 9F 2224*9da20b8aSRobert Mustacchi.It Xr kstat_named_setstr 9F Ta Xr kstat_queue 9F 2225*9da20b8aSRobert Mustacchi.It Xr kstat_runq_back_to_waitq 9F Ta Xr kstat_runq_enter 9F 2226*9da20b8aSRobert Mustacchi.It Xr kstat_runq_exit 9F Ta Xr kstat_waitq_enter 9F 2227*9da20b8aSRobert Mustacchi.It Xr kstat_waitq_exit 9F Ta Xr kstat_waitq_to_runq 9F 2228*9da20b8aSRobert Mustacchi.El 2229*9da20b8aSRobert Mustacchi.Ss NDI Events 2230*9da20b8aSRobert MustacchiThese functions are used to allow a device driver to register for 2231*9da20b8aSRobert Mustacchicertain events that might occur to its device or a parent in the tree 2232*9da20b8aSRobert Mustacchiand receive a callback function when they occur. 2233*9da20b8aSRobert MustacchiA good example of this is when a device has been removed from the system 2234*9da20b8aSRobert Mustacchisuch as someone just pulling out a USB device or NVMe U.2 device. 2235*9da20b8aSRobert MustacchiThe event handlers work by first getting a cookie that names the type of 2236*9da20b8aSRobert Mustacchievent with 2237*9da20b8aSRobert Mustacchi.Xr ddi_get_eventcookie 9F 2238*9da20b8aSRobert Mustacchiand then registering the callback with 2239*9da20b8aSRobert Mustacchi.Xr ddi_add_event_handler 9F . 2240*9da20b8aSRobert Mustacchi.Pp 2241*9da20b8aSRobert MustacchiThe 2242*9da20b8aSRobert Mustacchi.Xr ddi_cb_register 9F 2243*9da20b8aSRobert Mustacchifunction is used to collect over classes of events such as when 2244*9da20b8aSRobert Mustacchiparticipating in dynamic interrupt sharing. 2245*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2246*9da20b8aSRobert Mustacchi.It Xr ddi_add_event_handler 9F Ta Xr ddi_cb_register 9F 2247*9da20b8aSRobert Mustacchi.It Xr ddi_cb_unregister 9F Ta Xr ddi_get_eventcookie 9F 2248*9da20b8aSRobert Mustacchi.It Xr ddi_remove_event_handler 9F Ta 2249*9da20b8aSRobert Mustacchi.El 2250*9da20b8aSRobert Mustacchi.Ss Layered Device Interfaces 2251*9da20b8aSRobert MustacchiThe LDI 2252*9da20b8aSRobert Mustacchi.Pq Layered Device Interface 2253*9da20b8aSRobert Mustacchiprovides a mechanism for a driver to open up another device in the 2254*9da20b8aSRobert Mustacchikernel and begin calling basic operations on the device as though the 2255*9da20b8aSRobert Mustacchicalling driver were a normal user process. 2256*9da20b8aSRobert MustacchiThrough the LDI, drivers can perform equivalents to the basic file 2257*9da20b8aSRobert Mustacchi.Xr read 2 2258*9da20b8aSRobert Mustacchiand 2259*9da20b8aSRobert Mustacchi.Xr write 2 2260*9da20b8aSRobert Mustacchicalls, look up properties on the device, perform networking style calls 2261*9da20b8aSRobert Mustacchiala 2262*9da20b8aSRobert Mustacchi.Xr getmsg 2 2263*9da20b8aSRobert Mustacchiand 2264*9da20b8aSRobert Mustacchi.Xr pumsg 2 , 2265*9da20b8aSRobert Mustacchiand register callbacks to be called when something happens to the 2266*9da20b8aSRobert Mustacchiunderlying device. 2267*9da20b8aSRobert MustacchiFor example, the ZFS file system uses the LDI to open and operate on 2268*9da20b8aSRobert Mustacchiblock devices. 2269*9da20b8aSRobert Mustacchi.Pp 2270*9da20b8aSRobert MustacchiBefore opening a device itself, callers must obtain a notion of their 2271*9da20b8aSRobert Mustacchiidentity which is used when making subsequent calls. 2272*9da20b8aSRobert MustacchiThe simplest form is often to use the device's 2273*9da20b8aSRobert Mustacchi.Vt dev_info_t 2274*9da20b8aSRobert Mustacchiand call 2275*9da20b8aSRobert Mustacchi.Xr ldi_ident_from_dip 9F ; 2276*9da20b8aSRobert Mustacchihowever, there are also methods available based upon having a 2277*9da20b8aSRobert Mustacchi.Vt dev_t 2278*9da20b8aSRobert Mustacchior a STREAMS 2279*9da20b8aSRobert Mustacchi.Vt struct queue . 2280*9da20b8aSRobert Mustacchi.Pp 2281*9da20b8aSRobert MustacchiOnce that identity is established, there are several ways to open a 2282*9da20b8aSRobert Mustacchidevice such as 2283*9da20b8aSRobert Mustacchi.Xr ldi_open_by_dev 9F , 2284*9da20b8aSRobert Mustacchi.Xr ldi_open_by_devid 9F , 2285*9da20b8aSRobert Mustacchior 2286*9da20b8aSRobert Mustacchi.Xr ldi_open_by_name 9F . 2287*9da20b8aSRobert MustacchiOnce an LDI device has been opened, then all of the other functions may 2288*9da20b8aSRobert Mustacchibe used to operate on the device; however, consumers of the LDI must 2289*9da20b8aSRobert Mustacchithink carefully about what kind of device they are opening. 2290*9da20b8aSRobert MustacchiWhile a kernel pseudo-device driver cannot disappear while it is open, 2291*9da20b8aSRobert Mustacchiwhen the device represents an actual piece of hardware, it is possible 2292*9da20b8aSRobert Mustacchifor it to be physically removed and no longer be accessible. 2293*9da20b8aSRobert MustacchiConsumers should not assume that a layered device will always be 2294*9da20b8aSRobert Mustacchipresent. 2295*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2296*9da20b8aSRobert Mustacchi.It Xr ldi_add_event_handler 9F Ta Xr ldi_aread 9F 2297*9da20b8aSRobert Mustacchi.It Xr ldi_awrite 9F Ta Xr ldi_close 9F 2298*9da20b8aSRobert Mustacchi.It Xr ldi_devmap 9F Ta Xr ldi_dump 9F 2299*9da20b8aSRobert Mustacchi.It Xr ldi_ev_finalize 9F Ta Xr ldi_ev_get_cookie 9F 2300*9da20b8aSRobert Mustacchi.It Xr ldi_ev_get_type 9F Ta Xr ldi_ev_notify 9F 2301*9da20b8aSRobert Mustacchi.It Xr ldi_ev_register_callbacks 9F Ta Xr ldi_ev_remove_callbacks 9F 2302*9da20b8aSRobert Mustacchi.It Xr ldi_get_dev 9F Ta Xr ldi_get_devid 9F 2303*9da20b8aSRobert Mustacchi.It Xr ldi_get_eventcookie 9F Ta Xr ldi_get_minor_name 9F 2304*9da20b8aSRobert Mustacchi.It Xr ldi_get_otyp 9F Ta Xr ldi_get_size 9F 2305*9da20b8aSRobert Mustacchi.It Xr ldi_getmsg 9F Ta Xr ldi_ident_from_dev 9F 2306*9da20b8aSRobert Mustacchi.It Xr ldi_ident_from_dip 9F Ta Xr ldi_ident_from_stream 9F 2307*9da20b8aSRobert Mustacchi.It Xr ldi_ident_release 9F Ta Xr ldi_ioctl 9F 2308*9da20b8aSRobert Mustacchi.It Xr ldi_open_by_dev 9F Ta Xr ldi_open_by_devid 9F 2309*9da20b8aSRobert Mustacchi.It Xr ldi_open_by_name 9F Ta Xr ldi_poll 9F 2310*9da20b8aSRobert Mustacchi.It Xr ldi_prop_exists 9F Ta Xr ldi_prop_get_int 9F 2311*9da20b8aSRobert Mustacchi.It Xr ldi_prop_get_int64 9F Ta Xr ldi_prop_lookup_byte_array 9F 2312*9da20b8aSRobert Mustacchi.It Xr ldi_prop_lookup_int_array 9F Ta Xr ldi_prop_lookup_int64_array 9F 2313*9da20b8aSRobert Mustacchi.It Xr ldi_prop_lookup_string_array 9F Ta Xr ldi_prop_lookup_string 9F 2314*9da20b8aSRobert Mustacchi.It Xr ldi_putmsg 9F Ta Xr ldi_read 9F 2315*9da20b8aSRobert Mustacchi.It Xr ldi_remove_event_handler 9F Ta Xr ldi_strategy 9F 2316*9da20b8aSRobert Mustacchi.It Xr ldi_write 9F Ta 2317*9da20b8aSRobert Mustacchi.El 2318*9da20b8aSRobert Mustacchi.Ss Signal Manipulation 2319*9da20b8aSRobert MustacchiThese utility functions all relate to understanding whether or not a 2320*9da20b8aSRobert Mustacchiprocess can receive a signal an actually delivering one to a process 2321*9da20b8aSRobert Mustacchifrom a driver. 2322*9da20b8aSRobert MustacchiThis interface is specific to device drivers and should not be used by 2323*9da20b8aSRobert Mustacchithe broader kernel. 2324*9da20b8aSRobert MustacchiThese interfaces are not recommended and should only be used after 2325*9da20b8aSRobert Mustacchiconsultation. 2326*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2327*9da20b8aSRobert Mustacchi.It Xr ddi_can_receive_sig 9F Ta Xr proc_ref 9F 2328*9da20b8aSRobert Mustacchi.It Xr proc_signal 9F Ta Xr proc_unref 9F 2329*9da20b8aSRobert Mustacchi.El 2330*9da20b8aSRobert Mustacchi.Ss Getting at Surrounding Context 2331*9da20b8aSRobert MustacchiThese functions allow a driver to better understand its current context. 2332*9da20b8aSRobert MustacchiFor example, some drivers have to deal with providing polled I/O or take 2333*9da20b8aSRobert Mustacchispecial care as part of creating a kernel crash dump. 2334*9da20b8aSRobert MustacchiThese cases may need to call the 2335*9da20b8aSRobert Mustacchi.Xr ddi_in_panic 9F 2336*9da20b8aSRobert Mustacchifunction. 2337*9da20b8aSRobert MustacchiThe other functions generally provie a way to get at information such as 2338*9da20b8aSRobert Mustacchithe process ID or other information from the system; however, this 2339*9da20b8aSRobert Mustacchigenerally should not be needed or used. 2340*9da20b8aSRobert MustacchiAlmost all values exposed by say 2341*9da20b8aSRobert Mustacchi.Xr drv_getparm 9F 2342*9da20b8aSRobert Mustacchihave more usable first-class methods of getting at the data. 2343*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2344*9da20b8aSRobert Mustacchi.It Xr ddi_get_kt_did 9F Ta Xr ddi_get_pid 9F 2345*9da20b8aSRobert Mustacchi.It Xr ddi_in_panic 9F Ta Xr drv_getparm 9F 2346*9da20b8aSRobert Mustacchi.El 2347*9da20b8aSRobert Mustacchi.Ss Driver Memory Mapping 2348*9da20b8aSRobert MustacchiThese functions are present for device drivers that implement the 2349*9da20b8aSRobert Mustacchi.Xr devmap 9E 2350*9da20b8aSRobert Mustacchior 2351*9da20b8aSRobert Mustacchi.Xr segmap 9E 2352*9da20b8aSRobert Mustacchientry points. 2353*9da20b8aSRobert MustacchiThe 2354*9da20b8aSRobert Mustacchi.Xr ddi_umem_alloc 9F 2355*9da20b8aSRobert Mustacchiroutines are used to allocate and lock memory that can later be used as 2356*9da20b8aSRobert Mustacchipart of passing this memory to userland through the mapping entry 2357*9da20b8aSRobert Mustacchipoints. 2358*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2359*9da20b8aSRobert Mustacchi.It Xr ddi_devmap_segmap 9F Ta Xr ddi_mmap_get_model 9F 2360*9da20b8aSRobert Mustacchi.It Xr ddi_segmap_setup 9F Ta Xr ddi_segmap 9F 2361*9da20b8aSRobert Mustacchi.It Xr ddi_umem_alloc 9F Ta Xr ddi_umem_free 9F 2362*9da20b8aSRobert Mustacchi.It Xr ddi_umem_iosetup 9F Ta Xr ddi_umem_lock 9F 2363*9da20b8aSRobert Mustacchi.It Xr ddi_umem_unlock 9F Ta Xr ddi_unmap_regs 9F 2364*9da20b8aSRobert Mustacchi.It Xr devmap_default_access 9F Ta Xr devmap_devmem_setup 9F 2365*9da20b8aSRobert Mustacchi.It Xr devmap_do_ctxmgt 9F Ta Xr devmap_load 9F 2366*9da20b8aSRobert Mustacchi.It Xr devmap_set_ctx_timeout 9F Ta Xr devmap_setup 9F 2367*9da20b8aSRobert Mustacchi.It Xr devmap_umem_setup 9F Ta Xr devmap_unload 9F 2368*9da20b8aSRobert Mustacchi.El 2369*9da20b8aSRobert Mustacchi.Ss UTF-8, UTF-16, UTF-32, and Code Set Utilities 2370*9da20b8aSRobert MustacchiThese routines provide the ability to work with and deal with text in 2371*9da20b8aSRobert Mustacchidifferent encodings and code sets. 2372*9da20b8aSRobert MustacchiGenerally the kernel does not assume that much about the type of the text 2373*9da20b8aSRobert Mustacchithat it is operating in, though some subsystems will require that the 2374*9da20b8aSRobert Mustacchinames of things be ASCII only. 2375*9da20b8aSRobert Mustacchi.Pp 2376*9da20b8aSRobert MustacchiThe primary other locales that the system supports are generally UTF-8 2377*9da20b8aSRobert Mustacchibased and so the kernel provides a set of routines to deal with UTF-8 2378*9da20b8aSRobert Mustacchiand Unicode normalization. 2379*9da20b8aSRobert MustacchiHowever, there are still cases where different character encodings are 2380*9da20b8aSRobert Mustacchirequired or conversation between UTF-8 and some other type is required. 2381*9da20b8aSRobert MustacchiThis is provided by the kernel iconv framework, which provides a 2382*9da20b8aSRobert Mustacchisubset of the traditional userland iconv conversions. 2383*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2384*9da20b8aSRobert Mustacchi.It Xr kiconv_close 9F Ta Xr kiconv_open 9F 2385*9da20b8aSRobert Mustacchi.It Xr kiconv 9F Ta Xr kiconvstr 9F 2386*9da20b8aSRobert Mustacchi.It Xr u8_strcmp 9F Ta Xr u8_textprep_str 9F 2387*9da20b8aSRobert Mustacchi.It Xr u8_validate 9F Ta Xr uconv_u16tou32 9F 2388*9da20b8aSRobert Mustacchi.It Xr uconv_u16tou8 9F Ta Xr uconv_u32tou16 9F 2389*9da20b8aSRobert Mustacchi.It Xr uconv_u32tou8 9F Ta Xr uconv_u8tou16 9F 2390*9da20b8aSRobert Mustacchi.It Xr uconv_u8tou32 9F Ta 2391*9da20b8aSRobert Mustacchi.El 2392*9da20b8aSRobert Mustacchi.Ss Raw I/O Port Access 2393*9da20b8aSRobert MustacchiThis group of functions provides raw access to I/O ports on architecture 2394*9da20b8aSRobert Mustacchithat support them. 2395*9da20b8aSRobert MustacchiThese functions do not allow any coordination with other callers nor is 2396*9da20b8aSRobert Mustacchithe validity of the port assured in any way. 2397*9da20b8aSRobert MustacchiIn general, device drivers should use the normal register access 2398*9da20b8aSRobert Mustacchiroutines to access I/O ports. 2399*9da20b8aSRobert MustacchiSee 2400*9da20b8aSRobert Mustacchi.Sx Device Register Setup and Access 2401*9da20b8aSRobert Mustacchifor more information on the preferred way to setup and access registers. 2402*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2403*9da20b8aSRobert Mustacchi.It Xr inb 9F Ta Xr inw 9F 2404*9da20b8aSRobert Mustacchi.It Xr inl 9F Ta Xr outb 9F 2405*9da20b8aSRobert Mustacchi.It Xr outw 9F Ta Xr outl 9F 2406*9da20b8aSRobert Mustacchi.El 2407*9da20b8aSRobert Mustacchi.Ss Power Management 2408*9da20b8aSRobert MustacchiThese functions are used to raise and lower the internal power levels of 2409*9da20b8aSRobert Mustacchia device driver or to indicate to the kernel that the device is busy and 2410*9da20b8aSRobert Mustacchitherefore cannot have its power changed. 2411*9da20b8aSRobert MustacchiSee 2412*9da20b8aSRobert Mustacchi.Xr power 9E 2413*9da20b8aSRobert Mustacchifor additional information. 2414*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2415*9da20b8aSRobert Mustacchi.It Xr ddi_removing_power 9F Ta Xr pm_busy_component 9F 2416*9da20b8aSRobert Mustacchi.It Xr pm_idle_component 9F Ta Xr pm_lower_power 9F 2417*9da20b8aSRobert Mustacchi.It Xr pm_power_has_changed 9F Ta Xr pm_raise_power 9F 2418*9da20b8aSRobert Mustacchi.It Xr pm_trans_check 9F Ta 2419*9da20b8aSRobert Mustacchi.El 2420*9da20b8aSRobert Mustacchi.Ss Network Packet Hooks 2421*9da20b8aSRobert MustacchiThese functions are intended to be used by device drivers that wish to 2422*9da20b8aSRobert Mustacchiinspect and potentially modify packets along their path through the 2423*9da20b8aSRobert Mustacchinetworking stack. 2424*9da20b8aSRobert MustacchiThe most common use case is for implementing something like a network 2425*9da20b8aSRobert Mustacchifirewall. 2426*9da20b8aSRobert MustacchiOtherwise, if looking to add support for a new protocol or other network 2427*9da20b8aSRobert Mustacchiprocessing feature, one is better off more directly integrating with the 2428*9da20b8aSRobert Mustacchinetworking stack. 2429*9da20b8aSRobert Mustacchi.Pp 2430*9da20b8aSRobert MustacchiTo get started, drivers generally will need to first use 2431*9da20b8aSRobert Mustacchi.Xr net_protocol_lookup 9F 2432*9da20b8aSRobert Mustacchito get a handle to say that they're interested in looking at IPv4 or 2433*9da20b8aSRobert MustacchiIPv6 traffic and then can allocate an actual hook object with 2434*9da20b8aSRobert Mustacchi.Xr hook_alloc 9F . 2435*9da20b8aSRobert MustacchiAfter filling out the hook, the hook can be inserted into the actual 2436*9da20b8aSRobert Mustacchisystem with 2437*9da20b8aSRobert Mustacchi.Xr net_hook_register 9F . 2438*9da20b8aSRobert Mustacchi.Pp 2439*9da20b8aSRobert MustacchiHooks operate in the context of a networking stack. 2440*9da20b8aSRobert MustacchiEvery networking stack in the system is independent and therefore has 2441*9da20b8aSRobert Mustacchiits own set of interfaces, routing tables, settings, and related. 2442*9da20b8aSRobert MustacchiMost zones have their own networking stack. 2443*9da20b8aSRobert MustacchiThis is the exclusive-IP option that is described in 2444*9da20b8aSRobert Mustacchi.Xr zoneadm 8 . 2445*9da20b8aSRobert Mustacchi.Pp 2446*9da20b8aSRobert MustacchiDrivers can register to get a callback for every netstack in the system 2447*9da20b8aSRobert Mustacchiand be notified when they are created and destroyed. 2448*9da20b8aSRobert MustacchiThis is done by calling the 2449*9da20b8aSRobert Mustacchi.Xr net_instance_register 9F 2450*9da20b8aSRobert Mustacchifunction, filling out its data structure, and then finally calling 2451*9da20b8aSRobert Mustacchi.Xr net_instance_regster 9F . 2452*9da20b8aSRobert MustacchiLike other callback interfaces, the moment the callback functions are 2453*9da20b8aSRobert Mustacchiregistered, drivers need to expect that they're going to be called. 2454*9da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2455*9da20b8aSRobert Mustacchi.It Xr hook_alloc 9F Ta Xr hook_free 9F 2456*9da20b8aSRobert Mustacchi.It Xr net_event_notify_register 9F Ta Xr net_event_notify_unregister 9F 2457*9da20b8aSRobert Mustacchi.It Xr net_getifname 9F Ta Xr net_getlifaddr 9F 2458*9da20b8aSRobert Mustacchi.It Xr net_getmtu 9F Ta Xr net_getnetid 9F 2459*9da20b8aSRobert Mustacchi.It Xr net_getpmtuenabled 9F Ta Xr net_hook_register 9F 2460*9da20b8aSRobert Mustacchi.It Xr net_hook_unregister 9F Ta Xr net_inject_alloc 9F 2461*9da20b8aSRobert Mustacchi.It Xr net_inject_free 9F Ta Xr net_inject 9F 2462*9da20b8aSRobert Mustacchi.It Xr net_instance_alloc 9F Ta Xr net_instance_free 9F 2463*9da20b8aSRobert Mustacchi.It Xr net_instance_notify_register 9F Ta Xr net_instance_notify_unregister 9F 2464*9da20b8aSRobert Mustacchi.It Xr net_instance_protocol_unregister 9F Ta Xr net_instance_register 9F 2465*9da20b8aSRobert Mustacchi.It Xr net_instance_unregister 9F Ta Xr net_ispartialchecksum 9F 2466*9da20b8aSRobert Mustacchi.It Xr net_isvalidchecksum 9F Ta Xr net_kstat_create 9F 2467*9da20b8aSRobert Mustacchi.It Xr net_kstat_delete 9F Ta Xr net_lifgetnext 9F 2468*9da20b8aSRobert Mustacchi.It Xr net_netidtozonid 9F Ta Xr net_phygetnext 9F 2469*9da20b8aSRobert Mustacchi.It Xr net_phylookup 9F Ta Xr net_protocol_lookup 9F 2470*9da20b8aSRobert Mustacchi.It Xr net_protocol_notify_register 9F Ta Xr net_protocol_release 9F 2471*9da20b8aSRobert Mustacchi.It Xr net_protocol_walk 9F Ta Xr net_routeto 9F 2472*9da20b8aSRobert Mustacchi.It Xr net_zoneidtonetid 9F Ta Xr netinfo 9F 2473*9da20b8aSRobert Mustacchi.El 2474*9da20b8aSRobert Mustacchi.Sh SEE ALSO 2475*9da20b8aSRobert Mustacchi.Xr Intro 2 , 2476*9da20b8aSRobert Mustacchi.Xr Intro 9 , 2477*9da20b8aSRobert Mustacchi.Xr Intro 9E , 2478*9da20b8aSRobert Mustacchi.Xr Intro 9S 2479*9da20b8aSRobert Mustacchi.Rs 2480*9da20b8aSRobert Mustacchi.%T illumos Developer's Guide 2481*9da20b8aSRobert Mustacchi.%U https://www.illumos.org/books/dev/ 2482*9da20b8aSRobert Mustacchi.Re 2483*9da20b8aSRobert Mustacchi.Rs 2484*9da20b8aSRobert Mustacchi.%T Writing Device Drivers 2485*9da20b8aSRobert Mustacchi.%U https://www.illumos.org/books/wdd/ 2486*9da20b8aSRobert Mustacchi.Re 2487