NAME

Intro, intro − introduction to DDI/DKI functions

DESCRIPTION

Section 9F describes the kernel functions available for use by device drivers. 

In this section, the information for each driver function is organized under the following headings:

• NAME summarizes the function’s purpose. 

• SYNOPSIS shows the syntax of the function’s entry point in the source code.  #include directives are shown for required headers. 

• INTERFACE LEVEL describes any architecture dependencies. 

• ARGUMENTS describes any arguments required to invoke the function. 

• DESCRIPTION describes general information about the function. 

• RETURN VALUES describes the return values and messages that can result from invoking the function. 

• CONTEXT indicates from which driver context (user, kernel, interrupt, or high-level interrupt) the function can be called. 

A driver function has user context if it was directly invoked because of a user thread. The read(9E) entry point of the driver, invoked by a read(2) system call, has user context. 

A driver function has kernel context if was invoked by some other part of the kernel. In a block device driver, the strategy(9E) entry point may be called by the page daemon to write pages to the device. The page daemon has no relation to the current user thread, so in this case strategy(9E) has kernel context. 

Interrupt context is kernel context, but also has an interrupt level associated with it.  Driver interrupt routines have interrupt context. 

High-level interrupt context is a more restricted form of interrupt context.  If ddi_intr_hilevel(9F) indicates that an interrupt is high-level, driver interrupt routines added for that interrupt with ddi_add_intr(9F) run in high-level interrupt context.  These interrupt routines are only allowed to call ddi_trigger_softintr(9F), mutex_enter(9F) and mutex_exit(9F).  Furthermore, mutex_enter(9F) and mutex_exit(9F) may only be called on mutexes initialized with the ddi_iblock_cookie returned by ddi_add_intr(9F). 

• SEE ALSO indicates functions that are related by usage and sources, and which can be referred to for further information. 

• EXAMPLES shows how the function can be used in driver code. 

Every driver MUST include <sys/ddi.h> and <sys/sunddi.h>, in that order, and as the last files the driver includes. 

STREAMS Kernel Function Summary

The following table summarizes the STREAMS functions described in this section. 

The following table summarizes the functions not specific to STREAMS. 

LIST OF FUNCTIONS

NameAppears on PageDescription
ASSERTASSERT(9F)expression verification
OTHERQOTHERQ(9F)get pointer to queue’s
partner queue
RDRD(9F)get pointer to the read
queue
SAMESTRSAMESTR(9F)test if next queue is
in the same stream
WRWR(9F)get pointer to the
write queue for this
module or driver
adjmsgadjmsg(9F)trim bytes from a
message
allocballocb(9F)allocate a message
block
assertASSERT(9F)expression verification
backqbackq(9F)get pointer to the
queue behind the
current queue
bcanputbcanput(9F)test for flow control
in specified priority
band
bcanputnextcanputnext(9F)test for room in next
module’s message queue
bcmpbcmp(9F)compare two byte arrays
bcopybcopy(9F)copy data between
address locations in
the kernel
biodonebiodone(9F)release buffer after
buffer I/O transfer and
notify blocked threads
bioerrorbioerror(9F)indicate error in
buffer header
bioresetbioreset(9F)reuse a private buffer
header after I/O is
complete
biowaitbiowait(9F)suspend processes
pending completion of
block I/O
bp_mapinbp_mapin(9F)allocate virtual
address space
bp_mapoutbp_mapout(9F)deallocate virtual
address space
brelsebrelse(9F)return buffer to the
free list
btopbtop(9F)convert size in bytes
to size in pages (round
down)
btoprbtopr(9F)convert size in bytes
to size in pages (round
up)
bufcallbufcall(9F)call a function when a
buffer becomes
available
bzerobzero(9F)clear memory for a
given number of bytes
canputcanput(9F)test for room in a
message queue
canputnextcanputnext(9F)test for room in next
module’s message queue
clrbufclrbuf(9F)erase the contents of a
buffer
cmn_errcmn_err(9F)display an error
message or panic the
system
condvarcondvar(9F)condition variable
routines
copybcopyb(9F)copy a message block
copyincopyin(9F)copy data from a user
program to a driver
buffer
copymsgcopymsg(9F)copy a message
copyoutcopyout(9F)copy data from a driver
to a user program
cv_broadcastcondvar(9F)condition variable
routines
cv_destroycondvar(9F)condition variable
routines
cv_initcondvar(9F)condition variable
routines
cv_signalcondvar(9F)condition variable
routines
cv_timedwaitcondvar(9F)condition variable
routines
cv_timedwait_sigcondvar(9F)condition variable
routines
cv_waitcondvar(9F)condition variable
routines
cv_wait_sigcondvar(9F)condition variable
routines
datamsgdatamsg(9F)test whether a message
is a data message
ddi_add_intrddi_add_intr(9F)add and remove an
interrupt handler
ddi_add_softintrddi_add_softintr(9F)add, remove or trigger
a soft interrupt
ddi_btopddi_btop(9F)page size conversions
ddi_btoprddi_btop(9F)page size conversions
ddi_copyinddi_copyin(9F)copy data to a driver
buffer
ddi_copyoutddi_copyout(9F)copy data from a driver
ddi_create_minor_nodeddi_create_minor_node(9F)create a minor node for
this device
ddi_dev_is_sidddi_dev_is_sid(9F)tell whether a device
is self-identifying
ddi_dev_nintrsddi_dev_nintrs(9F)return the number of
interrupt
specifications a device
has
ddi_dev_nregsddi_dev_nregs(9F)return the number of
register sets a device
has
ddi_dev_regsizeddi_dev_regsize(9F)return the size of a
device’s register
ddi_dma_addr_setupddi_dma_addr_setup(9F)easier DMA setup for
use with virtual
addresses
ddi_dma_buf_setupddi_dma_buf_setup(9F)easier DMA setup for
use with buffer
structures
ddi_dma_burstsizesddi_dma_burstsizes(9F)find out the allowed
burst sizes for a DMA
mapping
ddi_dma_coffddi_dma_coff(9F)convert a DMA cookie to
an offset within a DMA
handle
ddi_dma_curwinddi_dma_curwin(9F)report current DMA
window offset and size
ddi_dma_devalignddi_dma_devalign(9F)find DMA mapping
alignment and minimum
transfer size
ddi_dma_freeddi_dma_free(9F)release system DMA
resources
ddi_dma_htocddi_dma_htoc(9F)convert a DMA handle to
a DMA address cookie
ddi_dma_movwinddi_dma_movwin(9F)shift current DMA
window
ddi_dma_nextsegddi_dma_nextseg(9F)get next DMA segment
ddi_dma_nextwinddi_dma_nextwin(9F)get next DMA window
ddi_dma_segtocookieddi_dma_segtocookie(9F)convert a DMA segment
to a DMA address cookie
ddi_dma_setupddi_dma_setup(9F)setup DMA resources
ddi_dma_syncddi_dma_sync(9F)synchronize CPU and I/O
views of memory
ddi_dmaeddi_dmae(9F)system DMA engine
functions
ddi_dmae_1stpartyddi_dmae(9F)system DMA engine
functions
ddi_dmae_allocddi_dmae(9F)system DMA engine
functions
ddi_dmae_disableddi_dmae(9F)system DMA engine
functions
ddi_dmae_enableddi_dmae(9F)system DMA engine
functions
ddi_dmae_getcntddi_dmae(9F)system DMA engine
functions
ddi_dmae_getlimddi_dmae(9F)system DMA engine
functions
ddi_dmae_progddi_dmae(9F)system DMA engine
functions
ddi_dmae_releaseddi_dmae(9F)system DMA engine
functions
ddi_dmae_stopddi_dmae(9F)system DMA engine
functions
ddi_enter_criticalddi_enter_critical(9F)enter and exit a
critical region of
control
ddi_exit_criticalddi_enter_critical(9F)enter and exit a
critical region of
control
ddi_ffsddi_ffs(9F)find first (last) bit
set in a long integer
ddi_flsddi_ffs(9F)find first (last) bit
set in a long integer
ddi_get_credddi_get_cred(9F)returns a pointer to
the credential
structure of the
caller.
ddi_get_driver_privateddi_get_driver_private(9F)get or set the address
of the device’s private
data area
ddi_get_instanceddi_get_instance(9F)get device instance
number
ddi_get_nameddi_get_name(9F)return the devinfo node
name
ddi_get_parentddi_get_parent(9F)find the parent of a
device information
structure
ddi_get_soft_stateddi_soft_state(9F)driver soft state
utility routines
ddi_getlongpropddi_prop_op(9F)get property
information for leaf
device drivers
ddi_getlongprop_bufddi_prop_op(9F)get property
information for leaf
device drivers
ddi_getpropddi_prop_op(9F)get property
information for leaf
device drivers
ddi_getproplenddi_prop_op(9F)get property
information for leaf
device drivers
ddi_intr_hilevelddi_intr_hilevel(9F)indicate interrupt
handler type
ddi_iominddi_iomin(9F)find minimum alignment
and transfer size for
DMA
ddi_iopb_allocddi_iopb_alloc(9F)allocate and free
non-sequentially
accessed memory
ddi_iopb_freeddi_iopb_alloc(9F)allocate and free
non-sequentially
accessed memory
ddi_map_regsddi_map_regs(9F)map or unmap registers
ddi_mapdevddi_mapdev(9F)create
driver-controlled
mapping of device
ddi_mapdev_interceptddi_mapdev_intercept(9F)control driver
notification of user
accesses
ddi_mapdev_nointerceptddi_mapdev_intercept(9F)control driver
notification of user
accesses
ddi_mem_allocddi_mem_alloc(9F)allocate and free
sequentially accessed
memory
ddi_mem_freeddi_mem_alloc(9F)allocate and free
sequentially accessed
memory
ddi_peekddi_peek(9F)read a value from a
location
ddi_peekcddi_peek(9F)read a value from a
location
ddi_peekdddi_peek(9F)read a value from a
location
ddi_peeklddi_peek(9F)read a value from a
location
ddi_peeksddi_peek(9F)read a value from a
location
ddi_pokeddi_poke(9F)write a value to a
location
ddi_pokecddi_poke(9F)write a value to a
location
ddi_pokedddi_poke(9F)write a value to a
location
ddi_pokelddi_poke(9F)write a value to a
location
ddi_pokesddi_poke(9F)write a value to a
location
ddi_prop_createddi_prop_create(9F)create, remove, or
modify properties for
leaf device drivers
ddi_prop_modifyddi_prop_create(9F)create, remove, or
modify properties for
leaf device drivers
ddi_prop_opddi_prop_op(9F)get property
information for leaf
device drivers
ddi_prop_removeddi_prop_create(9F)create, remove, or
modify properties for
leaf device drivers
ddi_prop_remove_allddi_prop_create(9F)create, remove, or
modify properties for
leaf device drivers
ddi_prop_undefineddi_prop_create(9F)create, remove, or
modify properties for
leaf device drivers
ddi_ptobddi_btop(9F)page size conversions
ddi_remove_intrddi_add_intr(9F)add and remove an
interrupt handler
ddi_remove_minor_nodeddi_remove_minor_node(9F)remove a minor node for
this dev_info
ddi_remove_softintrddi_add_softintr(9F)add, remove or trigger
a soft interrupt
ddi_report_devddi_report_dev(9F)announce a device
ddi_root_nodeddi_root_node(9F)get the root of the
dev_info tree
ddi_segmapddi_segmap(9F)map a segment
ddi_set_driver_privateddi_get_driver_private(9F)get or set the address
of the device’s private
data area
ddi_slaveonlyddi_slaveonly(9F)tell if a device is
installed in a slave
access only location
ddi_soft_stateddi_soft_state(9F)driver soft state
utility routines
ddi_soft_state_finiddi_soft_state(9F)driver soft state
utility routines
ddi_soft_state_freeddi_soft_state(9F)driver soft state
utility routines
ddi_soft_state_initddi_soft_state(9F)driver soft state
utility routines
ddi_soft_state_zallocddi_soft_state(9F)driver soft state
utility routines
ddi_trigger_softintrddi_add_softintr(9F)add, remove or trigger
a soft interrupt
ddi_unmap_regsddi_map_regs(9F)map or unmap registers
delaydelay(9F)delay execution for a
specified number of
clock ticks
disksortdisksort(9F)single direction
elevator seek sort for
buffers
drv_getparmdrv_getparm(9F)retrieve kernel state
information
drv_hztousecdrv_hztousec(9F)convert clock ticks to
microseconds
drv_privdrv_priv(9F)determine driver
privilege
drv_usectohzdrv_usectohz(9F)convert microseconds to
clock ticks
drv_usecwaitdrv_usecwait(9F)busy-wait for specified
interval
dupbdupb(9F)duplicate a message
block descriptor
dupmsgdupmsg(9F)duplicate a message
enableokenableok(9F)reschedule a queue for
service
esballocesballoc(9F)allocate a message
block using a
caller-supplied buffer
esbbcallesbbcall(9F)call function when
buffer is available
flushbandflushband(9F)flush messages for a
specified priority band
flushqflushq(9F)remove messages from a
queue
free_pktiopbget_pktiopb(9F)allocate/free a SCSI
packet in the iopb map
freebfreeb(9F)free a message block
freemsgfreemsg(9F)free all message blocks
in a message
freerbuffreerbuf(9F)free a raw buffer
header
freezestrfreezestr(9F)freeze, thaw the state
of a stream
get_pktiopbget_pktiopb(9F)allocate/free a SCSI
packet in the iopb map
geterrorgeterror(9F)return I/O error
getmajorgetmajor(9F)get major device number
getminorgetminor(9F)get minor device number
getqgetq(9F)get the next message
from a queue
getrbufgetrbuf(9F)get a raw buffer header
hat_getkpfnumhat_getkpfnum(9F)get page frame number
for kernel address
inbinb(9F)read from an I/O port
inlinb(9F)read from an I/O port
insqinsq(9F)insert a message into a
queue
inwinb(9F)read from an I/O port
kmem_allockmem_alloc(9F)allocate space from
kernel free memory
kmem_freekmem_free(9F)free previously
allocated kernel memory
kmem_zallockmem_zalloc(9F)allocate and clear
space from kernel free
memory
kstat_createkstat_create(9F)create and initialize a
new kstat
kstat_deletekstat_delete(9F)remove a kstat from the
system
kstat_installkstat_install(9F)add a fully initialized
kstat to the system
kstat_named_initkstat_named_init(9F)initialize a named
kstat
kstat_queuekstat_queue(9F)update I/O kstat
statistics
kstat_runq_back_to_waitqkstat_queue(9F) update I/O kstat
statistics
kstat_runq_enterkstat_queue(9F)update I/O kstat
statistics
kstat_runq_exitkstat_queue(9F)update I/O kstat
statistics
kstat_waitq_enterkstat_queue(9F)update I/O kstat
statistics
kstat_waitq_exitkstat_queue(9F)update I/O kstat
statistics
kstat_waitq_to_runqkstat_queue(9F)update I/O kstat
statistics
linkblinkb(9F)concatenate two message
blocks
makecommakecom(9F)make a packet for SCSI
commands
makecom_g0makecom(9F)make a packet for SCSI
commands
makecom_g0_smakecom(9F)make a packet for SCSI
commands
makecom_g1makecom(9F)make a packet for SCSI
commands
makecom_g5makecom(9F)make a packet for SCSI
commands
makedevicemakedevice(9F)make device number from
major and minor numbers
maxmax(9F)return the larger of
two integers
minmin(9F)return the lesser of
two integers
minphysphysio(9F)perform physical I/O
mod_infomod_install(9F)add, remove or query a
loadable module
mod_installmod_install(9F)add, remove or query a
loadable module
mod_removemod_install(9F)add, remove or query a
loadable module
msgdsizemsgdsize(9F)return the number of
bytes in a message
msgpullupmsgpullup(9F)concatenate bytes in a
message
mt-streamsmt-streams(9F)STREAMS multithreading
mutexmutex(9F)mutual exclusion lock
routines
mutex_destroymutex(9F)mutual exclusion lock
routines
mutex_entermutex(9F)mutual exclusion lock
routines
mutex_exitmutex(9F)mutual exclusion lock
routines
mutex_initmutex(9F)mutual exclusion lock
routines
mutex_ownedmutex(9F)mutual exclusion lock
routines
mutex_tryentermutex(9F)mutual exclusion lock
routines
nochpollnochpoll(9F)error return function
for non-pollable
devices.
nodevnodev(9F)error return function
noenablenoenable(9F)prevent a queue from
being scheduled
nulldevnulldev(9F)zero return function
numtosstoi(9F)convert between an
integer and a decimal
string
otherqOTHERQ(9F)get pointer to queue’s
partner queue
outboutb(9F)write to an I/O port
outloutb(9F)write to an I/O port
outwoutb(9F)write to an I/O port
physiophysio(9F)perform physical I/O
pollwakeuppollwakeup(9F)inform a process that
an event has occurred
proc_refproc_signal(9F)send a signal to a
process
proc_signalproc_signal(9F)send a signal to a
process
proc_unrefproc_signal(9F)send a signal to a
process
ptobptob(9F)convert size in pages
to size in bytes
pullupmsgpullupmsg(9F)concatenate bytes in a
message
putput(9F)call a STREAMS put
procedure
putbqputbq(9F)place a message at the
head of a queue
putctl1putctl1(9F)send a control message
with a one-byte
parameter to a queue
putctlputctl(9F)send a control message
to a queue
putnextputnext(9F)send a message to the
next queue
putnextctl1putnextctl1(9F)send a control message
with a one-byte
parameter to a queue
putnextctlputnextctl(9F)send a control message
to a queue
putqputq(9F)put a message on a
queue
qbufcallqbufcall(9F)call a function when a
buffer becomes
available
qenableqenable(9F)enable a queue
qprocsoffqprocson(9F)enable, disable put and
service routines
qprocsonqprocson(9F)enable, disable put and
service routines
qreplyqreply(9F)send a message on a
stream in the reverse
direction
qsizeqsize(9F)find the number of
messages on a queue
qtimeoutqtimeout(9F)execute a function
after a specified
length of time
qunbufcallqunbufcall(9F)cancel a pending
qbufcall request
quntimeoutquntimeout(9F)cancel previous
qtimeout function call
qwaitqwait(9F)STREAMS wait routines
qwait_sigqwait(9F)STREAMS wait routines
qwriterqwriter(9F)asynchronous STREAMS
perimeter upgrade
rdRD(9F)get pointer to the read
queue
repinsbinb(9F)read from an I/O port
repinsdinb(9F)read from an I/O port
repinswinb(9F)read from an I/O port
repoutsboutb(9F)write to an I/O port
repoutsdoutb(9F)write to an I/O port
repoutswoutb(9F)write to an I/O port
rmallocrmalloc(9F)allocate space from a
resource map
rmalloc_waitrmalloc_wait(9F)allocate space from a
resource map, wait if
necessary
rmallocmaprmallocmap(9F)allocate and free
(respectively) resource
maps
rmfreermfree(9F)free space back into a
resource map
rmfreemaprmallocmap(9F)allocate and free
(respectively) resource
maps
rmvbrmvb(9F)remove a message block
from a message
rmvqrmvq(9F)remove a message from a
queue
rw_destroyrwlock(9F)readers/writer lock
functions
rw_downgraderwlock(9F)readers/writer lock
functions
rw_enterrwlock(9F)readers/writer lock
functions
rw_exitrwlock(9F)readers/writer lock
functions
rw_initrwlock(9F)readers/writer lock
functions
rw_read_lockedrwlock(9F)readers/writer lock
functions
rw_tryenterrwlock(9F)readers/writer lock
functions
rw_tryupgraderwlock(9F)readers/writer lock
functions
rwlockrwlock(9F)readers/writer lock
functions
samestrSAMESTR(9F)test if next queue is
in the same stream
scsi_abortscsi_abort(9F)abort a SCSI command
scsi_alloc_consistent_bufscsi_alloc_consistent_buf(9F)allocate an I/O buffer
for SCSI DMA
scsi_cnamescsi_cname(9F)decode a SCSI name
scsi_destroy_pktscsi_destroy_pkt(9F)free an allocated SCSI
packet and its DMA
resource
scsi_dmafreescsi_dmaget(9F)SCSI dma utility
routines
scsi_dmagetscsi_dmaget(9F)SCSI dma utility
routines
scsi_dnamescsi_cname(9F)decode a SCSI name
scsi_errmsgscsi_errmsg(9F)display a SCSI request
sense message
scsi_free_consistent_bufscsi_free_consistent_buf(9F)free a previously
allocated SCSI DMA I/O
buffer
scsi_hba_attachscsi_hba_attach(9F)SCSI HBA attach and
detach routines
scsi_hba_detachscsi_hba_attach(9F)SCSI HBA attach and
detach routines
scsi_hba_finiscsi_hba_init(9F)SCSI Host Bus Adapter
system initialization
and completion routines
scsi_hba_initscsi_hba_init(9F)SCSI Host Bus Adapter
system initialization
and completion routines
scsi_hba_lookup_capstrscsi_hba_lookup_capstr(9F)return index matching
capability string
scsi_hba_pkt_allocscsi_hba_pkt_alloc(9F)allocate and free a
scsi_pkt structure
scsi_hba_pkt_freescsi_hba_pkt_alloc(9F)allocate and free a
scsi_pkt structure
scsi_hba_probescsi_hba_probe(9F)default SCSI HBA probe
function
scsi_hba_tran_allocscsi_hba_tran_alloc(9F)allocate and free
transport structures
scsi_hba_tran_freescsi_hba_tran_alloc(9F)allocate and free
transport structures
scsi_ifgetcapscsi_ifgetcap(9F)get/set SCSI transport
capability
scsi_ifsetcapscsi_ifgetcap(9F)get/set SCSI transport
capability
scsi_init_pktscsi_init_pkt(9F)prepare a complete SCSI
packet
scsi_logscsi_log(9F)display a
SCSI-device-related
message
scsi_mnamescsi_cname(9F)decode a SCSI name
scsi_pktallocscsi_pktalloc(9F)SCSI packet utility
routines
scsi_pktfreescsi_pktalloc(9F)SCSI packet utility
routines
scsi_pollscsi_poll(9F)run a polled SCSI
command on behalf of a
target driver
scsi_probescsi_probe(9F)utility for probing a
scsi device
scsi_resallocscsi_pktalloc(9F)SCSI packet utility
routines
scsi_resetscsi_reset(9F)reset a SCSI bus or
target
scsi_resfreescsi_pktalloc(9F)SCSI packet utility
routines
scsi_rnamescsi_cname(9F)decode a SCSI name
scsi_slavescsi_slave(9F)utility for SCSI target
drivers to establish
the presence of a
target
scsi_snamescsi_cname(9F)decode a SCSI name
scsi_sync_pktscsi_sync_pkt(9F)synchronize CPU and I/O
views of memory
scsi_transportscsi_transport(9F)request by a SCSI
target driver to start
a command
scsi_unprobescsi_unprobe(9F)free resources
allocated during
initial probing
scsi_unslavescsi_unprobe(9F)free resources
allocated during
initial probing
sema_destroysemaphore(9F)semaphore functions
sema_initsemaphore(9F)semaphore functions
sema_psemaphore(9F)semaphore functions
sema_p_sigsemaphore(9F)semaphore functions
sema_trypsemaphore(9F)semaphore functions
sema_vsemaphore(9F)semaphore functions
semaphoresemaphore(9F)semaphore functions
sprintfsprintf(9F)format characters in
memory
stoistoi(9F)convert between an
integer and a decimal
string
strchrstrchr(9F)find a character in a
string
strcmpstrcmp(9F)compare two null
terminated strings.
strcpystrcpy(9F)copy a string from one
location to another.
strlenstrlen(9F)determine the number of
non-null bytes in a
string.
strlogstrlog(9F)submit messages to the
log driver
strncmpstrcmp(9F)compare two null
terminated strings.
strncpystrcpy(9F)copy a string from one
location to another.
strqgetstrqget(9F)get information about a
queue or band of the
queue
strqsetstrqset(9F)change information
about a queue or band
of the queue
swabswab(9F)swap bytes in 16-bit
halfwords
testbtestb(9F)check for an available
buffer
timeouttimeout(9F)execute a function
after a specified
length of time
uiomoveuiomove(9F)copy kernel data using
uio structure
unbufcallunbufcall(9F)cancel a pending
bufcall request
unfreezestrfreezestr(9F)freeze, thaw the state
of a stream
unlinkbunlinkb(9F)remove a message block
from the head of a
message
untimeoutuntimeout(9F)cancel previous timeout
function call
ureadcureadc(9F)add character to a uio
structure
uwritecuwritec(9F)remove a character from
a uio structure
vcmn_errcmn_err(9F)display an error
message or panic the
system
vsprintfvsprintf(9F)format characters in
memory
wrWR(9F)get pointer to the
write queue for this
module or driver

SunOS 5.4  —  Last change: 28 May 1994