man pages section 9: DDI and DKI Properties and Data Structures Sun Microsystems, Inc. 4150 Network Circle Santa Clara, CA 95054 U.S.A.
Copyright 2002 Sun Microsystems, Inc. 4150 Network Circle, Santa Clara, CA 95054 U.S.A. All rights reserved. This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or document may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers.
Contents Preface 7 Introduction Intro(9S) 13 14 Data Structures for Drivers aio_req(9S) buf(9S) 17 18 19 cb_ops(9S) 22 copyreq(9S) 24 copyresp(9S) datab(9S) 25 26 ddi_device_acc_attr(9S) ddi_dma_attr(9S) 31 ddi_dma_cookie(9S) ddi_dmae_req(9S) 27 34 35 ddi_dma_lim_sparc(9S) ddi_dma_lim_x86(9S) ddi_dma_req(9S) ddi-forceattach(9P) 39 41 43 46 ddi_idevice_cookie(9S) ddi_mapdev_ctl(9S) 47 48 devmap_callback_ctl(9S) dev_ops(9S) 51 fmodsw(9S) 52 49 3
free_rtn(9S) 53 gld_mac_info(9S) gld_stats(9S) 54 57 inquiry-device-type(9P) iocblk(9S) 59 60 iovec(9S) 61 kstat(9S) 62 kstat_intr(9S) 64 kstat_io(9S) 65 kstat_named(9S) linkblk(9S) 66 67 modldrv(9S) 68 modlinkage(9S) 69 modlstrmod(9S) 70 module_info(9S) 71 msgb(9S) 72 no-involuntary-power-cycles(9P) pm(9P) 75 pm-components(9P) qband(9S) 77 80 qinit(9S) 81 queclass(9S) queue(9S) 82 83 removable-media(9P) scsi_address(9S) 84 85 scsi_arq_status(9S) 86 scsi_asc_key_st
Index 111 Contents 5
man pages section 9: DDI and DKI Properties and Data Structures • December 2002
Preface Both novice users and those familar with the SunOS operating system can use online man pages to obtain information about the system and its features. A man page is intended to answer concisely the question “What does it do?” The man pages in general comprise a reference manual. They are not intended to be a tutorial.
■ Section 9 provides reference information needed to write device drivers in the kernel environment. It describes two device driver interface specifications: the Device Driver Interface (DDI) and the Driver⁄Kernel Interface (DKI). ■ Section 9E describes the DDI/DKI, DDI-only, and DKI-only entry-point routines a developer can include in a device driver. ■ Section 9F describes the kernel functions available for use by device drivers.
PROTOCOL This section occurs only in subsection 3R to indicate the protocol description file. DESCRIPTION This section defines the functionality and behavior of the service. Thus it describes concisely what the command does. It does not discuss OPTIONS or cite EXAMPLES. Interactive commands, subcommands, requests, macros, and functions are described under USAGE. IOCTL This section appears on pages in Section 7 only.
one condition can cause the same error, each condition is described in a separate paragraph under the error code. USAGE This section lists special rules, features, and commands that require in-depth explanations. The subsections listed here are used to explain built-in functionality: Commands Modifiers Variables Expressions Input Grammar 10 EXAMPLES This section provides examples of usage or of how to use a command or function.
DIAGNOSTICS This section lists diagnostic messages with a brief explanation of the condition causing the error. WARNINGS This section lists warnings about special conditions which could seriously affect your working conditions. This is not a list of diagnostics. NOTES This section lists additional information that does not belong anywhere else on the page. It takes the form of an aside to the user, covering points of special interest. Critical information is never covered here.
man pages section 9: DDI and DKI Properties and Data Structures • December 2002
Introduction 13
Intro(9S) NAME DESCRIPTION Intro – introduction to kernel data structures and properties Section 9P describes kernel properties used by device drivers. Section 9S describes the data structures used by drivers to share information between the driver and the kernel. See Intro(9E) for an overview of device driver interfaces. In Section 9S, reference pages contain the following headings: ■ ■ ■ ■ ■ ■ NAME summarizes the purpose of the structure or property.
Intro(9S) The following table summarizes structures that are not specific to STREAMS I/O.
Intro(9S) Structure SEE ALSO NOTES 16 Type scsi_hba_tran Solaris DDI scsi_inquiry Solaris DDI scsi_pkt Solaris DDI scsi_status Solaris DDI uio DDI/DKI Intro(9E) Do not declare arrays of structures as the size of the structures can change between releases. Rely only on the structure members listed in this chapter and not on unlisted members or the position of a member in a structure.
Data Structures for Drivers 17
aio_req(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS SEE ALSO 18 aio_req – asynchronous I/O request structure #include #include #include #include Solaris DDI specific (Solaris DDI) An aio_req structure describes an asynchronous I/O request. struct uio*aio_uio; /* uio structure describing the I/O request */ The aio_uio member is a pointer to a uio(9S) structure, describing the I/O transfer request.
buf(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION buf – block I/O data transfer structure #include #include Architecture independent level 1 (DDI/DKI) The buf structure is the basic data structure for block I/O transfers. Each block I/O transfer has an associated buffer header. The header contains all the buffer control and status information. For drivers, the buffer header pointer is the sole argument to a block driver strategy(9E) routine.
buf(9S) B_BUSY Indicates the buffer is in use. The driver must not change this flag unless it allocated the buffer with getrbuf(9F) and no I/O operation is in progress. B_DONE Indicates the data transfer has completed. This flag is read-only. B_ERROR Indicates an I/O transfer error. It is set in conjunction with the b_error field. bioerror(9F) should be used in preference to setting the B_ERROR bit. B_PAGEIO Indicates the buffer is being used in a paged I/O request. See the description of the b_un.
buf(9S) b_error can hold an error code that should be passed as a return code from the driver. b_error is set in conjunction with the B_ERROR bit set in the b_flags member. bioerror(9F) should be used in preference to setting the b_error field. b_private is for the private use of the device driver. b_edev contains the major and minor device numbers of the device accessed.
cb_ops(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION cb_ops – character/block entry points structure #include #include #include Solaris DDI specific (Solaris DDI) cb_ops contains all entry points for drivers that support both character and block entry points. All leaf device drivers supporting direct user process access to a device should declare a cb_ops structure.
cb_ops(9S) STRUCTURE MEMBERS SEE ALSO block/char Function Description c XXprop_op DDI(Sun) c XXaread DDI(Sun) c XXawrite DDI(Sun) int int int int int int int int (*cb_open)(dev_t *devp, int flag, int otyp, cred_t *credp); (*cb_close)(dev_t dev, int flag, int otyp, cred_t *credp); (*cb_strategy)(struct buf *bp);int(*cb_print)(dev_t dev, char *str); (*cb_print)(dev_t dev, char *str); (*cb_dump)(dev_t dev, caddr_t addr, daddr_t blkno, int nblk); (*cb_read)(dev_t dev, struct uio *uiop, cred_t *c
copyreq(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS SEE ALSO 24 copyreq – STREAMS data structure for the M_COPYIN and the M_COPYOUT message types #include Architecture independent level 1 (DDI/DKI) The data structure for the M_COPYIN and the M_COPYOUT message types.
copyresp(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS SEE ALSO copyresp – STREAMS data structure for the M_IOCDATA message type #include Architecture independent level 1 (DDI/DKI) The data structure copyresp is used with the M_IOCDATA message type.
datab(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION datab – STREAMS message data structure #include Architecture independent level 1 (DDI/DKI). The datab structure describes the data of a STREAMS message. The actual data contained in a STREAMS message is stored in a data buffer pointed to by this structure. A msgb (message block) structure includes a field that points to a datab structure.
ddi_device_acc_attr(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS ddi_device_acc_attr – data access attributes structure #include #include Solaris DDI specific (Solaris DDI). The ddi_device_acc_attr structure describes the data access characteristics and requirements of the device. ushort_t uchar_t uchar_t devacc_attr_version; devacc_attr_endian_flags; devacc_attr_dataorder; The devacc_attr_version member identifies the version number of this structure.
ddi_device_acc_attr(9S) one halfword store. It can also batch individual loads. For example, the CPU might turn two consecutive byte loads into one halfword load. DDI_MERGING_OK_ACC also implies re-ordering. DDI_LOADCACHING_OK_ACC The CPU can cache the data it fetches and reuse it until another store occurs. The default behavior is to fetch new data on every load. DDI_LOADCACHING_OK_ACC also implies merging and re-ordering.
ddi_device_acc_attr(9S) Using ddi_device_acc_attr() in ddi_regs_map_setup(9F) (Continued) EXAMPLE 1 */ ddi_regs_map_setup(dip, rnumber, (caddr_t *)&dev_addr, offset, len, &dev_attr, &handle); /* read a 16-bit word command register from the device dev_command = ddi_getw(handle, dev_addr); */ dev_command |= DEV_INTR_ENABLE; /* store a new value back to the device command register ddi_putw(handle, dev_addr, dev_command); EXAMPLE 2 */ Accessing a Device with Different Apertures The following example ill
ddi_device_acc_attr(9S) EXAMPLE 2 Accessing a Device with Different Apertures EXAMPLE 3 Functions That Call Out the Data Word Size (Continued) The following example illustrates the use of the functions that explicitly call out the data word size to override the data size in the device attribute structure.
ddi_dma_attr(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS ddi_dma_attr – DMA attributes structure #include Solaris DDI specific (Solaris DDI). A ddi_dma_attr_t structure describes device– and DMA engine-specific attributes necessary to allocate DMA resources for a device. The driver might have to extend the attributes with bus-specific information, depending on the bus to which the device is connected.
ddi_dma_attr(9S) The dma_attr_burstsizes field describes the possible burst sizes the device’s DMA engine can accept. The format of the data sizes is binary encoded in terms of powers of two. When DMA resources are allocated, the system can modify the burstsizes value to reflect the system limits. The driver must use the allowable burstsizes to program the DMA engine. See ddi_dma_burstsizes(9F). The dma_attr_minxfer field describes the minimum effective DMA access size in units of bytes.
ddi_dma_attr(9S) address by the system in order to perform the transfer. In this case, the underlying platform provides an IOMMU, which translates accesses to these virtual addresses into the proper physical addresses. Some of these platforms also support DMA. DDI_DMA_FORCE_PHYSICAL indicates that the system should return physical rather than virtual I/O addresses if the system supports both. If the system does not support physical DMA, the return value from ddi_dma_alloc_handle(9F) will be DDI_DMA_BADATTR.
ddi_dma_cookie(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS ddi_dma_cookie – DMA address cookie #include Solaris DDI specific (Solaris DDI). The ddi_dma_cookie_t structure contains DMA address information required to program a DMA engine. The structure is filled in by a call to ddi_dma_getwin(9F), ddi_dma_addr_bind_handle(9F), or ddi_dma_buf_bind_handle(9F), to get device-specific DMA transfer information for a DMA request or a DMA window.
ddi_dmae_req(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS ddi_dmae_req – DMA engine request structure #include Solaris IA DDI specific (Solaris IA DDI). A device driver uses the ddi_dmae_req structure to describe the parameters for a DMA channel. This structure contains all the information necessary to set up the channel, except for the DMA memory address and transfer count. The defaults, as specified below, support most standard devices.
ddi_dmae_req(9S) architecture. A driver must determine whether its parent bus nexus supports this feature by examining the scatter/gather list size returned in the dlim_sgllen member of the DMA limit structure returned by the driver’s call to ddi_dmae_getlim(). (See ddi_dma_lim_IA(9S).) If the size of the scatter/gather list is 1, then no chaining is available.
ddi_dmae_req(9S) ■ Second, on some bus architectures, the driver’s nextcookie routine can be called from a high-level interrupt routine. If the cookies were not prefetched, the nextcookie routine would have to call ddi_dma_nextseg() and ddi_dma_segtocookie() from a high-level interrupt routine, which is not recommended.
ddi_dmae_req(9S) ATTRIBUTE TYPE Architecture SEE ALSO 38 ATTRIBUTE VALUE IA eisa(4), isa(4), attributes(5), ddi_dma_segtocookie(9F), ddi_dmae(9F), ddi_dma_lim_IA(9S), ddi_dma_req(9S) man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 1 Jan 1997
ddi_dma_lim_sparc(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION ddi_dma_lim_sparc, ddi_dma_lim – SPARC DMA limits structure #include Solaris SPARC DDI specific (Solaris SPARC DDI). This page describes the SPARC version of the ddi_dma_lim structure. See ddi_dma_lim_x86(9S) for a description of the Intel version of this structure. A ddi_dma_lim structure describes in a generic fashion the possible limitations of a device’s DMA engine.
ddi_dma_lim_sparc(9S) The dlim_minxfer field describes the minimum effective DMA transfer size (in units of bytes). It must be a power of two. This value specifies the minimum effective granularity of the DMA engine. It is distinct from dlim_burstsizes in that it describes the minimum amount of access a DMA transfer will effect.
ddi_dma_lim_x86(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION ddi_dma_lim_x86 – IA DMA limits structure #include Solaris IA DDI specific (Solaris IA DDI) A ddi_dma_lim structure describes in a generic fashion the possible limitations of a device or its DMA engine. This information is used by the system when it attempts to set up DMA resources for a device.
ddi_dma_lim_x86(9S) The dlim_adreg_max field describes an inclusive upper bound for the device’s DMA engine address register. This bound handles a fairly common case where a portion of the address register is simply a latch rather than a full register. For example, the upper 16 bits of a 32–bit address register might be a latch. This splits the address register into a portion that acts as a true address register (lower 16 bits) for a 64–kilobyte segment and a latch (upper 16 bits) to hold a segment number.
ddi_dma_req(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS ddi_dma_req – DMA Request structure #include Solaris DDI specific (Solaris DDI). A ddi_dma_req structure describes a request for DMA resources. A driver can use it to describe forms of allocations and ways to allocate DMA resources for a DMA request.
ddi_dma_req(9S) Many machine implementations make this non-sequential memory access difficult to control in a generic and seamless fashion. Therefore, explicit synchronization steps using ddi_dma_sync(9F) or ddi_dma_free(9F) are required to make the view of a memory object shared between a CPU and a DMA device consistent.
ddi_dma_req(9S) The dmao_type element selects the kind of object described by dmao_obj. It can be set to DMA_OTYP_VADDR, indicating virtual addresses.
ddi-forceattach(9P) NAME DESCRIPTION ddi-forceattach, ddi-no-autodetach – properties controlling driver attach/detach behavior Solaris device drivers are attached by devfsadm(1M) and by the kernel in response to open(2) requests from applications. Drivers not currently in use can be detached when the system experiences memory pressure. The ddi-forceattach and ddi-no-autodetach properties can be used to customize driver attach/detach behavior.
ddi_idevice_cookie(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS ddi_idevice_cookie – device interrupt cookie #include #include Solaris DDI specific (Solaris DDI). The ddi_idevice_cookie_t structure contains interrupt priority and interrupt vector information for a device. This structure is useful for devices having programmable bus-interrupt levels. ddi_add_intr(9F) assigns values to the ddi_idevice_cookie_t structure members.
ddi_mapdev_ctl(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION ddi_mapdev_ctl – device mapping-control structure #include #include Solaris DDI specific (Solaris DDI). Future releases of Solaris will provide this structure for binary and source compatibility. However, for increased functionality, use devmap_callback_ctl(9S) instead. See devmap_callback_ctl(9S) for details.
devmap_callback_ctl(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION devmap_callback_ctl – device mapping-control structure #include Solaris DDI specific (Solaris DDI). A devmap_callback_ctl structure describes a set of callback routines that are called by the system to notify a device driver to manage events on the device mappings created by devmap_setup(9F) or ddi_devmap_segmap(9F).
devmap_callback_ctl(9S) int void SEE ALSO size_t len, uint_t type, uint_t rw); (*devmap_dup)(devmap_cookie_t dhp, void *pvtp, devmap_cookie_t new_dhp, void **new_pvtp); (*devmap_unmap)(devmap_cookie_t dhp, void *pvtp, offset_t off, size_t len, devmap_cookie_t new_dhp1, void **new_pvtp1, devmap_cookie_t new_dhp2, void **new_pvtp2); exit(2), fork(2), mmap(2), munmap(2), devmap(9E), devmap_access(9E), devmap_dup(9E), devmap_map(9E), devmap_unmap(9E), ddi_devmap_segmap(9F), devmap_default_access(9F), devmap_
dev_ops(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION dev_ops – device operations structure #include #include Solaris DDI specific (Solaris DDI). dev_ops contains driver common fields and pointers to the bus_ops and cb_ops(9S). Following are the device functions provided in the device operations structure. All fields must be set at compile time. STRUCTURE MEMBERS devo_rev Driver build version. Set this to DEVO_REV. devo_refcnt Driver reference count. Set this to 0.
fmodsw(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION fmodsw – STREAMS module declaration structure #include #include Solaris DDI specific (Solaris DDI) The fmodsw structure contains information for STREAMS modules. All STREAMS modules must define a fmodsw structure. f_name must match mi_idname in the module_info structure. See module_info(9S). All modules must set the f_flag to D_MP to indicate that they safely allow multiple threads of execution.
free_rtn(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS free_rtn – structure that specifies a driver’s message-freeing routine #include Architecture independent level 1 (DDI/DKI). The free_rtn structure is referenced by the datab structure. When freeb(9F) is called to free the message, the driver’s message-freeing routine (referenced through the free_rtn structure) is called, with arguments, to free the data buffer.
gld_mac_info(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION gld_mac_info – Generic LAN Driver MAC info data structure #include Solaris architecture specific (Solaris DDI). The Generic LAN Driver (GLD) Media Access Control (MAC) information (gld_mac_info) structure is the main data interface between the device-specific driver and GLD. It contains data required by GLD and a pointer to an optional additional driver-specific information structure.
gld_mac_info(9S) Conventionally, this is used as a pointer to private data, pointing to a driver-defined and driver-allocated per-instance data structure. The following group of structure members must be set by the driver before calling gld_register(), and should not thereafter be modified by the driver; gld_register() can use or cache the values of some of these structure members, so changes made by the driver after calling gld_register() might cause unpredicted results.
gld_mac_info(9S) SEE ALSO gldm_addrlen The length in bytes of physical addresses handled by the device. For Ethernet, Token Ring, and FDDI, the value of this structure member should be 6. gldm_saplen The length in bytes of the Service Access Point (SAP) address used by the driver. For GLD-based drivers, this should always be set to -2, to indicate that two-byte SAP values are supported and that the SAP appears after the physical address in a DLSAP address.
gld_stats(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION gld_stats – Generic LAN Driver statistics data structure #include Solaris architecture specific (Solaris DDI). The Generic LAN Driver (GLD) statistics (gld_stats) structure is used to communicate statistics and state information from a GLD-based driver to GLD when returning from a driver’s gldm_get_stats() routine as discussed in gld(9E) and gld(7D).
gld_stats(9S) uint32_t uint32_t uint32_t uint32_t glds_dot5_lost_frame_error glds_dot5_frame_copied_error glds_dot5_token_error glds_dot5_freq_error /* /* /* /* lost_frame_errors */ frame_copied_errors */ token_errors */ freq_errors */ The following structure members are defined for media type DL_FDDI: uint32_t uint32_t uint32_t uint32_t uint32_t uint32_t glds_fddi_mac_error; glds_fddi_mac_lost; glds_fddi_mac_token; glds_fddi_mac_tvx_expired; glds_fddi_mac_late; glds_fddi_mac_ring_op; /* /* /* /* /* /
inquiry-device-type(9P) NAME DESCRIPTION inquiry-device-type, inquiry-vendor-id, inquiry-product-id, inquiry-revision-id – properties from SCSI inquiry data These are optional properties created by the system for SCSI target devices. inquiry-device-type is an integer property. When present, the least significant byte of the value indicates the device type as defined by the SCSI standard. inquiry-vendor-id is a string property.
iocblk(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS SEE ALSO 60 iocblk – STREAMS data structure for the M_IOCTL message type #include Architecture independent level 1 (DDI/DKI). The iocblk data structure is used for passing M_IOCTL messages.
iovec(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS SEE ALSO iovec – data storage structure for I/O using uio #include Architecture independent level 1 (DDI/DKI). An iovec structure describes a data storage area for transfer in a uio(9S) structure. Conceptually, it can be thought of as a base address and length specification.
kstat(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION kstat – kernel statistics structure #include #include #include #include Solaris DDI specific (Solaris DDI) Each kernel statistic (kstat) exported by device drivers consists of a header section and a data section. The kstat structure is the header portion of the statistic. A driver receives a pointer to a kstat structure from a successful call to kstat_create(9F).
kstat(9S) acquire this lock for all of their operations on that kstat. It is up to the kstat provider to decide whether guaranteeing consistent data to kstat clients is sufficiently important to justify the locking cost. Note, however, that most statistic updates already occur under one of the provider’s mutexes. If the provider sets ks_lock to point to that mutex, then kstat data locking is free. ks_lock is really of type (kmutex_t*) and is declared as (void*) in the kstat header.
kstat_intr(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION kstat_intr – structure for interrupt kstats #include #include #include #include Solaris DDI specific (Solaris DDI) Interrupt statistics are kept in the kstat_intr structure. When kstat_create(9F) creates an interrupt kstat, the ks_data field is a pointer to one of these structures. The macro KSTAT_INTR_PTR() is provided to retrieve this field.
kstat_io(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS kstat_io – structure for I/O kstats #include #include #include #include Solaris DDI specific (Solaris DDI) I/O kstat statistics are kept in a kstat_io structure. When kstat_create(9F) creates an I/O kstat, the ks_data field is a pointer to one of these structures. The macro KSTAT_IO_PTR() is provided to retrieve this field.
kstat_named(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS kstat_named – structure for named kstats #include #include #include #include Solaris DDI specific (Solaris DDI) Named kstats are an array of name-value pairs. These pairs are kept in the kstat_named structure. When a kstat is created by kstat_create(9F), the driver specifies how many of these structures will be allocated.
linkblk(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS SEE ALSO linkblk – STREAMS data structure sent to multiplexor drivers to indicate a link #include Architecture independent level 1 (DDI/DKI) The linkblk structure is used to connect a lower Stream to an upper STREAMS multiplexor driver. This structure is used in conjunction with the I_LINK, I_UNLINK, P_LINK, and P_UNLINK ioctl commands. See streamio(7I).
modldrv(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS SEE ALSO modldrv – linkage structure for loadable drivers #include Solaris DDI specific (Solaris DDI) The modldrv structure is used by device drivers to export driver specific information to the kernel. struct mod_ops char struct dev_ops *drv_modops; *drv_link info; *drv_dev_ops; drv_modops Must always be initialized to the address of mod_driverops. This member identifies the module as a loadable driver.
modlinkage(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS SEE ALSO modlinkage – module linkage structure #include Solaris DDI specific (Solaris DDI) The modlinkage structure is provided by the module writer to the routines that install, remove, and retrieve information from a module. See _init(9E), _fini(9E), and _info(9E). int void ml_rev *ml_linkage[4]; ml_rev Is the revision of the loadable modules system. This must have the value MODREV_1 .
modlstrmod(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS SEE ALSO modlstrmod – linkage structure for loadable STREAMS modules #include Solaris DDI specific (Solaris DDI) The modlstrmod structure is used by STREAMS modules to export module specific information to the kernel. struct mod_ops char struct fmodsw *strmod_modops; *strmod_linkinfo; *strmod_fmodsw; strmod_modops Must always be initialized to the address of mod_strmodops.
module_info(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION module_info – STREAMS driver identification and limit value structure #include Architecture independent level 1 (DDI/DKI). When a module or driver is declared, several identification and limit values can be set. These values are stored in the module_info structure. The module_info structure is intended to be read-only.
msgb(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION msgb – STREAMS message block structure #include Architecture independent level 1 (DDI/DKI) A STREAMS message is made up of one or more message blocks, referenced by a pointer to a msgb structure. The b_next and b_prev pointers are used to link messages together on a QUEUE. The b_cont pointer links message blocks together when a message consists of more than one block.
no-involuntary-power-cycles(9P) NAME DESCRIPTION no-involuntary-power-cycles – device property to prevent involuntary power cycles A device that might be damaged by power cycles should export the boolean (zero length) property no-involuntary-power-cycles to notify the system that all power cycles for the device must be under the control of the device driver.
no-involuntary-power-cycles(9P) ATTRIBUTE TYPE Interface stability SEE ALSO ATTRIBUTE VALUE Evolving attributes(5), pm(7D), attach(9E), detach(9E), ddi_prop_create(9F) Writing Device Drivers 74 man pages section 9: DDI and DKI Properties and Data Structures • Last Revised 22 Mar 2001
pm(9P) NAME DESCRIPTION pm – Power Management properties The pm-hardware-state property can be used to influence the behavior of the Power Management framework. Its syntax and interpretation is described below. Note that this property is only interpreted by the system immediately after the device has successfully attached. Changes in the property made by the driver after the driver has attached will not be recognized. pm-hardware-state is a string-valued property.
pm(9P) ATTRIBUTE TYPE Interface stability SEE ALSO ATTRIBUTE VALUE Evolving power.
pm-components(9P) NAME DESCRIPTION pm-components – Power Management device property A device is power manageable if the power consumption of the device can be reduced when it is idle. In general, a power manageable device consists of a number of power manageable hardware units called components. Each component is separately controllable and has its own set of power parameters.
pm-components(9P) names should be descriptive, such as "On," "Off," "Suspend," "Standby," etc. The next component continues the array in the same manner, with a string that starts out NAME=, specifying the beginning of a new component (and its name), followed by specifications of the power levels the component supports. The components must be listed in increasing order according to the component number as interpreted by the driver’s power(9E) routine. (Components are numbered sequentially from 0).
pm-components(9P) ATTRIBUTE TYPE Interface stability SEE ALSO ATTRIBUTE VALUE Evolving power.
qband(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION qband – STREAMS queue flow control information structure #include Architecture independent level 1 (DDI/DKI) The qband structure contains flow control information for each priority band in a queue. The qband structure is defined as type qband_t.
qinit(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS SEE ALSO qinit – STREAMS queue processing procedures structure #include Architecture independent level 1 (DDI/DKI) The qinit structure contains pointers to processing procedures for a QUEUE. The streamtab structure for the module or driver contains pointers to one queue(9S) structure for both upstream and downstream processing.
queclass(9S) NAME SYNOPSIS queclass – a STREAMS macro that returns the queue message class definitions for a given message block #include queclass(mblk_t *bp); INTERFACE LEVEL DESCRIPTION Solaris DDI specific (Solaris DDI) queclass returns the queue message class definition for a given data block pointed to by the message block bp passed in. The message can be either QNORM, a normal priority message, or QPCTL, a high priority message.
queue(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION queue – STREAMS queue structure #include Architecture independent level 1 (DDI/DKI) A STREAMS driver or module consists of two queue structures, one for upstream processing (read) and one for downstream processing (write). This structure is the major building block of a stream.
removable-media(9P) NAME DESCRIPTION removable-media – removable media device property A device that supports removable media—such as CDROM, JAZZ, and ZIP drives—and that supports power management and expects automatic mounting of the device via the volume manager should export the boolean (zero length) property removable-media. This property enables the system to make the power state of the device dependent on the power state of the frame buffer and monitor. See the power.
scsi_address(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION scsi_address – SCSI address structure #include Solaris architecture specific (Solaris DDI) A scsi_address structure defines the addressing components for a SCSI target device. The address of the target device is separated into two components: target number and logical unit number.
scsi_arq_status(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS scsi_arq_status – SCSI auto request sense structure #include Solaris DDI specific (Solaris DDI) When auto request sense has been enabled using scsi_ifsetcap(9F) and the "auto-rqsense" capability, the target driver must allocate a status area in the SCSI packet structure for the auto request sense structure (see scsi_pkt(9S)).
scsi_asc_key_strings(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS SEE ALSO scsi_asc_key_strings – SCSI ASC ASCQ to message structure #include Solaris DDI specific (Solaris DDI). The scsi_asc_key_strings structure stores the ASC and ASCQ codes and a pointer to the related ASCII string. ushort_t asc; ushort_t ascq; char *message; /* ASC code */ /* ASCQ code */ /* ASCII message string */ asc Contains the ASC key code. ascq Contains the ASCQ code.
scsi_device(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS scsi_device – SCSI device structure #include Solaris DDI specific (Solaris DDI). The scsi_device structure stores common information about each SCSI logical unit, including pointers to areas that contain both generic and device specific information. There is one scsi_device structure for each logical unit attached to the system.
scsi_extended_sense(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS scsi_extended_sense – SCSI extended sense structure #include Solaris DDI specific (Solaris DDI). The scsi_extended_sense structure for error codes 0x70 (current errors) and 0x71 (deferred errors) is returned on a successful REQUEST SENSE command. SCSI-2 compliant targets are required to return at least the first 18 bytes of this structure. This structure is part of scsi_device(9S) structure.
scsi_extended_sense(9S) KEY_RECOVERABLE_ERROR Indicates that the last command completed successfully with some recovery action performed by the target. KEY_NOT_READY Indicates that the logical unit addressed cannot be accessed. KEY_MEDIUM_ERROR Indicates that the command terminated with a non-recovered error condition that was probably caused by a flaw on the medium or an error in the recorded data.
scsi_extended_sense(9S) es_add_len indicates the number of additional sense bytes to follow. es_cmd_info contains information that depends on the command that was executed. es_add_code (ASC) indicates further information related to the error or exception condition reported in the sense key field. es_qual_code (ASCQ) indicates detailed information related to the additional sense code. es_fru_code (FRU) indicates a device-specific mechanism to unit that has failed.
scsi_hba_tran(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS scsi_hba_tran – SCSI Host Bus Adapter (HBA) driver transport vector structure #include Solaris architecture specific (Solaris DDI). A scsi_hba_tran_t structure defines vectors that an HBA driver exports to SCSA interfaces so that HBA specific functions can be executed.
scsi_hba_tran(9S) SEE ALSO tran_start The function entry that starts a SCSI command execution on the HBA hardware. tran_reset The function entry that resets a SCSI bus or target device. tran_abort The function entry that aborts one SCSI command, or all pending SCSI commands. tran_getcap The function entry that retrieves a SCSI capability. tran_setcap The function entry that sets a SCSI capability. tran_init_pkt The function entry that allocates a scsi_pkt structure.
scsi_inquiry(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS scsi_inquiry – SCSI inquiry structure #include Solaris DDI specific (Solaris DDI). The scsi_inquiry structure contains 36 required bytes, followed by a variable number of vendor-specific parameters. Bytes 59 through 95, if returned, are reserved for future standardization. This structure is part of scsi_device(9S) structure and typically filled in by scsi_probe(9F).
scsi_inquiry(9S) DTYPE_COMM Communications device. DTYPE_UNKNOWN Unknown or no device type. DTYPE_MASK Mask to isolate Peripheral Device Type field. The following values are appropriate for the Peripheral Qualifier field: DPQ_POSSIBLE The specified peripheral device type is currently connected to this logical unit. If the target cannot determine whether or not a physical device is currently connected, it uses this peripheral qualifier when returning the INQUIRY data.
scsi_inquiry(9S) inq_inq_len is the additional length field that specifies the length in bytes of the parameters. inq_reladdr, if set, indicates that the device supports the relative addressing mode of this logical unit. inq_wbus32, if set, indicates that the device supports 32-bit wide data transfers. inq_wbus16, if set, indicates that the device supports 16-bit wide data transfers. inq_sync, if set, indicates that the device supports synchronous data transfers.
scsi_pkt(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS scsi_pkt – SCSI packet structure #include Solaris DDI specific (Solaris DDI). A scsi_pkt structure defines the packet that is allocated by scsi_init_pkt(9F). The target driver fills in some information, and passes it to scsi_transport(9F) for execution on the target. The host bus adapter (HBA) fills in some other information as the command is processed.
scsi_pkt(9S) will call the function pointed to by this field and pass a pointer to the packet as argument. The callback routine itself is called from interrupt context and must not sleep or call any function that might sleep. pkt_flags Provides additional information about how the target driver expects the command to be executed. See pkt_flag Definitions. pkt_time Will be set by the target driver to represent the maximum time in seconds that this command is allowed to take to complete.
scsi_pkt(9S) FLAG_NOINTR Run command with no command completion callback; command is complete upon return from scsi_transport(9F). FLAG_NODISCON Run command without disconnects. FLAG_NOPARITY Run command without parity checking. FLAG_HTAG Run command as the head-of-queue-tagged command. FLAG_OTAG Run command as an ordered-queue-tagged command. FLAG_STAG Run command as a simple-queue —tagged command. FLAG_SENSING Indicates command is a request sense command. FLAG_HEAD Place command at the head of the queue.
scsi_pkt(9S) pkt_state Definitions: pkt_statistics Definitions: SEE ALSO CMD_NOMSGOUT Target refused to go to message out phase. CMD_XID_FAIL Extended identify message rejected. CMD_IDE_FAIL “Initiator Detected Error” message rejected. CMD_ABORT_FAIL Abort message rejected. CMD_REJECT_FAIL Reject message rejected. CMD_NOP_FAIL “No Operation” message rejected. CMD_PER_FAIL “Message Parity Error” message rejected. CMD_BDR_FAIL “Bus Device Reset" message rejected.
scsi_status(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS scsi_status – SCSI status structure #include Solaris DDI specific (Solaris DDI) The SCSI-2standard defines a status byte that is normally sent by the target to the initiator during the status phase at the completion of each command.
scsi_status(9S) SEE ALSO STATUS_INTERMEDIATE_MET This status is a combination of STATUS_MET and STATUS_INTERMEDIATE. STATUS_RESERVATION_CONFLICT This status is a combination of STATUS_INTERMEDIATE and STATUS_BUSY, and it is returned whenever an initiator attempts to access a logical unit or an extent within a logical unit is reserved.
streamtab(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION streamtab – STREAMS entity declaration structure #include Architecture independent level 1 (DDI/DKI). Each STREAMS driver or module must have a streamtab structure. streamtab is made up of qinit structures for both the read and write queue portions of each module or driver. Multiplexing drivers require both upper and lower qinit structures.
stroptions(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION STRUCTURE MEMBERS stroptions – options structure for M_SETOPTS message #include #include #include #include Architecture independent level 1 (DDI/DKI) The M_SETOPTS message contains a stroptions structure and is used to control options in the stream head.
stroptions(9S) When SO_READOPT is set, the so_readopt field of the stroptions structure can take one of the following values. See read(2). RNORM Read message normal. RMSGD Read message discard. RMSGN Read message, no discard. When SO_BAND is set, so_band determines to which band so_hiwat and so_lowat apply. When SO_ERROPT is set, the so_erropt field of the stroptions structure can take a value that is either none or one of: RERRNORM Persistent read errors; default.
tuple(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION tuple – card information structure (CIS) access structure #include Solaris DDI Specific (Solaris DDI) The tuple_t structure is the basic data structure provided by card services to manage PC card information. A PC card provides identification and configuration information through its card information structure (CIS). A PC card driver accesses a PC card’s CIS through various card services functions.
tuple(9S) cisdata_t cisdata_t TupleCode; TupleLink; /* body tuple data */ /* tuple type code */ /* tuple link */ The fields are defined as follows: Socket Not used in Solaris, but for portability with other card services implementations, it should be set to the logical socket number. Attributes This field is bit-mapped. The following bits are defined: TUPLE_RETURN_LINK Return link tuples if set. TUPLE_RETURN_IGNORED_TUPLES Return ignored tuples if set.
tuple(9S) SEE ALSO csx_GetFirstTuple(9F), csx_GetTupleData(9F), csx_ParseTuple(9F), csx_Parse_CISTPL_BATTERY(9F), csx_Parse_CISTPL_BYTEORDER(9F), csx_Parse_CISTPL_CFTABLE_ENTRY(9F), csx_Parse_CISTPL_CONFIG(9F), csx_Parse_CISTPL_DATE(9F), csx_Parse_CISTPL_DEVICE(9F), csx_Parse_CISTPL_FUNCE(9F), csx_Parse_CISTPL_FUNCID(9F), csx_Parse_CISTPL_JEDEC_C(9F), csx_Parse_CISTPL_MANFID(9F), csx_Parse_CISTPL_SPCL(9F), csx_Parse_CISTPL_VERS_1(9F), csx_Parse_CISTPL_VERS_2(9F) PC Card 95 Standard, PCMCIA/JEIDA 108 man
uio(9S) NAME SYNOPSIS INTERFACE LEVEL DESCRIPTION uio – scatter/gather I/O request structure #include Architecture independent level 1 (DDI/DKI) A uio structure describes an I/O request that can be broken up into different data storage areas (scatter/gather I/O). A request is a list of iovec structures (base-length pairs) indicating where in user space or kernel space the I/O data is to be read or written.
uio(9S) When performing I/O on a seekable device, the driver should not modify either the uio_offset or the uio_loffset field of the uio structure. I/O to such a device is constrained by the maximum offset value. When performing I/O on a device on which the concept of position has no relevance, the driver may preserve the uio_offset or uio_loffset, perform the I/O operation, then restore the uio_offset or uio_loffset to the field’s initial value. I/O performed to a device in this manner is not constrained.
Index A aio_req — asynchronous I/O request structure, 18 asynchronous I/O request structure — aio_req, 18 B buf — block I/O data transfer structure, 19 C Card Information Structure (CIS) access structure — tuple, 106 character/block entry points structure for drivers, — cb_ops, 22 copyreq — STREAMS data structure for the M_COPYIN and the M_COPYOUT message types, 24 copyresp — STREAMS data structure for the M_IOCDATA message type, 25 D data access attributes structure — ddi_device_acc_attr, 27 ddi_device_
DMA Request structure, — ddi_dma_req, 43 driver’s message-freeing routine, — free_rtn, 53 drivers, loadable, linkage structure, — modldrv, 68 M modlinkage — module linkage structure, 69 O options structure for M_SETOPTS message — stroptions, 104 F fmodsw — STREAMS module declaration structure, 52 P G gld_mac_info — GLD mac info data structure, 54 gld_stats — GLD statistics data structure, 57 pm-components— Power Management device property, 77 Power Management device property — pm-component, 77 Q I I/O
scsi_inquiry — SCSI device structure, 94 SCSI packet structure — scsi_pkt, 97 scsi_pkt — SCSI packet structure, 97 pkt_flags Definitions, 98 pkt_reason Definitions, 99 pkt_state Definitions, 100 pkt_statistics Definitions, 100 scsi_status — SCSI status structure, 101 SCSI status structure — scsi_status, 101 STREAMS data structure for the M_COPYIN and the M_COPYOUT message types — copyreq, 24 STREAMS data structure for the M_IOCDATA message type — copyresp, 25 STREAMS data structure for the M_IOCTL message t
man pages section 9: DDI and DKI Properties and Data Structures • December 2002
