NAME

Intro, intro − introduction to Device Driver Interface and Driver Kernel Interface 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.  STREAMS functions may be used in either DDI or DKI. 

The following table summarizes the functions not specific to STREAMS.  Functions can be used in either DDI or DKI, except as noted. 

LIST OF COMMANDS

NameAppears on PageDescription
adjmsgadjmsg(9F)trim bytes from a message
allocballocb(9F)allocate a message block
assertASSERT(9F)expression verification
ASSERTASSERT(9F)expression verification
backqbackq(9F)get pointer to the queue behind
the current queue
bcanputbcanput(9F)test for flow control
bcanputnextcanputnext(9F)test for room in next module’s
message queue
bcmpbcmp(9F)compare two byte arrays
bcopybcopy(9F)copy data between kernel
address locations
biodonebiodone(9F)release buffer after block I/O
biowaitbiowait(9F)suspend processes pending
block I/O completion
bp_mapinbp_mapin(9F)allocate virtual address space
bp_mapoutbp_mapout(9F)deallocate virtual address space
brelsebrelse(9F)return buffer to the bfreelist
btopbtop(9F)convert byte size to page size
(round down)
btoprbtopr(9F)convert byte size to page size
(round up)
bufcallbufcall(9F)call function when 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 error message or panic
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_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 or remove an interrupt
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 dev_info
ddi_dev_is_sidddi_dev_is_sid(9F)tell whether a device is
self-identifying
ddi_dev_nintrsddi_dev_nintrs(9F)return number of interrupt
specifications a device has
ddi_dev_nregsddi_dev_nregs(9F)return 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 DMA mapping
ddi_dma_coffddi_dma_coff(9F)convert a DMA cookie to an
offset within DMA handle
ddi_dma_curwinddi_dma_curwin(9F)report current DMA window
offset and size
ddi_dma_devalignddi_dma_devalign(9F)find post DMA mapping
alignment and minimum effect
properties
ddi_dma_freeddi_dma_free(9F)tear down DMA mappings
ddi_dma_htocddi_dma_htoc(9F)convert a DMA handle to a DMA
addressing 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 or tear down DMA
mappings
ddi_dma_syncddi_dma_sync(9F)synchronize CPU and I/O
views of memory
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
credentials 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
effect for DMA to or from
primary memory
ddi_iopb_allocddi_iopb_alloc(9F)allocate or free memory for DMA
ddi_iopb_freeddi_iopb_alloc(9F)allocate or free memory for DMA
ddi_map_regsddi_map_regs(9F)map or unmap registers
ddi_mem_allocddi_mem_alloc(9F)allocate and free memory for
streaming mode access
ddi_mem_freeddi_mem_alloc(9F)allocate and free memory for
streaming mode access
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 or remove an interrupt
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 process 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)request/free a 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)request/free a 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
insqinsq(9F)insert a message into a queue
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
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 for illegal
entries in device switch tables
noenablenoenable(9F)prevent a queue from being
scheduled
nulldevnulldev(9F)return function for insignificant
entries in device switch tables
numtosstoi(9F)convert between an integer and
a decimal string
otherqOTHERQ(9F)get pointer to queue’s partner
queue
OTHERQOTHERQ(9F)get pointer to queue’s partner
queue
physiophysio(9F)perform physical I/O
pollwakeuppollwakeup(9F)inform a process that an event
has occurred
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
putctlputctl(9F)send a control message to
a queue
putctl1putctl1(9F)send a control message with a
one-byte parameter to a queue
putnextputnext(9F)send a message to the next queue
putnextctlputnextctl(9F)send a control message to a queue
putnextctl1putnextctl1(9F)send a control message with a
one-byte parameter 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)disable, enable put and
service routines
qprocsonqprocson(9F)disable, enable 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
RDRD(9F)get pointer to the read queue
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
SAMESTRSAMESTR(9F)test if next queue is in the
same stream
scsi_abortscsi_abort(9F)abort a 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 consistent 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_ifgetcapscsi_ifgetcap(9F)set/get transport capability
scsi_ifsetcapscsi_ifgetcap(9F)set/get 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 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)target driver asks the host
adapter driver to reset
scsi_resfreescsi_pktalloc(9F)scsi packet utility routines
scsi_rnamescsi_cname(9F)decode a scsi name
scsi_slavescsi_slave(9F)utility for target drivers to
establish the presence of a target
scsi_snamescsi_cname(9F)decode a scsi name
scsi_transportscsi_transport(9F)request by a 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(9S)
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(9F)
function call
ureadcureadc(9F)add character to a uio structure
useraccuseracc(9F)verify whether user has access
to memory
uwritecuwritec(9F)remove a character from a
uio structure
vcmn_errcmn_err(9F)display error message or
panic system
vsprintfvsprintf(9F)format characters in memory
wrWR(9F)get pointer to the write queue for
this module or driver
WRWR(9F)get pointer to the write queue for
this module or driver

Sun Microsystems  —  Last change: 24 Mar 1993