19da20b8aSRobert Mustacchi.\" 29da20b8aSRobert Mustacchi.\" This file and its contents are supplied under the terms of the 39da20b8aSRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 49da20b8aSRobert Mustacchi.\" You may only use this file in accordance with the terms of version 59da20b8aSRobert Mustacchi.\" 1.0 of the CDDL. 69da20b8aSRobert Mustacchi.\" 79da20b8aSRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 89da20b8aSRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 99da20b8aSRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 109da20b8aSRobert Mustacchi.\" 119da20b8aSRobert Mustacchi.\" 129da20b8aSRobert Mustacchi.\" Copyright 2023 Oxide Computer Company 13*496cffd8SPeter Tribble.\" Copyright 2023 Peter Tribble 149da20b8aSRobert Mustacchi.\" 15*496cffd8SPeter Tribble.Dd July 17, 2023 169da20b8aSRobert Mustacchi.Dt INTRO 9F 179da20b8aSRobert Mustacchi.Os 189da20b8aSRobert Mustacchi.Sh NAME 199da20b8aSRobert Mustacchi.Nm Intro 209da20b8aSRobert Mustacchi.Nd Introduction to kernel and device driver functions 219da20b8aSRobert Mustacchi.Sh SYNOPSIS 229da20b8aSRobert Mustacchi.In sys/ddi.h 239da20b8aSRobert Mustacchi.In sys/sunddi.h 249da20b8aSRobert Mustacchi.Sh DESCRIPTION 259da20b8aSRobert MustacchiSection 9F of the manual page describes functions that are used for device 269da20b8aSRobert Mustacchidrivers, kernel modules, and the implementation of the kernel itself. 279da20b8aSRobert MustacchiThis first provides an overview for the use of kernel functions and portions of 289da20b8aSRobert Mustacchithe manual that are specific to the kernel. 299da20b8aSRobert MustacchiAfter that, we have grouped together most functions that are available by use, 309da20b8aSRobert Mustacchiwith some brief commentary and introduction. 319da20b8aSRobert Mustacchi.Pp 329da20b8aSRobert MustacchiMost manual pages are similar to those in other sections. 339da20b8aSRobert MustacchiThey have common fields such as the NAME, a SYNOPSIS to show which header files 349da20b8aSRobert Mustacchito include and prototypes, an extended DESCRIPTION discussing its use, and the 359da20b8aSRobert Mustacchicommon combination of RETURN VALUES and ERRORS. 369da20b8aSRobert MustacchiSome manuals will have examples and additional manuals to reference in the SEE 379da20b8aSRobert MustacchiALSO section. 389da20b8aSRobert Mustacchi.Ss RETURN VALUES and ERRORS 399da20b8aSRobert MustacchiOne major difference when programming in the kernel versus userland is that 409da20b8aSRobert Mustacchithere is no equivalent to 419da20b8aSRobert Mustacchi.Va errno . 429da20b8aSRobert MustacchiInstead, there are a few common patterns that are used throughout the kernel 439da20b8aSRobert Mustacchithat we'll discuss. 449da20b8aSRobert MustacchiWhile there are common patterns, please be aware that due to the natural 459da20b8aSRobert Mustacchievolution of the system, you will need to read the specifics of the 469da20b8aSRobert Mustacchisection. 479da20b8aSRobert Mustacchi.Bl -bullet 489da20b8aSRobert Mustacchi.It 499da20b8aSRobert MustacchiMany functions will return a specific DDI 509da20b8aSRobert Mustacchi.Pq Device Driver Interface 519da20b8aSRobert Mustacchivalue, which is commonly one of 529da20b8aSRobert Mustacchi.Dv DDI_SUCCESS 539da20b8aSRobert Mustacchior 549da20b8aSRobert Mustacchi.Dv DDI_FAILURE , 559da20b8aSRobert Mustacchiindicating success and failure respectively. 569da20b8aSRobert MustacchiSome functions will return additional error codes to indicate why something 579da20b8aSRobert Mustacchifailed. 589da20b8aSRobert MustacchiIn general, when checking a response code is always preferred to compare that 599da20b8aSRobert Mustacchisomething equals or does not equal 609da20b8aSRobert Mustacchi.Dv DDI_SUCCESS 619da20b8aSRobert Mustacchias there can be many different error cases and additional ones can be added over 629da20b8aSRobert Mustacchitime. 639da20b8aSRobert Mustacchi.It 649da20b8aSRobert MustacchiMany routines explicitly return 659da20b8aSRobert Mustacchi.Sy 0 669da20b8aSRobert Mustacchion success and will return an explicit error number. 679da20b8aSRobert Mustacchi.Xr Intro 2 689da20b8aSRobert Mustacchihas a list of error numbers. 699da20b8aSRobert Mustacchi.It 709da20b8aSRobert MustacchiThere are classes of functions that return either a pointer or a boolean type, 719da20b8aSRobert Mustacchieither the C99 729da20b8aSRobert Mustacchi.Vt bool 739da20b8aSRobert Mustacchior the system's traditional type 749da20b8aSRobert Mustacchi.Vt boolean_t . 759da20b8aSRobert MustacchiIn these cases, sometimes a more detailed error is provided via an additional 769da20b8aSRobert Mustacchiargument such as a 779da20b8aSRobert Mustacchi.Vt "int *" . 789da20b8aSRobert MustacchiAbsent such an argument, there is generally no more detailed information 799da20b8aSRobert Mustacchiavailable. 809da20b8aSRobert Mustacchi.El 819da20b8aSRobert Mustacchi.Ss CONTEXT 829da20b8aSRobert MustacchiThe CONTEXT section of a manual page describes the times in which this function 839da20b8aSRobert Mustacchimay be called. 849da20b8aSRobert MustacchiIn generally there are three different contexts that come up: 859da20b8aSRobert Mustacchi.Bl -tag -width Ds 869da20b8aSRobert Mustacchi.It Sy User 879da20b8aSRobert MustacchiUser context implies that the thread of execution is operating because a user 889da20b8aSRobert Mustacchithread has entered the kernel for an operation. 899da20b8aSRobert MustacchiWhen an application issues a system call such as 909da20b8aSRobert Mustacchi.Xr open 2 , 919da20b8aSRobert Mustacchi.Xr read 2 , 929da20b8aSRobert Mustacchi.Xr write 2 , 939da20b8aSRobert Mustacchior 949da20b8aSRobert Mustacchi.Xr ioctl 2 959da20b8aSRobert Mustacchithen we are said to be in user context. 969da20b8aSRobert MustacchiWhen in user context, one can copy in or out data from a user's address space. 979da20b8aSRobert MustacchiWhen writing a character or block device driver, the majority of the time that a 989da20b8aSRobert Mustacchicharacter device operation such as the corresponding 999da20b8aSRobert Mustacchi.Xr open 9E , 1009da20b8aSRobert Mustacchi.Xr read 9E , 1019da20b8aSRobert Mustacchi.Xr write 9E , 1029da20b8aSRobert Mustacchiand 1039da20b8aSRobert Mustacchi.Xr ioctl 9E 1049da20b8aSRobert Mustacchientry point being called, it is executing in user context. 1059da20b8aSRobert MustacchiIt is possible to call those entry points through the kernel's layered device 1069da20b8aSRobert Mustacchiinterface, so drivers cannot assume those entry points will always have a user 1079da20b8aSRobert Mustacchiprocess present, strictly speaking. 1089da20b8aSRobert Mustacchi.It Sy Interrupt 1099da20b8aSRobert MustacchiInterrupt context refers to when the operating system is handling an interrupt 1109da20b8aSRobert Mustacchi.Po 1119da20b8aSRobert MustacchiSee 1129da20b8aSRobert Mustacchi.Sx Interrupt Related Functions 1139da20b8aSRobert Mustacchi.Pc 1149da20b8aSRobert Mustacchiand executing a registered interrupt handler. 1159da20b8aSRobert MustacchiInterrupt context is split into two different sets: high-level and low-level 1169da20b8aSRobert Mustacchiinterrupts. 1179da20b8aSRobert MustacchiMost device drivers are always going to be executing low-level interrupts. 1189da20b8aSRobert MustacchiTo determine whether an interrupt is considered high level or not, you should 1199da20b8aSRobert Mustacchipass the interrupt handle to the 1209da20b8aSRobert Mustacchi.Xr ddi_intr_get_pri 9F 1219da20b8aSRobert Mustacchifunction and compare the resulting priority with 1229da20b8aSRobert Mustacchi.Xr ddi_intr_get_hilevel_pri 9F . 1239da20b8aSRobert Mustacchi.Pp 1249da20b8aSRobert MustacchiWhen executing high-level interrupts, the thread may only execute a limited 1259da20b8aSRobert Mustacchinumber of functions. 1269da20b8aSRobert MustacchiIn particular, it may call 1279da20b8aSRobert Mustacchi.Xr ddi_intr_trigger_softint 9F , 1289da20b8aSRobert Mustacchi.Xr mutex_enter 9F , 1299da20b8aSRobert Mustacchiand 1309da20b8aSRobert Mustacchi.Xr mutex_exit 9F . 1319da20b8aSRobert MustacchiIt is critical that the mutex being used be properly initialized with the 1329da20b8aSRobert Mustacchidriver's interrupt priority. 1339da20b8aSRobert MustacchiThe system will transparently pick the correct implementation of a mutex based 1349da20b8aSRobert Mustacchion the interrupt type. 1359da20b8aSRobert MustacchiAside from the above, one must not block while in high-level interrupt context. 1369da20b8aSRobert Mustacchi.Pp 1379da20b8aSRobert MustacchiOn the other hand, when a thread is not in high-level interrupt context, most of 1389da20b8aSRobert Mustacchithese restrictions are lifted. 1399da20b8aSRobert MustacchiKernel memory may be allocated 1409da20b8aSRobert Mustacchi.Po 1419da20b8aSRobert Mustacchiif using a non-blocking allocation such as 1429da20b8aSRobert Mustacchi.Dv KM_NOSLEEP 1439da20b8aSRobert Mustacchior 1449da20b8aSRobert Mustacchi.Dv KM_NOSLEEP_LAZY 1459da20b8aSRobert Mustacchi.Pc , 1469da20b8aSRobert Mustacchiand many of the other documented functions may be called. 1479da20b8aSRobert Mustacchi.Pp 1489da20b8aSRobert MustacchiRegardless of whether a thread is in high-level or low-level interrupt context, 1499da20b8aSRobert Mustacchiit will never have a user context associated with it and therefore cannot use 1509da20b8aSRobert Mustacchiroutines like 1519da20b8aSRobert Mustacchi.Xr ddi_copyin 9F 1529da20b8aSRobert Mustacchior 1539da20b8aSRobert Mustacchi.Xr ddi_copyout 9F . 1549da20b8aSRobert Mustacchi.It Sy Kernel 1559da20b8aSRobert MustacchiKernel context refers to all other times in the kernel. 1569da20b8aSRobert MustacchiWhenever the kernel is executing something on a thread that is not associated 1579da20b8aSRobert Mustacchiwith a user process, then one is in kernel context. 1589da20b8aSRobert MustacchiThe most common situation for writers of kernel modules are things like timeout 1599da20b8aSRobert Mustacchicallbacks, such as 1609da20b8aSRobert Mustacchi.Xr timeout 9F 1619da20b8aSRobert Mustacchior 1629da20b8aSRobert Mustacchi.Xr ddi_periodic_add 9F , 1639da20b8aSRobert Mustacchicases where the kernel is invoking a driver's device operation routines such as 1649da20b8aSRobert Mustacchi.Xr attach 9E 1659da20b8aSRobert Mustacchiand 1669da20b8aSRobert Mustacchi.Xr detach 9E , 1679da20b8aSRobert Mustacchior many of the device driver's registered callbacks from frameworks such as the 1689da20b8aSRobert Mustacchi.Xr mac 9E , 1699da20b8aSRobert Mustacchi.Xr usba_hcdi 9E , 1709da20b8aSRobert Mustacchiand various portions of SCSI, USB, and block devices. 1719da20b8aSRobert Mustacchi.It Sy Framework-specific Contexts 1729da20b8aSRobert MustacchiSome manuals will discuss more specific constraints about when they can be used. 1739da20b8aSRobert MustacchiFor example, some functions may only be called while executing a specific entry 1749da20b8aSRobert Mustacchipoint like 1759da20b8aSRobert Mustacchi.Xr attach 9E . 1769da20b8aSRobert MustacchiAnother example of this is that the 1779da20b8aSRobert Mustacchi.Xr mac_transceiver_info_set_present 9F 1789da20b8aSRobert Mustacchifunction is only meant to be used while executing a networking driver's 1799da20b8aSRobert Mustacchi.Xr mct_info 9E 1809da20b8aSRobert Mustacchientry point. 1819da20b8aSRobert Mustacchi.El 1829da20b8aSRobert Mustacchi.Ss PARAMETERS 1839da20b8aSRobert MustacchiIn kernel manual pages 1849da20b8aSRobert Mustacchi.Pq section 9 , 1859da20b8aSRobert Mustacchieach function and entry point description generally has a separate list 1869da20b8aSRobert Mustacchiof parameters which are arguments to the function. 1879da20b8aSRobert MustacchiThe parameters section describes the basic purpose of each argument and 1889da20b8aSRobert Mustacchishould explain where such things often come from and any constraints on 1899da20b8aSRobert Mustacchitheir values. 1909da20b8aSRobert Mustacchi.Sh INTERFACES 1919da20b8aSRobert MustacchiFunctions below are organized into categories that describe their purpose. 1929da20b8aSRobert MustacchiIndividual functions are documented in their own manual pages. 1939da20b8aSRobert MustacchiFor each of these areas, we discuss high-level concepts behind each area and 1949da20b8aSRobert Mustacchiprovide a brief discussion of how to get started with it. 1959da20b8aSRobert MustacchiNote, some deprecated functions or older frameworks are not listed here. 1969da20b8aSRobert Mustacchi.Pp 1979da20b8aSRobert MustacchiEvery function listed below has its own manual page in section 9F and 1989da20b8aSRobert Mustacchican be read with 1999da20b8aSRobert Mustacchi.Xr man 1 . 2009da20b8aSRobert MustacchiIn addition, some corresponding concepts are documented in section 9 and 2019da20b8aSRobert Mustacchisome groups of functions are present to support a specific type of 2029da20b8aSRobert Mustacchidevice driver, which is discussed more in section 9E . 2039da20b8aSRobert Mustacchi.Ss Logging Functions 2049da20b8aSRobert MustacchiThrough the kernel there are often needs to log messages that either 2059da20b8aSRobert Mustacchimake it into the system log or on the console. 2069da20b8aSRobert MustacchiThese kinds of messages can be performed with the 2079da20b8aSRobert Mustacchi.Xr cmn_err 9F 2089da20b8aSRobert Mustacchifunction or one of its more specific variants that operate in the 2099da20b8aSRobert Mustacchicontext of a device 2109da20b8aSRobert Mustacchi.Po 2119da20b8aSRobert Mustacchi.Xr dev_err 9F 2129da20b8aSRobert Mustacchi.Pc 2139da20b8aSRobert Mustacchior a zone 2149da20b8aSRobert Mustacchi.Po 2159da20b8aSRobert Mustacchi.Xr zcmn_err 9F 2169da20b8aSRobert Mustacchi.Pc . 2179da20b8aSRobert Mustacchi.Pp 2189da20b8aSRobert MustacchiThe console should be used sparingly. 2199da20b8aSRobert MustacchiWhile a notice may be found there, one should assume that it may be 2209da20b8aSRobert Mustacchimissed either due to overflow, not being connected to say a serial 2219da20b8aSRobert Mustacchiconsole at the time, or some other reason. 2229da20b8aSRobert MustacchiWhile the system log is better than the console, folks need to take care 2239da20b8aSRobert Mustacchinot to spam the log. 2249da20b8aSRobert MustacchiImagine if someone logged every time a network packet was generated or 2259da20b8aSRobert Mustacchireceived, you'd quickly potentially run out of space and make it harder 2269da20b8aSRobert Mustacchito find useful messages for bizarre behavior. 2279da20b8aSRobert MustacchiIt's also important to remember that only system administrators and 2289da20b8aSRobert Mustacchiprivileged users can actually see this log. 2299da20b8aSRobert MustacchiWhere possible and appropriate use programmatic errors in routines that 2309da20b8aSRobert Mustacchiallow it. 2319da20b8aSRobert Mustacchi.Pp 2329da20b8aSRobert MustacchiThe system also supports a structured event log called a system event 2339da20b8aSRobert Mustacchithat is processed by 2349da20b8aSRobert Mustacchi.Xr syseventd 8 . 2359da20b8aSRobert MustacchiThis is used by the OS to provide notifications for things like device 2369da20b8aSRobert Mustacchiinsertion and removal or the change of a data link. 2379da20b8aSRobert MustacchiThese are driven by the 2389da20b8aSRobert Mustacchi.Xr ddi_log_sysevent 9F 2399da20b8aSRobert Mustacchifunction and allow arbitrary additional structured metadata in the form 2409da20b8aSRobert Mustacchiof a 2419da20b8aSRobert Mustacchi.Vt nvlist_t . 2429da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 2439da20b8aSRobert Mustacchi.It Xr cmn_err 9F Ta Xr dev_err 9F 2449da20b8aSRobert Mustacchi.It Xr vcmn_err 9F Ta Xr vzcmn_err 9F 2459da20b8aSRobert Mustacchi.It Xr zcmn_err 9F Ta Xr ddi_log_sysevent 9F 2469da20b8aSRobert Mustacchi.El 2479da20b8aSRobert Mustacchi.Ss Memory Allocation 2489da20b8aSRobert MustacchiAt the heart of most device drivers is memory allocation. 2499da20b8aSRobert MustacchiThe primary kernel allocator is called 2509da20b8aSRobert Mustacchi.Qq kmem 2519da20b8aSRobert Mustacchi.Pq kernel memory 2529da20b8aSRobert Mustacchiand it is based on the 2539da20b8aSRobert Mustacchi.Qq vmem 2549da20b8aSRobert Mustacchi.Pq virtual memory 2559da20b8aSRobert Mustacchisubsystem. 2569da20b8aSRobert MustacchiMost of the time, device drivers should use 2579da20b8aSRobert Mustacchi.Xr kmem_alloc 9F 2589da20b8aSRobert Mustacchiand 2599da20b8aSRobert Mustacchi.Xr kmem_zalloc 9F 2609da20b8aSRobert Mustacchito allocate memory and free it with 2619da20b8aSRobert Mustacchi.Xr kmem_free 9F . 2629da20b8aSRobert MustacchiBased on the original kmem and subsequent vmem papers, the kernel is 2639da20b8aSRobert Mustacchiinternally using object caches and magazines to allow high-throughput 2649da20b8aSRobert Mustacchiallocation in a multi-CPU environment. 2659da20b8aSRobert Mustacchi.Pp 2669da20b8aSRobert MustacchiWhen allocating memory, an important choice must be made: whether or not 2679da20b8aSRobert Mustacchito block for memory. 2689da20b8aSRobert MustacchiIf one opts to perform a sleeping allocation, then the caller can be 2699da20b8aSRobert Mustacchiguaranteed that the allocation will succeed, but it may take some time 2709da20b8aSRobert Mustacchiand the thread will be blocked during that entire duration. 2719da20b8aSRobert MustacchiThis is the 2729da20b8aSRobert Mustacchi.Dv KM_SLEEP 2739da20b8aSRobert Mustacchiflag. 2749da20b8aSRobert MustacchiOn the other hand, there are many circumstances where this is not 2759da20b8aSRobert Mustacchiappropriate, especially because a thread that is inside a memory 2769da20b8aSRobert Mustacchiallocation function cannot currently be cancelled. 2779da20b8aSRobert MustacchiIf the thread corresponds to a user process, then it will not be 2789da20b8aSRobert Mustacchikillable. 2799da20b8aSRobert Mustacchi.Pp 2809da20b8aSRobert MustacchiGiven that there are many situations where this is not appropriate, the 2819da20b8aSRobert Mustacchikernel offers an allocation mode where it will not block for memory to 2829da20b8aSRobert Mustacchibe available: 2839da20b8aSRobert Mustacchi.Dv KM_NOSLEEP 2849da20b8aSRobert Mustacchiand 2859da20b8aSRobert Mustacchi.Dv KM_NOSLEEP_LAZY . 2869da20b8aSRobert MustacchiThese allocations can fail and return 2879da20b8aSRobert Mustacchi.Dv NULL 2889da20b8aSRobert Mustacchiwhen they do fail. 2899da20b8aSRobert MustacchiEven though these are said to be no sleep operations, that does not mean 2909da20b8aSRobert Mustacchithat the caller may not end up temporarily blocked due to mutex 2919da20b8aSRobert Mustacchicontention or due to trying a bit more aggressively to reclaim memory in 2929da20b8aSRobert Mustacchithe case of 2939da20b8aSRobert Mustacchi.Dv KM_NOSLEEP . 2949da20b8aSRobert MustacchiUnless operating in special circumstances, using 2959da20b8aSRobert Mustacchi.Dv KM_NOSLEEP_LAZY 2969da20b8aSRobert Mustacchishould be preferred to 2979da20b8aSRobert Mustacchi.Dv KM_NOSLEEP . 2989da20b8aSRobert Mustacchi.Pp 2999da20b8aSRobert MustacchiIf a device driver has its own complex object that has more significant 3009da20b8aSRobert Mustacchiset up and tear down costs, then the kmem cache function family should 3019da20b8aSRobert Mustacchibe considered. 3029da20b8aSRobert MustacchiTo use a kmem cache, it must first be created using the 3039da20b8aSRobert Mustacchi.Xr kmem_cache_create 9F 3049da20b8aSRobert Mustacchifunction, which requires specifying the size, alignment, and 3059da20b8aSRobert Mustacchiconstructors and destructors. 3069da20b8aSRobert MustacchiIndividual objects are allocated from the cache with the 3079da20b8aSRobert Mustacchi.Xr kmem_cache_alloc 9F 3089da20b8aSRobert Mustacchifunction. 3099da20b8aSRobert MustacchiAn important constraint when using the caches is that when an object is 3109da20b8aSRobert Mustacchifreed with 3119da20b8aSRobert Mustacchi.Xr kmem_cache_free 9F , 3129da20b8aSRobert Mustacchiit is the callers responsibility to ensure that the object is returned 3139da20b8aSRobert Mustacchito its constructed state prior to freeing it. 3149da20b8aSRobert MustacchiIf the object is reused, prior to the kernel reclaiming the memory for 3159da20b8aSRobert Mustacchiother uses, then the constructor will not be called again. 3169da20b8aSRobert MustacchiMost device drivers do not need to create a kmem cache for their 3179da20b8aSRobert Mustacchiown allocations. 3189da20b8aSRobert Mustacchi.Pp 3199da20b8aSRobert MustacchiIf you are writing a device driver that is trying to interact with the 3209da20b8aSRobert Mustacchinetworking, STREAMS, or USB subsystems, then they are generally using 3219da20b8aSRobert Mustacchithe 3229da20b8aSRobert Mustacchi.Vt mblk_t 3239da20b8aSRobert Mustacchidata structure which is managed through a different set of APIs, though 3249da20b8aSRobert Mustacchithey are leveraging kmem under the hood. 3259da20b8aSRobert Mustacchi.Pp 3269da20b8aSRobert MustacchiThe vmem set of interfaces allows for the management of abstract regions 3279da20b8aSRobert Mustacchiof integers, generally representing memory or some other object, each 3289da20b8aSRobert Mustacchiwith an offset and length. 3299da20b8aSRobert MustacchiWhile it is not common that a device driver needs to do their own such 3309da20b8aSRobert Mustacchimanagement, 3319da20b8aSRobert Mustacchi.Xr vmem_create 9F 3329da20b8aSRobert Mustacchiand 3339da20b8aSRobert Mustacchi.Xr vmem_alloc 9F 3349da20b8aSRobert Mustacchiare what to reach for when the need arises. 3359da20b8aSRobert MustacchiRather than using vmem, if one needs to model a set of integers where 3369da20b8aSRobert Mustacchieach is a valid identifier, that is you need to allocate every integer 3379da20b8aSRobert Mustacchibetween 0 and 1000 as a distinct identifier, instead use 3389da20b8aSRobert Mustacchi.Xr id_space_create 9F 3399da20b8aSRobert Mustacchiwhich is discussed in 3409da20b8aSRobert Mustacchi.Sx Identifier Management . 3419da20b8aSRobert MustacchiFor more information on vmem, see 3429da20b8aSRobert Mustacchi.Xr vmem 9 . 3439da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 3449da20b8aSRobert Mustacchi.It Xr kmem_alloc 9F Ta Xr kmem_cache_alloc 9F 3459da20b8aSRobert Mustacchi.It Xr kmem_cache_create 9F Ta Xr kmem_cache_destroy 9F 3469da20b8aSRobert Mustacchi.It Xr kmem_cache_free 9F Ta Xr kmem_cache_set_move 9F 3479da20b8aSRobert Mustacchi.It Xr kmem_free 9F Ta Xr kmem_zalloc 9F 3489da20b8aSRobert Mustacchi.It Xr vmem_add 9F Ta Xr vmem_alloc 9F 3499da20b8aSRobert Mustacchi.It Xr vmem_contains 9F Ta Xr vmem_create 9F 3509da20b8aSRobert Mustacchi.It Xr vmem_destroy 9F Ta Xr vmem_free 9F 3519da20b8aSRobert Mustacchi.It Xr vmem_size 9F Ta Xr vmem_walk 9F 3529da20b8aSRobert Mustacchi.It Xr vmem_xalloc 9F Ta Xr vmem_xcreate 9F 3539da20b8aSRobert Mustacchi.It Xr vmem_xfree 9F Ta Xr bufcall 9F 3549da20b8aSRobert Mustacchi.It Xr esbbcall 9F Ta Xr qbufcall 9F 3559da20b8aSRobert Mustacchi.It Xr qunbufcall 9F Ta Xr unbufcall 9F 3569da20b8aSRobert Mustacchi.El 3579da20b8aSRobert Mustacchi.Ss String and libc Analogues 3589da20b8aSRobert MustacchiThe kernel has many analogues for classic libc functions that deal with 3599da20b8aSRobert Mustacchistring processing, memory copying, and related. 3609da20b8aSRobert MustacchiFor the most part, these behave similarly to their userland analogues, 3619da20b8aSRobert Mustacchibut there can be some differences in return values and for example, in 3629da20b8aSRobert Mustacchithe set of supported format characters in the case of 3639da20b8aSRobert Mustacchi.Xr snprintf 9F 3649da20b8aSRobert Mustacchiand related. 3659da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 3669da20b8aSRobert Mustacchi.It Xr ASSERT 9F Ta Xr bcmp 9F 3679da20b8aSRobert Mustacchi.It Xr bzero 9F Ta Xr bcopy 9F 3689da20b8aSRobert Mustacchi.It Xr ddi_strdup 9F Ta Xr ddi_strtol 9F 3699da20b8aSRobert Mustacchi.It Xr ddi_strtoll 9F Ta Xr ddi_strtoul 9F 3709da20b8aSRobert Mustacchi.It Xr ddi_strtoull 9F Ta Xr ddi_ffs 9F 3719da20b8aSRobert Mustacchi.It Xr ddi_fls 9F Ta Xr max 9F 3729da20b8aSRobert Mustacchi.It Xr memchr 9F Ta Xr memcmp 9F 3739da20b8aSRobert Mustacchi.It Xr memcpy 9F Ta Xr memmove 9F 3749da20b8aSRobert Mustacchi.It Xr memset 9F Ta Xr min 9F 3759da20b8aSRobert Mustacchi.It Xr numtos 9F Ta Xr snprintf 9F 3769da20b8aSRobert Mustacchi.It Xr sprintf 9F Ta Xr stoi 9F 3779da20b8aSRobert Mustacchi.It Xr strcasecmp 9F Ta Xr strcat 9F 3789da20b8aSRobert Mustacchi.It Xr strchr 9F Ta Xr strcmp 9F 3799da20b8aSRobert Mustacchi.It Xr strcpy 9F Ta Xr strdup 9F 3809da20b8aSRobert Mustacchi.It Xr strfree 9F Ta Xr string 9F 3819da20b8aSRobert Mustacchi.It Xr strlcat 9F Ta Xr strlcpy 9F 3829da20b8aSRobert Mustacchi.It Xr strlen 9F Ta Xr strlog 9F 3839da20b8aSRobert Mustacchi.It Xr strncasecmp 9F Ta Xr strncat 9F 3849da20b8aSRobert Mustacchi.It Xr strncmp 9F Ta Xr strncpy 9F 3859da20b8aSRobert Mustacchi.It Xr strnlen 9F Ta Xr strqget 9F 3869da20b8aSRobert Mustacchi.It Xr strqset 9F Ta Xr strrchr 9F 3879da20b8aSRobert Mustacchi.It Xr strspn 9F Ta Xr swab 9F 3889da20b8aSRobert Mustacchi.It Xr vsnprintf 9F Ta Xr va_arg 9F 3899da20b8aSRobert Mustacchi.It Xr va_copy 9F Ta Xr va_end 9F 3909da20b8aSRobert Mustacchi.It Xr va_start 9F Ta Xr vsprintf 9F 3919da20b8aSRobert Mustacchi.El 3929da20b8aSRobert Mustacchi.Ss Tree Data Structures 3939da20b8aSRobert MustacchiThese functions provide access to an intrusive self-balancing binary 3949da20b8aSRobert Mustacchitree that is generally used throughout illumos. 3959da20b8aSRobert MustacchiThe primary type here is the 3969da20b8aSRobert Mustacchi.Vt avl_tree_t . 3979da20b8aSRobert MustacchiStructures can be present in multiple trees and there are built-in 3989da20b8aSRobert Mustacchiwalkers for the data structure in 3999da20b8aSRobert Mustacchi.Xr mdb 1 . 4009da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 4019da20b8aSRobert Mustacchi.It Xr avl_add 9F Ta Xr avl_create 9F 4029da20b8aSRobert Mustacchi.It Xr avl_destroy_nodes 9F Ta Xr avl_destroy 9F 4039da20b8aSRobert Mustacchi.It Xr avl_find 9F Ta Xr avl_first 9F 4049da20b8aSRobert Mustacchi.It Xr avl_insert_here 9F Ta Xr avl_insert 9F 4059da20b8aSRobert Mustacchi.It Xr avl_is_empty 9F Ta Xr avl_last 9F 4069da20b8aSRobert Mustacchi.It Xr avl_nearest 9F Ta Xr AVL_NEXT 9F 4079da20b8aSRobert Mustacchi.It Xr avl_numnodes 9F Ta Xr AVL_PREV 9F 4089da20b8aSRobert Mustacchi.It Xr avl_remove 9F Ta Xr avl_swap 9F 4099da20b8aSRobert Mustacchi.El 4109da20b8aSRobert Mustacchi.Ss Linked Lists 4119da20b8aSRobert MustacchiThese functions provide a standard, intrusive doubly-linked list whose 4129da20b8aSRobert Mustacchitype is the 4139da20b8aSRobert Mustacchi.Vt list_t . 4149da20b8aSRobert MustacchiThis list implementation is used extensively throughout illumos, has 4159da20b8aSRobert Mustacchidebugging support through 4169da20b8aSRobert Mustacchi.Xr mdb 1 4179da20b8aSRobert Mustacchiwalkers, and is generally recommended rather than creating your own 4189da20b8aSRobert Mustacchilist. 4199da20b8aSRobert MustacchiDue to its intrusive nature, a given structure can be present on 4209da20b8aSRobert Mustacchimultiple lists. 4219da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 4229da20b8aSRobert Mustacchi.It Xr list_create 9F Ta Xr list_destroy 9F 4239da20b8aSRobert Mustacchi.It Xr list_head 9F Ta Xr list_insert_after 9F 4249da20b8aSRobert Mustacchi.It Xr list_insert_before 9F Ta Xr list_insert_head 9F 4259da20b8aSRobert Mustacchi.It Xr list_insert_tail 9F Ta Xr list_is_empty 9F 4269da20b8aSRobert Mustacchi.It Xr list_link_active 9F Ta Xr list_link_init 9F 4279da20b8aSRobert Mustacchi.It Xr list_link_replace 9F Ta Xr list_move_tail 9F 4289da20b8aSRobert Mustacchi.It Xr list_next 9F Ta Xr list_prev 9F 4299da20b8aSRobert Mustacchi.It Xr list_remove_head 9F Ta Xr list_remove_tail 9F 4309da20b8aSRobert Mustacchi.It Xr list_remove 9F Ta Xr list_tail 9F 4319da20b8aSRobert Mustacchi.El 4329da20b8aSRobert Mustacchi.Ss Name-Value Pairs 4339da20b8aSRobert MustacchiThe kernel often uses the 4349da20b8aSRobert Mustacchi.Vt nvlist_t 4359da20b8aSRobert Mustacchidata structure to pass around a list of typed name-value pairs. 4369da20b8aSRobert MustacchiThis data structure is used in diverse areas, particularly because of 4379da20b8aSRobert Mustacchiits ability to be serialized in different formats that are suitable not 4389da20b8aSRobert Mustacchionly for use between userland and the kernel, but also persistently to a 4399da20b8aSRobert Mustacchifile. 4409da20b8aSRobert Mustacchi.Pp 4419da20b8aSRobert MustacchiA 4429da20b8aSRobert Mustacchi.Vt nvlist_t 4439da20b8aSRobert Mustacchistructure is initialized with the 4449da20b8aSRobert Mustacchi.Xr nvlist_alloc 9F 4459da20b8aSRobert Mustacchifunction and can operate with two different degrees of uniqueness: a 4469da20b8aSRobert Mustacchimode where only names are unique or that every name is qualified to a 4479da20b8aSRobert Mustacchitype. 4489da20b8aSRobert MustacchiThe former means that if I have an integer name 4499da20b8aSRobert Mustacchi.Dq foo 4509da20b8aSRobert Mustacchiand then add a string, array, or any other value with the same name, it 4519da20b8aSRobert Mustacchiwill be replaced. 4529da20b8aSRobert MustacchiHowever, if were using the name and type as unique, then the value would 4539da20b8aSRobert Mustacchionly be replaced if both the pair's type and the name 4549da20b8aSRobert Mustacchi.Dq foo 4559da20b8aSRobert Mustacchimatched a pair that was already present. 4569da20b8aSRobert MustacchiOtherwise, the two different entries would co-exist. 4579da20b8aSRobert Mustacchi.Pp 4589da20b8aSRobert MustacchiWhen constructing an nvlist, it is normally backed by the normal kmem 4599da20b8aSRobert Mustacchiallocator and may either use sleeping or non-sleeping allocations. 4609da20b8aSRobert MustacchiIt is also possible to use a custom allocator, though that generally has 4619da20b8aSRobert Mustacchinot been necessary in the kernel. 4629da20b8aSRobert Mustacchi.Pp 4639da20b8aSRobert MustacchiSpecific keys and values can be looked up directly with the 4649da20b8aSRobert Mustacchinvlist_lookup family of functions, but the entire list can be iterated 4659da20b8aSRobert Mustacchias well, which is especially useful when trying to validate that no 4669da20b8aSRobert Mustacchiunknown keys are present in the list. 4679da20b8aSRobert MustacchiThe iteration API 4689da20b8aSRobert Mustacchi.Xr nvlist_next_nvpair 9F 4699da20b8aSRobert Mustacchiallows one to then get both the key's name, the type of value of the 4709da20b8aSRobert Mustacchipair, and then the value itself. 4719da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 4729da20b8aSRobert Mustacchi.It Xr nv_alloc_fini 9F Ta Xr nv_alloc_init 9F 4739da20b8aSRobert Mustacchi.It Xr nvlist_add_boolean_array 9F Ta Xr nvlist_add_boolean_value 9F 4749da20b8aSRobert Mustacchi.It Xr nvlist_add_boolean 9F Ta Xr nvlist_add_byte_array 9F 4759da20b8aSRobert Mustacchi.It Xr nvlist_add_byte 9F Ta Xr nvlist_add_int16_array 9F 4769da20b8aSRobert Mustacchi.It Xr nvlist_add_int16 9F Ta Xr nvlist_add_int32_array 9F 4779da20b8aSRobert Mustacchi.It Xr nvlist_add_int32 9F Ta Xr nvlist_add_int64_array 9F 4789da20b8aSRobert Mustacchi.It Xr nvlist_add_int64 9F Ta Xr nvlist_add_int8_array 9F 4799da20b8aSRobert Mustacchi.It Xr nvlist_add_int8 9F Ta Xr nvlist_add_nvlist_array 9F 4809da20b8aSRobert Mustacchi.It Xr nvlist_add_nvlist 9F Ta Xr nvlist_add_nvpair 9F 4819da20b8aSRobert Mustacchi.It Xr nvlist_add_string_array 9F Ta Xr nvlist_add_string 9F 4829da20b8aSRobert Mustacchi.It Xr nvlist_add_uint16_array 9F Ta Xr nvlist_add_uint16 9F 4839da20b8aSRobert Mustacchi.It Xr nvlist_add_uint32_array 9F Ta Xr nvlist_add_uint32 9F 4849da20b8aSRobert Mustacchi.It Xr nvlist_add_uint64_array 9F Ta Xr nvlist_add_uint64 9F 4859da20b8aSRobert Mustacchi.It Xr nvlist_add_uint8_array 9F Ta Xr nvlist_add_uint8 9F 4869da20b8aSRobert Mustacchi.It Xr nvlist_alloc 9F Ta Xr nvlist_dup 9F 4879da20b8aSRobert Mustacchi.It Xr nvlist_exists 9F Ta Xr nvlist_free 9F 4889da20b8aSRobert Mustacchi.It Xr nvlist_lookup_boolean_array 9F Ta Xr nvlist_lookup_boolean_value 9F 4899da20b8aSRobert Mustacchi.It Xr nvlist_lookup_boolean 9F Ta Xr nvlist_lookup_byte_array 9F 4909da20b8aSRobert Mustacchi.It Xr nvlist_lookup_byte 9F Ta Xr nvlist_lookup_int16_array 9F 4919da20b8aSRobert Mustacchi.It Xr nvlist_lookup_int16 9F Ta Xr nvlist_lookup_int32_array 9F 4929da20b8aSRobert Mustacchi.It Xr nvlist_lookup_int32 9F Ta Xr nvlist_lookup_int64_array 9F 4939da20b8aSRobert Mustacchi.It Xr nvlist_lookup_int64 9F Ta Xr nvlist_lookup_int8_array 9F 4949da20b8aSRobert Mustacchi.It Xr nvlist_lookup_int8 9F Ta Xr nvlist_lookup_nvlist_array 9F 4959da20b8aSRobert Mustacchi.It Xr nvlist_lookup_nvlist 9F Ta Xr nvlist_lookup_nvpair 9F 4969da20b8aSRobert Mustacchi.It Xr nvlist_lookup_pairs 9F Ta Xr nvlist_lookup_string_array 9F 4979da20b8aSRobert Mustacchi.It Xr nvlist_lookup_string 9F Ta Xr nvlist_lookup_uint16_array 9F 4989da20b8aSRobert Mustacchi.It Xr nvlist_lookup_uint16 9F Ta Xr nvlist_lookup_uint32_array 9F 4999da20b8aSRobert Mustacchi.It Xr nvlist_lookup_uint32 9F Ta Xr nvlist_lookup_uint64_array 9F 5009da20b8aSRobert Mustacchi.It Xr nvlist_lookup_uint64 9F Ta Xr nvlist_lookup_uint8_array 9F 5019da20b8aSRobert Mustacchi.It Xr nvlist_lookup_uint8 9F Ta Xr nvlist_merge 9F 5029da20b8aSRobert Mustacchi.It Xr nvlist_next_nvpair 9F Ta Xr nvlist_pack 9F 5039da20b8aSRobert Mustacchi.It Xr nvlist_remove_all 9F Ta Xr nvlist_remove 9F 5049da20b8aSRobert Mustacchi.It Xr nvlist_size 9F Ta Xr nvlist_t 9F 5059da20b8aSRobert Mustacchi.It Xr nvlist_unpack 9F Ta Xr nvlist_xalloc 9F 5069da20b8aSRobert Mustacchi.It Xr nvlist_xdup 9F Ta Xr nvlist_xpack 9F 5079da20b8aSRobert Mustacchi.It Xr nvlist_xunpack 9F Ta Xr nvpair_name 9F 5089da20b8aSRobert Mustacchi.It Xr nvpair_type 9F Ta Xr nvpair_value_boolean_array 9F 5099da20b8aSRobert Mustacchi.It Xr nvpair_value_byte_array 9F Ta Xr nvpair_value_byte 9F 5109da20b8aSRobert Mustacchi.It Xr nvpair_value_int16_array 9F Ta Xr nvpair_value_int16 9F 5119da20b8aSRobert Mustacchi.It Xr nvpair_value_int32_array 9F Ta Xr nvpair_value_int32 9F 5129da20b8aSRobert Mustacchi.It Xr nvpair_value_int64_array 9F Ta Xr nvpair_value_int64 9F 5139da20b8aSRobert Mustacchi.It Xr nvpair_value_int8_array 9F Ta Xr nvpair_value_int8 9F 5149da20b8aSRobert Mustacchi.It Xr nvpair_value_nvlist_array 9F Ta Xr nvpair_value_nvlist 9F 5159da20b8aSRobert Mustacchi.It Xr nvpair_value_string_array 9F Ta Xr nvpair_value_string 9F 5169da20b8aSRobert Mustacchi.It Xr nvpair_value_uint16_array 9F Ta Xr nvpair_value_uint16 9F 5179da20b8aSRobert Mustacchi.It Xr nvpair_value_uint32_array 9F Ta Xr nvpair_value_uint32 9F 5189da20b8aSRobert Mustacchi.It Xr nvpair_value_uint64_array 9F Ta Xr nvpair_value_uint64 9F 5199da20b8aSRobert Mustacchi.It Xr nvpair_value_uint8_array 9F Ta Xr nvpair_value_uint8 9F 5209da20b8aSRobert Mustacchi.El 5219da20b8aSRobert Mustacchi.Ss Identifier Management 5229da20b8aSRobert MustacchiA common challenge in the kernel is the management of a series of 5239da20b8aSRobert Mustacchidifferent IDs. 5249da20b8aSRobert MustacchiThere are three different families of routines for managing identifiers 5259da20b8aSRobert Mustacchipresented here, but we recommend the use of the 5269da20b8aSRobert Mustacchi.Xr id_space_create 9F 5279da20b8aSRobert Mustacchiand 5289da20b8aSRobert Mustacchi.Xr id_alloc 9F 5299da20b8aSRobert Mustacchifamily for new use cases. 5309da20b8aSRobert MustacchiThe ID space can cover all or a subset of the 32-bit integer space and 5319da20b8aSRobert Mustacchiprovides different allocation strategies for this. 5329da20b8aSRobert Mustacchi.Pp 5339da20b8aSRobert MustacchiDue to the current implementation, callers should generally prefer the 5349da20b8aSRobert Mustacchinon-sleeping variants because the sleeping ones are not cancellable 5359da20b8aSRobert Mustacchi.Po 5369da20b8aSRobert Mustacchicurrently this is backed by vmem, but this should not be assumed and may 5379da20b8aSRobert Mustacchichange in the future 5389da20b8aSRobert Mustacchi.Pc . 5399da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 5409da20b8aSRobert Mustacchi.It Xr id_alloc_nosleep 9F Ta Xr id_alloc_specific_nosleep 9F 5419da20b8aSRobert Mustacchi.It Xr id_alloc 9F Ta Xr id_allocff_nosleep 9F 5429da20b8aSRobert Mustacchi.It Xr id_allocff 9F Ta Xr id_free 9F 5439da20b8aSRobert Mustacchi.It Xr id_space_create 9F Ta Xr id_space_destroy 9F 5449da20b8aSRobert Mustacchi.It Xr id_space_extend 9F Ta Xr id_space 9F 5459da20b8aSRobert Mustacchi.It Xr id32_alloc 9F Ta Xr id32_free 9F 5469da20b8aSRobert Mustacchi.It Xr id32_lookup 9F Ta Xr rmalloc_wait 9F 5479da20b8aSRobert Mustacchi.It Xr rmalloc 9F Ta Xr rmallocmap_wait 9F 5489da20b8aSRobert Mustacchi.It Xr rmallocmap 9F Ta Xr rmfree 9F 5499da20b8aSRobert Mustacchi.It Xr rmfreemap 9F Ta 5509da20b8aSRobert Mustacchi.El 5519da20b8aSRobert Mustacchi.Ss Bit Manipulation Routines 5529da20b8aSRobert MustacchiMany device drivers that are working with registers often need to get a 5539da20b8aSRobert Mustacchispecific range of bits out of an integer. 5549da20b8aSRobert MustacchiThese functions provide safe ways to set 5559da20b8aSRobert Mustacchi.Pq bitset 5569da20b8aSRobert Mustacchiand extract 5579da20b8aSRobert Mustacchi.Pq bitx 5589da20b8aSRobert Mustacchibit ranges, as well 5599da20b8aSRobert Mustacchias modify an integer to remove a set of bits entirely 5609da20b8aSRobert Mustacchi.Pq bitdel . 5619da20b8aSRobert MustacchiUsing these functions is preferred to constructing manual masks and 5629da20b8aSRobert Mustacchishifts particularly when a programming manual for a device is specified 5639da20b8aSRobert Mustacchiin ranges of bits. 5649da20b8aSRobert MustacchiOn debug builds, these provide extra checking to try and catch 5659da20b8aSRobert Mustacchiprogrammer error. 5669da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 5679da20b8aSRobert Mustacchi.It Xr bitdel64 9F Ta Xr bitset8 9F 5689da20b8aSRobert Mustacchi.It Xr bitset16 9F Ta Xr bitset32 9F 5699da20b8aSRobert Mustacchi.It Xr bitset64 9F Ta Xr bitx8 9F 5709da20b8aSRobert Mustacchi.It Xr bitx16 9F Ta Xr bitx32 9F 5719da20b8aSRobert Mustacchi.It Xr bitx64 9F Ta 5729da20b8aSRobert Mustacchi.El 5739da20b8aSRobert Mustacchi.Ss Synchronization Primitives 5749da20b8aSRobert MustacchiThe kernel provides a set of basic synchronization primitives that can 5759da20b8aSRobert Mustacchibe used by the system. 5769da20b8aSRobert MustacchiThese include mutexes, condition variables, reader/writer locks, and 5779da20b8aSRobert Mustacchisemaphores. 5789da20b8aSRobert MustacchiWhen creating mutexes and reader/writer locks, the kernel requires that 5799da20b8aSRobert Mustacchione pass in the interrupt priority of a mutex if it will be used in 5809da20b8aSRobert Mustacchiinterrupt context. 5819da20b8aSRobert MustacchiThis is required so the kernel can determine the correct underlying type 5829da20b8aSRobert Mustacchiof lock to use. 5839da20b8aSRobert MustacchiThis ensures that if for some reason a mutex needs to be used in 5849da20b8aSRobert Mustacchihigh-level interrupt context, the kernel will use a spin lock, but 5859da20b8aSRobert Mustacchiotherwise can use the standard adaptive mutex that might block. 5869da20b8aSRobert MustacchiFor developers familiar with other operating systems, this is somewhat 5879da20b8aSRobert Mustacchidifferent in that the consumer does not need to generally figure out 5889da20b8aSRobert Mustacchithis level of detail and this is why this is not present. 5899da20b8aSRobert Mustacchi.Pp 5909da20b8aSRobert MustacchiIn addition, condition variables provide means for waiting and detecting 5919da20b8aSRobert Mustacchithat a signal has been delivered. 5929da20b8aSRobert MustacchiThese variants are particularly useful when writing character device 5939da20b8aSRobert Mustacchioperations for device drivers as it allows users the chance to cancel an 5949da20b8aSRobert Mustacchioperation and not be blocked indefinitely on something that may not 5959da20b8aSRobert Mustacchioccur. 5969da20b8aSRobert MustacchiThese _sig variants should generally be preferred where applicable. 5979da20b8aSRobert Mustacchi.Pp 5989da20b8aSRobert MustacchiThe kernel also provides memory barrier primitives. 5999da20b8aSRobert MustacchiSee the 6009da20b8aSRobert Mustacchi.Sx Memory Barriers 6019da20b8aSRobert Mustacchisection for more information. 6029da20b8aSRobert MustacchiThere is no need to use manual memory barriers when using the 6039da20b8aSRobert Mustacchisynchronization primitives. 6049da20b8aSRobert MustacchiThe synchronization primitives contain that the appropriate barriers are 6059da20b8aSRobert Mustacchipresent to ensure coherency while the lock is held. 6069da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 6079da20b8aSRobert Mustacchi.It Xr cv_broadcast 9F Ta Xr cv_destroy 9F 6089da20b8aSRobert Mustacchi.It Xr cv_init 9F Ta Xr cv_reltimedwait_sig 9F 6099da20b8aSRobert Mustacchi.It Xr cv_reltimedwait 9F Ta Xr cv_signal 9F 6109da20b8aSRobert Mustacchi.It Xr cv_timedwait_sig 9F Ta Xr cv_timedwait 9F 6119da20b8aSRobert Mustacchi.It Xr cv_wait_sig 9F Ta Xr cv_wait 9F 6129da20b8aSRobert Mustacchi.It Xr ddi_enter_critical 9F Ta Xr ddi_exit_critical 9F 6139da20b8aSRobert Mustacchi.It Xr mutex_destroy 9F Ta Xr mutex_enter 9F 6149da20b8aSRobert Mustacchi.It Xr mutex_exit 9F Ta Xr mutex_init 9F 6159da20b8aSRobert Mustacchi.It Xr mutex_owned 9F Ta Xr mutex_tryenter 9F 6169da20b8aSRobert Mustacchi.It Xr rw_destroy 9F Ta Xr rw_downgrade 9F 6179da20b8aSRobert Mustacchi.It Xr rw_enter 9F Ta Xr rw_exit 9F 6189da20b8aSRobert Mustacchi.It Xr rw_init 9F Ta Xr rw_read_locked 9F 6199da20b8aSRobert Mustacchi.It Xr rw_tryenter 9F Ta Xr rw_tryupgrade 9F 6209da20b8aSRobert Mustacchi.It Xr sema_destroy 9F Ta Xr sema_init 9F 6219da20b8aSRobert Mustacchi.It Xr sema_p_sig 9F Ta Xr sema_p 9F 6229da20b8aSRobert Mustacchi.It Xr sema_tryp 9F Ta Xr sema_v 9F 6239da20b8aSRobert Mustacchi.It Xr semaphore 9F Ta 6249da20b8aSRobert Mustacchi.El 6259da20b8aSRobert Mustacchi.Ss Atomic Operations 6269da20b8aSRobert MustacchiThis group of functions provides a general way to perform atomic 6279da20b8aSRobert Mustacchioperations on integers of different sizes and explicit types. 6289da20b8aSRobert MustacchiThe 6299da20b8aSRobert Mustacchi.Xr atomic_ops 9F 6309da20b8aSRobert Mustacchimanual page describes the different classes of functions in more detail, 6319da20b8aSRobert Mustacchibut there are functions that take care of using the CPU's instructions 6329da20b8aSRobert Mustacchifor addition, compare and swap, and more. 6339da20b8aSRobert MustacchiIf data is being protected and only accessed under a synchronization 6349da20b8aSRobert Mustacchiprimitive such as a mutex or reader-writer lock, then there isn't a 6359da20b8aSRobert Mustacchireason to use an atomic operation for that data, generally speaking. 6369da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 6379da20b8aSRobert Mustacchi.It Xr atomic_add_8_nv 9F Ta Xr atomic_add_8 9F 6389da20b8aSRobert Mustacchi.It Xr atomic_add_16_nv 9F Ta Xr atomic_add_16 9F 6399da20b8aSRobert Mustacchi.It Xr atomic_add_32_nv 9F Ta Xr atomic_add_32 9F 6409da20b8aSRobert Mustacchi.It Xr atomic_add_64_nv 9F Ta Xr atomic_add_64 9F 6419da20b8aSRobert Mustacchi.It Xr atomic_add_char_nv 9F Ta Xr atomic_add_char 9F 6429da20b8aSRobert Mustacchi.It Xr atomic_add_int_nv 9F Ta Xr atomic_add_int 9F 6439da20b8aSRobert Mustacchi.It Xr atomic_add_long_nv 9F Ta Xr atomic_add_long 9F 6449da20b8aSRobert Mustacchi.It Xr atomic_add_ptr_nv 9F Ta Xr atomic_add_ptr 9F 6459da20b8aSRobert Mustacchi.It Xr atomic_add_short_nv 9F Ta Xr atomic_add_short 9F 6469da20b8aSRobert Mustacchi.It Xr atomic_and_8_nv 9F Ta Xr atomic_and_8 9F 6479da20b8aSRobert Mustacchi.It Xr atomic_and_16_nv 9F Ta Xr atomic_and_16 9F 6489da20b8aSRobert Mustacchi.It Xr atomic_and_32_nv 9F Ta Xr atomic_and_32 9F 6499da20b8aSRobert Mustacchi.It Xr atomic_and_64_nv 9F Ta Xr atomic_and_64 9F 6509da20b8aSRobert Mustacchi.It Xr atomic_and_uchar_nv 9F Ta Xr atomic_and_uchar 9F 6519da20b8aSRobert Mustacchi.It Xr atomic_and_uint_nv 9F Ta Xr atomic_and_uint 9F 6529da20b8aSRobert Mustacchi.It Xr atomic_and_ulong_nv 9F Ta Xr atomic_and_ulong 9F 6539da20b8aSRobert Mustacchi.It Xr atomic_and_ushort_nv 9F Ta Xr atomic_and_ushort 9F 6549da20b8aSRobert Mustacchi.It Xr atomic_cas_16 9F Ta Xr atomic_cas_32 9F 6559da20b8aSRobert Mustacchi.It Xr atomic_cas_64 9F Ta Xr atomic_cas_8 9F 6569da20b8aSRobert Mustacchi.It Xr atomic_cas_ptr 9F Ta Xr atomic_cas_uchar 9F 6579da20b8aSRobert Mustacchi.It Xr atomic_cas_uint 9F Ta Xr atomic_cas_ulong 9F 6589da20b8aSRobert Mustacchi.It Xr atomic_cas_ushort 9F Ta Xr atomic_clear_long_excl 9F 6599da20b8aSRobert Mustacchi.It Xr atomic_dec_8_nv 9F Ta Xr atomic_dec_8 9F 6609da20b8aSRobert Mustacchi.It Xr atomic_dec_16_nv 9F Ta Xr atomic_dec_16 9F 6619da20b8aSRobert Mustacchi.It Xr atomic_dec_32_nv 9F Ta Xr atomic_dec_32 9F 6629da20b8aSRobert Mustacchi.It Xr atomic_dec_64_nv 9F Ta Xr atomic_dec_64 9F 6639da20b8aSRobert Mustacchi.It Xr atomic_dec_ptr_nv 9F Ta Xr atomic_dec_ptr 9F 6649da20b8aSRobert Mustacchi.It Xr atomic_dec_uchar_nv 9F Ta Xr atomic_dec_uchar 9F 6659da20b8aSRobert Mustacchi.It Xr atomic_dec_uint_nv 9F Ta Xr atomic_dec_uint 9F 6669da20b8aSRobert Mustacchi.It Xr atomic_dec_ulong_nv 9F Ta Xr atomic_dec_ulong 9F 6679da20b8aSRobert Mustacchi.It Xr atomic_dec_ushort_nv 9F Ta Xr atomic_dec_ushort 9F 6689da20b8aSRobert Mustacchi.It Xr atomic_inc_8_nv 9F Ta Xr atomic_inc_8 9F 6699da20b8aSRobert Mustacchi.It Xr atomic_inc_16_nv 9F Ta Xr atomic_inc_16 9F 6709da20b8aSRobert Mustacchi.It Xr atomic_inc_32_nv 9F Ta Xr atomic_inc_32 9F 6719da20b8aSRobert Mustacchi.It Xr atomic_inc_64_nv 9F Ta Xr atomic_inc_64 9F 6729da20b8aSRobert Mustacchi.It Xr atomic_inc_ptr_nv 9F Ta Xr atomic_inc_ptr 9F 6739da20b8aSRobert Mustacchi.It Xr atomic_inc_uchar_nv 9F Ta Xr atomic_inc_uchar 9F 6749da20b8aSRobert Mustacchi.It Xr atomic_inc_uint_nv 9F Ta Xr atomic_inc_uint 9F 6759da20b8aSRobert Mustacchi.It Xr atomic_inc_ulong_nv 9F Ta Xr atomic_inc_ulong 9F 6769da20b8aSRobert Mustacchi.It Xr atomic_inc_ushort_nv 9F Ta Xr atomic_inc_ushort 9F 6779da20b8aSRobert Mustacchi.It Xr atomic_or_8_nv 9F Ta Xr atomic_or_8 9F 6789da20b8aSRobert Mustacchi.It Xr atomic_or_16_nv 9F Ta Xr atomic_or_16 9F 6799da20b8aSRobert Mustacchi.It Xr atomic_or_32_nv 9F Ta Xr atomic_or_32 9F 6809da20b8aSRobert Mustacchi.It Xr atomic_or_64_nv 9F Ta Xr atomic_or_64 9F 6819da20b8aSRobert Mustacchi.It Xr atomic_or_uchar_nv 9F Ta Xr atomic_or_uchar 9F 6829da20b8aSRobert Mustacchi.It Xr atomic_or_uint_nv 9F Ta Xr atomic_or_uint 9F 6839da20b8aSRobert Mustacchi.It Xr atomic_or_ulong_nv 9F Ta Xr atomic_or_ulong 9F 6849da20b8aSRobert Mustacchi.It Xr atomic_or_ushort_nv 9F Ta Xr atomic_or_ushort 9F 6859da20b8aSRobert Mustacchi.It Xr atomic_set_long_excl 9F Ta Xr atomic_swap_8 9F 6869da20b8aSRobert Mustacchi.It Xr atomic_swap_16 9F Ta Xr atomic_swap_32 9F 6879da20b8aSRobert Mustacchi.It Xr atomic_swap_64 9F Ta Xr atomic_swap_ptr 9F 6889da20b8aSRobert Mustacchi.It Xr atomic_swap_uchar 9F Ta Xr atomic_swap_uint 9F 6899da20b8aSRobert Mustacchi.It Xr atomic_swap_ulong 9F Ta Xr atomic_swap_ushort 9F 6909da20b8aSRobert Mustacchi.El 6919da20b8aSRobert Mustacchi.Ss Memory Barriers 6929da20b8aSRobert MustacchiThe kernel provides general purpose memory barriers that can be used 6939da20b8aSRobert Mustacchiwhen required. 6949da20b8aSRobert MustacchiIn general, when using items described in the 6959da20b8aSRobert Mustacchi.Sx Synchronization Primitives 6969da20b8aSRobert Mustacchisection, these are not required. 6979da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 6989da20b8aSRobert Mustacchi.It Xr membar_consumer 9F Ta Xr membar_enter 9F 6999da20b8aSRobert Mustacchi.It Xr membar_exit 9F Ta Xr membar_producer 9F 7009da20b8aSRobert Mustacchi.El 7019da20b8aSRobert Mustacchi.Ss Virtual Memory and Pages 7029da20b8aSRobert MustacchiAll platforms that the operating system supports have some form of 7039da20b8aSRobert Mustacchivirtual memory which is managed in units of pages. 7049da20b8aSRobert MustacchiThe page size varies between architectures and platforms. 7059da20b8aSRobert MustacchiFor example, the smallest x86 page size is 4 KiB while SPARC 7069da20b8aSRobert Mustacchitraditionally used 8 KiB pages. 7079da20b8aSRobert MustacchiThese functions can be used to convert between pages and bytes. 7089da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 7099da20b8aSRobert Mustacchi.It Xr btop 9F Ta Xr btopr 9F 7109da20b8aSRobert Mustacchi.It Xr ddi_btop 9F Ta Xr ddi_btopr 9F 7119da20b8aSRobert Mustacchi.It Xr ddi_ptob 9F Ta Xr ptob 9F 7129da20b8aSRobert Mustacchi.El 7139da20b8aSRobert Mustacchi.Ss Module and Device Framework 7149da20b8aSRobert MustacchiThese functions are used as part of implementing kernel modules and 7159da20b8aSRobert Mustacchiregister device drivers with the various kernel frameworks. 716*496cffd8SPeter TribbleThere are also functions here that are suitable for use in the 717*496cffd8SPeter Tribble.Xr dev_ops 9S , 718*496cffd8SPeter Tribble.Xr cb_ops 9S , 7199da20b8aSRobert Mustacchietc. 7209da20b8aSRobert Mustacchistructures and for interrogating module information. 7219da20b8aSRobert Mustacchi.Pp 7229da20b8aSRobert MustacchiThe 7239da20b8aSRobert Mustacchi.Xr mod_install 9F 7249da20b8aSRobert Mustacchiand 7259da20b8aSRobert Mustacchi.Xr mod_remove 9F 7269da20b8aSRobert Mustacchifunctions are used during a driver's 7279da20b8aSRobert Mustacchi.Xr _init 9E 7289da20b8aSRobert Mustacchiand 7299da20b8aSRobert Mustacchi.Xr _fini 9E 7309da20b8aSRobert Mustacchifunctions. 7319da20b8aSRobert Mustacchi.Pp 7329da20b8aSRobert MustacchiThere are two different ways that drivers often manage their instance 7339da20b8aSRobert Mustacchistate which is created during 7349da20b8aSRobert Mustacchi.Xr attach 9E . 7359da20b8aSRobert MustacchiThe first is the use of 7369da20b8aSRobert Mustacchi.Xr ddi_set_driver_private 9F 7379da20b8aSRobert Mustacchiand 7389da20b8aSRobert Mustacchi.Xr ddi_get_driver_private 9F . 7399da20b8aSRobert MustacchiThis stores a driver-specific value on the 7409da20b8aSRobert Mustacchi.Vt dev_info_t 7419da20b8aSRobert Mustacchistructure which allows it to be used during other operations. 7429da20b8aSRobert MustacchiSome device driver frameworks may use this themselves, making this 7439da20b8aSRobert Mustacchiunavailable to the driver. 7449da20b8aSRobert Mustacchi.Pp 7459da20b8aSRobert MustacchiThe other path is to use the soft state suite of functions which 7469da20b8aSRobert Mustacchidynamically grows to cover the number of instances of a device that 7479da20b8aSRobert Mustacchiexist. 7489da20b8aSRobert MustacchiThe soft state is generally initialized in the 7499da20b8aSRobert Mustacchi.Xr _init 9E 7509da20b8aSRobert Mustacchientry point with 7519da20b8aSRobert Mustacchi.Xr ddi_soft_state_init 9F 7529da20b8aSRobert Mustacchiand then instances are allocated and freed during 7539da20b8aSRobert Mustacchi.Xr attach 9E 7549da20b8aSRobert Mustacchiand 7559da20b8aSRobert Mustacchi.Xr detach 9E 7569da20b8aSRobert Mustacchiwith 7579da20b8aSRobert Mustacchi.Xr ddi_soft_state_zalloc 9F 7589da20b8aSRobert Mustacchiand 7599da20b8aSRobert Mustacchi.Xr ddi_soft_state_free 9F , 7609da20b8aSRobert Mustacchiand then retrieved with 7619da20b8aSRobert Mustacchi.Xr ddi_get_soft_state 9F . 7629da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 7639da20b8aSRobert Mustacchi.It Xr ddi_get_driver_private 9F Ta Xr ddi_get_soft_state 9F 7649da20b8aSRobert Mustacchi.It Xr ddi_modclose 9F Ta Xr ddi_modopen 9F 7659da20b8aSRobert Mustacchi.It Xr ddi_modsym 9F Ta Xr ddi_no_info 9F 7669da20b8aSRobert Mustacchi.It Xr ddi_report_dev 9F Ta Xr ddi_set_driver_private 9F 7679da20b8aSRobert Mustacchi.It Xr ddi_soft_state_fini 9F Ta Xr ddi_soft_state_free 9F 7689da20b8aSRobert Mustacchi.It Xr ddi_soft_state_init 9F Ta Xr ddi_soft_state_zalloc 9F 7699da20b8aSRobert Mustacchi.It Xr mod_info 9F Ta Xr mod_install 9F 7709da20b8aSRobert Mustacchi.It Xr mod_modname 9F Ta Xr mod_remove 9F 7719da20b8aSRobert Mustacchi.It Xr nochpoll 9F Ta Xr nodev 9F 7729da20b8aSRobert Mustacchi.It Xr nulldev 9F Ta 7739da20b8aSRobert Mustacchi.El 7749da20b8aSRobert Mustacchi.Ss Device Tree Information 7759da20b8aSRobert MustacchiDevices are organized into a tree that is partially seeded by the 7769da20b8aSRobert Mustacchiplatform based on information discovered at boot and augmented with 7779da20b8aSRobert Mustacchiadditional information at runtime. 7789da20b8aSRobert MustacchiEvery instance of a device driver is given a 7799da20b8aSRobert Mustacchi.Vt "dev_info_t *" 7809da20b8aSRobert Mustacchi.Pq device information 7819da20b8aSRobert Mustacchidata structure which corresponds to information about an instance and 7829da20b8aSRobert Mustacchihas a place in the tree. 7839da20b8aSRobert MustacchiWhen a driver requests operations like to allocate memory for DMA, that 7849da20b8aSRobert Mustacchirequest is passed up the tree and modified. 7859da20b8aSRobert MustacchiThe same is true for other things like interrupts, event notifications, 7869da20b8aSRobert Mustacchior properties. 7879da20b8aSRobert Mustacchi.Pp 7889da20b8aSRobert MustacchiThere are many different informational properties about a device driver. 7899da20b8aSRobert MustacchiFor example, 7909da20b8aSRobert Mustacchi.Xr ddi_driver_name 9F 7919da20b8aSRobert Mustacchireturns the name of the device driver, 7929da20b8aSRobert Mustacchi.Xr ddi_get_name 9F 7939da20b8aSRobert Mustacchireturns the name of the node in the tree, 7949da20b8aSRobert Mustacchi.Xr ddi_get_parent 9F 7959da20b8aSRobert Mustacchireturns a node's parent, and 7969da20b8aSRobert Mustacchi.Xr ddi_get_instance 9F 7979da20b8aSRobert Mustacchireturns the instance number of a specific driver. 7989da20b8aSRobert Mustacchi.Pp 7999da20b8aSRobert MustacchiThere are a series of properties that exist on the tree, the exact set 8009da20b8aSRobert Mustacchiof which depend on the class of the device and are often documented in a 8019da20b8aSRobert Mustacchispecific device class's manual. 8029da20b8aSRobert MustacchiFor example, the 8039da20b8aSRobert Mustacchi.Dq reg 8049da20b8aSRobert Mustacchiproperty is used for PCI and PCIe devices to describe the various base 8059da20b8aSRobert Mustacchiaddress registers, their types, and related, which are documented in 8069da20b8aSRobert Mustacchi.Xr pci 5 . 8079da20b8aSRobert Mustacchi.Pp 8089da20b8aSRobert MustacchiWhen getting a property one can constrain it to the current instance or 8099da20b8aSRobert Mustacchiyou can ask for a parent to try to look up the property. 8109da20b8aSRobert MustacchiWhich mode is appropriate depends on the specific class of driver, its 8119da20b8aSRobert Mustacchiparent, and the property. 8129da20b8aSRobert Mustacchi.Pp 8139da20b8aSRobert MustacchiUsing a 8149da20b8aSRobert Mustacchi.Vt "dev_info_t *" 8159da20b8aSRobert Mustacchipointer has to be done carefully. 8169da20b8aSRobert MustacchiWhen a device driver is in any of its 8179da20b8aSRobert Mustacchi.Xr dev_ops 9S , 8189da20b8aSRobert Mustacchi.Xr cb_ops 9S , 8199da20b8aSRobert Mustacchior similar callback functions that it has registered with the kernel, 8209da20b8aSRobert Mustacchithen it can always safely use its own 8219da20b8aSRobert Mustacchi.Vt "dev_info_t" 8229da20b8aSRobert Mustacchiand those of any parents it discovers through 8239da20b8aSRobert Mustacchi.Xr ddi_get_parent 9F . 8249da20b8aSRobert MustacchiHowever, it cannot assume the validity of any siblings or children 8259da20b8aSRobert Mustacchiunless there are other circumstances that guarantee that they will not 8269da20b8aSRobert Mustacchidisappear. 8279da20b8aSRobert MustacchiIn the broader kernel, one should not assume that it is safe to use a 8289da20b8aSRobert Mustacchigiven 8299da20b8aSRobert Mustacchi.Vt "dev_info_t *" 8309da20b8aSRobert Mustacchistructure without the appropriate NDI 8319da20b8aSRobert Mustacchi.Pq nexus driver interface 8329da20b8aSRobert Mustacchihold having been applied. 8339da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 8349da20b8aSRobert Mustacchi.It Xr ddi_binding_name 9F Ta Xr ddi_dev_is_sid 9F 8359da20b8aSRobert Mustacchi.It Xr ddi_driver_major 9F Ta Xr ddi_driver_name 9F 8369da20b8aSRobert Mustacchi.It Xr ddi_get_devstate 9F Ta Xr ddi_get_instance 9F 8379da20b8aSRobert Mustacchi.It Xr ddi_get_name 9F Ta Xr ddi_get_parent 9F 8389da20b8aSRobert Mustacchi.It Xr ddi_getlongprop_buf 9F Ta Xr ddi_getlongprop 9F 8399da20b8aSRobert Mustacchi.It Xr ddi_getprop 9F Ta Xr ddi_getproplen 9F 8409da20b8aSRobert Mustacchi.It Xr ddi_node_name 9F Ta Xr ddi_prop_create 9F 8419da20b8aSRobert Mustacchi.It Xr ddi_prop_exists 9F Ta Xr ddi_prop_free 9F 8429da20b8aSRobert Mustacchi.It Xr ddi_prop_get_int 9F Ta Xr ddi_prop_get_int64 9F 8439da20b8aSRobert Mustacchi.It Xr ddi_prop_lookup_byte_array 9F Ta Xr ddi_prop_lookup_int_array 9F 8449da20b8aSRobert Mustacchi.It Xr ddi_prop_lookup_int64_array 9F Ta Xr ddi_prop_lookup_string_array 9F 8459da20b8aSRobert Mustacchi.It Xr ddi_prop_lookup_string 9F Ta Xr ddi_prop_lookup 9F 8469da20b8aSRobert Mustacchi.It Xr ddi_prop_modify 9F Ta Xr ddi_prop_op 9F 8479da20b8aSRobert Mustacchi.It Xr ddi_prop_remove_all 9F Ta Xr ddi_prop_remove 9F 8489da20b8aSRobert Mustacchi.It Xr ddi_prop_undefine 9F Ta Xr ddi_prop_update_byte_array 9F 8499da20b8aSRobert Mustacchi.It Xr ddi_prop_update_int_array 9F Ta Xr ddi_prop_update_int 9F 8509da20b8aSRobert Mustacchi.It Xr ddi_prop_update_int64_array 9F Ta Xr ddi_prop_update_int64 9F 8519da20b8aSRobert Mustacchi.It Xr ddi_prop_update_string_array 9F Ta Xr ddi_prop_update_string 9F 8529da20b8aSRobert Mustacchi.It Xr ddi_prop_update 9F Ta Xr ddi_root_node 9F 8539da20b8aSRobert Mustacchi.It Xr ddi_slaveonly 9F Ta 8549da20b8aSRobert Mustacchi.El 8559da20b8aSRobert Mustacchi.Ss Copying Data to and from Userland 8569da20b8aSRobert MustacchiThe kernel operates in a different context from userland. 8579da20b8aSRobert MustacchiOne does not simply access user memory. 8589da20b8aSRobert MustacchiThis is enforced either by the architecture's memory model, where user 8599da20b8aSRobert Mustacchiaddress space isn't even present in the kernel's virtual address space 8609da20b8aSRobert Mustacchior by architectural mechanisms such as Supervisor Mode Access Protect 8619da20b8aSRobert Mustacchi.Pq SMAP 8629da20b8aSRobert Mustacchion x86. 8639da20b8aSRobert Mustacchi.Pp 8649da20b8aSRobert MustacchiTo facilitate accessing memory, the kernel provides a few routines that 8659da20b8aSRobert Mustacchican be used. 8669da20b8aSRobert MustacchiIn most contexts the main thing to use is 8679da20b8aSRobert Mustacchi.Xr ddi_copyin 9F 8689da20b8aSRobert Mustacchiand 8699da20b8aSRobert Mustacchi.Xr ddi_copyout 9F . 8709da20b8aSRobert MustacchiThese will safely dereference addresses and ensure that the address is 8719da20b8aSRobert Mustacchiappropriate depending on whether this is coming from the user or kernel. 8729da20b8aSRobert MustacchiWhen operating with the kernel's 8739da20b8aSRobert Mustacchi.Vt uio_t 8749da20b8aSRobert Mustacchistructure which is for mostly used when processing read and write 8759da20b8aSRobert Mustacchirequests, instead 8769da20b8aSRobert Mustacchi.Xr uiomove 9F 8779da20b8aSRobert Mustacchiis the goto function. 8789da20b8aSRobert Mustacchi.Pp 8799da20b8aSRobert MustacchiWhen reading data from userland into the kernel, there is another 8809da20b8aSRobert Mustacchiconcern: the data model. 8819da20b8aSRobert MustacchiThe most common place this comes up is in an 8829da20b8aSRobert Mustacchi.Xr ioctl 9E 8839da20b8aSRobert Mustacchihandler or other places where the kernel is operating on data that isn't 8849da20b8aSRobert Mustacchifixed size. 8859da20b8aSRobert MustacchiParticularly in C, though this applies to other languages, structures 8869da20b8aSRobert Mustacchiand unions vary in the size and alignment requirements between 32-bit 8879da20b8aSRobert Mustacchiand 64-bit processes. 8889da20b8aSRobert MustacchiThe same even applies if one uses pointers or the 8899da20b8aSRobert Mustacchi.Vt long , 8909da20b8aSRobert Mustacchi.Vt size_t , 8919da20b8aSRobert Mustacchior similar types in C. 8929da20b8aSRobert MustacchiIn supported 32-bit and 64-bit environments these types are 4 and 8 8939da20b8aSRobert Mustacchibytes respectively. 8949da20b8aSRobert MustacchiTo account for this, when data is not fixed size between all data 8959da20b8aSRobert Mustacchimodels, the driver must look at the data model of the process it is 8969da20b8aSRobert Mustacchicopying data from. 8979da20b8aSRobert Mustacchi.Pp 8989da20b8aSRobert MustacchiThe simplest way to solve this problem is to try to make the data 8999da20b8aSRobert Mustacchistructure the same across the different models. 9009da20b8aSRobert MustacchiIt's not sufficient to just use the same structure definition and fixed 9019da20b8aSRobert Mustacchisize types as the alignment and padding between the two can vary. 9029da20b8aSRobert MustacchiFor example, the alignment of a 64-bit integer like a 9039da20b8aSRobert Mustacchi.Vt uint64_t 9049da20b8aSRobert Mustacchican change between a 32-bit and 64-bit data model. 9059da20b8aSRobert MustacchiOne way to check for the data structures being identical is to leverage 9069da20b8aSRobert Mustacchithe 9079da20b8aSRobert Mustacchi.Xr ctfdiff 1 9089da20b8aSRobert Mustacchiprogram, generally with the 9099da20b8aSRobert Mustacchi.Fl I 9109da20b8aSRobert Mustacchioption. 9119da20b8aSRobert Mustacchi.Pp 9129da20b8aSRobert MustacchiHowever, there are times when a structure simply can't be the same, such 9139da20b8aSRobert Mustacchias when we're encoding a pointer into the structure or a type like the 9149da20b8aSRobert Mustacchi.Vt size_t . 9159da20b8aSRobert MustacchiWhen this happens, the most natural way to accomplish this is to use the 9169da20b8aSRobert Mustacchi.Xr ddi_model_convert_from 9F 9179da20b8aSRobert Mustacchifunction which can determine the appropriate model from the ioctl's 9189da20b8aSRobert Mustacchiarguments. 9199da20b8aSRobert MustacchiThis provides a natural way to copy a structure in and out in the 9209da20b8aSRobert Mustacchiappropriate data model and convert it at those points to the kernel's 9219da20b8aSRobert Mustacchinative form. 9229da20b8aSRobert Mustacchi.Pp 9239da20b8aSRobert MustacchiAn alternate way to approach the data model is to use the 9249da20b8aSRobert Mustacchi.Xr STRUCT_DECL 9F 9259da20b8aSRobert Mustacchifunctions, but as this requires wrapping every access to every member, 9269da20b8aSRobert Mustacchioften times the 9279da20b8aSRobert Mustacchi.Xr ddi_model_convert_from 9F 9289da20b8aSRobert Mustacchiapproach and taking care of converting values and ensuring that limits 9299da20b8aSRobert Mustacchiaren't exceeded at the end is preferred. 9309da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 9319da20b8aSRobert Mustacchi.It Xr bp_copyin 9F Ta Xr bp_copyout 9F 9329da20b8aSRobert Mustacchi.It Xr copyin 9F Ta Xr copyout 9F 9339da20b8aSRobert Mustacchi.It Xr ddi_copyin 9F Ta Xr ddi_copyout 9F 9349da20b8aSRobert Mustacchi.It Xr ddi_model_convert_from 9F Ta Xr SIZEOF_PTR 9F 9359da20b8aSRobert Mustacchi.It Xr SIZEOF_STRUCT 9F Ta Xr STRUCT_BUF 9F 9369da20b8aSRobert Mustacchi.It Xr STRUCT_DECL 9F Ta Xr STRUCT_FADDR 9F 9379da20b8aSRobert Mustacchi.It Xr STRUCT_FGET 9F Ta Xr STRUCT_FGETP 9F 9389da20b8aSRobert Mustacchi.It Xr STRUCT_FSET 9F Ta Xr STRUCT_FSETP 9F 9399da20b8aSRobert Mustacchi.It Xr STRUCT_HANDLE 9F Ta Xr STRUCT_INIT 9F 9409da20b8aSRobert Mustacchi.It Xr STRUCT_SET_HANDLE 9F Ta Xr STRUCT_SIZE 9F 9419da20b8aSRobert Mustacchi.It Xr uiomove 9F Ta Xr ureadc 9F 9429da20b8aSRobert Mustacchi.It Xr uwritec 9F Ta 9439da20b8aSRobert Mustacchi.El 9449da20b8aSRobert Mustacchi.Ss Device Register Setup and Access 9459da20b8aSRobert MustacchiThe kernel abstracts out accessing registers on a device on behalf of 9469da20b8aSRobert Mustacchidrivers. 9479da20b8aSRobert MustacchiThis allows a similar set of interfaces to be used whether the registers 9489da20b8aSRobert Mustacchiare found within a PCI BAR, utilizing I/O ports, memory mapped 9499da20b8aSRobert Mustacchiregisters, or some other scheme. 9509da20b8aSRobert MustacchiDevices with registers all have a 9519da20b8aSRobert Mustacchi.Dq regs 9529da20b8aSRobert Mustacchiproperty that is set up by their parent device, generally a kernel 9539da20b8aSRobert Mustacchiframework as is the case for PCIe devices, and the meaning is a contract 9549da20b8aSRobert Mustacchibetween the two. 9559da20b8aSRobert MustacchiRegister sets are identified by a numeric ID, which varies on the device 9569da20b8aSRobert Mustacchitype. 9579da20b8aSRobert MustacchiFor example, the first BAR of a PCI device is defined as register set 1. 9589da20b8aSRobert MustacchiOn the other hand, the AMD GPIO controller might have three register sets 9599da20b8aSRobert Mustacchibecause of how the hardware design splits them up. 9609da20b8aSRobert MustacchiThe meaning of the registers and their semantics is still 9619da20b8aSRobert Mustacchidevice-specific. 9629da20b8aSRobert MustacchiThe kernel doesn't know how to interpret the actual registers of a PCIe 9639da20b8aSRobert Mustacchidevice say, just that they exist. 9649da20b8aSRobert Mustacchi.Pp 9659da20b8aSRobert MustacchiTo begin with register setup, one often first looks at the number of 9669da20b8aSRobert Mustacchiregister sets that exist and their size. 9679da20b8aSRobert MustacchiMost PCI-based device drivers will skip calling 9689da20b8aSRobert Mustacchi.Xr ddi_dev_nregs 9F 9699da20b8aSRobert Mustacchiand will just move straight to calling 9709da20b8aSRobert Mustacchi.Xr ddi_dev_regsize 9F 9719da20b8aSRobert Mustacchito determine the size of a register set that they are interested in. 9729da20b8aSRobert MustacchiTo actually map the registers, a device driver will call 9739da20b8aSRobert Mustacchi.Xr ddi_regs_map_setup 9F 9749da20b8aSRobert Mustacchiwhich requires both a register set and a series of attributes and 9759da20b8aSRobert Mustacchireturns an access handle that is used to actually read and write the 9769da20b8aSRobert Mustacchiregisters. 9779da20b8aSRobert MustacchiWhen setting up registers, one must have a corresponding 9789da20b8aSRobert Mustacchi.Vt ddi_device_acc_attr_t 9799da20b8aSRobert Mustacchistructure which is used to define what endianness the register set is 9809da20b8aSRobert Mustacchiin, whether any kind of reordering is allowed 9819da20b8aSRobert Mustacchi.Po 9829da20b8aSRobert Mustacchiif in doubt specify 9839da20b8aSRobert Mustacchi.Dv DDI_STRICTORDER_ACC 9849da20b8aSRobert Mustacchi.Pc , 9859da20b8aSRobert Mustacchiand whether any particular error handling is being used. 9869da20b8aSRobert MustacchiThe structure and all of its different options are described in 9879da20b8aSRobert Mustacchi.Xr ddi_device_acc_attr 9S . 9889da20b8aSRobert Mustacchi.Pp 9899da20b8aSRobert MustacchiOnce a register handle is obtained, then it's easy to read and write the 9909da20b8aSRobert Mustacchiregister space. 9919da20b8aSRobert MustacchiFunctions are organized based on the size of the access. 9929da20b8aSRobert MustacchiFor the most part, most situations call for the use of the 9939da20b8aSRobert Mustacchi.Xr ddi_get8 9F , 9949da20b8aSRobert Mustacchi.Xr ddi_get16 9F , 9959da20b8aSRobert Mustacchi.Xr ddi_get32 9F , 9969da20b8aSRobert Mustacchiand 9979da20b8aSRobert Mustacchi.Xr ddi_get64 9F 9989da20b8aSRobert Mustacchifunctions to read a register and the 9999da20b8aSRobert Mustacchi.Xr ddi_put8 9F , 10009da20b8aSRobert Mustacchi.Xr ddi_put16 9F , 10019da20b8aSRobert Mustacchi.Xr ddi_put32 9F , 10029da20b8aSRobert Mustacchiand 10039da20b8aSRobert Mustacchi.Xr ddi_put64 9F 10049da20b8aSRobert Mustacchifunctions to set a register value. 10059da20b8aSRobert MustacchiWhile there are the ddi_io_ and ddi_mem_ families of functions below, 10069da20b8aSRobert Mustacchithese are not generally needed and are generally present for 10079da20b8aSRobert Mustacchicompatibility. 10089da20b8aSRobert MustacchiThe kernel will automatically perform the appropriate type of register 10099da20b8aSRobert Mustacchiread for the device type in question. 10109da20b8aSRobert Mustacchi.Pp 10119da20b8aSRobert MustacchiOnce a register set is no longer being used, the 10129da20b8aSRobert Mustacchi.Xr ddi_regs_map_free 9F 10139da20b8aSRobert Mustacchifunction should be used to release resources. 10149da20b8aSRobert MustacchiIn most cases, this happens while executing the 10159da20b8aSRobert Mustacchi.Xr detach 9E 10169da20b8aSRobert Mustacchientry point. 10179da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 10189da20b8aSRobert Mustacchi.It Xr ddi_dev_nregs 9F Ta Xr ddi_dev_regsize 9F 10199da20b8aSRobert Mustacchi.It Xr ddi_device_copy 9F Ta Xr ddi_device_zero 9F 10209da20b8aSRobert Mustacchi.It Xr ddi_regs_map_free 9F Ta Xr ddi_regs_map_setup 9F 10219da20b8aSRobert Mustacchi.It Xr ddi_get8 9F Ta Xr ddi_get16 9F 10229da20b8aSRobert Mustacchi.It Xr ddi_get32 9F Ta Xr ddi_get64 9F 10239da20b8aSRobert Mustacchi.It Xr ddi_io_get8 9F Ta Xr ddi_io_get16 9F 10249da20b8aSRobert Mustacchi.It Xr ddi_io_get32 9F Ta Xr ddi_io_put8 9F 10259da20b8aSRobert Mustacchi.It Xr ddi_io_put16 9F Ta Xr ddi_io_put32 9F 10269da20b8aSRobert Mustacchi.It Xr ddi_io_rep_get8 9F Ta Xr ddi_io_rep_get16 9F 10279da20b8aSRobert Mustacchi.It Xr ddi_io_rep_get32 9F Ta Xr ddi_io_rep_put8 9F 10289da20b8aSRobert Mustacchi.It Xr ddi_io_rep_put16 9F Ta Xr ddi_io_rep_put32 9F 10299da20b8aSRobert Mustacchi.It Xr ddi_map_regs 9F Ta Xr ddi_mem_get8 9F 10309da20b8aSRobert Mustacchi.It Xr ddi_mem_get16 9F Ta Xr ddi_mem_get32 9F 10319da20b8aSRobert Mustacchi.It Xr ddi_mem_get64 9F Ta Xr ddi_mem_put8 9F 10329da20b8aSRobert Mustacchi.It Xr ddi_mem_put16 9F Ta Xr ddi_mem_put32 9F 10339da20b8aSRobert Mustacchi.It Xr ddi_mem_put64 9F Ta Xr ddi_mem_rep_get8 9F 10349da20b8aSRobert Mustacchi.It Xr ddi_mem_rep_get16 9F Ta Xr ddi_mem_rep_get32 9F 10359da20b8aSRobert Mustacchi.It Xr ddi_mem_rep_get64 9F Ta Xr ddi_mem_rep_put8 9F 10369da20b8aSRobert Mustacchi.It Xr ddi_mem_rep_put16 9F Ta Xr ddi_mem_rep_put32 9F 10379da20b8aSRobert Mustacchi.It Xr ddi_mem_rep_put64 9F Ta Xr ddi_peek8 9F 10389da20b8aSRobert Mustacchi.It Xr ddi_peek16 9F Ta Xr ddi_peek32 9F 10399da20b8aSRobert Mustacchi.It Xr ddi_peek64 9F Ta Xr ddi_poke8 9F 10409da20b8aSRobert Mustacchi.It Xr ddi_poke16 9F Ta Xr ddi_poke32 9F 10419da20b8aSRobert Mustacchi.It Xr ddi_poke64 9F Ta Xr ddi_put8 9F 10429da20b8aSRobert Mustacchi.It Xr ddi_put16 9F Ta Xr ddi_put32 9F 10439da20b8aSRobert Mustacchi.It Xr ddi_put64 9F Ta Xr ddi_rep_get8 9F 10449da20b8aSRobert Mustacchi.It Xr ddi_rep_get16 9F Ta Xr ddi_rep_get32 9F 10459da20b8aSRobert Mustacchi.It Xr ddi_rep_get64 9F Ta Xr ddi_rep_put8 9F 10469da20b8aSRobert Mustacchi.It Xr ddi_rep_put16 9F Ta Xr ddi_rep_put32 9F 10479da20b8aSRobert Mustacchi.It Xr ddi_rep_put64 9F Ta 10489da20b8aSRobert Mustacchi.El 10499da20b8aSRobert Mustacchi.Ss DMA Related Functions 10509da20b8aSRobert MustacchiMost high-performance devices provide first-class support for DMA 10519da20b8aSRobert Mustacchi.Pq direct memory access . 10529da20b8aSRobert MustacchiDMA allows a transfer between a device and memory to occur 10539da20b8aSRobert Mustacchiasynchronously and generally without a thread's specific involvement. 10549da20b8aSRobert MustacchiToday, most DMA is provided directly by devices and the corresponding 10559da20b8aSRobert Mustacchidevice scheme. 10569da20b8aSRobert MustacchiTake PCI and PCI Express for example. 10579da20b8aSRobert MustacchiThe idea of DMA is built into the PCIe standard and therefore basic 10589da20b8aSRobert Mustacchisupport for it exists and therefore there isn't a lot of special 10599da20b8aSRobert Mustacchiprogramming required. 10609da20b8aSRobert MustacchiHowever, this hasn't always been true and still exists in some cases 10619da20b8aSRobert Mustacchiwhere there is a 3rd party DMA engine. 10629da20b8aSRobert MustacchiIf we consider the PCIe example, the PCIe device directly performs reads 10639da20b8aSRobert Mustacchiand writes to main memory on its own. 10649da20b8aSRobert MustacchiHowever, in the 3rd party case, there is a distinct controller that is 10659da20b8aSRobert Mustacchineither the device nor memory that facilitates this, which is called a 10669da20b8aSRobert MustacchiDMA engine. 10679da20b8aSRobert MustacchiFor most part, DMA engines are not something that needs to be thought 10689da20b8aSRobert Mustacchiabout for most platforms that illumos is present on; however, they still 10699da20b8aSRobert Mustacchiexist in some embedded and related contexts. 10709da20b8aSRobert Mustacchi.Pp 10719da20b8aSRobert MustacchiThe first thing that a driver needs to do to set up DMA is to understand 10729da20b8aSRobert Mustacchithe constraints of the device and bus. 10739da20b8aSRobert MustacchiThese constraints are described in a series of attributes in the 10749da20b8aSRobert Mustacchi.Vt ddi_dma_attr_t 10759da20b8aSRobert Mustacchistructure which is defined in 10769da20b8aSRobert Mustacchi.Xr ddi_dma_attr 9S . 10779da20b8aSRobert MustacchiThe reason that attributes exist is because different devices, and 10789da20b8aSRobert Mustacchisometimes different memory uses with a device, have different 10799da20b8aSRobert Mustacchirequirements for memory. 10809da20b8aSRobert MustacchiA simple example of this is that not all devices can accept memory 10819da20b8aSRobert Mustacchiaddresses that are 64-bits wide and may have to be constrained to the 10829da20b8aSRobert Mustacchilower 32-bits of memory. 10839da20b8aSRobert MustacchiAnother common constraint is how this memory is chunked up. 10849da20b8aSRobert MustacchiSome devices may require that all of the DMA memory be contiguous, while 10859da20b8aSRobert Mustacchiothers can allow that to be broken up into say up to 4 or 8 different 10869da20b8aSRobert Mustacchiregions. 10879da20b8aSRobert Mustacchi.Pp 10889da20b8aSRobert MustacchiWhen memory is allocated for DMA it isn't immediately mapped into the 10899da20b8aSRobert Mustacchikernel's address space. 10909da20b8aSRobert MustacchiThe addresses that describe a DMA address are defined in a DMA cookie, 10919da20b8aSRobert Mustacchiseveral of which may make up a request. 10929da20b8aSRobert MustacchiHowever, those addresses are always physical addresses or addresses that 10939da20b8aSRobert Mustacchiare virtualized by an IOMMU. 10949da20b8aSRobert MustacchiThere are some cases were the kernel or a driver needs to be able to 10959da20b8aSRobert Mustacchiaccess that memory, such as memory that represents a networking packet. 10969da20b8aSRobert MustacchiThe IP stack will expect to be able to actually read the data it's 10979da20b8aSRobert Mustacchigiven. 10989da20b8aSRobert Mustacchi.Pp 10999da20b8aSRobert MustacchiTo begin with allocating DMA memory, a driver first fills out its 11009da20b8aSRobert Mustacchiattribute structure. 11019da20b8aSRobert MustacchiOnce that's ready, the DMA allocation process can begin. 11029da20b8aSRobert MustacchiThis starts off by a driver calling 11039da20b8aSRobert Mustacchi.Xr ddi_dma_alloc_handle 9F . 11049da20b8aSRobert MustacchiThis handle is used through the lifetime of a given DMA memory buffer, 11059da20b8aSRobert Mustacchibut it can be used across multiple operations that a device or the 11069da20b8aSRobert Mustacchikernel may perform. 11079da20b8aSRobert MustacchiThe next step is to actually request that the kernel allocate some 11089da20b8aSRobert Mustacchiamount of memory in the kernel for this DMA request. 11099da20b8aSRobert MustacchiThis phase actually allocates addresses in virtual address space for the 11109da20b8aSRobert Mustacchiactivity and also requires a register attribute object that is discussed 11119da20b8aSRobert Mustacchiin 11129da20b8aSRobert Mustacchi.Sx Device Register Setup and Access . 11139da20b8aSRobert MustacchiArmed with this a driver can now call 11149da20b8aSRobert Mustacchi.Xr ddi_dma_mem_alloc 9F 11159da20b8aSRobert Mustacchito specify how much memory they are looking for. 11169da20b8aSRobert MustacchiIf this is successful, a virtual address, the actual length of the 11179da20b8aSRobert Mustacchiregion, and an access handle will be returned. 11189da20b8aSRobert Mustacchi.Pp 11199da20b8aSRobert MustacchiAt this point, the virtual address region is present. 11209da20b8aSRobert MustacchiMost drivers will access this virtual address range directly and will 11219da20b8aSRobert Mustacchiignore the register access handle. 11229da20b8aSRobert MustacchiThe side effect of this is that they will handle all endianness issues 11239da20b8aSRobert Mustacchiwith the memory region themselves. 11249da20b8aSRobert MustacchiIf the driver would prefer to go through the handle, then it can use the 11259da20b8aSRobert Mustacchiregister access functions discussed earlier. 11269da20b8aSRobert Mustacchi.Pp 11279da20b8aSRobert MustacchiBefore the memory can be programmed into the device, it must be bound to 11289da20b8aSRobert Mustacchia series of physical addresses or addresses virtualized by an IOMMU. 11299da20b8aSRobert MustacchiWhile the kernel presents the illusion of a single consistent virtual 11309da20b8aSRobert Mustacchiaddress range for applications, the physical reality can be quite 11319da20b8aSRobert Mustacchidifferent. 11329da20b8aSRobert MustacchiWhen the driver is ready it calls 11339da20b8aSRobert Mustacchi.Xr ddi_dma_addr_bind_handle 9F 11349da20b8aSRobert Mustacchito create the mapping to well known physical addresses. 11359da20b8aSRobert Mustacchi.Pp 11369da20b8aSRobert MustacchiThese addresses are stored in a series of cookies. 11379da20b8aSRobert MustacchiA driver can determine the number of cookies for a given request by 11389da20b8aSRobert Mustacchiutilizing its DMA handle and calling 11399da20b8aSRobert Mustacchi.Xr ddi_dma_ncookies 9F 11409da20b8aSRobert Mustacchiand then pairing that with 11419da20b8aSRobert Mustacchi.Xr ddi_dma_cookie_get 9F . 11429da20b8aSRobert MustacchiThese DMA cookies will not change and can be used time and time again 11439da20b8aSRobert Mustacchiuntil 11449da20b8aSRobert Mustacchi.Xr ddi_dma_unbind_handle 9F 11459da20b8aSRobert Mustacchiis called. 11469da20b8aSRobert MustacchiWith this information in hand, a physical device can be programmed with 11479da20b8aSRobert Mustacchithese addresses and let loose to perform I/O. 11489da20b8aSRobert Mustacchi.Pp 11499da20b8aSRobert MustacchiWhen performing I/O to and from a device, synchronization is a vitally 11509da20b8aSRobert Mustacchiimportant thing which ensures that the actual state in memory is 11519da20b8aSRobert Mustacchicoherent with the rest of the CPU's internal structures such as caches. 11529da20b8aSRobert MustacchiIn general, a given DMA request is only going in one direction: for a 11539da20b8aSRobert Mustacchidevice or for the local CPU. 11549da20b8aSRobert MustacchiIn either case, the 11559da20b8aSRobert Mustacchi.Xr ddi_dma_sync 9F 11569da20b8aSRobert Mustacchifunction must be called after the kernel is done writing to a region of 11579da20b8aSRobert MustacchiDMA memory and before it triggers the device or the kernel must call it 11589da20b8aSRobert Mustacchiafter the device has told it that some activity has completed that it is 11599da20b8aSRobert Mustacchigoing to check. 11609da20b8aSRobert Mustacchi.Pp 11619da20b8aSRobert MustacchiSome DMA operations utilize what are called DMA windows. 11629da20b8aSRobert MustacchiThe most common consumer is something like a disk device where DMA 11639da20b8aSRobert Mustacchioperations to a given series of sectors can be split up into different 11649da20b8aSRobert Mustacchichunks where as long as all the transfers are performed, the 11659da20b8aSRobert Mustacchiintermediate states are acceptable. 11669da20b8aSRobert MustacchiPut another way, because of how SCSI and SAS commands are designed, 11679da20b8aSRobert Mustacchiblock devices can basically take a given I/O request and break it into 11689da20b8aSRobert Mustacchimultiple independent I/Os that will equate to the same final item. 11699da20b8aSRobert Mustacchi.Pp 11709da20b8aSRobert MustacchiWhen a device supports this mode of operation and it is opted into, then 11719da20b8aSRobert Mustacchia DMA allocation may result in the use of DMA windows. 11729da20b8aSRobert MustacchiThis allows for cases where the kernel can't perform a DMA allocation 11739da20b8aSRobert Mustacchifor the entire request, but instead can allocate a partial region and 11749da20b8aSRobert Mustacchithen walk through each part one at a time. 11759da20b8aSRobert MustacchiThis is uncommon outside of block devices and usually also is related to 11769da20b8aSRobert Mustacchicalling 11779da20b8aSRobert Mustacchi.Xr ddi_dma_buf_bind_handle 9F . 11789da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 11799da20b8aSRobert Mustacchi.It Xr ddi_dma_addr_bind_handle 9F Ta Xr ddi_dma_alloc_handle 9F 11809da20b8aSRobert Mustacchi.It Xr ddi_dma_buf_bind_handle 9F Ta Xr ddi_dma_burstsizes 9F 11819da20b8aSRobert Mustacchi.It Xr ddi_dma_cookie_get 9F Ta Xr ddi_dma_cookie_iter 9F 11829da20b8aSRobert Mustacchi.It Xr ddi_dma_cookie_one 9F Ta Xr ddi_dma_free_handle 9F 11839da20b8aSRobert Mustacchi.It Xr ddi_dma_getwin 9F Ta Xr ddi_dma_mem_alloc 9F 11849da20b8aSRobert Mustacchi.It Xr ddi_dma_mem_free 9F Ta Xr ddi_dma_ncookies 9F 11859da20b8aSRobert Mustacchi.It Xr ddi_dma_nextcookie 9F Ta Xr ddi_dma_numwin 9F 11869da20b8aSRobert Mustacchi.It Xr ddi_dma_set_sbus64 9F Ta Xr ddi_dma_sync 9F 11879da20b8aSRobert Mustacchi.It Xr ddi_dma_unbind_handle 9F Ta Xr ddi_dmae_1stparty 9F 11889da20b8aSRobert Mustacchi.It Xr ddi_dmae_alloc 9F Ta Xr ddi_dmae_disable 9F 11899da20b8aSRobert Mustacchi.It Xr ddi_dmae_enable 9F Ta Xr ddi_dmae_getattr 9F 11909da20b8aSRobert Mustacchi.It Xr ddi_dmae_getcnt 9F Ta Xr ddi_dmae_prog 9F 11919da20b8aSRobert Mustacchi.It Xr ddi_dmae_release 9F Ta Xr ddi_dmae_stop 9F 11929da20b8aSRobert Mustacchi.It Xr ddi_dmae 9F Ta 11939da20b8aSRobert Mustacchi.El 11949da20b8aSRobert Mustacchi.Ss Interrupt Handler Related Functions 11959da20b8aSRobert MustacchiInterrupts are a central part of the role of device drivers and one of 11969da20b8aSRobert Mustacchithe things that's important to get right. 11979da20b8aSRobert MustacchiInterrupts come in different types: fixed, MSI, and MSI-X. 11989da20b8aSRobert MustacchiThe kinds that are available depend on the device and the rest of the 11999da20b8aSRobert Mustacchisystem. 12009da20b8aSRobert MustacchiFor example, MSI and MSI-X interrupts are generally specific to PCI and 12019da20b8aSRobert MustacchiPCI Express devices. 12029da20b8aSRobert MustacchiTo begin the interrupt allocation process, the first thing a driver 12039da20b8aSRobert Mustacchineeds to do is to discover what type of interrupts it supports with 12049da20b8aSRobert Mustacchi.Xr ddi_intr_get_supported_types 9F . 12059da20b8aSRobert MustacchiThen, the driver should work through the supported types, preferring 12069da20b8aSRobert MustacchiMSI-X, then MSI, and finally fixed interrupts, and try to allocate 12079da20b8aSRobert Mustacchiinterrupts. 12089da20b8aSRobert Mustacchi.Pp 12099da20b8aSRobert MustacchiDrivers first need to know how many interrupts that they require. 12109da20b8aSRobert MustacchiFor example, a networking driver may want to have an interrupt made 12119da20b8aSRobert Mustacchiavailable for each ring that it has. 12129da20b8aSRobert MustacchiTo discover the number of interrupts available, the driver should call 12139da20b8aSRobert Mustacchi.Xr ddi_intr_get_navail 9F . 12149da20b8aSRobert MustacchiIf there are sufficient interrupts, it can proceed to actually 12159da20b8aSRobert Mustacchiallocate the interrupts with 12169da20b8aSRobert Mustacchi.Xr ddi_intr_alloc 9F . 12179da20b8aSRobert MustacchiWhen allocating interrupts, callers need to check to see how many 12189da20b8aSRobert Mustacchiinterrupts the system actually gave them. 12199da20b8aSRobert MustacchiJust because an interrupt is allocated does not mean that it will fire 12209da20b8aSRobert Mustacchior be ready to use, there are a series of additional steps that the 12219da20b8aSRobert Mustacchidriver must take. 12229da20b8aSRobert Mustacchi.Pp 12239da20b8aSRobert MustacchiTo go through and enable the interrupt, the driver should go through and 12249da20b8aSRobert Mustacchiget the interrupt capabilities with 12259da20b8aSRobert Mustacchi.Xr ddi_intr_get_cap 9F 12269da20b8aSRobert Mustacchiand the priority of the interrupt with 12279da20b8aSRobert Mustacchi.Xr ddi_intr_get_pri 9F . 12289da20b8aSRobert MustacchiThe priority must be used while creating mutexes and related 12299da20b8aSRobert Mustacchisynchronization primitives that will be used during the interrupt 12309da20b8aSRobert Mustacchihandler. 12319da20b8aSRobert MustacchiAt this point, the driver can go ahead and register the functions that 12329da20b8aSRobert Mustacchiwill be called with each allocated interrupt with the 12339da20b8aSRobert Mustacchi.Xr ddi_intr_add_handler 9F 12349da20b8aSRobert Mustacchifunction. 12359da20b8aSRobert MustacchiThe arguments can vary for each allocated interrupt. 12369da20b8aSRobert MustacchiIt is common to have an interrupt-specific data structure passed in one 12379da20b8aSRobert Mustacchiof the arguments or an interrupt number, while the other argument is 12389da20b8aSRobert Mustacchigenerally the driver's instance-specific data structure. 12399da20b8aSRobert Mustacchi.Pp 12409da20b8aSRobert MustacchiAt this point, the last step for the interrupt to be made active from 12419da20b8aSRobert Mustacchithe kernel's perspective is to enable it. 12429da20b8aSRobert MustacchiThis will use either the 12439da20b8aSRobert Mustacchi.Xr ddi_intr_block_enable 9F 12449da20b8aSRobert Mustacchior 12459da20b8aSRobert Mustacchi.Xr ddi_intr_enable 9F 12469da20b8aSRobert Mustacchifunctions depending on the interrupt's capabilities. 12479da20b8aSRobert MustacchiThe reason that these are different is because some interrupt types 12489da20b8aSRobert Mustacchi.Pq MSI 12499da20b8aSRobert Mustacchirequire that all interrupts in a group be enabled and disabled at the 12509da20b8aSRobert Mustacchisame time. 12519da20b8aSRobert MustacchiThis is indicated with the 12529da20b8aSRobert Mustacchi.Dv DDI_INTR_FLAG_BLOCK 12539da20b8aSRobert Mustacchiflag found in the interrupt's capabilities. 12549da20b8aSRobert MustacchiOnce that is called, interrupts that are generated by a device will be 12559da20b8aSRobert Mustacchidelivered to the registered function. 12569da20b8aSRobert Mustacchi.Pp 12579da20b8aSRobert MustacchiIt's important to note that there is often device-specific interrupt 12589da20b8aSRobert Mustacchisetup that is required. 12599da20b8aSRobert MustacchiWhile the kernel takes care of updating any pieces of the processor's 12609da20b8aSRobert Mustacchiinterrupt controller, I/O crossbar, or the PCI MSI and MSI-X 12619da20b8aSRobert Mustacchicapabilities, many devices have device-specific registers that are used 12629da20b8aSRobert Mustacchito manage, set up, and acknowledge interrupts. 12639da20b8aSRobert MustacchiThese registers or other controls are often capable of separately 12649da20b8aSRobert Mustacchimasking interrupts and are generally what should be used if there are 12659da20b8aSRobert Mustacchitimes that you need to separately enable or disable interrupts such as 12669da20b8aSRobert Mustacchito poll an I/O ring. 12679da20b8aSRobert Mustacchi.Pp 12689da20b8aSRobert MustacchiWhen unwinding interrupts, one needs to work in the reverse order here. 12699da20b8aSRobert MustacchiUntil 12709da20b8aSRobert Mustacchi.Xr ddi_intr_block_disable 9F 12719da20b8aSRobert Mustacchior 12729da20b8aSRobert Mustacchi.Xr ddi_intr_disable 9F 12739da20b8aSRobert Mustacchiis called, one should assume that their interrupt handler will be 12749da20b8aSRobert Mustacchicalled. 12759da20b8aSRobert MustacchiDue to cases where an interrupt is shared between multiple devices, this 12769da20b8aSRobert Mustacchican happen even if the device is quiesced! 12779da20b8aSRobert MustacchiOnly after that is done is it safe to then free the interrupts with a 12789da20b8aSRobert Mustacchicall to 12799da20b8aSRobert Mustacchi.Xr ddi_intr_free 9F . 12809da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 12819da20b8aSRobert Mustacchi.It Xr ddi_add_intr 9F Ta Xr ddi_add_softintr 9F 12829da20b8aSRobert Mustacchi.It Xr ddi_get_iblock_cookie 9F Ta Xr ddi_get_soft_iblock_cookie 9F 12839da20b8aSRobert Mustacchi.It Xr ddi_intr_add_handler 9F Ta Xr ddi_intr_add_softint 9F 12849da20b8aSRobert Mustacchi.It Xr ddi_intr_alloc 9F Ta Xr ddi_intr_block_disable 9F 12859da20b8aSRobert Mustacchi.It Xr ddi_intr_block_enable 9F Ta Xr ddi_intr_clr_mask 9F 12869da20b8aSRobert Mustacchi.It Xr ddi_intr_disable 9F Ta Xr ddi_intr_dup_handler 9F 12879da20b8aSRobert Mustacchi.It Xr ddi_intr_enable 9F Ta Xr ddi_intr_free 9F 12889da20b8aSRobert Mustacchi.It Xr ddi_intr_get_cap 9F Ta Xr ddi_intr_get_hilevel_pri 9F 12899da20b8aSRobert Mustacchi.It Xr ddi_intr_get_navail 9F Ta Xr ddi_intr_get_nintrs 9F 12909da20b8aSRobert Mustacchi.It Xr ddi_intr_get_pending 9F Ta Xr ddi_intr_get_pri 9F 12919da20b8aSRobert Mustacchi.It Xr ddi_intr_get_softint_pri 9F Ta Xr ddi_intr_get_supported_types 9F 12929da20b8aSRobert Mustacchi.It Xr ddi_intr_hilevel 9F Ta Xr ddi_intr_remove_handler 9F 12939da20b8aSRobert Mustacchi.It Xr ddi_intr_remove_softint 9F Ta Xr ddi_intr_set_cap 9F 12949da20b8aSRobert Mustacchi.It Xr ddi_intr_set_mask 9F Ta Xr ddi_intr_set_nreq 9F 12959da20b8aSRobert Mustacchi.It Xr ddi_intr_set_pri 9F Ta Xr ddi_intr_set_softint_pri 9F 12969da20b8aSRobert Mustacchi.It Xr ddi_intr_trigger_softint 9F Ta Xr ddi_remove_intr 9F 12979da20b8aSRobert Mustacchi.It Xr ddi_remove_softintr 9F Ta Xr ddi_trigger_softintr 9F 12989da20b8aSRobert Mustacchi.El 12999da20b8aSRobert Mustacchi.Ss Minor Nodes 13009da20b8aSRobert MustacchiFor a device driver to be accessed by a program in user space 13019da20b8aSRobert Mustacchi.Pq or with the kernel layered device interface 13029da20b8aSRobert Mustacchithen it must create a minor node. 13039da20b8aSRobert MustacchiMinor nodes are created under 13049da20b8aSRobert Mustacchi.Pa /devices 13059da20b8aSRobert Mustacchi.Pq Xr devfs 4FS 13069da20b8aSRobert Mustacchiand are tied to the instance of a device driver via its 13079da20b8aSRobert Mustacchi.Vt dev_info_t . 13089da20b8aSRobert MustacchiThe 13099da20b8aSRobert Mustacchi.Xr devfsadm 8 13109da20b8aSRobert Mustacchidaemon and the 13119da20b8aSRobert Mustacchi.Pa /dev 13129da20b8aSRobert Mustacchifile system 13139da20b8aSRobert Mustacchi.Po 13149da20b8aSRobert Mustacchisdev, 13159da20b8aSRobert Mustacchi.Xr dev 4FS 13169da20b8aSRobert Mustacchi.Pc 13179da20b8aSRobert Mustacchiare responsible for creating a coherent set of names that user programs 13189da20b8aSRobert Mustacchiaccess. 13199da20b8aSRobert MustacchiDrivers create these minor nodes using the 13209da20b8aSRobert Mustacchi.Xr ddi_create_minor_node 9F 13219da20b8aSRobert Mustacchifunction listed below. 13229da20b8aSRobert Mustacchi.Pp 13239da20b8aSRobert MustacchiIn UNIX tradition, character, block, and STREAMS device special files 13249da20b8aSRobert Mustacchiare identified by a major and minor number. 13259da20b8aSRobert MustacchiAll instances of a given driver share the same major number, which means 13269da20b8aSRobert Mustacchithat a device driver must coordinate the minor number space across 13279da20b8aSRobert Mustacchi.Em all 13289da20b8aSRobert Mustacchiinstances. 13299da20b8aSRobert MustacchiWhile a minor node is created with a fixed minor number, it is possible 13309da20b8aSRobert Mustacchito change the minor number while processing an 13319da20b8aSRobert Mustacchi.Xr open 9E 13329da20b8aSRobert Mustacchicall, allowing subsequent character device operations to uniquely 13339da20b8aSRobert Mustacchiidentify a particular caller. 13349da20b8aSRobert MustacchiThis is usually referred to as a driver that 13359da20b8aSRobert Mustacchi.Dq clones . 13369da20b8aSRobert Mustacchi.Pp 13379da20b8aSRobert MustacchiWhen drivers aren't performing cloning, then usually the minor number 13389da20b8aSRobert Mustacchiused when creating the minor node is some fixed offset or multiple of 13399da20b8aSRobert Mustacchithe driver's instance number. 13409da20b8aSRobert MustacchiWhen cloning and a driver needs to allocate and manage a minor number 13419da20b8aSRobert Mustacchispace, usually an ID space is leveraged whose IDs are usually in the 13429da20b8aSRobert Mustacchirange from 0 through 13439da20b8aSRobert Mustacchi.Dv MAXMIN32 . 1344*496cffd8SPeter TribbleThere are several different strategies for tracking data structures as 13459da20b8aSRobert Mustacchithey relate to minor numbers. 13469da20b8aSRobert MustacchiSometimes, the soft state functionality is used. 13479da20b8aSRobert MustacchiOthers might keep an AVL tree around or tie the data to some other data 13489da20b8aSRobert Mustacchistructure. 13499da20b8aSRobert MustacchiThe method chosen often varies on the specifics of the implementation 13509da20b8aSRobert Mustacchiand its broader context. 13519da20b8aSRobert Mustacchi.Pp 13529da20b8aSRobert MustacchiThe 13539da20b8aSRobert Mustacchi.Vt dev_t 13549da20b8aSRobert Mustacchistructure represents the combined major and minor number. 13559da20b8aSRobert MustacchiIt can be taken apart with the 13569da20b8aSRobert Mustacchi.Xr getmajor 9F 13579da20b8aSRobert Mustacchiand 13589da20b8aSRobert Mustacchi.Xr getminor 9F 13599da20b8aSRobert Mustacchifunctions and then reconstructed with the 13609da20b8aSRobert Mustacchi.Xr makedevice 9F 13619da20b8aSRobert Mustacchifunction. 13629da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 13639da20b8aSRobert Mustacchi.It Xr ddi_create_minor_node 9F Ta Xr ddi_remove_minor_node 9F 13649da20b8aSRobert Mustacchi.It Xr getmajor 9F Ta Xr getminor 9F 13659da20b8aSRobert Mustacchi.It Xr devfs_clean 9F Ta Xr makedevice 9F 13669da20b8aSRobert Mustacchi.El 13679da20b8aSRobert Mustacchi.Ss Accessing Time, Delays, and Periodic Events 13689da20b8aSRobert MustacchiThe kernel provides a number of ways to understand time in the system. 13699da20b8aSRobert MustacchiIn particular it provides a few different clocks and time measurements: 13709da20b8aSRobert Mustacchi.Bl -tag -width Ds 13719da20b8aSRobert Mustacchi.It High-resolution monotonic time 13729da20b8aSRobert MustacchiThe kernel provides access to a high-resolution monotonic clock that is 13739da20b8aSRobert Mustacchitracked in nanoseconds. 13749da20b8aSRobert MustacchiThis clock is perfect for measuring durations and is accessed via 13759da20b8aSRobert Mustacchi.Xr gethrtime 9F . 13769da20b8aSRobert MustacchiUnlike the real-time clock, this clock is not subject to adjustments by 13779da20b8aSRobert Mustacchia time synchronization daemon and is the preferred clock that drivers 13789da20b8aSRobert Mustacchishould be using for tracking events. 13799da20b8aSRobert MustacchiThe high-resolution clock is consistent across CPUs, meaning that you 13809da20b8aSRobert Mustacchimay call 13819da20b8aSRobert Mustacchi.Xr gethrtime 9F 13829da20b8aSRobert Mustacchion one CPU and the value will be consistent with what is returned, even 13839da20b8aSRobert Mustacchiif a thread is migrated to another CPU. 13849da20b8aSRobert Mustacchi.Pp 13859da20b8aSRobert MustacchiThe high-resolution clock is implemented using an architecture and 13869da20b8aSRobert Mustacchiplatform-specific means. 13879da20b8aSRobert MustacchiFor example, on x86 it is generally backed by the TSC 13889da20b8aSRobert Mustacchi.Pq time stamp counter . 13899da20b8aSRobert Mustacchi.It Real-time 13909da20b8aSRobert MustacchiThe real-time clock tracks time as humans perceive it. 13919da20b8aSRobert MustacchiThis clock is accessed using 13929da20b8aSRobert Mustacchi.Xr ddi_get_time 9F . 13939da20b8aSRobert MustacchiIf the system is running a time synchronization daemon that leverages 13949da20b8aSRobert Mustacchithe network time protocol, then this time may be in sync with other 13959da20b8aSRobert Mustacchisystems 13969da20b8aSRobert Mustacchi.Pq subject to some amount of variance ; 13979da20b8aSRobert Mustacchihowever, it is critical that this is not assumed. 13989da20b8aSRobert Mustacchi.Pp 13999da20b8aSRobert MustacchiIn general, this time should not be used by drivers for any purpose. 14009da20b8aSRobert MustacchiIt can jump around, drift, and most aspects in the kernel are not based 14019da20b8aSRobert Mustacchion the real-time clock. 14029da20b8aSRobert MustacchiFor any device timing activities, the high-resolution clock should be 14039da20b8aSRobert Mustacchiused. 14049da20b8aSRobert Mustacchi.It Tick-based monotonic time 14059da20b8aSRobert MustacchiThe kernel has a running periodic function that fires based on the rate 14069da20b8aSRobert Mustacchidictated by the 14079da20b8aSRobert Mustacchi.Va hz 14089da20b8aSRobert Mustacchivariable, generally operating at 100 or 1000 kHz. 14099da20b8aSRobert MustacchiThe current number of ticks since boot is accessible through the 14109da20b8aSRobert Mustacchi.Xr ddi_get_lbolt 9F 14119da20b8aSRobert Mustacchifunction. 14129da20b8aSRobert MustacchiWhen functions operate in units of ticks, this is what they are 14139da20b8aSRobert Mustacchitracking. 14149da20b8aSRobert MustacchiThis value can be converted to and from microseconds using the 14159da20b8aSRobert Mustacchi.Xr drv_usectohz 9F 14169da20b8aSRobert Mustacchiand 14179da20b8aSRobert Mustacchi.Xr drv_hztousec 9F 14189da20b8aSRobert Mustacchifunctions. 14199da20b8aSRobert Mustacchi.Pp 14209da20b8aSRobert MustacchiIn general, drivers should prefer the high-resolution monotonic clock 14219da20b8aSRobert Mustacchifor tracking events internally. 14229da20b8aSRobert Mustacchi.El 14239da20b8aSRobert Mustacchi.Pp 14249da20b8aSRobert MustacchiWith these different timing mechanisms, the kernel provides a few 14259da20b8aSRobert Mustacchidifferent ways to delay execution or to get a callback after some 14269da20b8aSRobert Mustacchiamount of time passes. 14279da20b8aSRobert Mustacchi.Pp 14289da20b8aSRobert MustacchiThe 14299da20b8aSRobert Mustacchi.Xr delay 9F 14309da20b8aSRobert Mustacchiand 14319da20b8aSRobert Mustacchi.Xr drv_usecwait 9F 14329da20b8aSRobert Mustacchifunctions are used to block the execution of the current thread. 14339da20b8aSRobert Mustacchi.Xr delay 9F 14349da20b8aSRobert Mustacchican be used in conditions where sleeping and blocking is allowed where 14359da20b8aSRobert Mustacchias 14369da20b8aSRobert Mustacchi.Xr drv_usecwait 9F 14379da20b8aSRobert Mustacchiis a busy-wait, which is appropriate for some device drivers, 14389da20b8aSRobert Mustacchiparticularly when in high-level interrupt context. 14399da20b8aSRobert Mustacchi.Pp 14409da20b8aSRobert MustacchiThe kernel also allows a function to be called after some time has 14419da20b8aSRobert Mustacchielapsed. 14429da20b8aSRobert MustacchiThis callback occurs on a different thread and will be executed in 14439da20b8aSRobert Mustacchi.Sy kernel 14449da20b8aSRobert Mustacchicontext. 14459da20b8aSRobert MustacchiA timeout can be scheduled in the future with the 14469da20b8aSRobert Mustacchi.Xr timeout 9F 14479da20b8aSRobert Mustacchifunction and cancelled with the 14489da20b8aSRobert Mustacchi.Xr untimeout 9F 14499da20b8aSRobert Mustacchifunction. 14509da20b8aSRobert MustacchiThere is also a STREAMs-specific version that can be used if the 14519da20b8aSRobert Mustacchicircumstances are required with the 14529da20b8aSRobert Mustacchi.Xr qtimeout 9F 14539da20b8aSRobert Mustacchifunction. 14549da20b8aSRobert Mustacchi.Pp 14559da20b8aSRobert MustacchiThese are all considered one-shot events. 14569da20b8aSRobert MustacchiThat is, they will only happen once after being scheduled. 14579da20b8aSRobert MustacchiIf instead, a driver requires periodic behavior, such as needing 14589da20b8aSRobert Mustacchisomething to occur every second, then it should use the 14599da20b8aSRobert Mustacchi.Xr ddi_periodic_add 9F 14609da20b8aSRobert Mustacchifunction to establish that. 14619da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 14629da20b8aSRobert Mustacchi.It Xr delay 9F Ta Xr ddi_get_lbolt 9F 14639da20b8aSRobert Mustacchi.It Xr ddi_get_lbolt64 9F Ta Xr ddi_get_time 9F 14649da20b8aSRobert Mustacchi.It Xr ddi_periodic_add 9F Ta Xr ddi_periodic_delete 9F 14659da20b8aSRobert Mustacchi.It Xr drv_hztousec 9F Ta Xr drv_usectohz 9F 14669da20b8aSRobert Mustacchi.It Xr drv_usecwait 9F Ta Xr gethrtime 9F 14679da20b8aSRobert Mustacchi.It Xr qtimeout 9F Ta Xr quntimeout 9F 14689da20b8aSRobert Mustacchi.It Xr timeout 9F Ta Xr untimeout 9F 14699da20b8aSRobert Mustacchi.El 14709da20b8aSRobert Mustacchi.Ss Task Queues 14719da20b8aSRobert MustacchiA task queue provides an asynchronous processing mechanism that can be 14729da20b8aSRobert Mustacchiused by drivers and the broader system. 14739da20b8aSRobert MustacchiA task queue can be created with 14749da20b8aSRobert Mustacchi.Xr ddi_taskq_create 9F 14759da20b8aSRobert Mustacchiand sized with a given number of threads and a relative priority of those 14769da20b8aSRobert Mustacchithreads. 14779da20b8aSRobert MustacchiOnce created, tasks can be dispatched to the queue with 14789da20b8aSRobert Mustacchi.Xr ddi_taskq_dispatch 9F . 14799da20b8aSRobert MustacchiThe different functions and arguments dispatched do not need to be the 14809da20b8aSRobert Mustacchisame and can vary from invocation to invocation. 14819da20b8aSRobert MustacchiHowever, it is the caller's responsibility to ensure that any reference 14829da20b8aSRobert Mustacchimemory is valid until the task queue is done processing. 14839da20b8aSRobert MustacchiIt is possible to create a barrier for a task queue by using the 14849da20b8aSRobert Mustacchi.Xr ddi_taskq_wait 9F 14859da20b8aSRobert Mustacchifunction. 14869da20b8aSRobert Mustacchi.Pp 14879da20b8aSRobert MustacchiWhile task queues are a flexible mechanism for handling and processing 14889da20b8aSRobert Mustacchievents that occur in a well defined context, they do not have an 14899da20b8aSRobert Mustacchiinherent backpressure mechanism built in. 14909da20b8aSRobert MustacchiThis means it is possible to add events to a task queue faster than they 14919da20b8aSRobert Mustacchican be processed. 14929da20b8aSRobert MustacchiFor high-volume events, this must be considered before just dispatching 14939da20b8aSRobert Mustacchian event. 14949da20b8aSRobert MustacchiDo not rely on a non-sleeping allocation in the task queue dispatch 14959da20b8aSRobert Mustacchicontext. 14969da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 14979da20b8aSRobert Mustacchi.It Xr ddi_taskq_create 9F Ta Xr ddi_taskq_destroy 9F 14989da20b8aSRobert Mustacchi.It Xr ddi_taskq_dispatch 9F Ta Xr ddi_taskq_resume 9F 14999da20b8aSRobert Mustacchi.It Xr ddi_taskq_suspend 9F Ta Xr ddi_taskq_suspended 9F 15009da20b8aSRobert Mustacchiddi_taskq_wait 15019da20b8aSRobert Mustacchi.El 15029da20b8aSRobert Mustacchi.Ss Credential Management and Privileges 15039da20b8aSRobert MustacchiNot everything in the system has the same power to impact it. 15049da20b8aSRobert MustacchiTo determine the permissions and context of a caller, the 15059da20b8aSRobert Mustacchi.Vt cred_t 15069da20b8aSRobert Mustacchidata structure encapsulates a number of different things including the 15079da20b8aSRobert Mustacchitraditional user and group IDs, but also the zone that one is operating 15089da20b8aSRobert Mustacchiin the context of and the associated privileges that the caller has. 15099da20b8aSRobert MustacchiWhile this concept is more often thought of due to userland processes being 15109da20b8aSRobert Mustacchiassociated with specific users, these same principles apply to different 15119da20b8aSRobert Mustacchithreads in the kernel. 15129da20b8aSRobert MustacchiNot all kernel threads are allowed to indiscriminately do what they 15139da20b8aSRobert Mustacchiwant, they can be constrained by the same privilege model that processes 15149da20b8aSRobert Mustacchiare, which is discussed in 15159da20b8aSRobert Mustacchi.Xr privileges 7 . 15169da20b8aSRobert Mustacchi.Pp 15179da20b8aSRobert MustacchiMost operations that device drivers implement are given a credential. 15189da20b8aSRobert MustacchiHowever, from within the kernel, a credential can be obtained that 15199da20b8aSRobert Mustacchirefers to a specific zone, the current process, or a generic kernel 15209da20b8aSRobert Mustacchicredential. 15219da20b8aSRobert Mustacchi.Pp 15229da20b8aSRobert MustacchiIt is up to drivers and the kernel writ-large to check whether a given 15239da20b8aSRobert Mustacchicredential is authorized to perform a given operation. 15249da20b8aSRobert MustacchiThis is encapsulated by the various privilege checks that exist. 15259da20b8aSRobert MustacchiThe most common check used is 15269da20b8aSRobert Mustacchi.Xr drv_priv 9F 15279da20b8aSRobert Mustacchiwhich checks for 15289da20b8aSRobert Mustacchi.Dv PRIV_SYS_DEVICES . 15299da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 15309da20b8aSRobert Mustacchi.It Xr CRED 9F Ta Xr crdup 9F 15319da20b8aSRobert Mustacchi.It Xr crfree 9F Ta Xr crget 9F 15329da20b8aSRobert Mustacchi.It Xr crgetgid 9F Ta Xr crgetgroups 9F 15339da20b8aSRobert Mustacchi.It Xr crgetngroups 9F Ta Xr crgetrgid 9F 15349da20b8aSRobert Mustacchi.It Xr crgetruid 9F Ta Xr crgetsgid 9F 15359da20b8aSRobert Mustacchi.It Xr crgetsuid 9F Ta Xr crgetuid 9F 15369da20b8aSRobert Mustacchi.It Xr crgetzoneid 9F Ta Xr crhold 9F 15379da20b8aSRobert Mustacchi.It Xr ddi_get_cred 9F Ta Xr drv_priv 9F 15389da20b8aSRobert Mustacchi.It Xr kcred 9F Ta Xr priv_getbyname 9F 15399da20b8aSRobert Mustacchi.It Xr priv_policy_choice 9F Ta Xr priv_policy_only 9F 15409da20b8aSRobert Mustacchi.It Xr priv_policy 9F Ta Xr zone_kcred 9F 15419da20b8aSRobert Mustacchi.El 15429da20b8aSRobert Mustacchi.Ss Device ID Management 15439da20b8aSRobert MustacchiDevice IDs are a means of establishing a unique ID for a device in the 15449da20b8aSRobert Mustacchikernel. 15459da20b8aSRobert MustacchiThese unique IDs are generally tied to something from the device's 15469da20b8aSRobert Mustacchihardware such as a serial number or related, but can also be fabricated 15479da20b8aSRobert Mustacchiand stored on the device. 15489da20b8aSRobert MustacchiThese device IDs are used by other subsystems like ZFS to record 15499da20b8aSRobert Mustacchiinformation about a device as the actual 15509da20b8aSRobert Mustacchi.Pa /devices 15519da20b8aSRobert Mustacchipath that a device resides at may change because it is moved around in 15529da20b8aSRobert Mustacchithe system. 15539da20b8aSRobert Mustacchi.Pp 15549da20b8aSRobert MustacchiFor device drivers, particularly those that represent block devices, 15559da20b8aSRobert Mustacchithey should first call 15569da20b8aSRobert Mustacchi.Xr ddi_devid_init 9F 15579da20b8aSRobert Mustacchito initialize the device ID data structure. 15589da20b8aSRobert MustacchiAfter that is done, it is then safe to call 15599da20b8aSRobert Mustacchi.Xr ddi_devid_register 9F 15609da20b8aSRobert Mustacchito notify the kernel about the ID. 15619da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 15629da20b8aSRobert Mustacchi.It Xr ddi_devid_compare 9F Ta Xr ddi_devid_free 9F 15639da20b8aSRobert Mustacchi.It Xr ddi_devid_get 9F Ta Xr ddi_devid_init 9F 15649da20b8aSRobert Mustacchi.It Xr ddi_devid_register 9F Ta Xr ddi_devid_sizeof 9F 15659da20b8aSRobert Mustacchi.It Xr ddi_devid_str_decode 9F Ta Xr ddi_devid_str_encode 9F 15669da20b8aSRobert Mustacchi.It Xr ddi_devid_str_free 9F Ta Xr ddi_devid_unregister 9F 15679da20b8aSRobert Mustacchi.It Xr ddi_devid_valid 9F Ta 15689da20b8aSRobert Mustacchi.El 15699da20b8aSRobert Mustacchi.Ss Message Block Functions 15709da20b8aSRobert MustacchiThe 15719da20b8aSRobert Mustacchi.Vt "mblk_t" 15729da20b8aSRobert Mustacchidata structure is used to chain together messages which are used through 15739da20b8aSRobert Mustacchithe kernel for different subsystems including all of networking, 15749da20b8aSRobert Mustacchiterminals, STREAMS, USB, and more. 15759da20b8aSRobert Mustacchi.Pp 15769da20b8aSRobert MustacchiMessage blocks are chained together by a series of two different 15779da20b8aSRobert Mustacchipointers: 15789da20b8aSRobert Mustacchi.Fa b_cont 15799da20b8aSRobert Mustacchiand 15809da20b8aSRobert Mustacchi.Fa b_next . 15819da20b8aSRobert MustacchiWhen a message is split across multiple data buffers, they are linked by 15829da20b8aSRobert Mustacchithe 15839da20b8aSRobert Mustacchi.Fa b_cont 15849da20b8aSRobert Mustacchipointer. 15859da20b8aSRobert MustacchiHowever, multiple distinct messages can be chained together and linked 15869da20b8aSRobert Mustacchiby the 15879da20b8aSRobert Mustacchi.Fa b_next 15889da20b8aSRobert Mustacchipointer. 15899da20b8aSRobert MustacchiLet's look at this in the context of a series of networking packets. 15909da20b8aSRobert MustacchiIf we had a chain of say 10 UDP packets that we were given, each UDP 15919da20b8aSRobert Mustacchipacket is considered an independent message and would be linked from one 15929da20b8aSRobert Mustacchito the next based on the order they should be transmitted with the 15939da20b8aSRobert Mustacchi.Fa b_next 15949da20b8aSRobert Mustacchipointer. 15959da20b8aSRobert MustacchiHowever, an individual message may be entirely in one message block, in 15969da20b8aSRobert Mustacchiwhich case its 15979da20b8aSRobert Mustacchi.Fa b_cont 15989da20b8aSRobert Mustacchipointer would be 15999da20b8aSRobert Mustacchi.Dv NULL , 16009da20b8aSRobert Mustacchibut if say the packet were split into a 100 byte data buffer that 16019da20b8aSRobert Mustacchicontained the headers and then a 1000 byte data buffer that contained 16029da20b8aSRobert Mustacchithe actual packet data, those two would be linked together by 16039da20b8aSRobert Mustacchi.Fa b_cont . 16049da20b8aSRobert MustacchiA continued message would never have its next pointer used to link it to 16059da20b8aSRobert Mustacchia wholly different message. 16069da20b8aSRobert MustacchiVisually you might see this as: 16079da20b8aSRobert Mustacchi.Bd -literal 16089da20b8aSRobert Mustacchi +---------------+ 16099da20b8aSRobert Mustacchi | UDP Message 0 | 16109da20b8aSRobert Mustacchi | Bytes 0-1100 | 16119da20b8aSRobert Mustacchi | b_cont ---+--> NULL 16129da20b8aSRobert Mustacchi | b_next + | 16139da20b8aSRobert Mustacchi +---------|-----+ 16149da20b8aSRobert Mustacchi | 16159da20b8aSRobert Mustacchi v 16169da20b8aSRobert Mustacchi +---------------+ +----------------+ 16179da20b8aSRobert Mustacchi | UDP Message 1 | | UDP Message 1+ | 16189da20b8aSRobert Mustacchi | Bytes 0-100 | | Bytes 100-1100 | 16199da20b8aSRobert Mustacchi | b_cont ---+--> | b_cont ----+->NULL 16209da20b8aSRobert Mustacchi | b_next + | | b_next ----+->NULL 16219da20b8aSRobert Mustacchi +---------|-----+ +----------------+ 16229da20b8aSRobert Mustacchi | 16239da20b8aSRobert Mustacchi ... 16249da20b8aSRobert Mustacchi | 16259da20b8aSRobert Mustacchi v 16269da20b8aSRobert Mustacchi +---------------+ 16279da20b8aSRobert Mustacchi | UDP Message 9 | 16289da20b8aSRobert Mustacchi | Bytes 0-1100 | 16299da20b8aSRobert Mustacchi | b_cont ---+--> NULL 16309da20b8aSRobert Mustacchi | b_next ---+--> NULL 16319da20b8aSRobert Mustacchi +---------------+ 16329da20b8aSRobert Mustacchi.Ed 16339da20b8aSRobert Mustacchi.Pp 16349da20b8aSRobert MustacchiMessage blocks all have an associated data block which contains the 16359da20b8aSRobert Mustacchiactual data that is present. 16369da20b8aSRobert MustacchiMultiple message blocks can share the same data block as well. 16379da20b8aSRobert MustacchiThe data block has a notion of a type, which is generally 16389da20b8aSRobert Mustacchi.Dv M_DATA 16399da20b8aSRobert Mustacchiwhich signifies that they operate on data. 16409da20b8aSRobert Mustacchi.Pp 16419da20b8aSRobert MustacchiTo allocate message blocks, one generally uses the 16429da20b8aSRobert Mustacchi.Xr allocb 9F 16439da20b8aSRobert Mustacchifunction to create one; however, you can also create message blocks 16449da20b8aSRobert Mustacchiusing your own source of data through functions like 16459da20b8aSRobert Mustacchi.Xr desballoc 9F . 16469da20b8aSRobert MustacchiThis is generally used when one wants to use memory that was originally 16479da20b8aSRobert Mustacchiused for DMA to pass data back into the kernel, such as in a networking 16489da20b8aSRobert Mustacchidevice driver. 16499da20b8aSRobert MustacchiWhen this happens, a callback function will be called once the last user 16509da20b8aSRobert Mustacchiof the data block is done with it. 16519da20b8aSRobert Mustacchi.Pp 16529da20b8aSRobert MustacchiThe functions listed below often end in either 16539da20b8aSRobert Mustacchi.Dq msg 16549da20b8aSRobert Mustacchior 16559da20b8aSRobert Mustacchi.Dq b 16569da20b8aSRobert Mustacchito indicate that they will operate on an entire message and follow the 16579da20b8aSRobert Mustacchi.Fa b_cont 16589da20b8aSRobert Mustacchipointer or they will not respectively. 16599da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 16609da20b8aSRobert Mustacchi.It Xr adjmsg 9F Ta Xr allocb 9F 16619da20b8aSRobert Mustacchi.It Xr copyb 9F Ta Xr copymsg 9F 16629da20b8aSRobert Mustacchi.It Xr datamsg 9F Ta Xr desballoc 9F 16639da20b8aSRobert Mustacchi.It Xr desballoca 9F Ta Xr dupb 9F 16649da20b8aSRobert Mustacchi.It Xr dupmsg 9F Ta Xr esballoc 9F 16659da20b8aSRobert Mustacchi.It Xr esballoca 9F Ta Xr freeb 9F 16669da20b8aSRobert Mustacchi.It Xr freemsg 9F Ta Xr linkb 9F 16679da20b8aSRobert Mustacchi.It Xr mcopymsg 9F Ta Xr msgdsize 9F 16689da20b8aSRobert Mustacchi.It Xr msgpullup 9F Ta Xr msgsize 9F 16699da20b8aSRobert Mustacchi.It Xr pullupmsg 9F Ta Xr rmvb 9F 16709da20b8aSRobert Mustacchi.It Xr testb 9F Ta Xr unlinkb 9F 16719da20b8aSRobert Mustacchi.El 16729da20b8aSRobert Mustacchi.Ss Upgradable Firmware Modules 16739da20b8aSRobert MustacchiThe UFM 16749da20b8aSRobert Mustacchi.Pq Upgradable Firmware Module 16759da20b8aSRobert Mustacchisubsystem is used to grant the system observability into firmware that 16769da20b8aSRobert Mustacchiexists persistently on a device. 16779da20b8aSRobert MustacchiThese functions are intended for use by drivers that are participating in 16789da20b8aSRobert Mustacchithe kernel's UFM framework, which is discussed in 16799da20b8aSRobert Mustacchi.Xr ddi_ufm 9E . 16809da20b8aSRobert Mustacchi.Pp 16819da20b8aSRobert MustacchiThe 16829da20b8aSRobert Mustacchi.Xr ddi_ufm_init 9E 16839da20b8aSRobert Mustacchiand 16849da20b8aSRobert Mustacchi.Xr ddi_ufm_fini 9E 16859da20b8aSRobert Mustacchifunctions are used to indicate support of the subsystem to the kernel. 16869da20b8aSRobert MustacchiThe driver is required to use the 16879da20b8aSRobert Mustacchi.Xr ddi_ufm_update 9F 16889da20b8aSRobert Mustacchifunction to indicate both that it is ready to receive UFM requests and 16899da20b8aSRobert Mustacchito indicate that any data that the kernel may have previously received 16909da20b8aSRobert Mustacchihas changed. 16919da20b8aSRobert MustacchiOnce that's completed, then the other functions listed here are 16929da20b8aSRobert Mustacchigenerally used as part of implementing specific callback functions that 16939da20b8aSRobert Mustacchiare registered. 16949da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 16959da20b8aSRobert Mustacchi.It Xr ddi_ufm_fini 9F Ta Xr ddi_ufm_image_set_desc 9F 16969da20b8aSRobert Mustacchi.It Xr ddi_ufm_image_set_misc 9F Ta Xr ddi_ufm_image_set_nslots 9F 16979da20b8aSRobert Mustacchi.It Xr ddi_ufm_init 9F Ta Xr ddi_ufm_slot_set_attrs 9F 16989da20b8aSRobert Mustacchi.It Xr ddi_ufm_slot_set_imgsize 9F Ta Xr ddi_ufm_slot_set_misc 9F 16999da20b8aSRobert Mustacchi.It Xr ddi_ufm_slot_set_version 9F Ta Xr ddi_ufm_update 9F 17009da20b8aSRobert Mustacchi.El 17019da20b8aSRobert Mustacchi.Ss Firmware Loading 17029da20b8aSRobert MustacchiSome hardware devices have firmware that is not stored as part of the 17039da20b8aSRobert Mustacchidevice itself and must instead be sent to the device each time it is 17049da20b8aSRobert Mustacchipowered on. 17059da20b8aSRobert MustacchiThese routines help drivers that need to perform this read such data 17069da20b8aSRobert Mustacchifrom the file system from well-known locations in the operating system. 17079da20b8aSRobert MustacchiTo begin with, a driver should call 17089da20b8aSRobert Mustacchi.Xr firmware_open 9F 17099da20b8aSRobert Mustacchito open a handle to the firmware file. 17109da20b8aSRobert MustacchiAt that point, one can determine the size of the file with the 17119da20b8aSRobert Mustacchi.Xr firmware_get_size 9F 17129da20b8aSRobert Mustacchifunction and allocate the appropriate sized memory buffer to read it in. 17139da20b8aSRobert MustacchiCallers should always check what the size of the returned file is and 17149da20b8aSRobert Mustacchishould not just blindly pass that size off to the kernel memory 17159da20b8aSRobert Mustacchiallocator. 17169da20b8aSRobert MustacchiFor example, if a file was over 100 MiB in size, then one should not 17179da20b8aSRobert Mustacchiassume that they're going to just blindly allocate 100 MiB of kernel 17189da20b8aSRobert Mustacchimemory and should instead perform incremental reads and sends to a 17199da20b8aSRobert Mustacchidevice that are smaller in size. 17209da20b8aSRobert Mustacchi.Pp 17219da20b8aSRobert MustacchiA driver can then go through and perform arbitrary reads of the firmware 17229da20b8aSRobert Mustacchifile through the 17239da20b8aSRobert Mustacchi.Xr firmware_read 9F 17249da20b8aSRobert Mustacchiinterface until they have read everything that they need. 17259da20b8aSRobert MustacchiOnce complete, the corresponding handle needs to be released through the 17269da20b8aSRobert Mustacchi.Xr firmware_close 9F 17279da20b8aSRobert Mustacchifunction. 17289da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 17299da20b8aSRobert Mustacchi.It Xr firmware_close 9F Ta Xr firmware_get_size 9F 17309da20b8aSRobert Mustacchi.It Xr firmware_open 9F Ta Xr firmware_read 9F 17319da20b8aSRobert Mustacchi.El 17329da20b8aSRobert Mustacchi.Ss Fault Management Handling 17339da20b8aSRobert MustacchiThese functions allow device drivers to harden themselves against errors 17349da20b8aSRobert Mustacchithat might occur while interfacing with devices and tie into the broader 17359da20b8aSRobert Mustacchifault management architecture. 17369da20b8aSRobert Mustacchi.Pp 17379da20b8aSRobert MustacchiTo begin, a driver must declare which capabilities it implements during 17389da20b8aSRobert Mustacchiits 17399da20b8aSRobert Mustacchi.Xr attach 9E 17409da20b8aSRobert Mustacchifunction by calling 17419da20b8aSRobert Mustacchi.Xr ddi_fm_init 9F . 17429da20b8aSRobert MustacchiThe set of capabilities it receives back may be less than what was 17439da20b8aSRobert Mustacchirequested because the capabilities are dependent on the overall chain of 17449da20b8aSRobert Mustacchidrivers present. 17459da20b8aSRobert Mustacchi.Pp 17469da20b8aSRobert MustacchiIf 17479da20b8aSRobert Mustacchi.Dv DDI_FM_EREPORT_CAPABLE 17489da20b8aSRobert Mustacchiwas negotiated, then the driver is expected to generate error events 17499da20b8aSRobert Mustacchiwhen certain conditions occur using the 17509da20b8aSRobert Mustacchi.Xr ddi_fm_ereport_post 9F 17519da20b8aSRobert Mustacchifunction or the more specific 17529da20b8aSRobert Mustacchi.Xr pci_ereport_post 9F 17539da20b8aSRobert Mustacchifunction. 17549da20b8aSRobert MustacchiIf a caller has negotiated 17559da20b8aSRobert Mustacchi.Dv DDI_FM_ACCCHK_CAPABLE , 17569da20b8aSRobert Mustacchithen it is allowed to set up its register attributes to indicate that it 17579da20b8aSRobert Mustacchiwill check for errors on the register handle after using functions like 17589da20b8aSRobert Mustacchi.Xr ddi_get8 9F 17599da20b8aSRobert Mustacchiand 17609da20b8aSRobert Mustacchi.Xr ddi_set8 9F 17619da20b8aSRobert Mustacchiby calling 17629da20b8aSRobert Mustacchi.Xr ddi_fm_acc_err_get 9F 17639da20b8aSRobert Mustacchiand reacting accordingly. 17649da20b8aSRobert MustacchiSimilarly, if a driver has negotiated 17659da20b8aSRobert Mustacchi.Dv DDI_FM_DMACHK_CAPABLE , 17669da20b8aSRobert Mustacchithen it will use 17679da20b8aSRobert Mustacchi.Xr ddi_check_dma_handle 9F 17689da20b8aSRobert Mustacchito check the results of DMA activity and handle the results 17699da20b8aSRobert Mustacchiappropriately. 17709da20b8aSRobert MustacchiSimilar to register accesses, the DMA attributes must be updated to set 17719da20b8aSRobert Mustacchithat error handling is anticipated on this handle. 17729da20b8aSRobert MustacchiThe 17739da20b8aSRobert Mustacchi.Xr ddi_fm_init 9F 17749da20b8aSRobert Mustacchimanual page has an overview of the other types of flags that can be 17759da20b8aSRobert Mustacchinegotiated and how they are used. 17769da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 17779da20b8aSRobert Mustacchi.It Xr ddi_check_acc_handle 9F Ta Xr ddi_check_dma_handle 9F 17789da20b8aSRobert Mustacchi.It Xr ddi_dev_report_fault 9F Ta Xr ddi_fm_acc_err_clear 9F 17799da20b8aSRobert Mustacchi.It Xr ddi_fm_acc_err_get 9F Ta Xr ddi_fm_capable 9F 17809da20b8aSRobert Mustacchi.It Xr ddi_fm_dma_err_clear 9F Ta Xr ddi_fm_dma_err_get 9F 17819da20b8aSRobert Mustacchi.It Xr ddi_fm_ereport_post 9F Ta Xr ddi_fm_fini 9F 17829da20b8aSRobert Mustacchi.It Xr ddi_fm_handler_register 9F Ta Xr ddi_fm_handler_unregister 9F 17839da20b8aSRobert Mustacchi.It Xr ddi_fm_init 9F Ta Xr ddi_fm_service_impact 9F 17849da20b8aSRobert Mustacchi.It Xr pci_ereport_post 9F Ta Xr pci_ereport_setup 9F 17859da20b8aSRobert Mustacchi.It Xr pci_ereport_teardown 9F Ta 17869da20b8aSRobert Mustacchi.El 17879da20b8aSRobert Mustacchi.Ss SCSI and SAS Device Driver Functions 17889da20b8aSRobert MustacchiThese functions are for use by SCSI and SAS device drivers that leverage 17899da20b8aSRobert Mustacchithe kernel's frameworks. 17909da20b8aSRobert MustacchiOther device drivers should not use these. 17919da20b8aSRobert MustacchiFor more background on these, some of the general concepts are discussed 17929da20b8aSRobert Mustacchiin 17939da20b8aSRobert Mustacchi.Xr iport 9 , 17949da20b8aSRobert Mustacchi.Xr phymap 9 , 17959da20b8aSRobert Mustacchiand 17969da20b8aSRobert Mustacchi.Xr tgtmap 9 . 17979da20b8aSRobert Mustacchi.Pp 17989da20b8aSRobert MustacchiDevice drivers register initially with the kernel by using the 17999da20b8aSRobert Mustacchi.Xr scsi_ha_init 9F 18009da20b8aSRobert Mustacchifunction and then, in their attach routine, register specific instances, 18019da20b8aSRobert Mustacchiusing functions like 18029da20b8aSRobert Mustacchi.Xr scsi_hba_iport_register 9F 18039da20b8aSRobert Mustacchior instead 18049da20b8aSRobert Mustacchi.Xr scsi_hba_tran_alloc 9F 18059da20b8aSRobert Mustacchiand 18069da20b8aSRobert Mustacchi.Xr scsi_hba_attach_setup 9F . 18079da20b8aSRobert MustacchiNew drivers are encouraged to use the target map and iports framework to 18089da20b8aSRobert Mustacchisimplify the device driver writing process. 18099da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 18109da20b8aSRobert Mustacchi.It Xr makecom_g0_s 9F Ta Xr makecom_g0 9F 18119da20b8aSRobert Mustacchi.It Xr makecom_g1 9F Ta Xr makecom_g5 9F 18129da20b8aSRobert Mustacchi.It Xr makecom 9F Ta Xr sas_phymap_create 9F 18139da20b8aSRobert Mustacchi.It Xr sas_phymap_destroy 9F Ta Xr sas_phymap_lookup_ua 9F 18149da20b8aSRobert Mustacchi.It Xr sas_phymap_lookup_uapriv 9F Ta Xr sas_phymap_phy_add 9F 18159da20b8aSRobert Mustacchi.It Xr sas_phymap_phy_rem 9F Ta Xr sas_phymap_phy2ua 9F 18169da20b8aSRobert Mustacchi.It Xr sas_phymap_phys_free 9F Ta Xr sas_phymap_phys_next 9F 18179da20b8aSRobert Mustacchi.It Xr sas_phymap_ua_free 9F Ta Xr sas_phymap_ua2phys 9F 18189da20b8aSRobert Mustacchi.It Xr sas_phymap_uahasphys 9F Ta Xr scsi_abort 9F 18199da20b8aSRobert Mustacchi.It Xr scsi_address_device 9F Ta Xr scsi_alloc_consistent_buf 9F 18209da20b8aSRobert Mustacchi.It Xr scsi_cname 9F Ta Xr scsi_destroy_pkt 9F 18219da20b8aSRobert Mustacchi.It Xr scsi_device_hba_private_get 9F Ta Xr scsi_device_hba_private_set 9F 18229da20b8aSRobert Mustacchi.It Xr scsi_device_unit_address 9F Ta Xr scsi_dmafree 9F 18239da20b8aSRobert Mustacchi.It Xr scsi_dmaget 9F Ta Xr scsi_dname 9F 18249da20b8aSRobert Mustacchi.It Xr scsi_errmsg 9F Ta Xr scsi_ext_sense_fields 9F 18259da20b8aSRobert Mustacchi.It Xr scsi_find_sense_descr 9F Ta Xr scsi_free_consistent_buf 9F 18269da20b8aSRobert Mustacchi.It Xr scsi_free_wwnstr 9F Ta Xr scsi_get_device_type_scsi_options 9F 18279da20b8aSRobert Mustacchi.It Xr scsi_get_device_type_string 9F Ta Xr scsi_hba_attach_setup 9F 18289da20b8aSRobert Mustacchi.It Xr scsi_hba_detach 9F Ta Xr scsi_hba_fini 9F 18299da20b8aSRobert Mustacchi.It Xr scsi_hba_init 9F Ta Xr scsi_hba_iport_exist 9F 18309da20b8aSRobert Mustacchi.It Xr scsi_hba_iport_find 9F Ta Xr scsi_hba_iport_register 9F 18319da20b8aSRobert Mustacchi.It Xr scsi_hba_iport_unit_address 9F Ta Xr scsi_hba_iportmap_create 9F 18329da20b8aSRobert Mustacchi.It Xr scsi_hba_iportmap_destroy 9F Ta Xr scsi_hba_iportmap_iport_add 9F 18339da20b8aSRobert Mustacchi.It Xr scsi_hba_iportmap_iport_remove 9F Ta Xr scsi_hba_lookup_capstr 9F 18349da20b8aSRobert Mustacchi.It Xr scsi_hba_pkt_alloc 9F Ta Xr scsi_hba_pkt_comp 9F 18359da20b8aSRobert Mustacchi.It Xr scsi_hba_pkt_free 9F Ta Xr scsi_hba_probe 9F 18369da20b8aSRobert Mustacchi.It Xr scsi_hba_tgtmap_create 9F Ta Xr scsi_hba_tgtmap_destroy 9F 18379da20b8aSRobert Mustacchi.It Xr scsi_hba_tgtmap_scan_luns 9F Ta Xr scsi_hba_tgtmap_set_add 9F 18389da20b8aSRobert Mustacchi.It Xr scsi_hba_tgtmap_set_begin 9F Ta Xr scsi_hba_tgtmap_set_end 9F 18399da20b8aSRobert Mustacchi.It Xr scsi_hba_tgtmap_set_flush 9F Ta Xr scsi_hba_tgtmap_tgt_add 9F 18409da20b8aSRobert Mustacchi.It Xr scsi_hba_tgtmap_tgt_remove 9F Ta Xr scsi_hba_tran_alloc 9F 18419da20b8aSRobert Mustacchi.It Xr scsi_hba_tran_free 9F Ta Xr scsi_ifgetcap 9F 18429da20b8aSRobert Mustacchi.It Xr scsi_ifsetcap 9F Ta Xr scsi_init_pkt 9F 18439da20b8aSRobert Mustacchi.It Xr scsi_log 9F Ta Xr scsi_mname 9F 18449da20b8aSRobert Mustacchi.It Xr scsi_pktalloc 9F Ta Xr scsi_pktfree 9F 18459da20b8aSRobert Mustacchi.It Xr scsi_poll 9F Ta Xr scsi_probe 9F 18469da20b8aSRobert Mustacchi.It Xr scsi_resalloc 9F Ta Xr scsi_reset_notify 9F 18479da20b8aSRobert Mustacchi.It Xr scsi_reset 9F Ta Xr scsi_resfree 9F 18489da20b8aSRobert Mustacchi.It Xr scsi_rname 9F Ta Xr scsi_sense_asc 9F 18499da20b8aSRobert Mustacchi.It Xr scsi_sense_ascq 9F Ta Xr scsi_sense_cmdspecific_uint64 9F 18509da20b8aSRobert Mustacchi.It Xr scsi_sense_info_uint64 9F Ta Xr scsi_sense_key 9F 18519da20b8aSRobert Mustacchi.It Xr scsi_setup_cdb 9F Ta Xr scsi_slave 9F 18529da20b8aSRobert Mustacchi.It Xr scsi_sname 9F Ta Xr scsi_sync_pkt 9F 18539da20b8aSRobert Mustacchi.It Xr scsi_transport 9F Ta Xr scsi_unprobe 9F 18549da20b8aSRobert Mustacchi.It Xr scsi_unslave 9F Ta Xr scsi_validate_sense 9F 18559da20b8aSRobert Mustacchi.It Xr scsi_vu_errmsg 9F Ta Xr scsi_wwn_to_wwnstr 9F 18569da20b8aSRobert Mustacchiscsi_wwnstr_to_wwn 18579da20b8aSRobert Mustacchi.El 18589da20b8aSRobert Mustacchi.Ss Block Device Buffer Handling 18599da20b8aSRobert MustacchiBlock devices operate with a data structure called the 18609da20b8aSRobert Mustacchi.Vt struct buf 18619da20b8aSRobert Mustacchiwhich is described in 18629da20b8aSRobert Mustacchi.Xr buf 9S . 18639da20b8aSRobert MustacchiThis structure is used to represent a given block request and is used 18649da20b8aSRobert Mustacchiheavily in block devices, the SCSI/SAS framework, and the blkdev 18659da20b8aSRobert Mustacchiframework. 18669da20b8aSRobert MustacchiThe functions described here are used to manipulate these structures in 18679da20b8aSRobert Mustacchivarious ways such as copying them around, indicating error conditions, 18689da20b8aSRobert Mustacchior indicating when the I/O operation is done. 18699da20b8aSRobert MustacchiBy default, this memory is not mapped into the kernel's address space so 18709da20b8aSRobert Mustacchiseveral functions such as 18719da20b8aSRobert Mustacchi.Xr bp_mapin 9F 18729da20b8aSRobert Mustacchiare present to allow for that to happen when required. 18739da20b8aSRobert Mustacchi.Pp 18749da20b8aSRobert MustacchiTo initially obtain a 18759da20b8aSRobert Mustacchi.Vt struct buf , 18769da20b8aSRobert Mustacchidrivers should begin by calling 1877*496cffd8SPeter Tribble.Xr getrbuf 9F 18789da20b8aSRobert Mustacchiat which point, the caller can fill in the structure. 18799da20b8aSRobert MustacchiOnce that's done, the 18809da20b8aSRobert Mustacchi.Xr physio 9F 18819da20b8aSRobert Mustacchifunction can be used to actually perform the I/O and wait until it's 18829da20b8aSRobert Mustacchicomplete. 18839da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 18849da20b8aSRobert Mustacchi.It Xr bioclone 9F Ta Xr biodone 9F 18859da20b8aSRobert Mustacchi.It Xr bioerror 9F Ta Xr biofini 9F 18869da20b8aSRobert Mustacchi.It Xr bioinit 9F Ta Xr biomodified 9F 18879da20b8aSRobert Mustacchi.It Xr bioreset 9F Ta Xr biosize 9F 18889da20b8aSRobert Mustacchi.It Xr biowait 9F Ta Xr bp_mapin 9F 18899da20b8aSRobert Mustacchi.It Xr bp_mapout 9F Ta Xr clrbuf 9F 18909da20b8aSRobert Mustacchi.It Xr disksort 9F Ta Xr freerbuf 9F 18919da20b8aSRobert Mustacchi.It Xr geterror 9F Ta Xr getrbuf 9F 18929da20b8aSRobert Mustacchi.It Xr minphys 9F Ta Xr physio 9F 18939da20b8aSRobert Mustacchi.El 18949da20b8aSRobert Mustacchi.Ss Networking Device Driver Functions 18959da20b8aSRobert MustacchiThese functions are for networking device drivers that implant the MAC, 18969da20b8aSRobert MustacchiGLDv3 interfaces. 18979da20b8aSRobert MustacchiThe full framework and how to use it is described in 18989da20b8aSRobert Mustacchi.Xr mac 9E . 18999da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 19009da20b8aSRobert Mustacchi.It Xr mac_alloc 9F Ta Xr mac_fini_ops 9F 19019da20b8aSRobert Mustacchi.It Xr mac_free 9F Ta Xr mac_hcksum_get 9F 19029da20b8aSRobert Mustacchi.It Xr mac_hcksum_set 9F Ta Xr mac_init_ops 9F 19039da20b8aSRobert Mustacchi.It Xr mac_link_update 9F Ta Xr mac_lso_get 9F 19049da20b8aSRobert Mustacchi.It Xr mac_maxsdu_update 9F Ta Xr mac_prop_info_set_default_fec 9F 19059da20b8aSRobert Mustacchi.It Xr mac_prop_info_set_default_link_flowctrl 9F Ta Xr mac_prop_info_set_default_str 9F 19069da20b8aSRobert Mustacchi.It Xr mac_prop_info_set_default_uint32 9F Ta Xr mac_prop_info_set_default_uint64 9F 19079da20b8aSRobert Mustacchi.It Xr mac_prop_info_set_default_uint8 9F Ta Xr mac_prop_info_set_perm 9F 19089da20b8aSRobert Mustacchi.It Xr mac_prop_info_set_range_uint32 9F Ta Xr mac_prop_info 9F 1909*496cffd8SPeter Tribble.It Xr mac_register 9F Ta Xr mac_rx_ring 9F 19109da20b8aSRobert Mustacchi.It Xr mac_rx 9F Ta Xr mac_transceiver_info_set_present 9F 19119da20b8aSRobert Mustacchi.It Xr mac_transceiver_info_set_usable 9F Ta Xr mac_transceiver_info 9F 19129da20b8aSRobert Mustacchi.It Xr mac_tx_ring_update 9F Ta Xr mac_tx_update 9F 19139da20b8aSRobert Mustacchi.It Xr mac_unregister 9F Ta 19149da20b8aSRobert Mustacchi.El 19159da20b8aSRobert Mustacchi.Ss USB Device Driver Functions 19169da20b8aSRobert MustacchiThese functions are designed for USB device drivers. 19179da20b8aSRobert MustacchiTo first initialize with the kernel, a device driver must call 19189da20b8aSRobert Mustacchi.Xr usb_client_attach 9F 19199da20b8aSRobert Mustacchiand then 19209da20b8aSRobert Mustacchi.Xr usb_get_dev_data 9F . 19219da20b8aSRobert MustacchiThe latter call is required to get access to the USB-level 19229da20b8aSRobert Mustacchidescriptors about the device which describe what kinds of USB endpoints 19239da20b8aSRobert Mustacchi.Pq control, bulk, interrupt, or isochronous 19249da20b8aSRobert Mustacchiexist on the device as well as how many different interfaces and 19259da20b8aSRobert Mustacchiconfigurations are present. 19269da20b8aSRobert Mustacchi.Pp 19279da20b8aSRobert MustacchiOnce a given configuration, sometimes the default, is selected, then the 19289da20b8aSRobert Mustacchidriver can proceed to opening up what the USB architecture calls a pipe, 19299da20b8aSRobert Mustacchiwhich provides a way to send requests to a specific USB endpoint. 19309da20b8aSRobert MustacchiFirst, specific endpoints can be looked up using the 19319da20b8aSRobert Mustacchi.Xr usb_lookup_ep_data 9F 19329da20b8aSRobert Mustacchifunction which gets information from the parsed descriptors and then 19339da20b8aSRobert Mustacchithat gets filled into an extended descriptor with 19349da20b8aSRobert Mustacchi.Xr usb_ep_xdescr_fill 9F . 19359da20b8aSRobert MustacchiWith that in hand, a pipe can be opened with 19369da20b8aSRobert Mustacchi.Xr usb_pipe_xopen 9F . 19379da20b8aSRobert Mustacchi.Pp 19389da20b8aSRobert MustacchiOnce a pipe has been opened, which most often happens in a driver's 19399da20b8aSRobert Mustacchi.Xr attach 9E 19409da20b8aSRobert Mustacchientry point, then requests can be allocated and submitted. 19419da20b8aSRobert MustacchiThere is a different allocation for each type of request 19429da20b8aSRobert Mustacchi.Po 19439da20b8aSRobert Mustacchie.g. 19449da20b8aSRobert Mustacchi.Xr usb_alloc_bulk_req 9F 19459da20b8aSRobert Mustacchi.Pc 19469da20b8aSRobert Mustacchiand a different submission function for each type as well. 19479da20b8aSRobert MustacchiEach request structure has a corresponding page in section 9S that 19489da20b8aSRobert Mustacchidescribes the structure, its members, and how to work with it. 19499da20b8aSRobert Mustacchi.Pp 19509da20b8aSRobert MustacchiOne other major concern for USB devices, which isn't as common with 19519da20b8aSRobert Mustacchiother types of devices, is that they can be yanked out and reinserted 19529da20b8aSRobert Mustacchiat any time. 19539da20b8aSRobert MustacchiTo help determine when this happens, the kernel offers the 19549da20b8aSRobert Mustacchi.Xr usb_register_event_cbs 9F 19559da20b8aSRobert Mustacchifunction which allows a driver to register for callbacks when a device 19569da20b8aSRobert Mustacchiis disconnected, reconnected, or around checkpoint suspend/resume 19579da20b8aSRobert Mustacchibehavior. 19589da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 19599da20b8aSRobert Mustacchi.It Xr usb_alloc_bulk_req 9F Ta Xr usb_alloc_ctrl_req 9F 19609da20b8aSRobert Mustacchi.It Xr usb_alloc_intr_req 9F Ta Xr usb_alloc_isoc_req 9F 19619da20b8aSRobert Mustacchi.It Xr usb_alloc_request 9F Ta Xr usb_client_attach 9F 19629da20b8aSRobert Mustacchi.It Xr usb_client_detach 9F Ta Xr usb_clr_feature 9F 19639da20b8aSRobert Mustacchi.It Xr usb_create_pm_components 9F Ta Xr usb_ep_xdescr_fill 9F 19649da20b8aSRobert Mustacchi.It Xr usb_free_bulk_req 9F Ta Xr usb_free_ctrl_req 9F 19659da20b8aSRobert Mustacchi.It Xr usb_free_descr_tree 9F Ta Xr usb_free_dev_data 9F 19669da20b8aSRobert Mustacchi.It Xr usb_free_intr_req 9F Ta Xr usb_free_isoc_req 9F 19679da20b8aSRobert Mustacchi.It Xr usb_get_addr 9F Ta Xr usb_get_alt_if 9F 19689da20b8aSRobert Mustacchi.It Xr usb_get_cfg 9F Ta Xr usb_get_current_frame_number 9F 19699da20b8aSRobert Mustacchi.It Xr usb_get_dev_data 9F Ta Xr usb_get_if_number 9F 19709da20b8aSRobert Mustacchi.It Xr usb_get_max_pkts_per_isoc_request 9F Ta Xr usb_get_status 9F 19719da20b8aSRobert Mustacchi.It Xr usb_get_string_descr 9F Ta Xr usb_handle_remote_wakeup 9F 19729da20b8aSRobert Mustacchi.It Xr usb_lookup_ep_data 9F Ta Xr usb_owns_device 9F 19739da20b8aSRobert Mustacchi.It Xr usb_parse_data 9F Ta Xr usb_pipe_bulk_xfer 9F 19749da20b8aSRobert Mustacchi.It Xr usb_pipe_close 9F Ta Xr usb_pipe_ctrl_xfer_wait 9F 19759da20b8aSRobert Mustacchi.It Xr usb_pipe_ctrl_xfer 9F Ta Xr usb_pipe_drain_reqs 9F 19769da20b8aSRobert Mustacchi.It Xr usb_pipe_get_max_bulk_transfer_size 9F Ta Xr usb_pipe_get_private 9F 19779da20b8aSRobert Mustacchi.It Xr usb_pipe_get_state 9F Ta Xr usb_pipe_intr_xfer 9F 19789da20b8aSRobert Mustacchi.It Xr usb_pipe_isoc_xfer 9F Ta Xr usb_pipe_open 9F 19799da20b8aSRobert Mustacchi.It Xr usb_pipe_reset 9F Ta Xr usb_pipe_set_private 9F 19809da20b8aSRobert Mustacchi.It Xr usb_pipe_stop_intr_polling 9F Ta Xr usb_pipe_stop_isoc_polling 9F 19819da20b8aSRobert Mustacchi.It Xr usb_pipe_xopen 9F Ta Xr usb_print_descr_tree 9F 19829da20b8aSRobert Mustacchi.It Xr usb_register_hotplug_cbs 9F Ta Xr usb_reset_device 9F 19839da20b8aSRobert Mustacchi.It Xr usb_set_alt_if 9F Ta Xr usb_set_cfg 9F 19849da20b8aSRobert Mustacchi.It Xr usb_unregister_hotplug_cbs 9F Ta 19859da20b8aSRobert Mustacchi.El 19869da20b8aSRobert Mustacchi.Ss PCI Device Driver Functions 19879da20b8aSRobert MustacchiThese functions are specific for PCI and PCI Express based device 19889da20b8aSRobert Mustacchidrivers and are intended to be used to get access to PCI configuration 19899da20b8aSRobert Mustacchispace. 19909da20b8aSRobert MustacchiFor normal PCI base address registers 19919da20b8aSRobert Mustacchi.Pq BARs 19929da20b8aSRobert Mustacchiinstead see 19939da20b8aSRobert Mustacchi.Sx Register Setup and Access . 19949da20b8aSRobert Mustacchi.Pp 19959da20b8aSRobert MustacchiTo access PCI configuration space, a device driver should first call 19969da20b8aSRobert Mustacchi.Xr pci_config_setup 9F . 19979da20b8aSRobert MustacchiGenerally, drivers will call this in their 19989da20b8aSRobert Mustacchi.Xr attach 9E 19999da20b8aSRobert Mustacchientry point and then tear down the configuration space access with the 20009da20b8aSRobert Mustacchi.Xr pci_config_teardown 9F 20019da20b8aSRobert Mustacchientry point in 20029da20b8aSRobert Mustacchi.Xr detach 9E . 20039da20b8aSRobert MustacchiAfter setting up access to configuration space, the returned handle can 20049da20b8aSRobert Mustacchibe used in all of the various configuration space routines to get and 20059da20b8aSRobert Mustacchiset specific sized values in configuration space. 20069da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 20079da20b8aSRobert Mustacchi.It Xr pci_config_get8 9F Ta Xr pci_config_get16 9F 20089da20b8aSRobert Mustacchi.It Xr pci_config_get32 9F Ta Xr pci_config_get64 9F 20099da20b8aSRobert Mustacchi.It Xr pci_config_put8 9F Ta Xr pci_config_put16 9F 20109da20b8aSRobert Mustacchi.It Xr pci_config_put32 9F Ta Xr pci_config_put64 9F 20119da20b8aSRobert Mustacchi.It Xr pci_config_setup 9F Ta Xr pci_config_teardown 9F 20129da20b8aSRobert Mustacchi.It Xr pci_report_pmcap 9F Ta Xr pci_restore_config_regs 9F 20139da20b8aSRobert Mustacchi.It Xr pci_save_config_regs 9F Ta 20149da20b8aSRobert Mustacchi.El 20159da20b8aSRobert Mustacchi.Ss USB Host Controller Interface Functions 20169da20b8aSRobert MustacchiThese routines are used for device drivers which implement the USB 20179da20b8aSRobert Mustacchihost controller interfaces described in 20189da20b8aSRobert Mustacchi.Xr usba_hcdi 9E . 20199da20b8aSRobert MustacchiOther types of devices drivers and modules should not call these 20209da20b8aSRobert Mustacchifunctions. 20219da20b8aSRobert MustacchiIn particular, if one is writing a device driver for a USB device, these 20229da20b8aSRobert Mustacchiare not the routines you're looking for and you want to see 20239da20b8aSRobert Mustacchi.Sx USB Device Driver Functions . 20249da20b8aSRobert MustacchiThese are what the 20259da20b8aSRobert Mustacchi.Xr ehci 4D 20269da20b8aSRobert Mustacchior 20279da20b8aSRobert Mustacchi.Xr xhci 4D 20289da20b8aSRobert Mustacchidrivers use to provide services that USB drivers use via the kernel USB 20299da20b8aSRobert Mustacchiarchitecture. 20309da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 20319da20b8aSRobert Mustacchi.It Xr usba_alloc_hcdi_ops 9F Ta Xr usba_free_hcdi_ops 9F 20329da20b8aSRobert Mustacchi.It Xr usba_hcdi_cb 9F Ta Xr usba_hcdi_dup_intr_req 9F 20339da20b8aSRobert Mustacchi.It Xr usba_hcdi_dup_isoc_req 9F Ta Xr usba_hcdi_get_device_private 9F 20349da20b8aSRobert Mustacchi.It Xr usba_hcdi_register 9F Ta Xr usba_hcdi_unregister 9F 20359da20b8aSRobert Mustacchi.It Xr usba_hubdi_bind_root_hub 9F Ta Xr usba_hubdi_cb_ops 9F 20369da20b8aSRobert Mustacchi.It Xr usba_hubdi_close 9F Ta Xr usba_hubdi_dev_ops 9F 20379da20b8aSRobert Mustacchi.It Xr usba_hubdi_ioctl 9F Ta Xr usba_hubdi_open 9F 20389da20b8aSRobert Mustacchi.It Xr usba_hubdi_root_hub_power 9F Ta Xr usba_hubdi_unbind_root_hub 9F 20399da20b8aSRobert Mustacchi.El 20409da20b8aSRobert Mustacchi.Ss Functions for PCMCIA Drivers 20419da20b8aSRobert MustacchiThese functions exist for older PCMCIA device drivers. 20429da20b8aSRobert MustacchiThese should not otherwise be used by the system. 20439da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 20449da20b8aSRobert Mustacchi.It Xr csx_AccessConfigurationRegister 9F Ta Xr csx_ConvertSize 9F 20459da20b8aSRobert Mustacchi.It Xr csx_ConvertSpeed 9F Ta Xr csx_CS_DDI_Info 9F 20469da20b8aSRobert Mustacchi.It Xr csx_DeregisterClient 9F Ta Xr csx_DupHandle 9F 20479da20b8aSRobert Mustacchi.It Xr csx_Error2Text 9F Ta Xr csx_Event2Text 9F 20489da20b8aSRobert Mustacchi.It Xr csx_FreeHandle 9F Ta Xr csx_Get16 9F 20499da20b8aSRobert Mustacchi.It Xr csx_Get32 9F Ta Xr csx_Get64 9F 20509da20b8aSRobert Mustacchi.It Xr csx_Get8 9F Ta Xr csx_GetEventMask 9F 20519da20b8aSRobert Mustacchi.It Xr csx_GetFirstClient 9F Ta Xr csx_GetFirstTuple 9F 20529da20b8aSRobert Mustacchi.It Xr csx_GetHandleOffset 9F Ta Xr csx_GetMappedAddr 9F 20539da20b8aSRobert Mustacchi.It Xr csx_GetNextClient 9F Ta Xr csx_GetNextTuple 9F 20549da20b8aSRobert Mustacchi.It Xr csx_GetStatus 9F Ta Xr csx_GetTupleData 9F 20559da20b8aSRobert Mustacchi.It Xr csx_MakeDeviceNode 9F Ta Xr csx_MapLogSocket 9F 20569da20b8aSRobert Mustacchi.It Xr csx_MapMemPage 9F Ta Xr csx_ModifyConfiguration 9F 20579da20b8aSRobert Mustacchi.It Xr csx_ModifyWindow 9F Ta Xr csx_Parse_CISTPL_BATTERY 9F 20589da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_BYTEORDER 9F Ta Xr csx_Parse_CISTPL_CFTABLE_ENTRY 9F 20599da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_CONFIG 9F Ta Xr csx_Parse_CISTPL_DATE 9F 20609da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_DEVICE_A 9F Ta Xr csx_Parse_CISTPL_DEVICE_OA 9F 20619da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_DEVICE_OC 9F Ta Xr csx_Parse_CISTPL_DEVICE 9F 20629da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_DEVICEGEO_A 9F Ta Xr csx_Parse_CISTPL_DEVICEGEO 9F 20639da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_FORMAT 9F Ta Xr csx_Parse_CISTPL_FUNCE 9F 20649da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_FUNCID 9F Ta Xr csx_Parse_CISTPL_GEOMETRY 9F 20659da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_JEDEC_A 9F Ta Xr csx_Parse_CISTPL_JEDEC_C 9F 20669da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_LINKTARGET 9F Ta Xr csx_Parse_CISTPL_LONGLINK_A 9F 20679da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_LONGLINK_C 9F Ta Xr csx_Parse_CISTPL_LONGLINK_MFC 9F 20689da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_MANFID 9F Ta Xr csx_Parse_CISTPL_ORG 9F 20699da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_SPCL 9F Ta Xr csx_Parse_CISTPL_SWIL 9F 20709da20b8aSRobert Mustacchi.It Xr csx_Parse_CISTPL_VERS_1 9F Ta Xr csx_Parse_CISTPL_VERS_2 9F 20719da20b8aSRobert Mustacchi.It Xr csx_ParseTuple 9F Ta Xr csx_Put16 9F 20729da20b8aSRobert Mustacchi.It Xr csx_Put32 9F Ta Xr csx_Put64 9F 20739da20b8aSRobert Mustacchi.It Xr csx_Put8 9F Ta Xr csx_RegisterClient 9F 20749da20b8aSRobert Mustacchi.It Xr csx_ReleaseConfiguration 9F Ta Xr csx_ReleaseIO 9F 20759da20b8aSRobert Mustacchi.It Xr csx_ReleaseIRQ 9F Ta Xr csx_ReleaseSocketMask 9F 20769da20b8aSRobert Mustacchi.It Xr csx_ReleaseWindow 9F Ta Xr csx_RemoveDeviceNode 9F 20779da20b8aSRobert Mustacchi.It Xr csx_RepGet16 9F Ta Xr csx_RepGet32 9F 20789da20b8aSRobert Mustacchi.It Xr csx_RepGet64 9F Ta Xr csx_RepGet8 9F 20799da20b8aSRobert Mustacchi.It Xr csx_RepPut16 9F Ta Xr csx_RepPut32 9F 20809da20b8aSRobert Mustacchi.It Xr csx_RepPut64 9F Ta Xr csx_RepPut8 9F 20819da20b8aSRobert Mustacchi.It Xr csx_RequestConfiguration 9F Ta Xr csx_RequestIO 9F 20829da20b8aSRobert Mustacchi.It Xr csx_RequestIRQ 9F Ta Xr csx_RequestSocketMask 9F 20839da20b8aSRobert Mustacchi.It Xr csx_RequestWindow 9F Ta Xr csx_ResetFunction 9F 20849da20b8aSRobert Mustacchi.It Xr csx_SetEventMask 9F Ta Xr csx_SetHandleOffset 9F 20859da20b8aSRobert Mustacchi.It Xr csx_ValidateCIS 9F Ta 20869da20b8aSRobert Mustacchi.El 20879da20b8aSRobert Mustacchi.Ss STREAMS related functions 20889da20b8aSRobert MustacchiThese functions are meant to be used when interacting with STREAMS 20899da20b8aSRobert Mustacchidevices or when implementing one. 20909da20b8aSRobert MustacchiWhen a STREAMS driver is opened, it receives messages on a queue which 20919da20b8aSRobert Mustacchiare then processed and can be sent back. 20929da20b8aSRobert MustacchiAs different queues are often linked together, the most common thing is 20939da20b8aSRobert Mustacchito process a message and then pass the message onto the next queue using 20949da20b8aSRobert Mustacchithe 20959da20b8aSRobert Mustacchi.Xr putnext 9F 20969da20b8aSRobert Mustacchifunction. 20979da20b8aSRobert Mustacchi.Pp 20989da20b8aSRobert MustacchiSTREAMS messages are passed around using message blocks, which use the 20999da20b8aSRobert Mustacchi.Vt mblk_t 21009da20b8aSRobert Mustacchitype. 21019da20b8aSRobert MustacchiSee 21029da20b8aSRobert Mustacchi.Sx Message Block Functions 21039da20b8aSRobert Mustacchifor more about how the data structure and functions that manipulate 21049da20b8aSRobert Mustacchimessage blocks. 21059da20b8aSRobert Mustacchi.Pp 21069da20b8aSRobert MustacchiThese functions should generally not be used when implementing a 21079da20b8aSRobert Mustacchinetworking device driver today. 21089da20b8aSRobert MustacchiSee 21099da20b8aSRobert Mustacchi.Xr mac 9E 21109da20b8aSRobert Mustacchiinstead. 21119da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 21129da20b8aSRobert Mustacchi.It Xr backq 9F Ta Xr bcanput 9F 21139da20b8aSRobert Mustacchi.It Xr bcanputnext 9F Ta Xr canput 9F 21149da20b8aSRobert Mustacchi.It Xr canputnext 9F Ta Xr enableok 9F 21159da20b8aSRobert Mustacchi.It Xr flushband 9F Ta Xr flushq 9F 21169da20b8aSRobert Mustacchi.It Xr freezestr 9F Ta Xr getq 9F 21179da20b8aSRobert Mustacchi.It Xr insq 9F Ta Xr merror 9F 21189da20b8aSRobert Mustacchi.It Xr mexchange 9F Ta Xr noenable 9F 21199da20b8aSRobert Mustacchi.It Xr put 9F Ta Xr putbq 9F 21209da20b8aSRobert Mustacchi.It Xr putctl 9F Ta Xr putctl1 9F 21219da20b8aSRobert Mustacchi.It Xr putnext 9F Ta Xr putnextctl 9F 21229da20b8aSRobert Mustacchi.It Xr putnextctl1 9F Ta Xr putq 9F 21239da20b8aSRobert Mustacchi.It Xr mt-streams 9F Ta Xr qassociate 9F 21249da20b8aSRobert Mustacchi.It Xr qenable 9F Ta Xr qprocsoff 9F 21259da20b8aSRobert Mustacchi.It Xr qprocson 9F Ta Xr qreply 9F 21269da20b8aSRobert Mustacchi.It Xr qsize 9F Ta Xr qwait_sig 9F 21279da20b8aSRobert Mustacchi.It Xr qwait 9F Ta Xr qwriter 9F 21289da20b8aSRobert Mustacchi.It Xr OTHERQ 9F Ta Xr RD 9F 21299da20b8aSRobert Mustacchi.It Xr rmvq 9F Ta Xr SAMESTR 9F 21309da20b8aSRobert Mustacchi.It Xr unfreezestr 9F Ta Xr WR 9F 21319da20b8aSRobert Mustacchi.El 21329da20b8aSRobert Mustacchi.Ss STREAMS ioctls 21339da20b8aSRobert MustacchiThe following functions are used when a STREAMS-based device driver is 21349da20b8aSRobert Mustacchiprocessing its 21359da20b8aSRobert Mustacchi.Xr ioctl 9E 21369da20b8aSRobert Mustacchientry point. 21379da20b8aSRobert MustacchiUnlike character and block devices, STREAMS ioctls are passed around in 21389da20b8aSRobert Mustacchimessage blocks and copying data in and out of userland as STREAMS 21399da20b8aSRobert Mustacchiioctls are generally always processed in 21409da20b8aSRobert Mustacchi.Sy kernel 21419da20b8aSRobert Mustacchicontext. 21429da20b8aSRobert MustacchiThis means that the normal functions like 21439da20b8aSRobert Mustacchi.Xr ddi_copyin 9F 21449da20b8aSRobert Mustacchiand 21459da20b8aSRobert Mustacchi.Xr ddi_copyout 9F 21469da20b8aSRobert Mustacchicannot be used. 21479da20b8aSRobert MustacchiInstead, when a message block has a type of 21489da20b8aSRobert Mustacchi.Dv M_IOCTL , 21499da20b8aSRobert Mustacchithen these routines can often be used to convert the structure into one 21509da20b8aSRobert Mustacchithat asks for data to be copied in, copied out, or to finally 21519da20b8aSRobert Mustacchiacknowledge the ioctl as successful or to terminate the processing in 21529da20b8aSRobert Mustacchierror. 21539da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 21549da20b8aSRobert Mustacchi.It Xr mcopyin 9F Ta Xr mcopyout 9F 21559da20b8aSRobert Mustacchi.It Xr mioc2ack 9F Ta Xr miocack 9F 21569da20b8aSRobert Mustacchi.It Xr miocnak 9F Ta Xr miocpullup 9F 21579da20b8aSRobert Mustacchi.It Xr mkiocb 9F Ta 21589da20b8aSRobert Mustacchi.El 21599da20b8aSRobert Mustacchi.Ss chpoll(9E) Related Functions 21609da20b8aSRobert MustacchiThese functions are present in service of the 21619da20b8aSRobert Mustacchi.Xr chpoll 9E 21629da20b8aSRobert Mustacchiinterface which is used to support the traditional 21639da20b8aSRobert Mustacchi.Xr poll 2 , 21649da20b8aSRobert Mustacchiand 21659da20b8aSRobert Mustacchi.Xr select 3C 21669da20b8aSRobert Mustacchiinterfaces as well as event ports through the 21679da20b8aSRobert Mustacchi.Xr port_get 3C 21689da20b8aSRobert Mustacchiinterface. 21699da20b8aSRobert MustacchiSee 21709da20b8aSRobert Mustacchi.Xr chpoll 9E 21719da20b8aSRobert Mustacchifor the specific cases this should be called. 21729da20b8aSRobert MustacchiIf a device driver does not implement the 21739da20b8aSRobert Mustacchi.Xr chpoll 9E 21749da20b8aSRobert Mustacchicharacter device entry point, then these functions should not be used. 21759da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 21769da20b8aSRobert Mustacchi.It Xr pollhead_clean 9F Ta Xr pollwakeup 9F 21779da20b8aSRobert Mustacchi.El 21789da20b8aSRobert Mustacchi.Ss Kernel Statistics 21799da20b8aSRobert MustacchiThe kernel statistics or kstat framework provides an easy way of 21809da20b8aSRobert Mustacchiexporting statistic information to be consumed outside of the kernel. 21819da20b8aSRobert MustacchiUsers can interface with this data via 21829da20b8aSRobert Mustacchi.Xr kstat 8 21839da20b8aSRobert Mustacchiand the corresponding kstat library discussed in 21849da20b8aSRobert Mustacchi.Xr kstat 3KSTAT . 21859da20b8aSRobert Mustacchi.Pp 21869da20b8aSRobert MustacchiKernel statistics are grouped using a tuple of four identifiers, 21879da20b8aSRobert Mustacchiseparated by colons when using 21889da20b8aSRobert Mustacchi.Xr kstat 8 . 21899da20b8aSRobert MustacchiThese are, in order, the statistic module name, instance, a name 21909da20b8aSRobert Mustacchiwhich covers a group of statistics, and an individual name for a 21919da20b8aSRobert Mustacchistatistic. 21929da20b8aSRobert MustacchiIn addition, kernel statistics have a class which is used to group 21939da20b8aSRobert Mustacchisimilar named groups of statistics together across devices. 21949da20b8aSRobert MustacchiWhen using 21959da20b8aSRobert Mustacchi.Xr kstat_create 9F , 21969da20b8aSRobert Mustacchidrivers specify the first three parts of the tuple and the class. 21979da20b8aSRobert MustacchiThe naming of individual statistics, the last part of the tuple, varies 21989da20b8aSRobert Mustacchibased upon the type of the statistic. 21999da20b8aSRobert MustacchiFor the most part, drivers will use the kstat type 22009da20b8aSRobert Mustacchi.Dv KSTAT_TYPE_NAMED , 22019da20b8aSRobert Mustacchiwhich allows multiple name-value pairs to exist within the statistic. 22029da20b8aSRobert MustacchiFor example, the kernel's layer 2 networking framework, 22039da20b8aSRobert Mustacchi.Xr mac 9E , 22049da20b8aSRobert Mustacchicreates a kstat with the driver's name and instance and names it 22059da20b8aSRobert Mustacchi.Dq mac . 22069da20b8aSRobert MustacchiWithin this named group, there are statistics for all of the different 22079da20b8aSRobert Mustacchiindividual stats that the kernel and devices track such as bytes 22089da20b8aSRobert Mustacchitransmitted and received, the state and speed of the link, and 22099da20b8aSRobert Mustacchiadvertised and enabled capabilities. 22109da20b8aSRobert Mustacchi.Pp 22119da20b8aSRobert MustacchiA device driver can initialize a kstat with the 22129da20b8aSRobert Mustacchi.Xr kstat_create 9F 22139da20b8aSRobert Mustacchifunction. 22149da20b8aSRobert MustacchiIt will not be made accessible to users until the 22159da20b8aSRobert Mustacchi.Xr kstat_install 9F 22169da20b8aSRobert Mustacchifunction is called. 22179da20b8aSRobert MustacchiThe device driver must perform additional initialization of the kstat 22189da20b8aSRobert Mustacchibefore proceeding and calling 22199da20b8aSRobert Mustacchi.Xr kstat_install 9F . 22209da20b8aSRobert MustacchiThe kstat structure that drivers see is discussed in 22219da20b8aSRobert Mustacchi.Xr kstat 9S . 22229da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 22239da20b8aSRobert Mustacchi.It Xr kstat_create 9F Ta Xr kstat_delete 9F 22249da20b8aSRobert Mustacchi.It Xr kstat_install 9F Ta Xr kstat_named_init 9F 22259da20b8aSRobert Mustacchi.It Xr kstat_named_setstr 9F Ta Xr kstat_queue 9F 22269da20b8aSRobert Mustacchi.It Xr kstat_runq_back_to_waitq 9F Ta Xr kstat_runq_enter 9F 22279da20b8aSRobert Mustacchi.It Xr kstat_runq_exit 9F Ta Xr kstat_waitq_enter 9F 22289da20b8aSRobert Mustacchi.It Xr kstat_waitq_exit 9F Ta Xr kstat_waitq_to_runq 9F 22299da20b8aSRobert Mustacchi.El 22309da20b8aSRobert Mustacchi.Ss NDI Events 22319da20b8aSRobert MustacchiThese functions are used to allow a device driver to register for 22329da20b8aSRobert Mustacchicertain events that might occur to its device or a parent in the tree 22339da20b8aSRobert Mustacchiand receive a callback function when they occur. 22349da20b8aSRobert MustacchiA good example of this is when a device has been removed from the system 22359da20b8aSRobert Mustacchisuch as someone just pulling out a USB device or NVMe U.2 device. 22369da20b8aSRobert MustacchiThe event handlers work by first getting a cookie that names the type of 22379da20b8aSRobert Mustacchievent with 22389da20b8aSRobert Mustacchi.Xr ddi_get_eventcookie 9F 22399da20b8aSRobert Mustacchiand then registering the callback with 22409da20b8aSRobert Mustacchi.Xr ddi_add_event_handler 9F . 22419da20b8aSRobert Mustacchi.Pp 22429da20b8aSRobert MustacchiThe 22439da20b8aSRobert Mustacchi.Xr ddi_cb_register 9F 22449da20b8aSRobert Mustacchifunction is used to collect over classes of events such as when 22459da20b8aSRobert Mustacchiparticipating in dynamic interrupt sharing. 22469da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 22479da20b8aSRobert Mustacchi.It Xr ddi_add_event_handler 9F Ta Xr ddi_cb_register 9F 22489da20b8aSRobert Mustacchi.It Xr ddi_cb_unregister 9F Ta Xr ddi_get_eventcookie 9F 22499da20b8aSRobert Mustacchi.It Xr ddi_remove_event_handler 9F Ta 22509da20b8aSRobert Mustacchi.El 22519da20b8aSRobert Mustacchi.Ss Layered Device Interfaces 22529da20b8aSRobert MustacchiThe LDI 22539da20b8aSRobert Mustacchi.Pq Layered Device Interface 22549da20b8aSRobert Mustacchiprovides a mechanism for a driver to open up another device in the 22559da20b8aSRobert Mustacchikernel and begin calling basic operations on the device as though the 22569da20b8aSRobert Mustacchicalling driver were a normal user process. 22579da20b8aSRobert MustacchiThrough the LDI, drivers can perform equivalents to the basic file 22589da20b8aSRobert Mustacchi.Xr read 2 22599da20b8aSRobert Mustacchiand 22609da20b8aSRobert Mustacchi.Xr write 2 22619da20b8aSRobert Mustacchicalls, look up properties on the device, perform networking style calls 22629da20b8aSRobert Mustacchiala 22639da20b8aSRobert Mustacchi.Xr getmsg 2 22649da20b8aSRobert Mustacchiand 2265*496cffd8SPeter Tribble.Xr putmsg 2 , 22669da20b8aSRobert Mustacchiand register callbacks to be called when something happens to the 22679da20b8aSRobert Mustacchiunderlying device. 22689da20b8aSRobert MustacchiFor example, the ZFS file system uses the LDI to open and operate on 22699da20b8aSRobert Mustacchiblock devices. 22709da20b8aSRobert Mustacchi.Pp 22719da20b8aSRobert MustacchiBefore opening a device itself, callers must obtain a notion of their 22729da20b8aSRobert Mustacchiidentity which is used when making subsequent calls. 22739da20b8aSRobert MustacchiThe simplest form is often to use the device's 22749da20b8aSRobert Mustacchi.Vt dev_info_t 22759da20b8aSRobert Mustacchiand call 22769da20b8aSRobert Mustacchi.Xr ldi_ident_from_dip 9F ; 22779da20b8aSRobert Mustacchihowever, there are also methods available based upon having a 22789da20b8aSRobert Mustacchi.Vt dev_t 22799da20b8aSRobert Mustacchior a STREAMS 22809da20b8aSRobert Mustacchi.Vt struct queue . 22819da20b8aSRobert Mustacchi.Pp 22829da20b8aSRobert MustacchiOnce that identity is established, there are several ways to open a 22839da20b8aSRobert Mustacchidevice such as 22849da20b8aSRobert Mustacchi.Xr ldi_open_by_dev 9F , 22859da20b8aSRobert Mustacchi.Xr ldi_open_by_devid 9F , 22869da20b8aSRobert Mustacchior 22879da20b8aSRobert Mustacchi.Xr ldi_open_by_name 9F . 22889da20b8aSRobert MustacchiOnce an LDI device has been opened, then all of the other functions may 22899da20b8aSRobert Mustacchibe used to operate on the device; however, consumers of the LDI must 22909da20b8aSRobert Mustacchithink carefully about what kind of device they are opening. 22919da20b8aSRobert MustacchiWhile a kernel pseudo-device driver cannot disappear while it is open, 22929da20b8aSRobert Mustacchiwhen the device represents an actual piece of hardware, it is possible 22939da20b8aSRobert Mustacchifor it to be physically removed and no longer be accessible. 22949da20b8aSRobert MustacchiConsumers should not assume that a layered device will always be 22959da20b8aSRobert Mustacchipresent. 22969da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 22979da20b8aSRobert Mustacchi.It Xr ldi_add_event_handler 9F Ta Xr ldi_aread 9F 22989da20b8aSRobert Mustacchi.It Xr ldi_awrite 9F Ta Xr ldi_close 9F 22999da20b8aSRobert Mustacchi.It Xr ldi_devmap 9F Ta Xr ldi_dump 9F 23009da20b8aSRobert Mustacchi.It Xr ldi_ev_finalize 9F Ta Xr ldi_ev_get_cookie 9F 23019da20b8aSRobert Mustacchi.It Xr ldi_ev_get_type 9F Ta Xr ldi_ev_notify 9F 23029da20b8aSRobert Mustacchi.It Xr ldi_ev_register_callbacks 9F Ta Xr ldi_ev_remove_callbacks 9F 23039da20b8aSRobert Mustacchi.It Xr ldi_get_dev 9F Ta Xr ldi_get_devid 9F 23049da20b8aSRobert Mustacchi.It Xr ldi_get_eventcookie 9F Ta Xr ldi_get_minor_name 9F 23059da20b8aSRobert Mustacchi.It Xr ldi_get_otyp 9F Ta Xr ldi_get_size 9F 23069da20b8aSRobert Mustacchi.It Xr ldi_getmsg 9F Ta Xr ldi_ident_from_dev 9F 23079da20b8aSRobert Mustacchi.It Xr ldi_ident_from_dip 9F Ta Xr ldi_ident_from_stream 9F 23089da20b8aSRobert Mustacchi.It Xr ldi_ident_release 9F Ta Xr ldi_ioctl 9F 23099da20b8aSRobert Mustacchi.It Xr ldi_open_by_dev 9F Ta Xr ldi_open_by_devid 9F 23109da20b8aSRobert Mustacchi.It Xr ldi_open_by_name 9F Ta Xr ldi_poll 9F 23119da20b8aSRobert Mustacchi.It Xr ldi_prop_exists 9F Ta Xr ldi_prop_get_int 9F 23129da20b8aSRobert Mustacchi.It Xr ldi_prop_get_int64 9F Ta Xr ldi_prop_lookup_byte_array 9F 23139da20b8aSRobert Mustacchi.It Xr ldi_prop_lookup_int_array 9F Ta Xr ldi_prop_lookup_int64_array 9F 23149da20b8aSRobert Mustacchi.It Xr ldi_prop_lookup_string_array 9F Ta Xr ldi_prop_lookup_string 9F 23159da20b8aSRobert Mustacchi.It Xr ldi_putmsg 9F Ta Xr ldi_read 9F 23169da20b8aSRobert Mustacchi.It Xr ldi_remove_event_handler 9F Ta Xr ldi_strategy 9F 23179da20b8aSRobert Mustacchi.It Xr ldi_write 9F Ta 23189da20b8aSRobert Mustacchi.El 23199da20b8aSRobert Mustacchi.Ss Signal Manipulation 23209da20b8aSRobert MustacchiThese utility functions all relate to understanding whether or not a 23219da20b8aSRobert Mustacchiprocess can receive a signal an actually delivering one to a process 23229da20b8aSRobert Mustacchifrom a driver. 23239da20b8aSRobert MustacchiThis interface is specific to device drivers and should not be used by 23249da20b8aSRobert Mustacchithe broader kernel. 23259da20b8aSRobert MustacchiThese interfaces are not recommended and should only be used after 23269da20b8aSRobert Mustacchiconsultation. 23279da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 23289da20b8aSRobert Mustacchi.It Xr ddi_can_receive_sig 9F Ta Xr proc_ref 9F 23299da20b8aSRobert Mustacchi.It Xr proc_signal 9F Ta Xr proc_unref 9F 23309da20b8aSRobert Mustacchi.El 23319da20b8aSRobert Mustacchi.Ss Getting at Surrounding Context 23329da20b8aSRobert MustacchiThese functions allow a driver to better understand its current context. 23339da20b8aSRobert MustacchiFor example, some drivers have to deal with providing polled I/O or take 23349da20b8aSRobert Mustacchispecial care as part of creating a kernel crash dump. 23359da20b8aSRobert MustacchiThese cases may need to call the 23369da20b8aSRobert Mustacchi.Xr ddi_in_panic 9F 23379da20b8aSRobert Mustacchifunction. 2338*496cffd8SPeter TribbleThe other functions generally provide a way to get at information such as 23399da20b8aSRobert Mustacchithe process ID or other information from the system; however, this 23409da20b8aSRobert Mustacchigenerally should not be needed or used. 23419da20b8aSRobert MustacchiAlmost all values exposed by say 23429da20b8aSRobert Mustacchi.Xr drv_getparm 9F 23439da20b8aSRobert Mustacchihave more usable first-class methods of getting at the data. 23449da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 23459da20b8aSRobert Mustacchi.It Xr ddi_get_kt_did 9F Ta Xr ddi_get_pid 9F 23469da20b8aSRobert Mustacchi.It Xr ddi_in_panic 9F Ta Xr drv_getparm 9F 23479da20b8aSRobert Mustacchi.El 23489da20b8aSRobert Mustacchi.Ss Driver Memory Mapping 23499da20b8aSRobert MustacchiThese functions are present for device drivers that implement the 23509da20b8aSRobert Mustacchi.Xr devmap 9E 23519da20b8aSRobert Mustacchior 23529da20b8aSRobert Mustacchi.Xr segmap 9E 23539da20b8aSRobert Mustacchientry points. 23549da20b8aSRobert MustacchiThe 23559da20b8aSRobert Mustacchi.Xr ddi_umem_alloc 9F 23569da20b8aSRobert Mustacchiroutines are used to allocate and lock memory that can later be used as 23579da20b8aSRobert Mustacchipart of passing this memory to userland through the mapping entry 23589da20b8aSRobert Mustacchipoints. 23599da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 23609da20b8aSRobert Mustacchi.It Xr ddi_devmap_segmap 9F Ta Xr ddi_mmap_get_model 9F 23619da20b8aSRobert Mustacchi.It Xr ddi_segmap_setup 9F Ta Xr ddi_segmap 9F 23629da20b8aSRobert Mustacchi.It Xr ddi_umem_alloc 9F Ta Xr ddi_umem_free 9F 23639da20b8aSRobert Mustacchi.It Xr ddi_umem_iosetup 9F Ta Xr ddi_umem_lock 9F 23649da20b8aSRobert Mustacchi.It Xr ddi_umem_unlock 9F Ta Xr ddi_unmap_regs 9F 23659da20b8aSRobert Mustacchi.It Xr devmap_default_access 9F Ta Xr devmap_devmem_setup 9F 23669da20b8aSRobert Mustacchi.It Xr devmap_do_ctxmgt 9F Ta Xr devmap_load 9F 23679da20b8aSRobert Mustacchi.It Xr devmap_set_ctx_timeout 9F Ta Xr devmap_setup 9F 23689da20b8aSRobert Mustacchi.It Xr devmap_umem_setup 9F Ta Xr devmap_unload 9F 23699da20b8aSRobert Mustacchi.El 23709da20b8aSRobert Mustacchi.Ss UTF-8, UTF-16, UTF-32, and Code Set Utilities 23719da20b8aSRobert MustacchiThese routines provide the ability to work with and deal with text in 23729da20b8aSRobert Mustacchidifferent encodings and code sets. 23739da20b8aSRobert MustacchiGenerally the kernel does not assume that much about the type of the text 23749da20b8aSRobert Mustacchithat it is operating in, though some subsystems will require that the 23759da20b8aSRobert Mustacchinames of things be ASCII only. 23769da20b8aSRobert Mustacchi.Pp 23779da20b8aSRobert MustacchiThe primary other locales that the system supports are generally UTF-8 23789da20b8aSRobert Mustacchibased and so the kernel provides a set of routines to deal with UTF-8 23799da20b8aSRobert Mustacchiand Unicode normalization. 23809da20b8aSRobert MustacchiHowever, there are still cases where different character encodings are 23819da20b8aSRobert Mustacchirequired or conversation between UTF-8 and some other type is required. 23829da20b8aSRobert MustacchiThis is provided by the kernel iconv framework, which provides a 23839da20b8aSRobert Mustacchisubset of the traditional userland iconv conversions. 23849da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 23859da20b8aSRobert Mustacchi.It Xr kiconv_close 9F Ta Xr kiconv_open 9F 23869da20b8aSRobert Mustacchi.It Xr kiconv 9F Ta Xr kiconvstr 9F 23879da20b8aSRobert Mustacchi.It Xr u8_strcmp 9F Ta Xr u8_textprep_str 9F 23889da20b8aSRobert Mustacchi.It Xr u8_validate 9F Ta Xr uconv_u16tou32 9F 23899da20b8aSRobert Mustacchi.It Xr uconv_u16tou8 9F Ta Xr uconv_u32tou16 9F 23909da20b8aSRobert Mustacchi.It Xr uconv_u32tou8 9F Ta Xr uconv_u8tou16 9F 23919da20b8aSRobert Mustacchi.It Xr uconv_u8tou32 9F Ta 23929da20b8aSRobert Mustacchi.El 23939da20b8aSRobert Mustacchi.Ss Raw I/O Port Access 23949da20b8aSRobert MustacchiThis group of functions provides raw access to I/O ports on architecture 23959da20b8aSRobert Mustacchithat support them. 23969da20b8aSRobert MustacchiThese functions do not allow any coordination with other callers nor is 23979da20b8aSRobert Mustacchithe validity of the port assured in any way. 23989da20b8aSRobert MustacchiIn general, device drivers should use the normal register access 23999da20b8aSRobert Mustacchiroutines to access I/O ports. 24009da20b8aSRobert MustacchiSee 24019da20b8aSRobert Mustacchi.Sx Device Register Setup and Access 24029da20b8aSRobert Mustacchifor more information on the preferred way to setup and access registers. 24039da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 24049da20b8aSRobert Mustacchi.It Xr inb 9F Ta Xr inw 9F 24059da20b8aSRobert Mustacchi.It Xr inl 9F Ta Xr outb 9F 24069da20b8aSRobert Mustacchi.It Xr outw 9F Ta Xr outl 9F 24079da20b8aSRobert Mustacchi.El 24089da20b8aSRobert Mustacchi.Ss Power Management 24099da20b8aSRobert MustacchiThese functions are used to raise and lower the internal power levels of 24109da20b8aSRobert Mustacchia device driver or to indicate to the kernel that the device is busy and 24119da20b8aSRobert Mustacchitherefore cannot have its power changed. 24129da20b8aSRobert MustacchiSee 24139da20b8aSRobert Mustacchi.Xr power 9E 24149da20b8aSRobert Mustacchifor additional information. 24159da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 24169da20b8aSRobert Mustacchi.It Xr ddi_removing_power 9F Ta Xr pm_busy_component 9F 24179da20b8aSRobert Mustacchi.It Xr pm_idle_component 9F Ta Xr pm_lower_power 9F 24189da20b8aSRobert Mustacchi.It Xr pm_power_has_changed 9F Ta Xr pm_raise_power 9F 24199da20b8aSRobert Mustacchi.It Xr pm_trans_check 9F Ta 24209da20b8aSRobert Mustacchi.El 24219da20b8aSRobert Mustacchi.Ss Network Packet Hooks 24229da20b8aSRobert MustacchiThese functions are intended to be used by device drivers that wish to 24239da20b8aSRobert Mustacchiinspect and potentially modify packets along their path through the 24249da20b8aSRobert Mustacchinetworking stack. 24259da20b8aSRobert MustacchiThe most common use case is for implementing something like a network 24269da20b8aSRobert Mustacchifirewall. 24279da20b8aSRobert MustacchiOtherwise, if looking to add support for a new protocol or other network 24289da20b8aSRobert Mustacchiprocessing feature, one is better off more directly integrating with the 24299da20b8aSRobert Mustacchinetworking stack. 24309da20b8aSRobert Mustacchi.Pp 24319da20b8aSRobert MustacchiTo get started, drivers generally will need to first use 24329da20b8aSRobert Mustacchi.Xr net_protocol_lookup 9F 24339da20b8aSRobert Mustacchito get a handle to say that they're interested in looking at IPv4 or 24349da20b8aSRobert MustacchiIPv6 traffic and then can allocate an actual hook object with 24359da20b8aSRobert Mustacchi.Xr hook_alloc 9F . 24369da20b8aSRobert MustacchiAfter filling out the hook, the hook can be inserted into the actual 24379da20b8aSRobert Mustacchisystem with 24389da20b8aSRobert Mustacchi.Xr net_hook_register 9F . 24399da20b8aSRobert Mustacchi.Pp 24409da20b8aSRobert MustacchiHooks operate in the context of a networking stack. 24419da20b8aSRobert MustacchiEvery networking stack in the system is independent and therefore has 24429da20b8aSRobert Mustacchiits own set of interfaces, routing tables, settings, and related. 24439da20b8aSRobert MustacchiMost zones have their own networking stack. 24449da20b8aSRobert MustacchiThis is the exclusive-IP option that is described in 24459da20b8aSRobert Mustacchi.Xr zoneadm 8 . 24469da20b8aSRobert Mustacchi.Pp 24479da20b8aSRobert MustacchiDrivers can register to get a callback for every netstack in the system 24489da20b8aSRobert Mustacchiand be notified when they are created and destroyed. 24499da20b8aSRobert MustacchiThis is done by calling the 2450*496cffd8SPeter Tribble.Xr net_instance_alloc 9F 24519da20b8aSRobert Mustacchifunction, filling out its data structure, and then finally calling 2452*496cffd8SPeter Tribble.Xr net_instance_register 9F . 24539da20b8aSRobert MustacchiLike other callback interfaces, the moment the callback functions are 24549da20b8aSRobert Mustacchiregistered, drivers need to expect that they're going to be called. 24559da20b8aSRobert Mustacchi.Bl -column -offset indent "net_instance_protocol_unregister" "net_instance_protocol_unregister" 24569da20b8aSRobert Mustacchi.It Xr hook_alloc 9F Ta Xr hook_free 9F 24579da20b8aSRobert Mustacchi.It Xr net_event_notify_register 9F Ta Xr net_event_notify_unregister 9F 24589da20b8aSRobert Mustacchi.It Xr net_getifname 9F Ta Xr net_getlifaddr 9F 24599da20b8aSRobert Mustacchi.It Xr net_getmtu 9F Ta Xr net_getnetid 9F 24609da20b8aSRobert Mustacchi.It Xr net_getpmtuenabled 9F Ta Xr net_hook_register 9F 24619da20b8aSRobert Mustacchi.It Xr net_hook_unregister 9F Ta Xr net_inject_alloc 9F 24629da20b8aSRobert Mustacchi.It Xr net_inject_free 9F Ta Xr net_inject 9F 24639da20b8aSRobert Mustacchi.It Xr net_instance_alloc 9F Ta Xr net_instance_free 9F 24649da20b8aSRobert Mustacchi.It Xr net_instance_notify_register 9F Ta Xr net_instance_notify_unregister 9F 24659da20b8aSRobert Mustacchi.It Xr net_instance_protocol_unregister 9F Ta Xr net_instance_register 9F 24669da20b8aSRobert Mustacchi.It Xr net_instance_unregister 9F Ta Xr net_ispartialchecksum 9F 24679da20b8aSRobert Mustacchi.It Xr net_isvalidchecksum 9F Ta Xr net_kstat_create 9F 24689da20b8aSRobert Mustacchi.It Xr net_kstat_delete 9F Ta Xr net_lifgetnext 9F 24699da20b8aSRobert Mustacchi.It Xr net_netidtozonid 9F Ta Xr net_phygetnext 9F 24709da20b8aSRobert Mustacchi.It Xr net_phylookup 9F Ta Xr net_protocol_lookup 9F 24719da20b8aSRobert Mustacchi.It Xr net_protocol_notify_register 9F Ta Xr net_protocol_release 9F 24729da20b8aSRobert Mustacchi.It Xr net_protocol_walk 9F Ta Xr net_routeto 9F 24739da20b8aSRobert Mustacchi.It Xr net_zoneidtonetid 9F Ta Xr netinfo 9F 24749da20b8aSRobert Mustacchi.El 24759da20b8aSRobert Mustacchi.Sh SEE ALSO 24769da20b8aSRobert Mustacchi.Xr Intro 2 , 24779da20b8aSRobert Mustacchi.Xr Intro 9 , 24789da20b8aSRobert Mustacchi.Xr Intro 9E , 24799da20b8aSRobert Mustacchi.Xr Intro 9S 24809da20b8aSRobert Mustacchi.Rs 24819da20b8aSRobert Mustacchi.%T illumos Developer's Guide 24829da20b8aSRobert Mustacchi.%U https://www.illumos.org/books/dev/ 24839da20b8aSRobert Mustacchi.Re 24849da20b8aSRobert Mustacchi.Rs 24859da20b8aSRobert Mustacchi.%T Writing Device Drivers 24869da20b8aSRobert Mustacchi.%U https://www.illumos.org/books/wdd/ 24879da20b8aSRobert Mustacchi.Re 2488