diff options
Diffstat (limited to 'usr/src/man/man9s')
73 files changed, 11946 insertions, 0 deletions
diff --git a/usr/src/man/man9s/Intro.9s b/usr/src/man/man9s/Intro.9s new file mode 100644 index 0000000000..202b8589d6 --- /dev/null +++ b/usr/src/man/man9s/Intro.9s @@ -0,0 +1,196 @@ +'\" te +.\" Copyright (c) 2001, Sun Microsystems, Inc., All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH Intro 9S "15 May 2001" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +Intro, intro \- introduction to kernel data structures and properties +.SH DESCRIPTION +.sp +.LP +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 \fBIntro\fR(9E) for an overview of device driver +interfaces. +.sp +.LP +In Section 9S, reference pages contain the following headings: +.RS +4 +.TP +.ie t \(bu +.el o +\fBNAME\fR summarizes the purpose of the structure or property. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBSYNOPSIS\fR lists the include file that defines the structure or property. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBINTERFACE\fR \fBLEVEL\fR describes any architecture dependencies. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBDESCRIPTION\fR provides general information about the structure or property. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBSTRUCTURE\fR \fBMEMBERS\fR lists all accessible structure members (for +Section 9S). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBSEE\fR \fBALSO\fR gives sources for further information. +.RE +.sp +.LP +Of the preceding headings, Section 9P reference pages contain the \fBNAME\fR, +\fBDESCRIPTION\fR, and \fBSEE\fR \fBALSO\fR fields. +.sp +.LP +Every driver MUST include <\fBsys/ddi.h\fR> and <\fBsys/sunddi.h\fR>, in that +order, and as final entries. +.sp +.LP +The following table summarizes the STREAMS structures described in Section 9S. +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +StructureType +_ +\fBcopyreq\fRDDI/DKI +_ +\fBcopyresp\fRDDI/DKI +_ +\fBdatab\fRDDI/DKI +_ +\fBfmodsw\fRSolaris DDI +_ +\fBfree_rtn\fRDDI/DKI +_ +\fBiocblk\fRDDI/DKI +_ +\fBlinkblk\fRDDI/DKI +_ +\fBmodule_info\fRDDI/DKI +_ +\fBmsgb\fRDDI/DKI +_ +\fBqband\fRDDI/DKI +_ +\fBqinit\fRDDI/DKI +_ +\fBqueclass\fRSolaris DDI +_ +\fBqueue\fRDDI/DKI +_ +\fBstreamtab\fRDDI/DKI +_ +\fBstroptions\fRDDI/DKI +.TE + +.sp +.LP +The following table summarizes structures that are not specific to STREAMS I/O. +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +StructureType +_ +\fBaio_req\fRSolaris DDI +_ +\fBbuf\fRDDI/DKI +_ +\fBcb_ops\fRSolaris DDI +_ +\fBddi_device_acc_attr\fRSolaris DDI +_ +\fBddi_dma_attr\fRSolaris DDI +_ +\fBddi_dma_cookie\fRSolaris DDI +_ +\fBddi_dma_lim_sparc\fRSolaris SPARC DDI +_ +\fBddi_dma_lim_x86\fRSolaris x86 DDI +_ +\fBddi_dma_req\fRSolaris DDI +_ +\fBddi_dmae_req\fRSolaris x86 DDI +_ +\fBddi_idevice_cookie\fRSolaris DDI +_ +\fBddi_mapdev_ctl\fRSolaris DDI +_ +\fBdevmap_callback_ctl\fRSolaris DDI +_ +\fBdev_ops\fRSolaris DDI +_ +\fBiovec\fRDDI/DKI +_ +\fBkstat\fRSolaris DDI +_ +\fBkstat_intr\fRSolaris DDI +_ +\fBkstat_io\fRSolaris DDI +_ +\fBkstat_named\fRSolaris DDI +_ +\fBmap\fRDDI/DKI +_ +\fBmodldrv\fRSolaris DDI +_ +\fBmodlinkage\fRSolaris DDI +_ +\fBmodlstrmod\fRSolaris DDI +_ +\fBscsi_address\fRSolaris DDI +_ +\fBscsi_arq_status\fRSolaris DDI +_ +\fBscsi_device\fRSolaris DDI +_ +\fBscsi_extended_sense\fRSolaris DDI +_ +\fBscsi_hba_tran\fRSolaris DDI +_ +\fBscsi_inquiry\fRSolaris DDI +_ +\fBscsi_pkt\fRSolaris DDI +_ +\fBscsi_status\fRSolaris DDI +_ +\fBuio\fRDDI/DKI +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(9E) +.SH NOTES +.sp +.LP +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. diff --git a/usr/src/man/man9s/Makefile b/usr/src/man/man9s/Makefile new file mode 100644 index 0000000000..e55247938f --- /dev/null +++ b/usr/src/man/man9s/Makefile @@ -0,0 +1,110 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 9s + +MANFILES = Intro.9s \ + aio_req.9s \ + buf.9s \ + cb_ops.9s \ + copyreq.9s \ + copyresp.9s \ + datab.9s \ + ddi_device_acc_attr.9s \ + ddi_dma_attr.9s \ + ddi_dma_cookie.9s \ + ddi_dma_lim_sparc.9s \ + ddi_dma_lim_x86.9s \ + ddi_dma_req.9s \ + ddi_dmae_req.9s \ + ddi_fm_error.9s \ + ddi_idevice_cookie.9s \ + dev_ops.9s \ + devmap_callback_ctl.9s \ + fmodsw.9s \ + free_rtn.9s \ + gld_mac_info.9s \ + gld_stats.9s \ + hook_nic_event.9s \ + hook_pkt_event.9s \ + hook_t.9s \ + iocblk.9s \ + iovec.9s \ + kstat.9s \ + kstat_intr.9s \ + kstat_io.9s \ + kstat_named.9s \ + linkblk.9s \ + modldrv.9s \ + modlinkage.9s \ + modlmisc.9s \ + modlstrmod.9s \ + module_info.9s \ + msgb.9s \ + net_inject_t.9s \ + net_instance_t.9s \ + qband.9s \ + qinit.9s \ + queclass.9s \ + queue.9s \ + scsi_address.9s \ + scsi_arq_status.9s \ + scsi_asc_key_strings.9s \ + scsi_device.9s \ + scsi_extended_sense.9s \ + scsi_hba_tran.9s \ + scsi_inquiry.9s \ + scsi_pkt.9s \ + scsi_status.9s \ + streamtab.9s \ + stroptions.9s \ + tuple.9s \ + uio.9s \ + usb_bulk_request.9s \ + usb_callback_flags.9s \ + usb_cfg_descr.9s \ + usb_client_dev_data.9s \ + usb_completion_reason.9s \ + usb_ctrl_request.9s \ + usb_dev_descr.9s \ + usb_dev_qlf_descr.9s \ + usb_ep_descr.9s \ + usb_if_descr.9s \ + usb_intr_request.9s \ + usb_isoc_request.9s \ + usb_other_speed_cfg_descr.9s \ + usb_request_attributes.9s \ + usb_string_descr.9s + +MANSOFILES = dblk.9s \ + ddi_dma_lim.9s \ + intro.9s \ + mblk.9s + +MANFILES += $(MANSOFILES) + +intro.9s := SOSRC = man9s/Intro.9s + +dblk.9s := SOSRC = man9s/datab.9s + +ddi_dma_lim.9s := SOSRC = man9s/ddi_dma_lim_sparc.9s + +mblk.9s := SOSRC = man9s/msgb.9s + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) diff --git a/usr/src/man/man9s/aio_req.9s b/usr/src/man/man9s/aio_req.9s new file mode 100644 index 0000000000..4fb18dbac7 --- /dev/null +++ b/usr/src/man/man9s/aio_req.9s @@ -0,0 +1,42 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH aio_req 9S "28 Mar 1997" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +aio_req \- asynchronous I/O request structure +.SH SYNOPSIS +.LP +.nf +#include <sys/uio.h> +#include <sys/aio_req.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +An \fBaio_req\fR structure describes an asynchronous \fBI/O \fRrequest. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +struct uio*aio_uio; /* uio structure describing the I/O request */ +.fi +.in -2 + +.sp +.LP +The \fBaio_uio\fR member is a pointer to a \fBuio\fR(9S) structure, describing +the \fBI/O \fRtransfer request. +.SH SEE ALSO +.sp +.LP +\fBaread\fR(9E), \fBawrite\fR(9E), \fBaphysio\fR(9F), \fBuio\fR(9S) diff --git a/usr/src/man/man9s/buf.9s b/usr/src/man/man9s/buf.9s new file mode 100644 index 0000000000..d525bd4e85 --- /dev/null +++ b/usr/src/man/man9s/buf.9s @@ -0,0 +1,242 @@ +'\" te +.\" Copyright (c) 2002 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH buf 9S "19 Sep 2002" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +buf \- block I/O data transfer structure +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI) +.SH DESCRIPTION +.sp +.LP +The \fBbuf\fR structure is the basic data structure for block \fBI/O\fR +transfers. Each block \fBI/O\fR 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 \fBstrategy\fR(9E) +routine. Do not depend on the size of the \fBbuf\fR structure when writing a +driver. +.sp +.LP +A buffer header can be linked in multiple lists simultaneously. Because of +this, most of the members in the buffer header cannot be changed by the driver, +even when the buffer header is in one of the driver's work lists. +.sp +.LP +Buffer headers are also used by the system for unbuffered or physical \fBI/O\fR +for block drivers. In this case, the buffer describes a portion of user data +space that is locked into memory. +.sp +.LP +Block drivers often chain block requests so that overall throughput for the +device is maximized. The \fBav_forw\fR and the \fBav_back\fR members of the +\fBbuf\fR structure can serve as link pointers for chaining block requests. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +int b_flags; /* Buffer status */ +struct buf *av_forw; /* Driver work list link */ +struct buf *av_back; /* Driver work list link */ +size_t b_bcount; /* # of bytes to transfer */ +union { + caddr_t b_addr; /* Buffer's virtual address */ +} b_un; +daddr_t b_blkno; /* Block number on device */ +diskaddr_t b_lblkno; /* Expanded block number on dev. */ +size_t b_resid; /* # of bytes not xferred */ +size_t b_bufsize; /* size of alloc. buffer */ +int (*b_iodone)(struct buf *); /* function called */ + /* by biodone */ +int b_error; /* expanded error field */ +void *b_private; /* "opaque" driver private area */ +dev_t b_edev; /* expanded dev field */ +\fI\fR +.fi +.in -2 + +.sp +.LP +The members of the buffer header available to test or set by a driver are as +follows: +.sp +.LP +\fBb_flags\fR stores the buffer status and indicates to the driver whether to +read or write to the device. The driver must never clear the \fBb_flags\fR +member. If this is done, unpredictable results can occur including loss of disk +sanity and the possible failure of other kernel processes. +.sp +.LP +All \fBb_flags\fR bit values not otherwise specified above are reserved by the +kernel and may not be used. +.sp +.LP +Valid flags are as follows: +.sp +.ne 2 +.mk +.na +\fB\fBB_BUSY\fR \fR +.ad +.RS 13n +.rt +Indicates the buffer is in use. The driver must not change this flag unless it +allocated the buffer with \fBgetrbuf\fR(9F) and no \fBI/O\fR operation is in +progress. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBB_DONE\fR \fR +.ad +.RS 13n +.rt +Indicates the data transfer has completed. This flag is read-only. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBB_ERROR\fR \fR +.ad +.RS 13n +.rt +Indicates an \fBI/O\fR transfer error. It is set in conjunction with the +\fBb_error\fR field. \fBbioerror\fR(9F) should be used in preference to setting +the \fBB_ERROR\fR bit. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBB_PAGEIO\fR \fR +.ad +.RS 13n +.rt +Indicates the buffer is being used in a paged \fBI/O\fR request. See the +description of the \fBb_un.b_addr\fR field for more information. This flag is +read-only. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBB_PHYS\fR \fR +.ad +.RS 13n +.rt +indicates the buffer header is being used for physical (direct) \fBI/O\fR to a +user data area. See the description of the \fBb_un.b_addr\fR field for more +information. This flag is read-only. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBB_READ\fR \fR +.ad +.RS 13n +.rt +Indicates that data is to be read from the peripheral device into main memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBB_WRITE\fR \fR +.ad +.RS 13n +.rt +Indicates that the data is to be transferred from main memory to the peripheral +device. \fBB_WRITE\fR is a pseudo flag and cannot be directly tested; it is +only detected as the NOT form of \fBB_READ\fR. +.RE + +.sp +.LP +\fBav_forw\fR and \fBav_back\fR can be used by the driver to link the buffer +into driver work lists. +.sp +.LP +\fBb_bcount\fR specifies the number of bytes to be transferred in both a paged +and a non-paged \fBI/O\fR request. +.sp +.LP +\fBb_un.b_addr\fR is the virtual address of the \fBI/O\fR request, unless +\fBB_PAGEIO\fR is set. The address is a kernel virtual address, unless +\fBB_PHYS\fR is set, in which case it is a user virtual address. If +\fBB_PAGEIO\fR is set, \fBb_un.b_addr\fR contains kernel private data. Note +that either one of \fBB_PHYS\fR and \fBB_PAGEIO\fR, or neither, can be set, but +not both. +.sp +.LP +\fBb_blkno\fR identifies which logical block on the device (the device is +defined by the device number) is to be accessed. The driver might have to +convert this logical block number to a physical location such as a cylinder, +track, and sector of a disk. This is a 32-bit value. The driver should use +\fBb_blkno\fR or \fBb_lblkno\fR, but not both. +.sp +.LP +\fBb_lblkno\fR identifies which logical block on the device (the device is +defined by the device number) is to be accessed. The driver might have to +convert this logical block number to a physical location such as a cylinder, +track, and sector of a disk. This is a 64-bit value. The driver should use +\fBb_lblkno\fR or \fBb_blkno\fR, but not both. +.sp +.LP +\fBb_resid\fR should be set to the number of bytes not transferred because of +an error. +.sp +.LP +\fBb_bufsize\fR contains the size of the allocated buffer. +.sp +.LP +\fBb_iodone\fR identifies a specific \fBbiodone\fR routine to be called by the +driver when the \fBI/O\fR is complete. +.sp +.LP +\fBb_error\fR can hold an error code that should be passed as a return code +from the driver. \fBb_error\fR is set in conjunction with the \fBB_ERROR\fR bit +set in the \fBb_flags\fR member. \fBbioerror\fR(9F) should be used in +preference to setting the \fBb_error\fR field. +.sp +.LP +\fBb_private\fR is for the private use of the device driver. +.sp +.LP +\fBb_edev\fR contains the major and minor device numbers of the device +accessed. +.SH SEE ALSO +.sp +.LP +\fBstrategy\fR(9E), \fBaphysio\fR(9F), \fBbioclone\fR(9F), \fBbiodone\fR(9F), +\fBbioerror\fR(9F), \fBbioinit\fR(9F), \fBclrbuf\fR(9F), \fBgetrbuf\fR(9F), +\fBphysio\fR(9F), \fBiovec\fR(9S), \fBuio\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +Buffers are a shared resource within the kernel. Drivers should read or write +only the members listed in this section. Drivers that attempt to use +undocumented members of the \fBbuf\fR structure risk corrupting data in the +kernel or on the device. diff --git a/usr/src/man/man9s/cb_ops.9s b/usr/src/man/man9s/cb_ops.9s new file mode 100644 index 0000000000..377c603e3a --- /dev/null +++ b/usr/src/man/man9s/cb_ops.9s @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cb_ops 9S "24 Apr 2008" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +cb_ops \- character/block entry points structure +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBcb_ops\fR structure contains all entry points for drivers that support +both character and block entry points. All leaf device drivers that support +direct user process access to a device should declare a \fBcb_ops\fR structure. +.sp +.LP +All drivers that safely allow multiple threads of execution in the driver at +the same time must set the \fBD_MP\fR flag in the \fBcb_flag\fR field. See +\fBopen\fR(9E). +.sp +.LP +If the driver properly handles 64-bit offsets, it should also set the +\fBD_64BIT\fR flag in the \fBcb_flag\fR field. This specifies that the driver +will use the \fBuio_loffset\fR field of the \fBuio\fR(9S) structure. +.sp +.LP +If the driver returns \fBEINTR\fR from \fBopen\fR(9E), it should also set the +\fBD_OPEN_RETURNS_EINTR\fR flag in the \fBcb_flag\fR field. This lets the +framework know that it is safe for the driver to return \fBEINTR\fR when +waiting, to provide exclusion for a last-reference \fBclose\fR(9E) call to +complete before calling \fBopen\fR(9E). +.sp +.LP +The \fBmt-streams\fR(9F) function describes other flags that can be set in the +\fBcb_flag\fR field. +.sp +.LP +The \fBcb_rev\fR is the \fBcb_ops\fR structure revision number. This field must +be set to \fBCB_REV\fR. +.sp +.LP +Non-\fBSTREAMS\fR drivers should set \fBcb_str\fR to \fINULL\fR. +.sp +.LP +The following \fBDDI\fR/\fBDKI\fR or \fBDKI\fR-only or \fBDDI\fR-only functions +are provided in the character/block driver operations structure. +.sp + +.sp +.TS +tab(); +cw(1.17i) cw(1.36i) cw(1.25i) cw(1.72i) +lw(1.17i) lw(1.36i) lw(1.25i) lw(1.72i) +. +block/charFunctionDescription +_ +b/cXXopen\fBDDI\fR/\fBDKI\fR +b/cXXclose\fBDDI\fR/\fBDKI\fR +bXXstrategyDDI/DKI +bXXprintDDI/DKI +bXXdumpDDI(Sun) +cXXreadDDI/DKI +cXXwriteDDI/DKI +cXXioctlDDI/DKI +cXXdevmapDDI(Sun) +cXXmmapDKI +cXXsegmapDKI +cXXchpollDDI/DKI +cXXprop_opDDI(Sun) +cXXareadDDI(Sun) +cXXawriteDDI(Sun) +.TE + +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +int (*cb_open)(dev_t *devp, int flag, int otyp, cred_t *credp); +int (*cb_close)(dev_t dev, int flag, int otyp, cred_t *credp); +int (*cb_strategy)(struct buf *bp); +int (*cb_print)(dev_t dev, char *str); +int (*cb_dump)(dev_t dev, caddr_t addr, daddr_t blkno, int nblk); +int (*cb_read)(dev_t dev, struct uio *uiop, cred_t *credp); +int (*cb_write)(dev_t dev, struct uio *uiop, cred_t *credp); +int (*cb_ioctl)(dev_t dev, int cmd, intptr_t arg, int mode, + cred_t *credp, int *rvalp); +int (*cb_devmap)(dev_t dev, devmap_cookie_t dhp, offset_t off, + size_t len, size_t *maplen, uint_t model); +int (*cb_mmap)(dev_t dev, off_t off, int prot); +int (*cb_segmap)(dev_t dev, off_t off, struct as *asp, + caddr_t *addrp, off_t len, unsigned int prot, + unsigned int maxprot, unsigned int flags, cred_t *credp); +int (*cb_chpoll)(dev_t dev, short events, int anyyet, + short *reventsp, struct pollhead **phpp); +int (*cb_prop_op)(dev_t dev, dev_info_t *dip, + ddi_prop_op_t prop_op, int mod_flags, + char *name, caddr_t valuep, int *length); +struct streamtab *cb_str; /* streams information */ +int cb_flag; +int cb_rev; +int (*cb_aread)(dev_t dev, struct aio_req *aio, cred_t *credp); +int (*cb_awrite)(dev_t dev, struct aio_req *aio, cred_t *credp); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBaread\fR(9E), \fBawrite\fR(9E), \fBchpoll\fR(9E), \fBclose\fR(9E), +\fBdump\fR(9E), \fBioctl\fR(9E), \fBmmap\fR(9E), \fBopen\fR(9E), +\fBprint\fR(9E), \fBprop_op\fR(9E), \fBread\fR(9E), \fBsegmap\fR(9E), +\fBstrategy\fR(9E), \fBwrite\fR(9E), \fBnochpoll\fR(9F), \fBnodev\fR(9F), +\fBnulldev\fR(9F), \fBdev_ops\fR(9S), \fBqinit\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9s/copyreq.9s b/usr/src/man/man9s/copyreq.9s new file mode 100644 index 0000000000..89a8fc7370 --- /dev/null +++ b/usr/src/man/man9s/copyreq.9s @@ -0,0 +1,43 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc., All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH copyreq 9S "6 October 2000" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +copyreq \- STREAMS data structure for the M_COPYIN and the M_COPYOUT message +types +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI) +.SH DESCRIPTION +.sp +.LP +The data structure for the \fBM_COPYIN\fR and the \fBM_COPYOUT\fR message +types. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +int cq_cmd; /* ioctl command (from ioc_cmd) */ +cred_t *cq_cr; /* full credentials */ +uint_t cq_id; /* ioctl id (from ioc_id) */ +uint_t cq_flag; /* must be zero */ +mblk_t *cq_private; /* private state information */ +caddr_t cq_addr; /* address to copy data to/from */ +size_t cq_size; /* number of bytes to copy */ +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9s/copyresp.9s b/usr/src/man/man9s/copyresp.9s new file mode 100644 index 0000000000..ebdfa93434 --- /dev/null +++ b/usr/src/man/man9s/copyresp.9s @@ -0,0 +1,41 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH copyresp 9S "14 Nov 1996" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +copyresp \- STREAMS data structure for the M_IOCDATA message type +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI) +.SH DESCRIPTION +.sp +.LP +The data structure copyresp is used with the \fBM_IOCDATA\fR message type. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +int cp_cmd; /* ioctl command (from ioc_cmd) */ +cred_t *cp_cr; /* full credentials */ +uint_t cp_id; /* ioctl id (from ioc_id) */ +uint_t cp_flag; /* ioctl flags */ +mblk_t *cp_private; /* private state information */ +caddr_t cp_rval; /* status of request: 0 -> success; + /* non-zero -> failure */ +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9s/datab.9s b/usr/src/man/man9s/datab.9s new file mode 100644 index 0000000000..595edef517 --- /dev/null +++ b/usr/src/man/man9s/datab.9s @@ -0,0 +1,56 @@ +'\" te +.\" Copyright (c) 2003 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH datab 9S "24 Oct 2003" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +datab, dblk \- STREAMS message data structure +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH DESCRIPTION +.sp +.LP +The \fBdatab\fR 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 \fBmsgb\fR (message block) structure includes a field that +points to a \fBdatab\fR structure. +.sp +.LP +Because a data block can have more than one message block pointing to it at one +time, the \fBdb_ref\fR member keeps track of a data block's references, +preventing it from being deallocated until all message blocks are finished with +it. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +unsigned char *db_base; /* first byte of buffer */ +unsigned char *db_lim; /* last byte (+1) of buffer */ +unsigned char db_ref; /* # of message pointers to this data */ +unsigned char db_type; /* message type */ +.fi +.in -2 + +.sp +.LP +A \fBdatab\fR structure is defined as type \fBdblk_t\fR. +.SH SEE ALSO +.sp +.LP +\fBfree_rtn\fR(9S), \fBmsgb\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9s/ddi_device_acc_attr.9s b/usr/src/man/man9s/ddi_device_acc_attr.9s new file mode 100644 index 0000000000..3418a8c609 --- /dev/null +++ b/usr/src/man/man9s/ddi_device_acc_attr.9s @@ -0,0 +1,405 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_device_acc_attr 9S "13 May 2007" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +ddi_device_acc_attr \- data access attributes structure +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBddi_device_acc_attr\fR structure describes the data access +characteristics and requirements of the device. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +ushort_t devacc_attr_version; +uchar_t devacc_attr_endian_flags; +uchar_t devacc_attr_dataorder; +uchar_t devacc_attr_access; +.fi +.in -2 + +.sp +.LP +The \fBdevacc_attr_version\fR member identifies the version number of this +structure. The current version number is \fBDDI_DEVICE_ATTR_V0\fR. +.sp +.LP +The \fBdevacc_attr_endian_flags\fR member describes the endian characteristics +of the device. Specify one of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_NEVERSWAP_ACC\fR\fR +.ad +.RS 24n +.rt +Data access with no byte swapping +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_STRUCTURE_BE_ACC\fR\fR +.ad +.RS 24n +.rt +Structural data access in big-endian format +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_STRUCTURE_LE_ACC\fR\fR +.ad +.RS 24n +.rt +Structural data access in little endian format +.RE + +.sp +.LP +\fBDDI_STRUCTURE_BE_ACC\fR and \fBDDI_STRUCTURE_LE_ACC\fR describe the endian +characteristics of the device as big-endian or little-endian, respectively. +Although most of the devices have the same endian characteristics as their +buses, examples of devices that have opposite endian characteristics of the +buses do exist. When \fBDDI_STRUCTURE_BE_ACC\fR or \fBDDI_STRUCTURE_LE_ACC\fR +is set, byte swapping is automatically performed by the system if the host +machine and the device data formats have opposite endian characteristics. The +implementation can take advantage of hardware platform byte swapping +capabilities. +.sp +.LP +When you specify \fBDDI_NEVERSWAP_ACC\fR, byte swapping is not invoked in the +data access functions. +.sp +.LP +The \fBdevacc_attr_dataorder\fR member describes the order in which the +\fBCPU\fR references data. Specify one of the following values. +.sp +.ne 2 +.mk +.na +\fB\fBDDI_STRICTORDER_ACC\fR\fR +.ad +.RS 27n +.rt +Data references must be issued by a \fBCPU\fR in program order. Strict ordering +is the default behavior. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_UNORDERED_OK_ACC\fR\fR +.ad +.RS 27n +.rt +The \fBCPU\fR can reorder the data references. This includes all kinds of +reordering. For example, a load followed by a store might be replaced by a +store followed by a load. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_MERGING_OK_ACC\fR\fR +.ad +.RS 27n +.rt +The \fBCPU\fR can merge individual stores to consecutive locations. For +example, the \fBCPU\fR can turn two consecutive byte stores into one half-word +store. It can also batch individual loads. For example, the \fBCPU\fR might +turn two consecutive byte loads into one half-word load. +\fBDDI_MERGING_OK_ACC\fR also implies reordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_LOADCACHING_OK_ACC\fR\fR +.ad +.RS 27n +.rt +The \fBCPU\fR can cache the data it fetches and reuse it until another store +occurs. The default behavior is to fetch new data on every load. +\fBDDI_LOADCACHING_OK_ACC\fR also implies merging and reordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_STORECACHING_OK_ACC\fR\fR +.ad +.RS 27n +.rt +The \fBCPU\fR can keep the data in the cache and push it to the device, perhaps +with other data, at a later time. The default behavior is to push the data +right away. \fBDDI_STORECACHING_OK_ACC\fR also implies load caching, merging, +and reordering. +.RE + +.sp +.LP +These values are advisory, not mandatory. For example, data can be ordered +without being merged, or cached, even though a driver requests unordered, +merged, and cached together. +.sp +.LP +The values defined for \fBdevacc_attr_access\fR are: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEFAULT_ACC\fR\fR +.ad +.RS 20n +.rt +If an \fBI/O\fR fault occurs, the system will take the default action, which +might be to panic. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FLAGERR_ACC\fR\fR +.ad +.RS 20n +.rt +Using this value indicates that the driver is hardened: able to cope with the +incorrect results of \fBI/O\fR operations that might result from an \fBI/O\fR +fault. The value also indicates that the driver will use +\fBddi_fm_acc_err_get\fR(9F) to check access handles for faults on a regular +basis. +.sp +If possible, the system should not panic on such an \fBI/O\fR fault, but should +instead mark the \fBI/O\fR handle through which the access was made as having +faulted. +.sp +This value is advisory: it tells the system that the driver can continue in the +face of \fBI/O\fR faults. The value does not guarantee that the system will not +panic, as that depends on the nature of the fault and the capabilities of the +system. It is quite legitimate for an implementation to ignore this flag and +panic anyway. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_CAUTIOUS_ACC\fR\fR +.ad +.RS 20n +.rt +This value indicates that an \fBI/O\fR fault is anticipated and should be +handled as gracefully as possible. For example, the framework should not print +a console message. +.sp +This value should be used when it is not certain that a device is physically +present: for example, when probing. As such, it provides an alternative within +the \fBDDI\fR access framework to the existing peek/poke functions, which don't +use access handles and cannot be integrated easily into a more general +\fBI/O\fR fault handling framework. +.sp +In order to guarantee safe recovery from an \fBI/O\fR fault, it might be +necessary to acquire exclusive access to the parent bus, for example, or to +synchronize across processors on an \fBMP\fR machine. "Cautious" access can be +quite expensive and is only recommended for initial probing and possibly for +additional fault-recovery code. +.RE + +.SH EXAMPLES +.sp +.LP +The following examples illustrate the use of device register address mapping +setup functions and different data access functions. +.LP +\fBExample 1 \fRUsing \fBddi_device_acc_attr()\fR in +>\fBddi_regs_map_setup\fR(9F) +.sp +.LP +This example demonstrates the use of the \fBddi_device_acc_attr()\fR structure +in \fBddi_regs_map_setup\fR(9F). It also shows the use of \fBddi_getw\fR(9F) +and \fBddi_putw\fR(9F) functions in accessing the register contents. + +.sp +.in +2 +.nf +dev_info_t *dip; +uint_t rnumber; +ushort_t *dev_addr; +offset_t offset; +offset_t len; +ushort_t dev_command; +ddi_device_acc_attr_t dev_attr; +ddi_acc_handle_t handle; + +\&.\|.\|. + +/* + * setup the device attribute structure for little endian, + * strict ordering and 16-bit word access. + */ +dev_attr.devacc_attr_version = DDI_DEVICE_ATTR_V0; +dev_attr.devacc_attr_endian_flags = DDI_STRUCTURE_LE_ACC; +dev_attr.devacc_attr_dataorder = DDI_STRICTORDER_ACC; + +/* + * set up the device registers address mapping + */ +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); +.fi +.in -2 + +.LP +\fBExample 2 \fRAccessing a Device with Different Apertures +.sp +.LP +The following example illustrates the steps used to access a device with +different apertures. Several apertures are assumed to be grouped under one +single "reg" entry. For example, the sample device has four different +apertures, each 32 Kbyte in size. The apertures represent \fBYUV\fR +little-endian, \fBYUV\fR big-endian, \fBRGB\fR little-endian, and \fBRGB\fR +big-endian. This sample device uses entry \fB1\fR of the "reg" property list +for this purpose. The size of the address space is 128 Kbyte with each 32 Kbyte +range as a separate aperture. In the register mapping setup function, the +sample driver uses the \fIoffset\fR and \fIlen\fR parameters to specify one of +the apertures. + +.sp +.in +2 +.nf +ulong_t *dev_addr; +ddi_device_acc_attr_t dev_attr; +ddi_acc_handle_t handle; +uchar_t buf[256]; + +\&.\|.\|. + +/* + * setup the device attribute structure for never swap, + * unordered and 32-bit word access. + */ +dev_attr.devacc_attr_version = DDI_DEVICE_ATTR_V0; +dev_attr.devacc_attr_endian_flags = DDI_NEVERSWAP_ACC; +dev_attr.devacc_attr_dataorder = DDI_UNORDERED_OK_ACC; + +/* + * map in the RGB big-endian aperture + * while running in a big endian machine + * - offset 96K and len 32K + */ +ddi_regs_map_setup(dip, 1, (caddr_t *)&dev_addr, 96*1024, 32*1024, + &dev_attr, &handle); + +/* + * Write to the screen buffer + * first 1K bytes words, each size 4 bytes + */ +ddi_rep_putl(handle, buf, dev_addr, 256, DDI_DEV_AUTOINCR); +.fi +.in -2 + +.LP +\fBExample 3 \fRFunctions That Call Out the Data Word Size +.sp +.LP +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. + +.sp +.in +2 +.nf +struct device_blk { + ushort_t d_command; /* command register */ + ushort_t d_status; /* status register */ + ulong d_data; /* data register */ +} *dev_blkp; +dev_info_t *dip; +caddr_t dev_addr; +ddi_device_acc_attr_t dev_attr; +ddi_acc_handle_t handle; +uchar_t buf[256]; + +\&.\|.\|. + +/* + * setup the device attribute structure for never swap, + * strict ordering and 32-bit word access. + */ +dev_attr.devacc_attr_version = DDI_DEVICE_ATTR_V0; +dev_attr.devacc_attr_endian_flags = DDI_NEVERSWAP_ACC; +dev_attr.devacc_attr_dataorder= DDI_STRICTORDER_ACC; + +ddi_regs_map_setup(dip, 1, (caddr_t *)&dev_blkp, 0, 0, + &dev_attr, &handle); + +/* write command to the 16-bit command register */ +ddi_putw(handle, &dev_blkp->d_command, START_XFER); + +/* Read the 16-bit status register */ +status = ddi_getw(handle, &dev_blkp->d_status); + +if (status & DATA_READY) + /* Read 1K bytes off the 32-bit data register */ + ddi_rep_getl(handle, buf, &dev_blkp->d_data, + 256, DDI_DEV_NO_AUTOINCR); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_fm_acc_err_get\fR(9F), \fBddi_getw\fR(9F), +\fBddi_putw\fR(9F), \fBddi_regs_map_setup\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/ddi_dma_attr.9s b/usr/src/man/man9s/ddi_dma_attr.9s new file mode 100644 index 0000000000..0cb26bed70 --- /dev/null +++ b/usr/src/man/man9s/ddi_dma_attr.9s @@ -0,0 +1,350 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_attr 9S "12 Feb 2009" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +ddi_dma_attr \- DMA attributes structure +.SH SYNOPSIS +.LP +.nf +#include <sys/ddidmareq.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +A \fBddi_dma_attr_t\fR structure describes device- and \fBDMA\fR +engine-specific attributes necessary to allocate \fBDMA\fR 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. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +uint_t dma_attr_version; /* version number */ +uint64_t dma_attr_addr_lo; /* low DMA address range */ +uint64_t dma_attr_addr_hi; /* high DMA address range */ +uint64_t dma_attr_count_max; /* DMA counter register */ +uint64_t dma_attr_align; /* DMA address alignment */ +uint_t dma_attr_burstsizes; /* DMA burstsizes */ +uint32_t dma_attr_minxfer; /* min effective DMA size */ +uint64_t dma_attr_maxxfer; /* max DMA xfer size */ +uint64_t dma_attr_seg; /* segment boundary */ +int dma_attr_sgllen; /* s/g list length */ +uint32_t dma_attr_granular; /* granularity of device */ +uint_t dma_attr_flags; /* DMA transfer flags */ +\fI\fR +.fi +.in -2 + +.sp +.LP +The \fBdma_attr_version\fR stores the version number of this \fBDMA\fR +attribute structure. It should be set to \fBDMA_ATTR_V0\fR. +.sp +.LP +The \fBdma_attr_addr_lo\fR and \fBdma_attr_addr_hi\fR fields specify the +address range the device's \fBDMA\fR engine can access. The +\fBdma_attr_addr_lo\fR field describes the inclusive lower 64-bit boundary. The +\fBdma_attr_addr_hi\fR describes the inclusive upper 64-bit boundary. The +system ensures that allocated \fBDMA\fR resources are within the range +specified. See \fBddi_dma_cookie\fR(9S). +.sp +.LP +The \fBdma_attr_count_max\fR describes an inclusive upper bound for the +device's \fBDMA\fR counter register. For example, \fB0xFFFFFF\fR would describe +a \fBDMA\fR engine with a 24-bit counter register. \fBDMA\fR resource +allocation functions have to break up a \fBDMA\fR object into multiple +\fBDMA\fR cookies if the size of the object exceeds the size of the \fBDMA\fR +counter register. +.sp +.LP +The \fBdma_attr_align\fR specifies alignment requirements for allocated +\fBDMA\fR resources. This field can be used to force more restrictive alignment +than imposed by \fBdma_attr_burstsizes\fR or \fBdma_attr_minxfer\fR, such as +alignment at a page boundary. Most drivers set this field to 1, indicating byte +alignment. +.sp +.LP +The \fBdma_attr_align\fR only specifies alignment requirements for allocated +\fBDMA\fR resources. The buffer passed to \fBddi_dma_addr_bind_handle\fR(9F) or +\fBddi_dma_buf_bind_handle\fR(9F) must have an equally restrictive alignment +(see \fBddi_dma_mem_alloc\fR(9F)). +.sp +.LP +The \fBdma_attr_burstsizes\fR field describes the possible burst sizes the +\fBDMA\fR engine of a device can accept. The format of the data sizes is +binary, encoded in terms of powers of two. When \fBDMA\fR resources are +allocated, the system can modify the \fBburstsizes\fR value to reflect the +system limits. The driver must use the allowable \fBburstsizes\fR to program +the \fBDMA\fR engine. See \fBddi_dma_burstsizes\fR(9F). +.sp +.LP +The \fBdma_attr_minxfer\fR field describes the minimum effective \fBDMA\fR +access size in units of bytes. \fBDMA\fR resources can be modified, depending +on the presence and use of \fBI/O\fR caches and write buffers between the +\fBDMA\fR engine and the memory object. This field is used to determine +alignment and padding requirements for \fBddi_dma_mem_alloc\fR(9F). +.sp +.LP +The \fBdma_attr_maxxfer\fR field describes the maximum effective \fBDMA\fR +access size in units of bytes. +.sp +.LP +The \fBdma_attr_seg\fR field specifies segment boundary restrictions for +allocated \fBDMA\fR resources. The system allocates \fBDMA\fR resources for the +device so that the object does not span the segment boundary specified by +\fBdma_attr_seg\fR. For example, a value of \fB0xFFFF\fR means \fBDMA\fR +resources must not cross a 64-Kbyte boundary. \fBDMA\fR resource allocation +functions might have to break up a \fBDMA\fR object into multiple \fBDMA\fR +cookies to enforce segment boundary restrictions. In this case, the transfer +must be performed using scatter-gather \fBI/O\fR or multiple \fBDMA\fR windows. +.sp +.LP +The \fBdma_attr_sgllen\fR field describes the length of the \fBDMA\fR +scatter/gather list of a device. Possible values are as follows: +.sp +.ne 2 +.mk +.na +\fB\fB< 0\fR\fR +.ad +.RS 7n +.rt +Device \fBDMA\fR engine is not constrained by the size, for example, +with\fBDMA\fR chaining. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB= 0\fR\fR +.ad +.RS 7n +.rt +Reserved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB= 1\fR\fR +.ad +.RS 7n +.rt +Device \fBDMA\fR engine does not support scatter/gather such as third party +\fBDMA\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB> 1\fR\fR +.ad +.RS 7n +.rt +Device \fBDMA\fR engine uses scatter/gather. The \fBdma_attr_sgllen\fR value is +the maximum number of entries in the list. +.RE + +.sp +.LP +The \fBdma_attr_granular\fR field describes the granularity of the device +transfer size in units of bytes. When the system allocates \fBDMA\fR resources, +the size of a single segment is a multiple of the device granularity. If +\fBdma_attr_sgllen\fR is larger than \fB1\fR within a window, the sum of the +sizes for a subgroup of segments is a multiple of the device granularity. +.sp +.LP +All driver requests for \fBDMA\fR resources must be a multiple of the +granularity of the device transfer size. +.sp +.LP +The \fBdma_attr_flags\fR field can be set to a combination of: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_FORCE_PHYSICAL\fR\fR +.ad +.sp .6 +.RS 4n +Some platforms, such as SPARC systems, support what is called Direct Virtual +Memory Access (\fBDVMA\fR). On these platforms, the device is provided with a +virtual address by the system in order to perform the transfer. In this case, +the underlying platform provides an \fIIOMMU\fR, which translates accesses to +these virtual addresses into the proper physical addresses. Some of these +platforms also support \fBDMA.\fR \fBDDI_DMA_FORCE_PHYSICAL\fR indicates that +the system should return physical rather than virtual \fBI/O\fR addresses if +the system supports both. If the system does not support physical \fBDMA\fR, +the return value from \fBddi_dma_alloc_handle\fR(9F) is \fBDDI_DMA_BADATTR.\fR +In this case, the driver has to clear \fBDDI_DMA_FORCE_PHYSICAL\fR and retry +the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_FLAGERR\fR\fR +.ad +.sp .6 +.RS 4n +Using this value indicates that the driver is hardened: able to cope with the +incorrect results of \fBDMA\fR operations that might result from an \fBI/O\fR +fault. The value also indicates that the driver will use +\fBddi_fm_dma_err_get\fR(9F) to check \fBDMA\fR handles for faults on a regular +basis. +.sp +If a \fBDMA\fR error is detected during a \fBDMA\fR access to an area mapped by +such a handle, the system should not panic if possible, but should instead mark +the \fBDMA\fR handle as having faulted. +.sp +This value is advisory: it tells the system that the driver can continue in the +face of \fBI/O\fR faults. It does not guarantee that the system will not panic, +as that depends on the nature of the fault and the capabilities of the system. +It is quite legitimate for an implementation to ignore this flag and panic +anyway. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_RELAXED_ORDERING\fR\fR +.ad +.sp .6 +.RS 4n +This optional flag can be set if the \fBDMA\fR transactions associated with +this handle are not required to observe strong \fBDMA\fR write ordering among +themselves, nor with \fBDMA\fR write transactions of other handles. +.sp +The flag allows the host bridge to transfer data to and from memory more +efficiently and might result in better \fBDMA\fR performance on some platforms. +.sp +Drivers for devices with hardware support, such as marking the bus transactions +relaxed ordered, should not use this flag. Such drivers should use the hardware +capability instead. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRInitializing the \fBddi_dma_attr_t\fR Structure +.sp +.LP +Assume a device has the following \fBDMA\fR characteristics: +.RS +4 +.TP +.ie t \(bu +.el o +Full 32-bit range addressable +.RE +.RS +4 +.TP +.ie t \(bu +.el o +24-bit DMA counter register +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Byte alignment +.RE +.RS +4 +.TP +.ie t \(bu +.el o +4- and 8-byte burst sizes support +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Minimum effective transfer size of 1 bytes +.RE +.RS +4 +.TP +.ie t \(bu +.el o +64 Mbyte minus 1 (26-bit) maximum transfer size limit +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Maximum segment size of 32 Kbyte +.RE +.RS +4 +.TP +.ie t \(bu +.el o +17 scatter/gather list elements +.RE +.RS +4 +.TP +.ie t \(bu +.el o +512-byte device transfer size granularity +.RE +.sp +.LP +The corresponding \fBddi_dma_attr_t\fR structure is initialized as follows: + +.sp +.in +2 +.nf +static ddi_dma_attr_t dma_attrs = { + DMA_ATTR_V0 /* version number */ + (uint64_t)0x0, /* low address */ + (uint64_t)0xffffffff, /* high address */ + (uint64_t)0xffffff, /* DMA counter max */ + (uint64_t)0x1 /* alignment */ + 0x0c, /* burst sizes */ + 0x1, /* minimum transfer size */ + (uint64_t)0x3ffffff, /* maximum transfer size */ + (uint64_t)0x7fff, /* maximum segment size */ + 17, /* scatter/gather list lgth */ + 512 /* granularity */ + 0 /* DMA flags */ +}; +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_dma_addr_bind_handle\fR(9F), +\fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), +\fBddi_dma_burstsizes\fR(9F), \fBddi_dma_mem_alloc\fR(9F), +\fBddi_dma_nextcookie\fR(9F), \fBddi_fm_dma_err_get\fR(9F), +\fBddi_dma_cookie\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/ddi_dma_cookie.9s b/usr/src/man/man9s/ddi_dma_cookie.9s new file mode 100644 index 0000000000..024443027a --- /dev/null +++ b/usr/src/man/man9s/ddi_dma_cookie.9s @@ -0,0 +1,85 @@ +'\" te +.\" Copyright (c) 2000 Sun Microsystems, Inc., All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_cookie 9S "30 Sep 1996" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +ddi_dma_cookie \- DMA address cookie +.SH SYNOPSIS +.LP +.nf +#include <sys/sunddi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_cookie_t\fR structure contains \fBDMA\fR address information +required to program a \fBDMA\fR engine. The structure is filled in by a call to +\fBddi_dma_getwin\fR(9F), \fBddi_dma_addr_bind_handle\fR(9F), or +\fBddi_dma_buf_bind_handle\fR(9F), to get device-specific \fBDMA\fR transfer +information for a \fBDMA\fR request or a \fBDMA\fR window. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +typedef struct { + union { + uint64_t _dmac_ll; /* 64 bit DMA add. */ + uint32_t _dmac_la[2]; /* 2 x 32 bit add. */ + } _dmu; + size_t dmac_size; /* DMA cookie size */ + uint_t dmac_type; /* bus spec. type bits */ +} ddi_dma_cookie_t; +.fi +.in -2 + +.sp +.LP +You can access the DMA address through the \fB#define\fRs: \fBdmac_address\fR +for 32-bit addresses and \fBdmac_laddress\fR for 64-bit addresses. These macros +are defined as follows: +.sp +.in +2 +.nf +#define dmac_laddress _dmu._dmac_ll +#ifdef _LONG_LONG_HTOL +#define dmac_notused _dmu._dmac_la[0] +#define dmac_address _dmu._dmac_la[1] +#else +#define dmac_address _dmu._dmac_la[0] +#define dmac_notused _dmu._dmac_la[1] +#endif +.fi +.in -2 + +.sp +.LP +\fBdmac_laddress\fR specifies a 64-bit \fBI/O\fR address appropriate for +programming the device's \fBDMA\fR engine. If a device has a 64-bit \fBDMA\fR +address register a driver should use this field to program the \fBDMA\fR +engine. \fBdmac_address\fR specifies a 32-bit \fBI/O\fR address. It should be +used for devices that have a 32-bit \fBDMA\fR address register. The \fBI/O\fR +address range that the device can address and other \fBDMA\fR attributes have +to be specified in a \fBddi_dma_attr\fR(9S) structure. +.sp +.LP +\fBdmac_size\fR describes the length of the transfer in bytes. +.sp +.LP +\fBdmac_type\fR contains bus-specific type bits, if appropriate. For example, a +device on a \fBPCI\fR bus has \fBPCI\fR address modifier bits placed here. +.SH SEE ALSO +.sp +.LP +\fBpci\fR(4), \fBsbus\fR(4), \fBsysbus\fR(4), +\fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), +\fBddi_dma_getwin\fR(9F), \fBddi_dma_nextcookie\fR(9F), \fBddi_dma_attr\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/ddi_dma_lim_sparc.9s b/usr/src/man/man9s/ddi_dma_lim_sparc.9s new file mode 100644 index 0000000000..9f5ae88373 --- /dev/null +++ b/usr/src/man/man9s/ddi_dma_lim_sparc.9s @@ -0,0 +1,130 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_lim_sparc 9S "12 Oct 2005" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +ddi_dma_lim_sparc, ddi_dma_lim \- SPARC DMA limits structure +.SH SYNOPSIS +.LP +.nf +#include <sys/ddidmareq.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris SPARC DDI specific (Solaris SPARC DDI). These interfaces are obsolete. +.SH DESCRIPTION +.sp +.LP +This page describes the SPARC version of the \fBddi_dma_lim\fR structure. See +\fBddi_dma_lim_x86\fR(9S) for a description of the x86 version of this +structure. +.sp +.LP +A \fBddi_dma_lim\fR structure describes in a generic fashion the possible +limitations of a device's \fBDMA\fR engine. This information is used by the +system when it attempts to set up \fBDMA\fR resources for a device. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +uint_t dlim_addr_lo; /* low range of 32 bit + addressing capability */ +uint_t dlim_addr_hi; /* inclusive upper bound of address. + capability */ +uint_t dlim_cntr_max; /* inclusive upper bound of + dma engine address limit * / +uint_t dlim_burstsizes; /* binary encoded dma burst sizes */ +uint_t dlim_minxfer; /* minimum effective dma xfer size */ +uint_t dlim_dmaspeed; /* average dma data rate (kb/s) */ +.fi +.in -2 + +.sp +.LP +The \fBdlim_addr_lo\fR and \fBdlim_addr_hi\fR fields specify the address range +the device's \fBDMA\fR engine can access. The \fBdlim_addr_lo\fR field +describes the lower 32-bit boundary of the device's \fBDMA\fR engine, the +\fBdlim_addr_hi\fR describes the inclusive upper 32-bit boundary. The system +allocates \fBDMA\fR resources in a way that the address for programming the +device's \fBDMA\fR engine (see \fBddi_dma_cookie\fR(9S) or +\fBddi_dma_htoc\fR(9F)) is within this range. For example, if your device can +access the whole 32-bit address range, you may use [\fB0\fR,\fB0xFFFFFFFF\fR]. +If your device has just a 16-bit address register but will access the top of +the 32-bit address range, then [\fB0xFFFF0000\fR,\fB0xFFFFFFFF\fR] is the +right limit. +.sp +.LP +The \fBdlim_cntr_max\fR field describes an inclusive upper bound for the +device's \fBDMA\fR engine address register. This handles a fairly common case +where a portion of the address register is only a latch rather than a full +register. For example, the upper 8 bits of a 32-bit address register can be a +latch. This splits the address register into a portion that acts as a true +address register (24 bits) for a 16 Mbyte segment and a latch (8 bits) to hold +a segment number. To describe these limits, specify \fB0xFFFFFF\fR in the +\fBdlim_cntr_max\fR structure. +.sp +.LP +The \fBdlim_burstsizes\fR field describes the possible burst sizes the device's +\fBDMA\fR engine can accept. At the time of a \fBDMA\fR resource request, this +element defines the possible \fBDMA\fR burst cycle sizes that the requester's +\fBDMA\fR engine can handle. The format of the data is binary encoding of burst +sizes assumed to be powers of two. That is, if a \fBDMA\fR engine is capable of +doing 1-, 2-, 4-, and 16-byte transfers, the encoding ix 0x17. If the device is +an SBus device and can take advantage of a 64-bit SBus, the lower 16 bits are +used to specify the burst size for 32-bit transfers and the upper 16 bits are +used to specify the burst size for 64-bit transfers. As the resource request is +handled by the system, the \fBburstsizes\fR value can be modified. Prior to +enabling \fBDMA\fR for the specific device, the driver that owns the \fBDMA\fR +engine should check (using \fBddi_dma_burstsizes\fR(9F)) what the allowed +\fBburstsizes\fR have become and program the \fBDMA\fR engine appropriately. +.sp +.LP +The \fBdlim_minxfer\fR field describes the minimum effective \fBDMA\fR transfer +size (in units of bytes). It must be a power of two. This value specifies the +minimum effective granularity of the \fBDMA\fR engine. It is distinct from +\fBdlim_burstsizes\fR in that it describes the minimum amount of access a +\fBDMA\fR transfer will effect. \fBdlim_burstsizes\fR describes in what +electrical fashion the \fBDMA\fR engine might perform its accesses, while +\fBdlim_minxfer\fR describes the minimum amount of memory that can be touched +by the \fBDMA\fR transfer. As a resource request is handled by the system, the +\fBdlim_minxfer\fR value can be modified contingent upon the presence (and use) +of \fBI/O \fRcaches and \fBDMA\fR write buffers in between the \fBDMA\fR engine +and the object that \fBDMA\fR is being performed on. After \fBDMA\fR resources +have been allocated, the resultant minimum transfer value can be gotten using +\fBddi_dma_devalign\fR(9F). +.sp +.LP +The field \fBdlim_dmaspeed\fR is the expected average data rate for the +\fBDMA\fR engine (in units of kilobytes per second). Note that this should not +be the maximum, or peak, burst data rate, but a reasonable guess as to the +average throughput. This field is entirely optional and can be left as zero. +Its intended use is to provide some hints about how much of the \fBDMA\fR +resource this device might need. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_dma_addr_setup\fR(9F), \fBddi_dma_buf_setup\fR(9F), +\fBddi_dma_burstsizes\fR(9F), \fBddi_dma_devalign\fR(9F), +\fBddi_dma_htoc\fR(9F), \fBddi_dma_setup\fR(9F), \fBddi_dma_cookie\fR(9S), +\fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S) diff --git a/usr/src/man/man9s/ddi_dma_lim_x86.9s b/usr/src/man/man9s/ddi_dma_lim_x86.9s new file mode 100644 index 0000000000..5e6799c0e7 --- /dev/null +++ b/usr/src/man/man9s/ddi_dma_lim_x86.9s @@ -0,0 +1,149 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_lim_x86 9S "12 Oct 2005" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +ddi_dma_lim_x86 \- x86 DMA limits structure +.SH SYNOPSIS +.LP +.nf +#include <sys/ddidmareq.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris x86 DDI specific (Solaris x86 DDI). This interface is obsolete. +.SH DESCRIPTION +.sp +.LP +A \fBddi_dma_lim\fR structure describes in a generic fashion the possible +limitations of a device or its \fBDMA\fR engine. This information is used by +the system when it attempts to set up \fBDMA\fR resources for a device. When +the system is requested to perform a \fBDMA\fR transfer to or from an object, +the request is broken up, if necessary, into multiple sub-requests. Each +sub-request conforms to the limitations expressed in the \fBddi_dma_lim\fR +structure. +.sp +.LP +This structure should be filled in by calling the routine +\fBddi_dmae_getlim\fR(9F). This routine sets the values of the structure +members appropriately based on the characteristics of the \fBDMA\fR engine on +the driver's parent bus. If the driver has additional limitations, it can +\fIfurther restrict\fR some of the values in the structure members. A driver +should \fInot relax\fR any restrictions imposed by \fBddi_dmae_getlim()\fR. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +uint_t dlim_addr_lo; /* low range of 32 bit + addressing capability */ +uint_t dlim_addr_hi; /* inclusive upper bound of + addressing capability */ +uint_t dlim_minxfer; /* minimum effective dma transfer size */ +uint_t dlim_version; /* version number of structure */ +uint_t dlim_adreg_max; /* inclusive upper bound of + incrementing addr reg */ +uint_t dlim_ctreg_max; /* maximum transfer count minus one */ +uint_t dlim_granular; /* granularity (and min size) of + transfer count */ +short dlim_sgllen; /* length of DMA scatter/gather list */ +uint_t dlim_reqsize; /* maximum transfer size in bytes of + a single I/O */ +.fi +.in -2 + +.sp +.LP +The \fBdlim_addr_lo\fR and \fBdlim_addr_hi\fR fields specify the address range +that the device's \fBDMA\fR engine can access. The \fBdlim_addr_lo\fR field +describes the lower 32-bit boundary of the device's \fBDMA\fR engine. The +\fBdlim_addr_hi\fR member describes the inclusive, upper 32-bit boundary. The +system allocates \fBDMA\fR resources in a way that the address for programming +the device's \fBDMA\fR engine will be within this range. For example, if your +device can access the whole 32-bit address range, you can use +[\fB0,0xFFFFFFFF\fR]. See \fBddi_dma_cookie\fR(9S) or +\fBddi_dma_segtocookie\fR(9F). +.sp +.LP +The \fBdlim_minxfer\fR field describes the minimum effective \fBDMA\fR transfer +size (in units of bytes), which must be a power of two. This value specifies +the minimum effective granularity of the \fBDMA\fR engine and describes the +minimum amount of memory that can be touched by the \fBDMA\fR transfer. As a +resource request is handled by the system, the \fBdlim_minxfer\fR value can be +modified. This modification is contingent upon the presence (and use) of +\fBI/O\fRcaches and \fBDMA\fR write buffers between the \fBDMA\fR engine and +the object that \fBDMA\fR is being performed on. After \fBDMA\fR resources have +been allocated, you can retrieve the resultant minimum transfer value using +\fBddi_dma_devalign\fR(9F). +.sp +.LP +The \fBdlim_version\fR field specifies the version number of this structure. +Set this field to \fBDMALIM_VER0\fR. +.sp +.LP +The \fBdlim_adreg_max\fR field describes an inclusive upper bound for the +device's \fBDMA\fR 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. To describe these limits, you specify +\fB0xFFFF\fR in the \fBdlim_adreg_max\fR structure member. +.sp +.LP +The \fBdlim_ctreg_max\fR field specifies the maximum transfer count that the +\fBDMA\fR engine can handle in one segment or cookie. The limit is expressed +as the maximum count minus one. This transfer count limitation is a per-segment +limitation. Because the limitation is used as a bit mask, it must be one less +than a power of two. +.sp +.LP +The \fBdlim_granular\fR field describes the granularity of the device's +\fBDMA\fR transfer ability, in units of bytes. This value is used to specify, +for example, the sector size of a mass storage device. \fBDMA\fR requests are +broken into multiples of this value. If there is no scatter/gather capability, +then the size of each \fBDMA\fR transfer will be a multiple of this value. If +there is scatter/gather capability, then a single segment cannot be smaller +than the minimum transfer value, but can be less than the granularity. However, +the total transfer length of the scatter/gather list is a multiple of the +granularity value. +.sp +.LP +The \fBdlim_sgllen\fR field specifies the maximum number of entries in the +scatter/gather list. This value is the number of segments or cookies that the +\fBDMA\fR engine can consume in one I/O request to the device. If the \fBDMA\fR +engine has no scatter/gather list, set this field to one. +.sp +.LP +The \fBdlim_reqsize\fR field describes the maximum number of bytes that the +\fBDMA\fR engine can transmit or receive in one I/O command. This limitation is +only significant if it is less than ( \fBdlim_ctreg_max\fR +1) * +\fBdlim_sgllen\fR. If the \fBDMA\fR engine has no particular limitation, set +this field to \fB0xFFFFFFFF\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_dmae\fR(9F), \fBddi_dma_addr_setup\fR(9F), \fBddi_dma_buf_setup\fR(9F), +\fBddi_dma_devalign\fR(9F), \fBddi_dma_segtocookie\fR(9F), +\fBddi_dma_setup\fR(9F), \fBddi_dma_cookie\fR(9S), \fBddi_dma_lim_sparc\fR(9S), +\fBddi_dma_req\fR(9S) diff --git a/usr/src/man/man9s/ddi_dma_req.9s b/usr/src/man/man9s/ddi_dma_req.9s new file mode 100644 index 0000000000..f0062f8a41 --- /dev/null +++ b/usr/src/man/man9s/ddi_dma_req.9s @@ -0,0 +1,227 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_req 9S "12 Oct 2005" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +ddi_dma_req \- DMA Request structure +.SH SYNOPSIS +.LP +.nf +#include <sys/ddidmareq.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). This interface is obsolete. +.SH DESCRIPTION +.sp +.LP +A \fBddi_dma_req\fR structure describes a request for \fBDMA\fR resources. A +driver can use it to describe forms of allocations and ways to allocate +\fBDMA\fR resources for a \fBDMA\fR request. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +ddi_dma_lim_t *dmar_limits; /* Caller's dma engine + constraints */ +uint_t dmar_flags; /* Contains info for + mapping routines */ +int (*dmar_fp)(caddr_t);/* Callback function */ +caddr_t dmar_arg; /* Callback function's argument */ +ddi_dma_obj_t dmar_object; /* Descrip. of object + to be mapped */ +.fi +.in -2 + +.sp +.LP +For the definition of the \fBDMA\fR limits structure, which \fBdmar_limits\fR +points to, see \fBddi_dma_lim_sparc\fR(9S) or \fBddi_dma_lim_x86\fR(9S). +.sp +.LP +Valid values for \fBdmar_flags\fR are: +.sp +.in +2 +.nf +DDI_DMA_WRITE /* Direction memory --> IO */ +DDI_DMA_READ /* Direction IO --> memory */ +DDI_DMA_RDWR /* Both read and write */ +DDI_DMA_REDZONE /* Establish MMU redzone at end of mapping */ +DDI_DMA_PARTIAL /* Partial mapping is allowed */ +DDI_DMA_CONSISTENT /* Byte consistent access wanted */ +DDI_DMA_SBUS_64BIT /* Use 64 bit capability on SBus */ +.fi +.in -2 + +.sp +.LP +\fBDDI_DMA_WRITE\fR, \fBDDI_DMA_READ\fR, and \fBDDI_DMA_RDWR\fR describe the +intended direction of the \fBDMA \fRtransfer. Some implementations might +explicitly disallow \fBDDI_DMA_RDWR\fR. +.sp +.LP +\fBDDI_DMA_REDZONE\fR asks the system to establish a protected \fBred zone\fR +after the object. The \fBDMA\fR resource allocation functions do not guarantee +the success of this request, as some implementations might not have the +hardware ability to support it. +.sp +.LP +\fBDDI_DMA_PARTIAL\fR lets the system know that the caller can accept partial +mapping. That is, if the size of the object exceeds the resources available, +the system allocates only a portion of the object and returns status indicating +this partial allocation. At a later point, the caller can use +\fBddi_dma_curwin\fR(9F) and \fBddi_dma_movwin\fR(9F) to change the valid +portion of the object that has resources allocated. +.sp +.LP +\fBDDI_DMA_CONSISTENT\fR gives a hint to the system that the object should be +mapped for \fBbyte consistent\fR access. Normal data transfers usually use a +\fBstreaming\fR mode of operation. They start at a specific point, transfer a +fairly large amount of data sequentially, and then stop, usually on an aligned +boundary. Control mode data transfers for memory-resident device control blocks +(for example, Ethernet message descriptors) do not access memory in such a +sequential fashion. Instead, they tend to modify a few words or bytes, move +around and maybe modify a few more. +.sp +.LP +Many machine implementations make this non-sequential memory access difficult +to control in a generic and seamless fashion. Therefore, explicit +synchronization steps using \fBddi_dma_sync\fR(9F) or \fBddi_dma_free\fR(9F) +are required to make the view of a memory object shared between a \fBCPU \fRand +a \fBDMA\fR device consistent. However, proper use of the +\fBDDI_DMA_CONSISTENT\fR flag can create a condition in which a system will +pick resources in a way that makes these synchronization steps are as efficient +as possible. +.sp +.LP +\fBDDI_DMA_SBUS_64BIT\fR tells the system that the device can perform 64-bit +transfers on a 64-bit SBus. If the SBus does not support 64-bit data transfers, +data will be transferred in 32-bit mode. +.sp +.LP +The callback function specified by the member \fBdmar_fp\fR indicates how a +caller to one of the \fBDMA\fR resource allocation functions wants to deal with +the possibility of resources not being available. (See +\fBddi_dma_setup\fR(9F).) If \fBdmar_fp\fR is set to \fBDDI_DMA_DONTWAIT\fR, +then the caller does not care if the allocation fails, and can deal with an +allocation failure appropriately. Setting \fBdmar_fp\fR to \fBDDI_DMA_SLEEP\fR +indicates the caller wants to have the allocation routines wait for resources +to become available. If any other value is set, and a \fBDMA\fR resource +allocation fails, this value is assumed to be a function to call later, when +resources become available. When the specified function is called, it is passed +the value set in the structure member \fBdmar_arg\fR. The specified callback +function \fBmust\fR return either: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +Indicating that it attempted to allocate a \fBDMA\fR resource but failed to do +so, again, in which case the callback function will be put back on a list to be +called again later. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 5n +.rt +Indicating either success at allocating \fBDMA\fR resources or that it no +longer wants to retry. +.RE + +.sp +.LP +The callback function is called in interrupt context. Therefore, only system +functions and contexts that are accessible from interrupt context are +available. The callback function must take whatever steps necessary to protect +its critical resources, data structures, and queues. +.sp +.LP +It is possible that a call to \fBddi_dma_free\fR(9F), which frees \fBDMA\fR +resources, might cause a callback function to be called and, unless some care +is taken, an undesired recursion can occur. This can cause an undesired +recursive \fBmutex_enter\fR(9F), which makes the system panic. +.SS "dmar_object Structure" +.sp +.LP +The \fBdmar_object\fR member of the \fBddi_dma_req\fR structure is itself a +complex and extensible structure: +.sp +.in +2 +.nf +uint_t dmao_size; /* size, in bytes, of the object */ +ddi_dma_atyp_t dmao_type; /* type of object */ +ddi_dma_aobj_t dmao_obj; /* the object described */ +.fi +.in -2 + +.sp +.LP +The \fBdmao_size\fR element is the size, in bytes, of the object resources +allocated for \fBDMA\fR. +.sp +.LP +The \fBdmao_type\fR element selects the kind of object described by +\fBdmao_obj\fR. It can be set to \fBDMA_OTYP_VADDR\fR, indicating virtual +addresses. +.sp +.LP +The last element, \fBdmao_obj\fR, consists of the virtual address type: +.sp +.in +2 +.nf +struct v_address virt_obj; +.fi +.in -2 + +.sp +.LP +It is specified as: +.sp +.in +2 +.nf +struct v_address { + caddr_t v_addr; /* base virtual address */ + struct as *v_as; /* pointer to address space */ + void *v_priv; /* priv data for shadow I/O */ +}; +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_dma_addr_setup\fR(9F), \fBddi_dma_buf_setup\fR(9F), +\fBddi_dma_curwin\fR(9F), \fBddi_dma_free\fR(9F), \fBddi_dma_movwin\fR(9F), +\fBddi_dma_setup\fR(9F), \fBddi_dma_sync\fR(9F), \fBmutex\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/ddi_dmae_req.9s b/usr/src/man/man9s/ddi_dmae_req.9s new file mode 100644 index 0000000000..79f493a064 --- /dev/null +++ b/usr/src/man/man9s/ddi_dmae_req.9s @@ -0,0 +1,238 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dmae_req 9S "18 Nov 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +ddi_dmae_req \- DMA engine request structure +.SH SYNOPSIS +.LP +.nf +#include <sys/dma_engine.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris x86 DDI specific (Solaris x86 DDI). +.SH DESCRIPTION +.sp +.LP +A device driver uses the \fBddi_dmae_req\fR structure to describe the +parameters for a \fBDMA\fR channel. This structure contains all the information +necessary to set up the channel, except for the \fBDMA\fR memory address and +transfer count. The defaults, as specified below, support most standard +devices. Other modes might be desirable for some devices, or to increase +performance. The \fBDMA\fR engine request structure is passed to +\fBddi_dmae_prog\fR(9F). +.SH STRUCTURE MEMBERS +.sp +.LP +The \fBddi_dmae_req\fR structure contains several members, each of which +controls some aspect of DMA engine operation. The structure members associated +with supported DMA engine options are described here. +.sp +.in +2 +.nf +uchar_tder_command; /* Read / Write * +/uchar_tder_bufprocess; /* Standard / Chain */ +uchar_tder_path; /* 8 / 16 / 32 */ +uchar_tder_cycles; /* Compat / Type A / Type B / Burst */ +uchar_tder_trans; /* Single / Demand / Block */ +ddi_dma_cookie_t*(*proc)(); /* address of nextcookie routine */ +void*procparms; /* parameter for nextcookie call */ +.fi +.in -2 + +.sp +.ne 2 +.mk +.na +\fB\fBder_command\fR\fR +.ad +.RS 18n +.rt +Specifies what \fBDMA\fR operation is to be performed. The value +\fBDMAE_CMD_WRITE\fR signifies that data is to be transferred from memory to +the \fBI/O \fRdevice. The value \fBDMAE_CMD_READ\fR signifies that data is to +be transferred from the \fBI/O\fR device to memory. This field must be set by +the driver before calling \fBddi_dmae_prog()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBder_bufprocess\fR\fR +.ad +.RS 18n +.rt +On some bus types, a driver can set \fBder_bufprocess\fR to the value +\fBDMAE_BUF_CHAIN\fR to specify that multiple \fBDMA\fR cookies will be given +to the \fBDMA\fR engine for a single \fBI/O\fR transfer. This action causes a +scatter/gather operation. In this mode of operation, the driver calls +\fBddi_dmae_prog()\fR to give the \fBDMA\fR engine the \fBDMA\fR engine request +structure and a pointer to the first cookie. The \fBproc\fR structure member +must be set to the address of a driver \fBnextcookie\fR routine. This routine +takes one argument, specified by the \fBprocparms\fR structure member, and +returns a pointer to a structure of type \fBddi_dma_cookie_t\fR that specifies +the next cookie for the \fBI/O \fR transfer. When the \fBDMA\fR engine is ready +to receive an additional cookie, the bus nexus driver controlling that +\fBDMA\fR engine calls the routine specified by the \fBproc\fR structure member +to obtain the next cookie from the driver. The driver's \fBnextcookie\fR +routine must then return the address of the next cookie (in static storage) to +the bus nexus routine that called it. If there are no more segments in the +current \fBDMA\fR window, then \fB(*proc)()\fR must return the \fBNULL\fR +pointer. +.sp +A driver can specify the \fBDMAE_BUF_CHAIN\fR flag only if the particular bus +architecture supports the use of multiple \fBDMA\fR cookies in a single +\fBI/O\fR transfer. A bus \fBDMA\fR engine can support this feature either with +a fixed-length scatter/gather list, or by an interrupt chaining feature. A +driver must determine whether its parent bus nexus supports this feature by +examining the scatter/gather list size returned in the \fBdlim_sgllen\fR member +of the \fBDMA\fR limit structure returned by the driver's call to +\fBddi_dmae_getlim()\fR. (See \fBddi_dma_lim_x86\fR(9S).) If the size of the +scatter/gather list is 1, then no chaining is available. The driver must not +specify the \fBDMAE_BUF_CHAIN\fR flag in the \fBddi_dmae_req\fR structure it +passes to \fBddi_dmae_prog()\fR, and the driver need not provide a +\fBnextcookie\fR routine. +.sp +If the size of the scatter/gather list is greater than 1, then \fBDMA\fR +chaining is available, and the driver has two options. Under the first option, +the driver chooses not to use the chaining feature. In this case (a) the driver +must \fBset\fR the size of the scatter/gather list to 1 before passing it to +the \fBDMA\fR setup routine, and (b) the driver must not set the +\fBDMAE_BUF_CHAIN\fR flag. +.sp +Under the second option, the driver chooses to use the chaining feature, in +which case, (a) it should leave the size of the scatter/gather list alone, and +(b) it must set the \fBDMAE_BUF_CHAIN\fR flag in the \fBddi_dmae_req\fR +structure. Before calling \fBddi_dmae_prog()\fR, the driver must \fIprefetch\fR +cookies by repeatedly calling \fBddi_dma_nextseg\fR(9F) and +\fBddi_dma_segtocookie\fR(9F) until either (1) the end of the DMA window is +reached (\fBddi_dma_nextseg\fR(9F) returns \fBNULL\fR), or (2) the size of the +scatter/gather list is reached, whichever occurs first. These cookies must be +saved by the driver until they are requested by the nexus driver calling the +driver's \fBnextcookie\fR routine. The driver's \fBnextcookie\fR routine must +return the prefetched cookies in order, one cookie for each call to the +\fBnextcookie\fR routine, until the list of prefetched cookies is exhausted. +After the end of the list of cookies is reached, the \fBnextcookie\fR routine +must return the \fBNULL\fR pointer. +.sp +The size of the scatter/gather list determines how many discontiguous segments +of physical memory can participate in a single \fBDMA\fR transfer. \fBISA\fR +bus \fBDMA\fR engines have no scatter/gather capability, so their +scatter/gather list sizes are 1. Other finite scatter/gather list sizes would +also be possible. For performance reasons, drivers should use the chaining +capability if it is available on their parent bus. +.sp +As described above, a driver making use of \fBDMA\fR chaining must prefetch +\fBDMA\fR cookies before calling \fBddi_dmae_prog()\fR. The reasons for this +are: +.RS +4 +.TP +.ie t \(bu +.el o +First, the driver must have some way to know the total \fBI/O\fR count with +which to program the \fBI/O\fR device. This \fBI/O\fR count must match the +total size of all the \fBDMA\fR segments that will be chained together into one +\fBDMA\fR operation. Depending on the size of the scatter/gather list and the +memory position and alignment of the \fBDMA\fR object, all or just part of the +current \fBDMA\fR window might be able to participate in a single \fBI/O\fR +operation. The driver must compute the \fBI/O\fR count by adding up the sizes +of the prefetched \fBDMA\fR cookies. The number of cookies whose sizes are to +be summed is the lesser of (a) the size of the scatter/gather list, or (b) the +number of segments remaining in the window. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Second, on some bus architectures, the driver's \fBnextcookie\fR routine can be +called from a high-level interrupt routine. If the cookies were not prefetched, +the \fBnextcookie\fR routine would have to call \fBddi_dma_nextseg()\fR and +\fBddi_dma_segtocookie()\fR from a high-level interrupt routine, which is not +recommended. +.RE +When breaking a \fBDMA\fR window into segments, the system arranges for the end +of every segment whose number is an integral multiple of the scatter/gather +list size to fall on a device-granularity boundary, as specified in the +\fBdlim_granular\fR field in the \fBddi_dma_lim_x86\fR(9S) structure. +.sp +If the scatter/gather list size is 1 (either because no chaining is available +or because the driver does not want to use the chaining feature), then the +total \fBI/O\fR count for a single \fBDMA\fR operation is the size of \fBDMA\fR +segment denoted by the single \fBDMA\fR cookie that is passed in the call to +\fBddi_dmae_prog()\fR. In this case, the system arranges for each \fBDMA\fR +segment to be a multiple of the device-granularity size. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBder_path\fR\fR +.ad +.RS 18n +.rt +Specifies the \fBDMA\fR transfer size. The default of zero +(\fBDMAE_PATH_DEF\fR) specifies \fBISA\fR compatibility mode. In that mode, +channels 0, 1, 2, and 3 are programmed in 8-bit mode (\fBDMAE_PATH_8\fR), and +channels 5, 6, and 7 are programmed in 16-bit, count-by-word mode +(\fBDMAE_PATH_16\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBder_cycles\fR\fR +.ad +.RS 18n +.rt +Specifies the timing mode to be used during \fBDMA\fR data transfers. The +default of zero (\fBDMAE_CYCLES_1\fR) specifies \fBISA\fR compatible timing. +Drivers using this mode must also specify \fBDMAE_TRANS_SNGL\fR in the +\fBder_trans\fR structure member. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBder_trans\fR\fR +.ad +.RS 18n +.rt +Specifies the bus transfer mode that the \fBDMA\fR engine should expect from +the device. The default value of zero (\fBDMAE_TRANS_SNGL\fR) specifies that +the device performs one transfer for each bus arbitration cycle. Devices that +use \fBISA\fR compatible timing (specified by a value of zero, which is the +default, in the \fBder_cycles\fR structure member) should use the +\fBDMAE_TRANS_SNGL\fR mode. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architecturex86 +.TE + +.SH SEE ALSO +.sp +.LP +\fBisa\fR(4), \fBattributes\fR(5), \fBddi_dma_segtocookie\fR(9F), +\fBddi_dmae\fR(9F), \fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S) diff --git a/usr/src/man/man9s/ddi_fm_error.9s b/usr/src/man/man9s/ddi_fm_error.9s new file mode 100644 index 0000000000..21c48c64c1 --- /dev/null +++ b/usr/src/man/man9s/ddi_fm_error.9s @@ -0,0 +1,144 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_fm_error 9S "13 May 2007" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +ddi_fm_error \- I/O error status structure +.SH SYNOPSIS +.LP +.nf +#include <sys/ddifm.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +A \fBddi_fm_error_t\fR structure contains common data necessary for \fBI/O\fR +error handling. A pointer to a \fBddi_fm_error_t\fR structure is passed to +error handling callbacks where it can then be used in a call to +\fBpci_ereport_post()\fR. The same structure is also returned to callers of +\fBddi_fm_acc_err_get()\fR and \fBddi_fm_dma_err_get()\fR. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +int fme_version; +uint64_t fme_ena; +int fme_status; +int fme_flag; +ddi_acc_handle_t fme_acc_handle; +ddi_dma_handle_t fme_dma_handle; +.fi +.in -2 + +.sp +.LP +The \fBfme_version\fR is the current version of \fBddi_fm_error_t\fR. Valid +values for the version are: \fBDDI_FME_VER0\fR and \fBDDI_FME_VER1\fR. +.sp +.LP +The \fBfme_ena\fR is the \fBFMA\fR event protocol Format 1 Error Numeric +Association (\fBENA\fR) for this error condition. +.sp +.LP +The \fBfme_flag\fR field is set to \fBDDI_FM_ERR_EXPECTED\fR if the error is +the result of a \fBDDI_ACC_CAUTIOUS\fR protected operation. In this case, +\fBfme_acc_handle\fR is valid and the driver should check for and report only +errors not associated with the \fBDDI_ACC_CAUTIOUS\fR protected access +operation. This field can also be set to \fBDDI_FM_ERR_POKE\fR or +\fBDDI_FM_ERR_PEEK\fR if the error is the result of a \fBddi_peek\fR(9F) or +\fBddi_poke\fR(9F) operation. The driver should handle these in a similar way +to \fBDDI_FM_ERR_EXPECTED\fR. Otherwise, \fBddi_flag\fR is set to +\fBDDI_FM_ERR_UNEXPECTED\fR and the driver must perform the full range of error +handling tasks. +.sp +.LP +The \fBfme_status\fR indicates current status of an error handler callback or +resource handle: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_OK\fR\fR +.ad +.RS 19n +.rt +No errors were detected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_FATAL\fR\fR +.ad +.RS 19n +.rt +An error which is considered fatal to the operational state of the system was +detected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_NONFATAL\fR\fR +.ad +.RS 19n +.rt +An error which is not considered fatal to the operational state of the system +was detected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_UNKNOWN\fR\fR +.ad +.RS 19n +.rt +An error was detected, but the driver was unable to determine the impact of the +error on the operational state of the system. +.RE + +.sp +.LP +The \fBfme_acc_handle\fR is the valid access handle associated with the error +that can be returned from \fBpci_ereport_post()\fR +.sp +.LP +The \fBfme_dma_handle\fR is the valid \fBDMA\fR handle associated with the +error that can be returned from \fBpci_ereport_post()\fR +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_fm_acc_err_get\fR(9F), +\fBddi_fm_dma_err_get\fR(9F), \fBddi_fm_handler_register\fR(9F), +\fBddi_peek\fR(9F), \fBddi_poke\fR(9F), \fBpci_ereport_post\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/ddi_idevice_cookie.9s b/usr/src/man/man9s/ddi_idevice_cookie.9s new file mode 100644 index 0000000000..b341179a6d --- /dev/null +++ b/usr/src/man/man9s/ddi_idevice_cookie.9s @@ -0,0 +1,66 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_idevice_cookie 9S "19 Oct 2005" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +ddi_idevice_cookie \- device interrupt cookie +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). This interface is obsolete. Use the new +interrupt interfaces referenced in \fBIntro\fR(9F). Refer to \fIWriting Device +Drivers\fR for more information. +.SH DESCRIPTION +.sp +.LP +The \fBddi_idevice_cookie_t\fR structure contains interrupt priority and +interrupt vector information for a device. This structure is useful for devices +having programmable bus-interrupt levels. \fBddi_add_intr\fR(9F) assigns values +to the \fBddi_idevice_cookie_t\fR structure members. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +u_short idev_vector; /* interrupt vector */ +ushort_t idev_priority; /* interrupt priority */ +.fi +.in -2 + +.sp +.LP +The \fBidev_vector\fR field contains the interrupt vector number for vectored +bus architectures such as VMEbus. The \fBidev_priority\fR field contains the +bus interrupt priority level. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_add_intr\fR(9F), \fBIntro\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/dev_ops.9s b/usr/src/man/man9s/dev_ops.9s new file mode 100644 index 0000000000..94b3d6d49b --- /dev/null +++ b/usr/src/man/man9s/dev_ops.9s @@ -0,0 +1,193 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dev_ops 9S "16 Sep 2008" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +dev_ops \- device operations structure +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/devops.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +\fBdev_ops\fR contains driver common fields and pointers to the \fBbus_ops\fR +and \fBcb_ops\fR(9S). +.sp +.LP +Following are the device functions provided in the device operations structure. +All fields must be set at compile time. +.sp +.ne 2 +.mk +.na +\fB\fBdevo_rev\fR\fR +.ad +.RS 17n +.rt +Driver build version. Set this to \fBDEVO_REV\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevo_refcnt\fR\fR +.ad +.RS 17n +.rt +Driver reference count. Set this to \fB0\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevo_getinfo\fR\fR +.ad +.RS 17n +.rt +Get device driver information (see \fBgetinfo\fR(9E)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevo_identify\fR\fR +.ad +.RS 17n +.rt +This entry point is obsolete. Set to \fBnulldev\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevo_probe\fR\fR +.ad +.RS 17n +.rt +Probe device. See \fBprobe\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevo_attach\fR\fR +.ad +.RS 17n +.rt +Attach driver to \fBdev_info\fR. See \fBattach\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevo_detach\fR\fR +.ad +.RS 17n +.rt +Detach/prepare driver to unload. See \fBdetach\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevo_reset\fR\fR +.ad +.RS 17n +.rt +Reset device. (Not supported in this release.) Set this to \fBnodev\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevo_cb_ops\fR\fR +.ad +.RS 17n +.rt +Pointer to \fBcb_ops\fR(9S) structure for leaf drivers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevo_bus_ops\fR\fR +.ad +.RS 17n +.rt +Pointer to bus operations structure for nexus drivers. Set this to \fINULL\fR +if this is for a leaf driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevo_power\fR\fR +.ad +.RS 17n +.rt +Power a device attached to system. See \fBpower\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevo_quiesce\fR\fR +.ad +.RS 17n +.rt +Quiesce a device attached to system (see \fBquiesce\fR(9E) for more +information). This can be set to \fBddi_quiesce_not_needed()\fR if the driver +does not need to implement quiesce. +.RE + +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +int devo_rev; +int devo_refcnt; +int (*devo_getinfo)(dev_info_t *dip, + ddi_info_cmd_t infocmd, void *arg, void **result); +int (*devo_identify)(dev_info_t *dip); +int (*devo_probe)(dev_info_t *dip); +int (*devo_attach)(dev_info_t *dip, + ddi_attach_cmd_t cmd); +int (*devo_detach)(dev_info_t *dip, + ddi_detach_cmd_t cmd); +int (*devo_reset)(dev_info_t *dip, ddi_reset_cmd_t cmd); +struct cb_ops *devo_cb_ops; +struct bus_ops *devo_bus_ops; +int (*devo_power)(dev_info_t *dip, int component, int level); +int (*devo_quiesce)(dev_info_t *dip); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBdetach\fR(9E), \fBgetinfo\fR(9E), \fBprobe\fR(9E), +\fBpower\fR(9E), \fBquiesce\fR(9E), \fBnodev\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/devmap_callback_ctl.9s b/usr/src/man/man9s/devmap_callback_ctl.9s new file mode 100644 index 0000000000..54ddeebbf4 --- /dev/null +++ b/usr/src/man/man9s/devmap_callback_ctl.9s @@ -0,0 +1,134 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH devmap_callback_ctl 9S "24 Jul 1996" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +devmap_callback_ctl \- device mapping-control structure +.SH SYNOPSIS +.LP +.nf +#include <sys/ddidevmap.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +A \fBdevmap_callback_ctl\fR 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 \fBdevmap_setup\fR(9F) or +\fBddi_devmap_segmap\fR(9F). +.sp +.LP +Device drivers pass the initialized \fBdevmap_callback_ctl\fR structure to +either \fBdevmap_devmem_setup\fR(9F) or \fBdevmap_umem_setup\fR(9F) in the +\fBdevmap\fR(9E) entry point during the mapping setup. The system makes a +private copy of the structure for later use. Device drivers can specify +different \fBdevmap_callback_ctl\fR for different mappings. +.sp +.LP +A device driver should allocate the device mapping control structure and +initialize the following fields, if the driver wants the entry points to be +called by the system: +.sp +.ne 2 +.mk +.na +\fB\fBdevmap_rev\fR \fR +.ad +.RS 18n +.rt +Version number. Set this to \fBDEVMAP_OPS_REV\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevmap_map\fR \fR +.ad +.RS 18n +.rt +Set to the address of the \fBdevmap_map\fR(9E) entry point or to \fINULL\fR if +the driver does not support this callback. If set, the system calls the +\fBdevmap_map\fR(9E) entry point during the \fBmmap\fR(2) system call. The +drivers typically allocate driver private data structure in this function and +return the pointer to the private data structure to the system for later use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevmap_access\fR \fR +.ad +.RS 18n +.rt +Set to the address of the \fBdevmap_access\fR(9E) entry point or to \fINULL\fR +if the driver does not support this callback. If set, the system calls the +driver's \fBdevmap_access\fR(9E) entry point during memory access. The system +expects \fBdevmap_access\fR(9E) to call either \fBdevmap_do_ctxmgt\fR(9F) or +\fBdevmap_default_access\fR(9F) to load the memory address translations before +it returns to the system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevmap_dup\fR \fR +.ad +.RS 18n +.rt +Set to the address of the \fBdevmap_dup\fR(9E) entry point or to \fINULL\fR if +the driver does not support this call. If set, the system calls the +\fBdevmap_dup\fR(9E) entry point during the \fBfork\fR(2) system call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevmap_unmap\fR \fR +.ad +.RS 18n +.rt +Set to the address of the \fBdevmap_unmap\fR(9E) entry point or to \fINULL\fR +if the driver does not support this call. If set, the system will call the +\fBdevmap_unmap\fR(9E) entry point during the \fBmunmap\fR(2) or \fBexit\fR(2) +system calls. +.RE + +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +int devmap_rev; +int (*devmap_map)(devmap_cookie_t dhp, dev_t dev, + uint_t flags,offset_t off, size_t len, void **pvtp); +int (*devmap_access)(devmap_cookie_t dhp, void *pvtp, + offset_t off, size_t len, uint_t type, uint_t rw); +int (*devmap_dup)(devmap_cookie_t dhp, void *pvtp, + devmap_cookie_t new_dhp, void **new_pvtp); +void (*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); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBexit\fR(2), \fBfork\fR(2), \fBmmap\fR(2), \fBmunmap\fR(2), \fBdevmap\fR(9E), +\fBdevmap_access\fR(9E), \fBdevmap_dup\fR(9E), \fBdevmap_map\fR(9E), +\fBdevmap_unmap\fR(9E), \fBddi_devmap_segmap\fR(9F), +\fBdevmap_default_access\fR(9F), \fBdevmap_devmem_setup\fR(9F), +\fBdevmap_do_ctxmgt\fR(9F), \fBdevmap_setup\fR(9F), \fBdevmap_umem_setup\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/fmodsw.9s b/usr/src/man/man9s/fmodsw.9s new file mode 100644 index 0000000000..0538391bf4 --- /dev/null +++ b/usr/src/man/man9s/fmodsw.9s @@ -0,0 +1,57 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH fmodsw 9S "14 Nov 2002" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +fmodsw \- STREAMS module declaration structure +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/conf.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBfmodsw\fR structure contains information for STREAMS modules. All +STREAMS modules must define a \fBfmodsw\fR structure. +.sp +.LP +\fBf_name\fR must match \fBmi_idname\fR in the \fBmodule_info\fR structure. See +\fBmodule_info\fR(9S). \fBf_name\fR should also match the module binary name. +(See WARNINGS.) +.sp +.LP +All modules must set the \fBf_flag\fR to \fBD_MP\fR to indicate that they +safely allow multiple threads of execution. See \fBmt-streams\fR(9F) for +additional flags. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +char f_name[FMNAMESZ + 1]; /* module name */ +struct streamtab *f_str; /* streams information */ +int f_flag; /* flags */ +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBmt-streams\fR(9F), \fBmodlstrmod\fR(9S), \fBmodule_info\fR(9S) +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH WARNINGS +.sp +.LP +If \fBf_name\fR does not match the module binary name, unexpected failures can +occur. diff --git a/usr/src/man/man9s/free_rtn.9s b/usr/src/man/man9s/free_rtn.9s new file mode 100644 index 0000000000..98a7993d03 --- /dev/null +++ b/usr/src/man/man9s/free_rtn.9s @@ -0,0 +1,45 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH free_rtn 9S "13 Nov 1996" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +free_rtn \- structure that specifies a driver's message-freeing routine +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH DESCRIPTION +.sp +.LP +The \fBfree_rtn\fR structure is referenced by the \fBdatab\fR structure. When +\fBfreeb\fR(9F) is called to free the message, the driver's message-freeing +routine (referenced through the \fBfree_rtn\fR structure) is called, with +arguments, to free the data buffer. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +void (*free_func)() /* user's freeing routine */ +char *free_arg /* arguments to free_func() */ +.fi +.in -2 + +.sp +.LP +The \fBfree_rtn\fR structure is defined as type \fBfrtn_t\fR. +.SH SEE ALSO +.sp +.LP +\fBesballoc\fR(9F), \fBfreeb\fR(9F), \fBdatab\fR(9S) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9s/gld_mac_info.9s b/usr/src/man/man9s/gld_mac_info.9s new file mode 100644 index 0000000000..980ef515da --- /dev/null +++ b/usr/src/man/man9s/gld_mac_info.9s @@ -0,0 +1,397 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH gld_mac_info 9S "7 June 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +gld_mac_info \- Generic LAN Driver MAC info data structure +.SH SYNOPSIS +.LP +.nf +#include <sys/gld.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The Generic LAN Driver (GLD) Media Access Control (MAC) information +(\fBgld_mac_info\fR) 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. +.sp +.LP +The \fBgld_mac_info\fR structure should be allocated using +\fBgld_mac_alloc()\fR and deallocated using \fBgld_mac_free()\fR. Drivers can +make no assumptions about the length of this structure, which might be +different in different releases of Solaris and/or GLD. Structure members +private to GLD, not documented here, should not be set or read by the +device-specific driver. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +caddr_t gldm_private; /* Driver private data */ +int (*gldm_reset)(); /* Reset device */ +int (*gldm_start)(); /* Start device */ +int (*gldm_stop)(); /* Stop device */ +int (*gldm_set_mac_addr)(); /* Set device phys addr */ +int (*gldm_set_multicast)(); /* Set/delete */ + /* multicast address */ +int (*gldm_set_promiscuous)(); + /* Set/reset promiscuous */ + /* mode*/ +int (*gldm_send)(); /* Transmit routine */ +u_int (*gldm_intr)(); /* Interrupt handler */ +int (*gldm_get_stats)(); /* Get device statistics */ +int (*gldm_ioctl)(); /* Driver-specific ioctls */ +char *gldm_ident; /* Driver identity string */ +uint32_t gldm_type; /* Device type */ +uint32_t gldm_minpkt; /* Minimum packet size */ + /* accepted by driver */ +uint32_t gldm_maxpkt; /* Maximum packet size */ + /* accepted by driver */ +uint32_t gldm_addrlen; /* Physical address */ + /* length */ +int32_t gldm_saplen; /* SAP length for */ + /* DL_INFO_ACK */ +unsigned char *gldm_broadcast_addr; /* Physical broadcast */ + /* addr */ +unsigned char *gldm_vendor_addr; /* Factory MAC address */ +t_uscalar_t gldm_ppa; /* Physical Point of */ + /* Attachment (PPA) number */ +dev_info_t *gldm_devinfo; /* Pointer to device's */ + /* dev_info node */ +ddi_iblock_cookie_tgldm_cookie; /* Device's interrupt */ + /* block cookie */ +int gldm_margin /* accepted data beyond */ + /*gldm_maxpkt */ +uint32_t gldm_capabilities; /* Device capabilities */ +.fi +.in -2 +.sp + +.sp +.LP +Below is a description of the members of the \fBgld_mac_info\fR structure that +are visible to the device driver. +.sp +.ne 2 +.mk +.na +\fB\fBgldm_private\fR\fR +.ad +.RS 16n +.rt +This structure member is private to the device-specific driver and is not used +or modified by GLD. Conventionally, this is used as a pointer to private data, +pointing to a driver-defined and driver-allocated per-instance data structure. +.RE + +.sp +.LP +The following group of structure members must be set by the driver before +calling \fBgld_register()\fR, and should not thereafter be modified by the +driver; \fBgld_register()\fR can use or cache the values of some of these +structure members, so changes made by the driver after calling +\fBgld_register()\fR might cause unpredicted results. +.sp +.ne 2 +.mk +.na +\fB\fBgldm_reset\fR\fR +.ad +.RS 24n +.rt +Pointer to driver entry point; see \fBgld\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_start\fR\fR +.ad +.RS 24n +.rt +Pointer to driver entry point; see \fBgld\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_stop\fR\fR +.ad +.RS 24n +.rt +Pointer to driver entry point; see \fBgld\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_set_mac_addr\fR\fR +.ad +.RS 24n +.rt +Pointer to driver entry point; see \fBgld\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_set_multicast\fR\fR +.ad +.RS 24n +.rt +Pointer to driver entry point; see \fBgld\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_set_promiscuous\fR\fR +.ad +.RS 24n +.rt +Pointer to driver entry point; see \fBgld\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_send\fR\fR +.ad +.RS 24n +.rt +Pointer to driver entry point; see \fBgld\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_intr\fR\fR +.ad +.RS 24n +.rt +Pointer to driver entry point; see \fBgld\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_get_stats\fR\fR +.ad +.RS 24n +.rt +Pointer to driver entry point; see \fBgld\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_ioctl\fR\fR +.ad +.RS 24n +.rt +Pointer to driver entry point; can be \fINULL\fR; see \fBgld\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_ident\fR\fR +.ad +.RS 24n +.rt +Pointer to a string containing a short description of the device. It is used to +identify the device in system messages. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_type\fR\fR +.ad +.RS 24n +.rt +The type of device the driver handles. The values currently supported by GLD +are \fBDL_ETHER\fR (IEEE 802.3 and Ethernet Bus), \fBDL_TPR\fR (IEEE 802.5 +Token Passing Ring), and \fBDL_FDDI\fR (ISO 9314-2 Fibre Distributed Data +Interface). This structure member must be correctly set for GLD to function +properly. +.sp +Support for the DL_TPR and DL_FDDI media types is obsolete and may be removed +in a future release of Solaris. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_minpkt\fR\fR +.ad +.RS 24n +.rt +Minimum \fIService\fR \fIData\fR \fIUnit\fR size \(em the minimum packet size, +not including the MAC header, that the device will transmit. This can be zero +if the device-specific driver can handle any required padding. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_maxpkt\fR\fR +.ad +.RS 24n +.rt +Maximum \fIService\fR \fIData\fR \fIUnit\fR size \(em the maximum size of +packet, not including the MAC header, that can be transmitted by the device. +For Ethernet, this number is 1500. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_addrlen\fR\fR +.ad +.RS 24n +.rt +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_saplen\fR\fR +.ad +.RS 24n +.rt +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 \fIafter\fR the +physical address in a DLSAP address. See the description under ``Message +DL_INFO_ACK'' in the DLPI specification for more details. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_broadcast_addr\fR\fR +.ad +.RS 24n +.rt +Pointer to an array of bytes of length \fBgldm_addrlen\fR containing the +broadcast address to be used for transmit. The driver must allocate space to +hold the broadcast address, fill it in with the appropriate value, and set +\fBgldm_broadcast_addr\fR to point at it. For Ethernet, Token Ring, and FDDI, +the broadcast address is normally 0xFF-FF-FF-FF-FF-FF. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_vendor_addr\fR\fR +.ad +.RS 24n +.rt +Pointer to an array of bytes of length \fBgldm_addrlen\fR containing the +vendor-provided network physical address of the device. The driver must +allocate space to hold the address, fill it in with information read from the +device, and set \fBgldm_vendor_addr\fR to point at it. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_ppa\fR\fR +.ad +.RS 24n +.rt +The Physical Point of Attachment (PPA) number for this instance of the device. +Normally this should be set to the instance number, returned from +\fBddi_get_instance\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_devinfo\fR\fR +.ad +.RS 24n +.rt +Pointer to the \fBdev_info\fR node for this device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_cookie\fR\fR +.ad +.RS 24n +.rt +The interrupt block cookie returned by \fBddi_get_iblock_cookie\fR(9F), +\fBddi_add_intr\fR(9F), \fBddi_get_soft_iblock_cookie\fR(9F), or +\fBddi_add_softintr\fR(9F). This must correspond to the device's receive +interrupt, from which \fBgld_recv()\fR is called. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_margin\fR\fR +.ad +.RS 24n +.rt +Drivers set this value to the amount of data in bytes that the device can +transmit beyond \fBgldm_maxpkt\fR. For example, if an Ethernet device can +handle packets whose payload section is no greater than 1522 bytes and the +\fBgldm_maxpkt\fR is set to 1500 (as is typical for Ethernet), then +\fBgldm_margin\fR is set to 22. The registered \fBgldm_margin\fR value is +reported in acknowledgements of the DLIOCMARGININFO ioctl (see \fBdlpi\fR(7P)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgldm_capabilities\fR\fR +.ad +.RS 24n +.rt +Bit-field of device capabilities. If the device is capable of reporting media +link state, the GLD_CAP_LINKSTATE bit should be set. +.RE + +.SH SEE ALSO +.sp +.LP +\fBgld\fR(7D), \fBdlpi\fR(7P), \fBattach\fR(9E), \fBgld\fR(9E), +\fBddi_add_intr\fR(9F), \fBgld\fR(9F), \fBgld_stats\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/gld_stats.9s b/usr/src/man/man9s/gld_stats.9s new file mode 100644 index 0000000000..5404b6b18d --- /dev/null +++ b/usr/src/man/man9s/gld_stats.9s @@ -0,0 +1,181 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH gld_stats 9S "7 Jun 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +gld_stats \- Generic LAN Driver statistics data structure +.SH SYNOPSIS +.LP +.nf +#include <sys/gld.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The Generic LAN Driver (GLD) statistics (\fBgld_stats\fR) structure is used to +communicate statistics and state information from a GLD-based driver to GLD +when returning from a driver's \fBgldm_get_stats()\fR routine as discussed in +\fBgld\fR(9E) and \fBgld\fR(7D). The members of this structure, filled in by +the GLD-based driver, are used when GLD reports the statistics. In the tables +below, the name of the statistics variable reported by GLD is noted in the +comments. See \fBgld\fR(7D) for a more detailed description of the meaning of +each statistic. +.sp +.LP +Drivers can make no assumptions about the length of this structure, which might +be different in different releases of Solaris and/or GLD. Structure members +private to GLD, not documented here, should not be set or read by the device +specific driver. +.SH STRUCTURE MEMBERS +.sp +.LP +The following structure members are defined for all media types: +.sp +.in +2 +.nf +uint64_t glds_speed; /* ifspeed */ +uint32_t glds_media; /* media */ +uint32_t glds_intr; /* intr */ +uint32_t glds_norcvbuf; /* norcvbuf */ +uint32_t glds_errrcv; /* ierrors */ +uint32_t glds_errxmt; /* oerrors */ +uint32_t glds_missed; /* missed */ +uint32_t glds_underflow; /* uflo */ +uint32_t glds_overflow; /* oflo */ +.fi +.in -2 +.sp + +.sp +.LP +The following structure members are defined for media type \fBDL_ETHER\fR: +.sp +.in +2 +.nf +uint32_t glds_frame; /* align_errors */ +uint32_t glds_crc; /* fcs_errors */ +uint32_t glds_duplex; /* duplex */ +uint32_t glds_nocarrier; /* carrier_errors */ +uint32_t glds_collisions; /* collisions */ +uint32_t glds_excoll; /* ex_collisions */ +uint32_t glds_xmtlatecoll; /* tx_late_collisions */ +uint32_t glds_defer; /* defer_xmts */ +uint32_t glds_dot3_first_coll; /* first_collisions */ +uint32_t glds_dot3_multi_coll; /* multi_collisions */ +uint32_t glds_dot3_sqe_error; /* sqe_errors */ +uint32_t glds_dot3_mac_xmt_error; /* macxmt_errors */ +uint32_t glds_dot3_mac_rcv_error; /* macrcv_errors */ +uint32_t glds_dot3_frame_too_long; /* toolong_errors */ +uint32_t glds_short; /* runt_errors */ +.fi +.in -2 +.sp + +.sp +.LP +The following structure members are defined for media type \fBDL_TPR\fR: +.sp +.in +2 +.nf +uint32_t glds_dot5_line_error /* line_errors */ +uint32_t glds_dot5_burst_error /* burst_errors */ +uint32_t glds_dot5_signal_loss /* signal_losses */ +uint32_t glds_dot5_ace_error /* ace_errors */ +uint32_t glds_dot5_internal_error /* internal_errors */ +uint32_t glds_dot5_lost_frame_error /* lost_frame_errors */ +uint32_t glds_dot5_frame_copied_error /* frame_copied_errors */ +uint32_t glds_dot5_token_error /* token_errors */ +uint32_t glds_dot5_freq_error /* freq_errors */ +.fi +.in -2 +.sp + +.LP +Note - +.sp +.RS 2 +Support for the DL_TPR media type is obsolete and may be removed in a future +release of Solaris. +.RE +.sp +.LP +The following structure members are defined for media type \fBDL_FDDI\fR: +.sp +.in +2 +.nf +uint32_t glds_fddi_mac_error; /* mac_errors */ +uint32_t glds_fddi_mac_lost; /* mac_lost_errors */ +uint32_t glds_fddi_mac_token; /* mac_tokens */ +uint32_t glds_fddi_mac_tvx_expired; /* mac_tvx_expired */ +uint32_t glds_fddi_mac_late; /* mac_late */ +uint32_t glds_fddi_mac_ring_op; /* mac_ring_ops */ +.fi +.in -2 +.sp + +.LP +Note - +.sp +.RS 2 +Support for the DL_FDDI media type is obsolete and may be removed in a future +release of Solaris. +.RE +.sp +.LP +Most of the above statistics variables are counters denoting the number of +times the particular event was observed. Exceptions are: +.sp +.ne 2 +.mk +.na +\fB\fBglds_speed\fR \fR +.ad +.RS 16n +.rt +An estimate of the interface's current bandwidth in bits per second. For +interfaces that do not vary in bandwidth or for those where no accurate +estimation can be made, this object should contain the nominal bandwidth. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBglds_media\fR \fR +.ad +.RS 16n +.rt +The type of media (wiring) or connector used by the hardware. Currently +supported media names include \fBGLDM_AUI\fR, \fBGLDM_BNC\fR, \fBGLDM_TP\fR, +\fBGLDM_10BT\fR, \fBGLDM_100BT\fR, \fBGLDM_100BTX\fR, \fBGLDM_100BT4\fR, +\fBGLDM_RING4\fR, \fBGLDM_RING16\fR, \fBGLDM_FIBER\fR, and \fBGLDM_PHYMII\fR. +\fBGLDM_UNKNOWN\fR can also be specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBglds_duplex\fR \fR +.ad +.RS 16n +.rt +Current duplex state of the interface. Supported values are +\fBGLD_DUPLEX_HALF\fR and \fBGLD_DUPLEX_FULL\fR. \fBGLD_DUPLEX_UNKNOWN\fR can +also be specified. +.RE + +.SH SEE ALSO +.sp +.LP +\fBgld\fR(7D), \fBgld\fR(9F), \fBgld\fR(9E), \fBgld_mac_info\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/hook_nic_event.9s b/usr/src/man/man9s/hook_nic_event.9s new file mode 100644 index 0000000000..a6cf54e7c4 --- /dev/null +++ b/usr/src/man/man9s/hook_nic_event.9s @@ -0,0 +1,164 @@ +'\" te +.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH hook_nic_event 9S "1 May 2008" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +hook_nic_event \- data structure describing events related to network +interfaces +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> +#include <sys/hook.h> +#include <sys/hook_event.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBhook_nic_event\fR structure contains fields that relate to an event that +has occurred and belongs to a network interface. This structure is passed +through to callbacks for \fBNE_PLUMB\fR, \fBNE_UNPLUMB\fR, \fBNE_UP\fR, +\fBNE_DOWN\fR and \fBNE_ADDRESS_CHANGE\fR events. +.sp +.LP +A callback may not alter any of the fields in this structure. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +net_data_t hne_family; +phy_if_t pkt_private; +lif_if_t hne_lif; +nic_event_t hne_event; +nic_event_data_t hne_data; +size_t hne_datalen; + +.fi +.in -2 + +.sp +.LP +The following fields are set for each event: +.sp +.ne 2 +.mk +.na +\fB\fBhne_family\fR\fR +.ad +.RS 14n +.rt +A valid reference for the network protocol that owns this network interface and +can be in calls to other \fBnetinfo\fR(9F) functions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBhne_nic\fR\fR +.ad +.RS 14n +.rt +The physical interface to which an event belongs. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBhne_event\fR\fR +.ad +.RS 14n +.rt +A value that indicates the respective event. The current list of available +events is: +.sp +.ne 2 +.mk +.na +\fB\fBNE_PLUMB\fR\fR +.ad +.RS 21n +.rt +an interface has just been created. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNE_UNPLUMB\fR\fR +.ad +.RS 21n +.rt +an interface has just been destroyed and no more events should be received for +it. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNE_UP\fR\fR +.ad +.RS 21n +.rt +an interface has changed the state to "up" and may now generate packet events. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNE_DOWN\fR\fR +.ad +.RS 21n +.rt +an interface has changed the state to "down" and will no longer generate packet +events. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNE_ADDRESS_CHANGE\fR\fR +.ad +.RS 21n +.rt +an address on an interface has changed. \fBhne_lif\fR refers to the logical +interface for which the change is occurring, \fBhne_data\fR is a pointer to a +\fBsockaddr\fR structure that is \fBhne_datalen\fR bytes long and contains the +new network address. +.RE + +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnetinfo\fR(9F) diff --git a/usr/src/man/man9s/hook_pkt_event.9s b/usr/src/man/man9s/hook_pkt_event.9s new file mode 100644 index 0000000000..ab91ecafc0 --- /dev/null +++ b/usr/src/man/man9s/hook_pkt_event.9s @@ -0,0 +1,196 @@ +'\" te +.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH hook_pkt_event 9S "1 May 2008" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +hook_pkt_event \- packet event structure passed through to hooks +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> +#include <sys/hook.h> +#include <sys/hook_event.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBhook_pkt_event\fR structure contains fields that relate to a packet in a +network protocol handler. This structure is passed through to a callback for +\fBNH_PRE_ROUTING\fR, \fBNH_POST_ROUTING\fR, \fBNH_FORWARDING\fR, +\fBNH_LOOPBACK_IN\fR and \fBNH_LOOPBACK_OUT\fR events. +.sp +.LP +A callback may only modify the \fBhpe_hdr\fR, \fBhpe_mp\fR and \fBhpe_mb\fR +fields. +.sp +.LP +The following table documents which fields can be safely used as a result of +each event. +.sp +.in +2 +.nf +Event hpe_ifp hpe_ofp hpe_hdr hpe_mp hpe_mb +----- ------- ------- ------- ------ ------ +NH_PRE_ROUTING yes yes yes yes +NH_POST_ROUTING yes yes yes yes +NH_FORWARDING yes yes yes yes yes +NH_LOOPBACK_IN yes yes yes yes +NH_LOOPBACK_OUT yes yes yes yes +.fi +.in -2 +.sp + +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +net_data_t hne_family; +phy_if_t hpe_ifp; +phy_if_t hpe_ofp; +void *hpe_hdr; +mblk_t *hpe_mp; +mblk_t *hpe_mb; +uint32_t hpe_flags; + + +.fi +.in -2 + +.sp +.LP +The following fields are set for each event: +.sp +.ne 2 +.mk +.na +\fB\fBhne_family\fR\fR +.ad +.RS 14n +.rt +The protocol family for this packet. This value matches the corresponding value +returned from a call to \fBnet_protocol_lookup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBhpe_ifp\fR\fR +.ad +.RS 14n +.rt +The inbound interface for a packet. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBhpe_ofp\fR\fR +.ad +.RS 14n +.rt +The outbound interface for a packet. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBhpe_hdr\fR\fR +.ad +.RS 14n +.rt +Pointer to the start of the network protocol header within an \fBmblk_t\fR +structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBhpe_mp\fR\fR +.ad +.RS 14n +.rt +Pointer to the \fBmblk_t\fR pointer that points to the first \fBmblk_t\fR +structure in this packet. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBhpe_mb\fR\fR +.ad +.RS 14n +.rt +Pointer to the \fBmblk_t\fR structure that contains \fBhpe_hdr\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBhpe_flags\fR\fR +.ad +.RS 13n +.rt +This field is used to carry additional properties of packets. The current +collection of defined bits available is: +.sp +.ne 2 +.mk +.na +\fB\fBHPE_BROADCAST\fR\fR +.ad +.RS 17n +.rt +This bit is set if the packet was recognized as a broadcast packet from the +link layer. The bit cannot be set if \fBHPE_MULTICAST\fR is set, currently only +possible with physical in packet events. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBHPE_MULTICAST\fR\fR +.ad +.RS 17n +.rt +This set if the packet was recognized as a multicast packet from the link +layer. This bit cannot be set if \fBHPE_BROADCAST\fR is set, currently only +possible with physical in packet events. +.RE + +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_protocol_lookup\fR(9F), \fBnetinfo\fR(9F) diff --git a/usr/src/man/man9s/hook_t.9s b/usr/src/man/man9s/hook_t.9s new file mode 100644 index 0000000000..0c51da7308 --- /dev/null +++ b/usr/src/man/man9s/hook_t.9s @@ -0,0 +1,124 @@ +'\" te +.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH hook_t 9S "1 May 2008" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +hook_t \- callback structure for subscribing to netinfo events +.SH SYNOPSIS +.LP +.nf +#include <sys/hook.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBhook_t\fR data structure defines a callback that is to be inserted into +a networking event. This data structure must be allocated with a call to +\fBhook_alloc()\fR and released with a call to \fBhook_free()\fR. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +hook_func_t h_func; /* callback function to invoke */ +char *h_name; /* unique name given to the hook */ +int h_flags; +hook_hint_t h_hint; /* insertion hint type */ +uintptr_t h_hintvalue; /* used with h_hint */ +void *h_arg; /* value to pass into h_func */ + +typedef int (*hook_func_t)(net_event_t token, hook_data_t info, + void *); +.fi +.in -2 + +.SS "HINT TYPES" +.sp +.LP +Hook hints are hints that are used at the time of insertion and are not rules +that enforce where a hook lives for its entire lifetime on an event. The valid +values for the \fBh_hint\fR field are: +.sp +.ne 2 +.mk +.na +\fB\fBHH_NONE\fR\fR +.ad +.RS 13n +.rt +Insert the hook wherever convenient. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBHH_FIRST\fR\fR +.ad +.RS 13n +.rt +Place the hook first on the list of hooks. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBHH_LAST\fR\fR +.ad +.RS 13n +.rt +Place the hook last on the list of hooks. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBHH_BEFORE\fR\fR +.ad +.RS 13n +.rt +Place the hook before another hook on the list of hooks. The value in +\fBh_hintvalue\fR must be a pointer to the name of another hook. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBHH_AFTER\fR\fR +.ad +.RS 13n +.rt +Place the hook after another hook on the list of hooks. The value in +\fBh_hintvalue\fR must be a pointer to the name of another hook. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnetinfo\fR(9F) diff --git a/usr/src/man/man9s/iocblk.9s b/usr/src/man/man9s/iocblk.9s new file mode 100644 index 0000000000..6366aa5f08 --- /dev/null +++ b/usr/src/man/man9s/iocblk.9s @@ -0,0 +1,41 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH iocblk 9S "13 Nov 1996" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +iocblk \- STREAMS data structure for the M_IOCTL message type +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH DESCRIPTION +.sp +.LP +The \fBiocblk\fR data structure is used for passing \fBM_IOCTL\fR messages. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +int ioc_cmd; /* ioctl command type */ +cred_t *ioc_cr; /* full credentials */ +uint_t ioc_id; /* ioctl id */ +uint_t ioc_flag; /* ioctl flags */ +uint_t ioc_count; /* count of bytes in data field */ +int ioc_rval; /* return value */ +int ioc_error; /* error code */ +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9s/iovec.9s b/usr/src/man/man9s/iovec.9s new file mode 100644 index 0000000000..fe4ac10923 --- /dev/null +++ b/usr/src/man/man9s/iovec.9s @@ -0,0 +1,42 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH iovec 9S "11 Apr 1991" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +iovec \- data storage structure for I/O using uio +.SH SYNOPSIS +.LP +.nf +#include <sys/uio.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH DESCRIPTION +.sp +.LP +An \fBiovec\fR structure describes a data storage area for transfer in a +\fBuio\fR(9S) structure. Conceptually, it can be thought of as a base address +and length specification. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +caddr_t iov_base; /* base address of the data storage area */ + /* represented by the iovec structure */ +int iov_len; /* size of the data storage area in bytes */ +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBuio\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/kstat.9s b/usr/src/man/man9s/kstat.9s new file mode 100644 index 0000000000..5365d81cdb --- /dev/null +++ b/usr/src/man/man9s/kstat.9s @@ -0,0 +1,149 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kstat 9S "4 Apr 1994" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +kstat \- kernel statistics structure +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kstat.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +Each kernel statistic (\fBkstat\fR) exported by device drivers consists of a +header section and a data section. The \fBkstat\fR structure is the header +portion of the statistic. +.sp +.LP +A driver receives a pointer to a \fBkstat\fR structure from a successful call +to \fBkstat_create\fR(9F). Drivers should never allocate a \fBkstat\fR +structure in any other manner. +.sp +.LP +After allocation, the driver should perform any further initialization needed +before calling \fBkstat_install\fR(9F) to actually export the \fBkstat\fR. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +void *ks_data; /* kstat type-specif. data */ +ulong_t ks_ndata; /* # of type-specif. data + records */ +ulong_t ks_data_size; /* total size of kstat data + section */ +int (*ks_update)(struct kstat *, int); +void *ks_private; /* arbitrary provider-private + data */ +void *ks_lock; /* protects kstat's data */ +.fi +.in -2 + +.sp +.LP +The members of the \fBkstat\fR structure available to examine or set by a +driver are as follows: +.sp +.ne 2 +.mk +.na +\fB\fBks_data\fR \fR +.ad +.RS 17n +.rt +Points to the data portion of the \fBkstat\fR. Either allocated by +\fBkstat_create\fR(9F) for the drivers use, or by the driver if it is using +virtual \fBkstat\fRs. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBks_ndata\fR \fR +.ad +.RS 17n +.rt +The number of data records in this \fBkstat\fR. Set by the \fBks_update\fR(9E) +routine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBks_data_size\fR \fR +.ad +.RS 17n +.rt +The amount of data pointed to by \fBks_data\fR. Set by the \fBks_update\fR(9E) +routine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBks_update\fR \fR +.ad +.RS 17n +.rt +Pointer to a routine that dynamically updates \fBkstat\fR. This is useful for +drivers where the underlying device keeps cheap hardware statistics, but where +extraction is expensive. Instead of constantly keeping the \fBkstat\fR data +section up to date, the driver can supply a \fBks_update\fR(9E) function that +updates the \fBkstat\fR data section on demand. To take advantage of this +feature, set the \fBks_update\fR field before calling \fBkstat_install\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBks_private\fR \fR +.ad +.RS 17n +.rt +Is a private field for the driver's use. Often used in \fBks_update\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBks_lock\fR \fR +.ad +.RS 17n +.rt +Is a pointer to a mutex that protects this \fBkstat\fR. \fBkstat\fR data +sections are optionally protected by the per-\fBkstat\fR \fBks_lock\fR. If +\fBks_lock\fR is non-\fINULL\fR, \fBkstat\fR clients (such as \fB/dev/kstat\fR) +will acquire this lock for all of their operations on that \fBkstat\fR. It is +up to the \fBkstat\fR provider to decide whether guaranteeing consistent data +to \fBkstat\fR 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 \fBks_lock\fR to point to that mutex, +then \fBkstat\fR data locking is free. \fBks_lock\fR is really of type +\fB(kmutex_t*)\fR and is declared as \fB(void*)\fR in the \fBkstat\fR header. +That way, users do not have to be exposed to all of the kernel's lock-related +data structures. +.RE + +.SH SEE ALSO +.sp +.LP +\fBkstat_create\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/kstat_intr.9s b/usr/src/man/man9s/kstat_intr.9s new file mode 100644 index 0000000000..2fd923f4b9 --- /dev/null +++ b/usr/src/man/man9s/kstat_intr.9s @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kstat_intr 9S "4 Apr 1994" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +kstat_intr \- structure for interrupt kstats +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kstat.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +Interrupt statistics are kept in the \fBkstat_intr\fR structure. When +\fBkstat_create\fR(9F) creates an interrupt \fBkstat\fR, the \fBks_data\fR +field is a pointer to one of these structures. The macro \fBKSTAT_INTR_PTR()\fR +is provided to retrieve this field. It looks like this: +.sp +.in +2 +.nf +#define KSTAT_INTR_PTR(kptr) ((kstat_intr_t *)(kptr)->ks_data) +.fi +.in -2 + +.sp +.LP +An interrupt is a hard interrupt (sourced from the hardware device itself), a +soft interrupt (induced by the system through the use of some system interrupt +source), a watchdog interrupt (induced by a periodic timer call), spurious (an +interrupt entry point was entered but there was no interrupt to service), or +multiple service (an interrupt was detected and serviced just prior to +returning from any of the other types). +.sp +.LP +Drivers generally report only claimed hard interrupts and soft interrupts from +their handlers, but measurement of the spurious class of interrupts is useful +for auto-vectored devices in order to pinpoint any interrupt latency problems +in a particular system configuration. +.sp +.LP +Devices that have more than one interrupt of the same type should use multiple +structures. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +ulong_t intrs[KSTAT_NUM_INTRS]; /* interrupt counters */ +.fi +.in -2 + +.sp +.LP +The only member exposed to drivers is the \fBintrs\fR member. This field is an +array of counters. The driver must use the appropriate counter in the array +based on the type of interrupt condition. +.sp +.LP +The following indexes are supported: +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_INTR_HARD\fR \fR +.ad +.RS 24n +.rt +Hard interrupt +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_INTR_SOFT\fR \fR +.ad +.RS 24n +.rt +Soft interrupt +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_INTR_WATCHDOG\fR \fR +.ad +.RS 24n +.rt +Watchdog interrupt +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_INTR_SPURIOUS\fR \fR +.ad +.RS 24n +.rt +Spurious interrupt +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_INTR_MULTSVC\fR \fR +.ad +.RS 24n +.rt +Multiple service interrupt +.RE + +.SH SEE ALSO +.sp +.LP +\fBkstat\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/kstat_io.9s b/usr/src/man/man9s/kstat_io.9s new file mode 100644 index 0000000000..a28378153a --- /dev/null +++ b/usr/src/man/man9s/kstat_io.9s @@ -0,0 +1,76 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kstat_io 9S "4 Apr 1994" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +kstat_io \- structure for I/O kstats +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kstat.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +I/O kstat statistics are kept in a \fBkstat_io\fR structure. When +\fBkstat_create\fR(9F) creates an \fBI/O\fR \fBkstat\fR, the \fBks_data\fR +field is a pointer to one of these structures. The macro \fBKSTAT_IO_PTR()\fR +is provided to retrieve this field. It looks like this: +.sp +.in +2 +.nf +#define KSTAT_IO_PTR(kptr) ((kstat_io_t *)(kptr)->ks_data) +.fi +.in -2 + +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +u_longlong_t nread; /* number of bytes read */ +u_longlong_t nwritten; /* number of bytes written *]/ +ulong_t reads; /* number of read operations */ +ulong_t writes; /* number of write operations */ +.fi +.in -2 + +.sp +.LP +The \fBnread\fR field should be updated by the driver with the number of bytes +successfully read upon completion. +.sp +.LP +The \fBnwritten\fR field should be updated by the driver with the number of +bytes successfully written upon completion. +.sp +.LP +The \fBreads\fR field should be updated by the driver after each successful +read operation. +.sp +.LP +The \fBwrites\fR field should be updated by the driver after each successful +write operation. +.sp +.LP +Other \fBI/O\fR statistics are updated through the use of the +\fBkstat_queue\fR(9F) functions. +.SH SEE ALSO +.sp +.LP +\fBkstat_create\fR(9F), \fBkstat_named_init\fR(9F), \fBkstat_queue\fR(9F), +\fBkstat_runq_back_to_waitq\fR(9F), \fBkstat_runq_enter\fR(9F), +\fBkstat_runq_exit\fR(9F), \fBkstat_waitq_enter\fR(9F), +\fBkstat_waitq_exit\fR(9F), \fBkstat_waitq_to_runq\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/kstat_named.9s b/usr/src/man/man9s/kstat_named.9s new file mode 100644 index 0000000000..4efc473497 --- /dev/null +++ b/usr/src/man/man9s/kstat_named.9s @@ -0,0 +1,55 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kstat_named 9S "4 Apr 1994" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +kstat_named \- structure for named kstats +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kstat.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +Named \fBkstats\fR are an array of name-value pairs. These pairs are kept in +the \fBkstat_named\fR structure. When a \fBkstat\fR is created by +\fBkstat_create\fR(9F), the driver specifies how many of these structures will +be allocated. The structures are returned as an array pointed to by the +\fBks_data\fR field. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +union { + char c[16]; + long l; + ulong_t ul; + longlong_t ll; + u_longlong_t ull; +} value; /* value of counter */ +.fi +.in -2 + +.sp +.LP +The only member exposed to drivers is the \fBvalue\fR member. This field is a +union of several data types. The driver must specify which type it will use in +the call to \fBkstat_named_init()\fR. +.SH SEE ALSO +.sp +.LP +\fBkstat_create\fR(9F), \fBkstat_named_init\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/linkblk.9s b/usr/src/man/man9s/linkblk.9s new file mode 100644 index 0000000000..de3f5bcc79 --- /dev/null +++ b/usr/src/man/man9s/linkblk.9s @@ -0,0 +1,47 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH linkblk 9S "7 Jul 1994" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +linkblk \- STREAMS data structure sent to multiplexor drivers to indicate a +link +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI) +.SH DESCRIPTION +.sp +.LP +The \fBlinkblk\fR structure is used to connect a lower Stream to an upper +STREAMS multiplexor driver. This structure is used in conjunction with the +\fBI_LINK\fR, \fBI_UNLINK\fR, \fBP_LINK\fR, and \fBP_UNLINK\fR ioctl commands. +See \fBstreamio\fR(7I). The \fBM_DATA\fR portion of the \fBM_IOCTL\fR +message contains the \fBlinkblk\fR structure. Note that the \fBlinkblk\fR +structure is allocated and initialized by the Stream head as a result of one +of the above ioctl commands. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +queue_t *l_qtop; /* lowest level write queue of upper stream */ + /* (set to NULL for persistent links) */ +queue_t *l_qbot; /* highest level write queue of lower stream */ +int l_index; /* index for lower stream. */ +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBioctl\fR(2), \fBstreamio\fR(7I) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9s/modldrv.9s b/usr/src/man/man9s/modldrv.9s new file mode 100644 index 0000000000..ffe222e8f6 --- /dev/null +++ b/usr/src/man/man9s/modldrv.9s @@ -0,0 +1,77 @@ +'\" te +.\" Copyright (C) 2001, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH modldrv 9S "5 Mar 2001" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +modldrv \- linkage structure for loadable drivers +.SH SYNOPSIS +.LP +.nf +#include <sys/modctl.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBmodldrv\fR structure is used by device drivers to export driver specific +information to the kernel. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +struct mod_ops *drv_modops; +char *drv_linkinfo; +struct dev_ops *drv_dev_ops; +.fi +.in -2 + +.sp +.ne 2 +.mk +.na +\fB\fBdrv_modops\fR \fR +.ad +.RS 17n +.rt +Must always be initialized to the address of \fBmod_driverops\fR. This member +identifies the module as a loadable driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdrv_linkinfo\fR \fR +.ad +.RS 17n +.rt +Can be any string up to \fBMODMAXNAMELEN\fR characters (including the +terminating NULL character), and is used to describe the module and its version +number. This is usually the name of the driver and module version information, +but can contain other information as well. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdrv_dev_ops\fR \fR +.ad +.RS 17n +.rt +Pointer to the driver's \fBdev_ops\fR(9S) structure. +.RE + +.SH SEE ALSO +.sp +.LP +\fBadd_drv\fR(1M), \fBdev_ops\fR(9S), \fBmodlinkage\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/modlinkage.9s b/usr/src/man/man9s/modlinkage.9s new file mode 100644 index 0000000000..5cc116d1a7 --- /dev/null +++ b/usr/src/man/man9s/modlinkage.9s @@ -0,0 +1,65 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH modlinkage 9S "18 Sep 1992" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +modlinkage \- module linkage structure +.SH SYNOPSIS +.LP +.nf +#include <sys/modctl.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBmodlinkage\fR structure is provided by the module writer to the routines +that install, remove, and retrieve information from a module. See +\fB_init\fR(9E), \fB_fini\fR(9E), and \fB_info\fR(9E). +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +int ml_rev +void *ml_linkage[4]; +.fi +.in -2 + +.sp +.ne 2 +.mk +.na +\fB\fBml_rev\fR \fR +.ad +.RS 15n +.rt +Is the revision of the loadable modules system. This must have the value +\fBMODREV_1\fR . +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBml_linkage\fR \fR +.ad +.RS 15n +.rt +Is a null-terminated array of pointers to linkage structures. Driver modules +have only one linkage structure. +.RE + +.SH SEE ALSO +.sp +.LP +\fBadd_drv\fR(1M), \fB_fini\fR(9E), \fB_info\fR(9E), \fB_init\fR(9E), +\fBmodldrv\fR(9S), \fBmodlstrmod\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/modlmisc.9s b/usr/src/man/man9s/modlmisc.9s new file mode 100644 index 0000000000..09616d1a47 --- /dev/null +++ b/usr/src/man/man9s/modlmisc.9s @@ -0,0 +1,61 @@ +'\" te +.\" Copyright (c) 2007 Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH modlmisc 9S "6 Nov 2007" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +modlmisc \- linkage structure for loadable miscellaneous modules +.SH SYNOPSIS +.LP +.nf +#include <sys/modctl.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBmodlmisc\fR structure is used by miscellaneous modules to export module +specific information to the kernel. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +struct mod_ops *misc_modops; +char *misc_linkinfo; +.fi +.in -2 + +.sp +.ne 2 +.mk +.na +\fB\fBmisc_modops\fR\fR +.ad +.RS 17n +.rt +Must always be initialized to the address of \fBmod_miscops\fR. This member +identifies the module as a loadable miscellaneous module. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBmisc_linkinfo\fR\fR +.ad +.RS 17n +.rt +Can be any string up to \fBMODMAXNAMELEN\fR characters (including the +terminating \fBNULL\fR characters), and is used to describe the module, but can +also contain other information (such as a version number). +.RE + +.SH SEE ALSO +.sp +.LP +\fBmodload\fR(1M), \fBmodlinkage\fR(9S) diff --git a/usr/src/man/man9s/modlstrmod.9s b/usr/src/man/man9s/modlstrmod.9s new file mode 100644 index 0000000000..47380e83b8 --- /dev/null +++ b/usr/src/man/man9s/modlstrmod.9s @@ -0,0 +1,77 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH modlstrmod 9S "7 Jun 1993" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +modlstrmod \- linkage structure for loadable STREAMS modules +.SH SYNOPSIS +.LP +.nf +#include <sys/modctl.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBmodlstrmod\fR structure is used by STREAMS modules to export module +specific information to the kernel. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +struct mod_ops *strmod_modops; +char *strmod_linkinfo; +struct fmodsw *strmod_fmodsw; +.fi +.in -2 + +.sp +.ne 2 +.mk +.na +\fB\fBstrmod_modops\fR \fR +.ad +.RS 20n +.rt +Must always be initialized to the address of \fBmod_strmodops\fR. This +identifies the module as a loadable STREAMS module. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBstrmod_linkinfo\fR \fR +.ad +.RS 20n +.rt +Can be any string up to \fBMODMAXNAMELEN\fR, and is used to describe the +module. This string is usually the name of the module, but can contain other +information (such as a version number). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBstrmod_fmodsw\fR \fR +.ad +.RS 20n +.rt +Is a pointer to a template of a class entry within the module that is copied to +the kernel's class table when the module is loaded. +.RE + +.SH SEE ALSO +.sp +.LP +\fBmodload\fR(1M) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/module_info.9s b/usr/src/man/man9s/module_info.9s new file mode 100644 index 0000000000..bf40b3ce38 --- /dev/null +++ b/usr/src/man/man9s/module_info.9s @@ -0,0 +1,59 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH module_info 9S "26 Nov 2002" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +module_info \- STREAMS driver identification and limit value structure +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH DESCRIPTION +.sp +.LP +When a module or driver is declared, several identification and limit values +can be set. These values are stored in the \fBmodule_info\fR structure. +.sp +.LP +The \fBmodule_info\fR structure is intended to be read-only. However, the flow +control limits (\fBmi_hiwat\fR and \fBmi_lowat\fR) and the packet size limits +(\fBmi_minpsz\fR and \fBmi_maxpsz\fR) are copied to the \fBQUEUE\fR structure, +where they can be modified. +.sp +.LP +For a driver, \fBmi_idname\fR must match the name of the driver binary file. +For a module, \fBmi_idname\fR must match the fname field of the \fBfmodsw\fR +structure. See \fBfmodsw\fR(9S) for details. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +ushort_t mi_idnum; /* module ID number */ +char *mi_idname; /* module name */ +ssize_t mi_minpsz; /* minimum packet size */ +ssize_t mi_maxpsz; /* maximum packet size */ +size_t mi_hiwat; /* high water mark */ +size_t mi_lowat; /* low water mark */ +.fi +.in -2 + +.sp +.LP +The constant \fBFMNAMESZ\fR, limiting the length of a module's name, is set to +eight in this release. +.SH SEE ALSO +.sp +.LP +\fBfmodsw\fR(9S), \fBqueue\fR(9S) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9s/msgb.9s b/usr/src/man/man9s/msgb.9s new file mode 100644 index 0000000000..e0d5d50669 --- /dev/null +++ b/usr/src/man/man9s/msgb.9s @@ -0,0 +1,84 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH msgb 9S "11 Apr 1991" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +msgb, mblk \- STREAMS message block structure +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI) +.SH DESCRIPTION +.sp +.LP +A STREAMS message is made up of one or more message blocks, referenced by a +pointer to a \fBmsgb\fR structure. The \fBb_next\fR and \fBb_prev\fR pointers +are used to link messages together on a \fBQUEUE\fR. The \fBb_cont\fR pointer +links message blocks together when a message consists of more than one block. +.sp +.LP +Each \fBmsgb\fR structure also includes a pointer to a \fBdatab\fR(9S) +structure, the data block (which contains pointers to the actual data of the +message), and the type of the message. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +struct msgb *b_next; /* next message on queue */ +struct msgb *b_prev; /* previous message on queue */ +struct msgb *b_cont; /* next message block */ +unsigned char *b_rptr; /* 1st unread data byte of buffer */ +unsigned char *b_wptr; /* 1st unwritten data byte of buffer */ +struct datab *b_datap; /* pointer to data block */ +unsigned char b_band; /* message priority */ +unsigned short b_flag; /* used by stream head */ +.fi +.in -2 + +.sp +.LP +Valid flags are as follows: +.sp +.ne 2 +.mk +.na +\fB\fBMSGMARK\fR \fR +.ad +.RS 13n +.rt +Last byte of message is marked. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMSGDELIM\fR \fR +.ad +.RS 13n +.rt +Message is delimited. +.RE + +.sp +.LP +The \fBmsgb\fR structure is defined as type \fBmblk_t\fR. +.SH SEE ALSO +.sp +.LP +\fBdatab\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9s/net_inject_t.9s b/usr/src/man/man9s/net_inject_t.9s new file mode 100644 index 0000000000..148a13733a --- /dev/null +++ b/usr/src/man/man9s/net_inject_t.9s @@ -0,0 +1,92 @@ +'\" te +.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_inject_t 9S "1 May 2008" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +net_inject_t \- structure for describing how to transmit a packet +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBnet_inject_t\fR data structure passes information in to \fBnet_inject\fR +about how to transmit a packet. Transmit includes sending the packet up into +the system as well as out of it. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf + mblk_t *ni_packet; /* start of the packet */ + struct sockaddr_storage ni_addr; /* address of next hop */ + phy_if_t ni_physical; /* network interface to use */ +.fi +.in -2 + +.sp +.ne 2 +.mk +.na +\fB\fBni_packet\fR\fR +.ad +.RS 15n +.rt +Pointer to the first the \fBmblk_t\fR data structure that makes up this packet. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBni_addr\fR\fR +.ad +.RS 15n +.rt +This field is only required to be initialized if \fBNI_DIRECT_OUT\fR is being +used to transmit the packet. The \fBsockaddr_storage\fR field must be set to +indicate whether the destination address contained in the structure is +\fBIPv4\fR (cast \fIni_addr\fR to struct \fIsockaddr_in\fR) or \fBIPv6\fR (cast +\fIni_addr\fR to struct \fIsockaddr_in6\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBni_physical\fR\fR +.ad +.RS 15n +.rt +The physical interface where the packet will be injected. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_inject\fR(9F), \fBnetinfo\fR(9F), \fBattributes\fR(5) diff --git a/usr/src/man/man9s/net_instance_t.9s b/usr/src/man/man9s/net_instance_t.9s new file mode 100644 index 0000000000..8a187f356d --- /dev/null +++ b/usr/src/man/man9s/net_instance_t.9s @@ -0,0 +1,104 @@ +'\" te +.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_instance_t 9S "1 May 2008" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +net_instance_t \- packet event structure passed through to hooks +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBnet_instance_t\fR data structure defines a collection of instances to be +called when relevant events happen within \fBIP\fR. The value returned by the +\fBnin_create()\fR function is stored internally and passed back to both the +\fBnin_destroy()\fR and \fBnin_shutdown()\fR functions as the second argument. +The \fBnetid_t\fR passed through to each function can be used to uniquely +identify each instance of \fBIP\fR. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf + char *nin_name; + void *(*nin_create)(const netid_t); + void (*nin_destroy)(const netid_t, void *); + void (*nin_shutdown)(const netid_t, void *); +.fi +.in -2 + +.sp +.ne 2 +.mk +.na +\fB\fBnin_name\fR\fR +.ad +.RS 16n +.rt +Name of the owner of the instance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnin_create\fR\fR +.ad +.RS 16n +.rt +Function to be called when a new instance of \fBIP\fR is created. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnin_destroy\fR\fR +.ad +.RS 16n +.rt +Function to be called when an instance of \fBIP\fR is being destroyed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnin_shutdown\fR\fR +.ad +.RS 16n +.rt +Function to be called when an instance of \fBIP\fR is being shutdown. +\fBnin_shutdown()\fR is called before \fBnin_destroy()\fR is called. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnetinfo\fR(9F), \fBattributes\fR(5) diff --git a/usr/src/man/man9s/qband.9s b/usr/src/man/man9s/qband.9s new file mode 100644 index 0000000000..0cb0da9408 --- /dev/null +++ b/usr/src/man/man9s/qband.9s @@ -0,0 +1,81 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH qband 9S "14 Nov 1996" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +qband \- STREAMS queue flow control information structure +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI) +.SH DESCRIPTION +.sp +.LP +The \fBqband\fR structure contains flow control information for each priority +band in a queue. +.sp +.LP +The \fBqband\fR structure is defined as type \fBqband_t\fR. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +struct qband*qb_next; /* next band's info */ +size_t qb_count /* number of bytes in band */ +struct msgb *qb_first; /* start of band's data */ +struct msgb *qb_last; /* end of band's data */ +size_t qb_hiwat; /* band's high water mark */ +size_t qb_lowat; /* band's low water mark */ +uint_t qb_flag; /* see below */ +.fi +.in -2 + +.sp +.LP +Valid flags are as follows: +.sp +.ne 2 +.mk +.na +\fB\fBQB_FULL\fR \fR +.ad +.RS 13n +.rt +Band is considered full. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQB_WANTW\fR \fR +.ad +.RS 13n +.rt +Someone wants to write to band. +.RE + +.SH SEE ALSO +.sp +.LP +\fBstrqget\fR(9F), \fBstrqset\fR(9F), \fBmsgb\fR(9S), \fBqueue\fR(9S) +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH NOTES +.sp +.LP +All access to this structure should be through \fBstrqget\fR(9F) and +\fBstrqset\fR(9F). It is logically part of the \fBqueue\fR(9S) and its layout +and partitioning with respect to that structure might change in future +releases. If portability is a concern, do not declare or store instances of or +references to this structure. diff --git a/usr/src/man/man9s/qinit.9s b/usr/src/man/man9s/qinit.9s new file mode 100644 index 0000000000..8bb2d4a85a --- /dev/null +++ b/usr/src/man/man9s/qinit.9s @@ -0,0 +1,54 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH qinit 9S "11 Apr 1991" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +qinit \- STREAMS queue processing procedures structure +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI) +.SH DESCRIPTION +.sp +.LP +The \fBqinit\fR structure contains pointers to processing procedures for a +\fBQUEUE\fR. The \fBstreamtab\fR structure for the module or driver contains +pointers to one \fBqueue\fR(9S) structure for both upstream and downstream +processing. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +int (*qi_putp)(); /* put procedure */ +int (*qi_srvp)(); /* service procedure */ +int (*qi_qopen)(); /* open procedure */ +int (*qi_qclose)(); /* close procedure */ +int (*qi_qadmin)(); /* unused */ +struct module_info *qi_minfo; /* module parameters */ +struct module_stat *qi_mstat; /* module statistics */ +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBqueue\fR(9S), \fBstreamtab\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH NOTES +.sp +.LP +This release includes no support for module statistics. diff --git a/usr/src/man/man9s/queclass.9s b/usr/src/man/man9s/queclass.9s new file mode 100644 index 0000000000..ea483db78a --- /dev/null +++ b/usr/src/man/man9s/queclass.9s @@ -0,0 +1,35 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH queclass 9S "07 Mar 1994" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +queclass \- a STREAMS macro that returns the queue message class definitions +for a given message block +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + +\fB\fR\fBqueclass\fR(\fBmblk_t *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +\fBqueclass\fR returns the queue message class definition for a given data +block pointed to by the message block \fIbp\fR passed in. +.sp +.LP +The message can be either \fBQNORM\fR, a normal priority message, or +\fBQPCTL\fR, a high priority message. +.SH SEE ALSO +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9s/queue.9s b/usr/src/man/man9s/queue.9s new file mode 100644 index 0000000000..fa672b7672 --- /dev/null +++ b/usr/src/man/man9s/queue.9s @@ -0,0 +1,246 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH queue 9S "10 Jan 2006" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +queue \- STREAMS queue structure +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI) +.SH DESCRIPTION +.sp +.LP +A \fBSTREAMS\fR driver or module consists of two \fBqueue\fR structures: +\fIread\fR for upstream processing and \fIwrite\fR for downstream processing. +The queue structure is the major building block of a stream. +.SS "\fBqueue\fR Structure Members" +.sp +.LP +The \fBqueue\fR structure is defined as type \fBqueue_t\fR. The structure can +be accessed at any time from inside a \fBSTREAMS\fR entry point associated with +that queue. +.sp +.in +2 +.nf +struct qinit *q_qinfo; /* queue processing procedure */ +struct msgb *q_first; /* first message in queue */ +struct msgb *q_last; /* last message in queue */ +struct queue *q_next; /* next queue in stream */ +void *q_ptr; /* module-specific data */ +size_t q_count; /* number of bytes on queue */ +uint_t q_flag; /* queue state */ +ssize_t q_minpsz; /* smallest packet OK on queue */ +ssize_t q_maxpsz; /* largest packet OK on queue */ +size_t q_hiwat; /* queue high water mark */ +size_t q_lowat; /* queue low water mark */ +.fi +.in -2 + +.sp +.LP +Contstraints and restrictions on the use of \fBq_flag\fR and \fBqueue_t\fR +fields and the \fBq_next\fR values are detailed in the following sections. +.SS "\fBq_flag\fR Field" +.sp +.LP +The \fBq_flag\fR field must be used only to check the following flag values. +.sp +.ne 2 +.mk +.na +\fB\fBQFULL\fR\fR +.ad +.RS 10n +.rt +Queue is full. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQREADR\fR\fR +.ad +.RS 10n +.rt +Queue is used for upstream (read-side) processing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQUSE\fR\fR +.ad +.RS 10n +.rt +Queue has been allocated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQENAB\fR\fR +.ad +.RS 10n +.rt +Queue has been enabled for service by \fBqenable\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQNOENB\fR\fR +.ad +.RS 10n +.rt +Queue will not be scheduled for service by \fBputq\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQWANTR\fR\fR +.ad +.RS 10n +.rt +Upstream processing element wants to read from queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQWANTW\fR\fR +.ad +.RS 10n +.rt +Downstream processing element wants to write to queue. +.RE + +.SS "\fBqueue_t\fR Fields" +.sp +.LP +Aside from \fBq_ptr\fR and \fBq_qinfo\fR, a module or driver must never assume +that a \fBqueue_t\fR field value will remain unchanged across calls to +\fBSTREAMS\fR entry points. In addition, many fields can change values inside a +\fBSTREAMS\fR entry point, especially if the \fBSTREAMS\fR module or driver has +perimeters that allow parallelism. See \fBmt-streams\fR(9F). Fields that are +not documented below are private to the \fBSTREAMS\fR framework and must not be +accessed. +.RS +4 +.TP +.ie t \(bu +.el o +The values of the \fBq_hiwat\fR, \fBq_lowat\fR, \fBq_minpsz\fR, and +\fBq_maxpsz\fR fields can be changed at the discretion of the module or driver. +As such, the stability of their values depends on the perimeter configuration +associated with any routines that modify them. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The values of the \fBq_first\fR, \fBq_last\fR, and \fBq_count\fR fields can +change whenever \fBputq\fR(9F), \fBputbq\fR(9F), \fBgetq\fR(9F), +\fBinsq\fR(9F), or \fBrmvq\fR(9F) is used on the queue. As such, the stability +of their values depends on the perimeter configuration associated with any +routines that call those \fBSTREAMS\fR functions. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fBq_flag\fR field can change at any time. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fBq_next\fR field will not change while inside a given \fBSTREAMS\fR entry +point. Additional restrictions on the use of the \fBq_next\fR value are +described in the next section. +.RE +.sp +.LP +A \fBSTREAMS\fR module or driver can assign any value to \fBq_ptr\fR. Typically +\fBq_ptr\fR is used to point to module-specific per-queue state, allocated in +\fBopen\fR(9E) and freed in \fBclose\fR(9E). The value or contents of +\fBq_ptr\fR is never inspected by the \fBSTREAMS\fR framework. +.sp +.LP +The initial values for \fBq_minpsz\fR, \fBq_maxpsz\fR, \fBq_hiwat\fR, and +\fBq_lowat\fR are set using the \fBmodule_info\fR(9S) structure when +\fBmod_install\fR(9F) is called. A \fBSTREAMS\fR\ module or driver can +subsequently change the values of those fields as necessary. The remaining +visible fields, \fBq_qinfo\fR, \fBq_first\fR, \fBq_last\fR, \fBq_next\fR, +\fBq_count\fR, and \fBq_flag\fR, must never be modified by a module or driver. +.sp +.LP +The Solaris DDI requires that \fBSTREAMS\fR modules and drivers obey the rules +described on this page. Those that do not follow the rules can cause data +corruption or system instability, and might change in behavior across patches +or upgrades. +.SS "\fBq_next\fR Restrictions" +.sp +.LP +There are additional restrictions associated with the use of the \fBq_next\fR +value. In particular, a \fBSTREAMS\fR module or driver: +.RS +4 +.TP +.ie t \(bu +.el o +Must not access the data structure pointed to by \fBq_next\fR. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Must not rely on the value of \fBq_next\fR before calling \fBqprocson\fR(9F) or +after calling \fBqprocsoff\fR(9F). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Must not pass the value into any \fBSTREAMS\fR framework function other than +\fBput\fR(9F), \fBcanput\fR(9F), \fBbcanput\fR(9F), \fBputctl\fR(9F), +\fBputctl1\fR(9F). However, in all cases the "next" version of these functions, +such as \fBputnext\fR(9F), should be preferred. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Must not use the value to compare against queue pointers from other streams. +However, checking \fBq_next\fR for NULL can be used to distinguish a module +from a driver in code shared by both. +.RE +.SH SEE ALSO +.sp +.LP +\fBclose\fR(9E), \fBopen\fR(9E), \fBbcanput\fR(9F), \fBcanput\fR(9F), +\fBgetq\fR(9F), \fBinsq\fR(9F), \fBmod_install\fR(9F), \fBput\fR(9F), +\fBputbq\fR(9F), \fBputctl\fR(9F), \fBputctl1\fR(9F), \fBputnext\fR(9F), +\fBputq\fR(9F), \fBqprocsoff\fR(9F), \fBqprocson\fR(9F), \fBrmvq\fR(9F), +\fBstrqget\fR(9F), \fBstrqset\fR(9F), \fBmodule_info\fR(9S), \fBmsgb\fR(9S), +\fBqinit\fR(9S), \fBstreamtab\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9s/scsi_address.9s b/usr/src/man/man9s/scsi_address.9s new file mode 100644 index 0000000000..cf2d6f38fd --- /dev/null +++ b/usr/src/man/man9s/scsi_address.9s @@ -0,0 +1,70 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_address 9S "30 Aug 1995" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +scsi_address \- SCSI address structure +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +A \fBscsi_address\fR structure defines the addressing components for a +\fBSCSI\fR target device. The address of the target device is separated into +two components: target number and logical unit number. The two addressing +components are used to uniquely identify any type of \fBSCSI\fR device; +however, most devices can be addressed with the target component of the +address. +.sp +.LP +In the case where only the target component is used to address the device, the +logical unit should be set to \fB0\fR. If the \fBSCSI\fR target device +supports logical units, then the \fBHBA\fR must interpret the logical units +field of the data structure. +.sp +.LP +The \fBpkt_address\fR member of a \fBscsi_pkt\fR(9S) is initialized by +\fBscsi_init_pkt\fR(9F). +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +scsi_hba_tran_t *a_hba_tran; /* Transport vectors for the SCSI bus */ +ushort_t a_target; /* SCSI target id */ +uchar_t a_lun; /* SCSI logical unit */ +.fi +.in -2 + +.sp +.LP +\fBa_hba_tran\fR is a pointer to the controlling \fBHBA\fR's transport vector +structure. The \fBSCSA\fR interface uses this field to pass any transport +requests from the \fBSCSI\fR target device drivers to the \fBHBA\fR driver. +.sp +.LP +\fBa_target\fR is the target component of the \fBSCSI\fR address. +.sp +.LP +\fBa_lun\fR is the logical unit component of the \fBSCSI\fR address. The +logical unit is used to further distinguish a \fBSCSI\fR target device that +supports multiple logical units from one that does not. The \fBmakecom\fR(9F) +family of functions use the \fBa_lun\fR field to set the logical unit field in +the \fBSCSI\fR \fBCDB\fR, for compatibility with \fBSCSI-1\fR. +.SH SEE ALSO +.sp +.LP +\fBmakecom\fR(9F), \fBscsi_init_pkt\fR(9F), \fBscsi_hba_tran\fR(9S), +\fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/scsi_arq_status.9s b/usr/src/man/man9s/scsi_arq_status.9s new file mode 100644 index 0000000000..5792eca23a --- /dev/null +++ b/usr/src/man/man9s/scsi_arq_status.9s @@ -0,0 +1,81 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. , All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_arq_status 9S "30 Sep 1996" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +scsi_arq_status \- SCSI auto request sense structure +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +When auto request sense has been enabled using \fBscsi_ifsetcap\fR(9F) and the +"auto-rqsense" capability, the target driver must allocate a status area in the +\fBSCSI\fR packet structure for the auto request sense structure (see +\fBscsi_pkt\fR(9S)). In the event of a \fBcheck\fR \fIcondition\fR, the +transport layer automatically executes a request sense command. This check +ensures that the request sense information does not get lost. The auto request +sense structure supplies the \fBSCSI\fR status of the original command, the +transport information pertaining to the request sense command, and the request +sense data. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +struct scsi_status sts_status; /* SCSI status */ +struct scsi_status sts_rqpkt_status; /* SCSI status of + request sense cmd */ +uchar_t sts_rqpkt_reason; /* reason completion */ +uchar_t sts_rqpkt_resid; /* residue */ +uint_t sts_rqpkt_state; /* state of command */ +uint_t sts_rqpkt_statistics;/* statistics */ +struct scsi_extended_sense sts_sensedata; /* actual sense data */ +.fi +.in -2 + +.sp +.LP +\fBsts_status\fR is the \fBSCSI\fR status of the original command. If the +status indicates a \fBcheck\fR \fIcondition\fR, the transport layer might have +performed an auto request sense command. +.sp +.LP +\fBsts_rqpkt_status\fR is the \fBSCSI\fR status of the request sense command. +\fBsts_rqpkt_reason\fR is the completion reason of the request sense command. +If the reason is not \fBCMD_CMPLT\fR, then the request sense command did not +complete normally. +.sp +.LP +\fBsts_rqpkt_resid\fR is the residual count of the data transfer and indicates +the number of data bytes that have not been transferred. The auto request sense +command requests \fBSENSE_LENGTH\fR bytes. +.sp +.LP +\fBsts_rqpkt_state\fR has bit positions representing the five most important +statuses that a \fBSCSI \fRcommand can go obtain. +.sp +.LP +\fBsts_rqpkt_statistics\fR maintains transport-related statistics of the +request sense command. +.sp +.LP +\fBsts_sensedata\fR contains the actual sense data if the request sense command +completed normally. +.SH SEE ALSO +.sp +.LP +\fBscsi_ifgetcap\fR(9F), \fBscsi_init_pkt\fR(9F), +\fBscsi_extended_sense\fR(9S), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/scsi_asc_key_strings.9s b/usr/src/man/man9s/scsi_asc_key_strings.9s new file mode 100644 index 0000000000..7fd323e05b --- /dev/null +++ b/usr/src/man/man9s/scsi_asc_key_strings.9s @@ -0,0 +1,50 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_asc_key_strings 9S "24 Feb 1998" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +scsi_asc_key_strings \- SCSI ASC ASCQ to message structure +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP + Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBscsi_asc_key_strings\fR structure stores the ASC and ASCQ codes and a +pointer to the related ASCII string. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +ushort_t asc; /* ASC code */ +ushort_t ascq; /* ASCQ code */ +char *message; /* ASCII message string */ + +asc Contains the ASC key code. + +ascq Contains the ASCQ code. + +message Points to the NULL terminated ASCII string + describing the asc and ascq condition +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBscsi_vu_errmsg\fR(9F) +.sp +.LP +\fIANSI Small Computer System Interface-2 (SCSI-2)\fR +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/scsi_device.9s b/usr/src/man/man9s/scsi_device.9s new file mode 100644 index 0000000000..3a5499fdf5 --- /dev/null +++ b/usr/src/man/man9s/scsi_device.9s @@ -0,0 +1,83 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_device 9S "19 Feb 1993" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +scsi_device \- SCSI device structure +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBscsi_device\fR structure stores common information about each SCSI +logical unit, including pointers to areas that contain both generic and device +specific information. There is one \fBscsi_device\fR structure for each logical +unit attached to the system. The host adapter driver initializes part of this +structure prior to \fBprobe\fR(9E) and destroys this structure after a probe +failure or successful \fBdetach\fR(9E). +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +struct scsi_address sd_address; /* Routing info. */ +dev_info_t *sd_dev; /* Cross-ref. to */ + /* dev_info_t */ +kmutex_t sd_mutex; /* Mutex for this dev. */ +struct scsi_inquiry *sd_inq; /* scsi_inquiry data struc. */ +struct scsi_extended_sense *sd_sense; /* Optional request */ + /* sense buffer ptr */ +caddr_t sd_private; /* Target drivers + private data */ +.fi +.in -2 + +.sp +.LP +\fBsd_address\fR contains the routing information that the target driver +normally copies into a \fBscsi_pkt\fR(9S) structure using the collection of +\fBmakecom\fR(9F) functions. The \fBSCSA\fR library routines use this +information to determine which host adapter, \fBSCSI\fR bus, and target/logical +unit number (lun) a command is intended for. This structure is initialized by +the host adapter driver. +.sp +.LP +\fBsd_dev\fR is a pointer to the corresponding \fBdev_info\fR structure. This +pointer is initialized by the host adapter driver. +.sp +.LP +\fBsd_mutex\fR is a mutual exclusion lock for this device. It is used to +serialize access to a device. The host adapter driver initializes this mutex. +See \fBmutex\fR(9F). +.sp +.LP +\fBsd_inq\fR is initially \fINULL\fR (zero). After executing +\fBscsi_probe\fR(9F), this field contains the inquiry data associated with the +particular device. +.sp +.LP +\fBsd_sense\fR is initially \fINULL\fR (zero). If the target driver wants to +use this field for storing \fBREQUEST SENSE\fR data, it should allocate an +\fBscsi_extended_sense\fR(9S) buffer and set this field to the address of this +buffer. +.sp +.LP +\fBsd_private\fR is reserved for the use of target drivers and should generally +be used to point to target specific data structures. +.SH SEE ALSO +.sp +.LP +\fBdetach\fR(9E), \fBprobe\fR(9E), \fBmakecom\fR(9F), \fBmutex\fR(9F), +\fBscsi_probe\fR(9F), \fBscsi_extended_sense\fR(9S), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/scsi_extended_sense.9s b/usr/src/man/man9s/scsi_extended_sense.9s new file mode 100644 index 0000000000..34d7bc81ca --- /dev/null +++ b/usr/src/man/man9s/scsi_extended_sense.9s @@ -0,0 +1,306 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. , All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_extended_sense 9S "30 Aug 1995" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +scsi_extended_sense \- SCSI extended sense structure +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBscsi_extended_sense\fR structure for error codes \fB0x70\fR (current +errors) and \fB0x71\fR (deferred errors) is returned on a successful \fBREQUEST +SENSE\fR command. \fBSCSI-2 \fRcompliant targets are required to return at +least the first 18 bytes of this structure. This structure is part of +\fBscsi_device\fR(9S) structure. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +uchar_t es_valid :1; /* Sense data is valid */ +uchar_t es_class :3; /* Error Class- fixed at 0x7 */ +uchar_t es_code :4; /* Vendor Unique error code */ +uchar_t es_segnum; /* Segment number: for COPY cmd only */ +uchar_t es_filmk :1; /* File Mark Detected */ +uchar_t es_eom :1; /* End of Media */ +uchar_t es_ili :1; /* Incorrect Length Indicator */ +uchar_t es_key :4; /* Sense key */ +uchar_t es_info_1; /* Information byte 1 */ +uchar_t es_info_2; /* Information byte 2 */ +uchar_t es_info_3; /* Information byte 3 */ +uchar_t es_info_4; /* Information byte 4 */ +uchar_t es_add_len; /* Number of additional bytes */ +uchar_t es_cmd_info[4]; /* Command specific information */ +uchar_t es_add_code; /* Additional Sense Code */ +uchar_t es_qual_code; /* Additional Sense Code Qualifier */ +uchar_t es_fru_code; /* Field Replaceable Unit Code */ +uchar_t es_skey_specific[3]; /* Sense Key Specific information */ +.fi +.in -2 + +.sp +.LP +\fBes_valid\fR, if set, indicates that the information field contains valid +information. +.sp +.LP +\fBes_class\fR should be \fB0x7\fR. +.sp +.LP +\fBes_code\fR is either \fB0x0\fR or \fB0x1\fR. +.sp +.LP +\fBes_segnum\fR contains the number of the current segment descriptor if the +\fBREQUEST SENSE \fRcommand is in response to a \fBCOPY\fR, \fBCOMPARE\fR, and +\fBCOPY AND VERIFY\fR command. +.sp +.LP +\fBes_filmk\fR, if set, indicates that the current command had read a file mark +or set mark (sequential access devices only). +.sp +.LP +\fBes_eom\fR, if set, indicates that an end-of-medium condition exists +(sequential access and printer devices only). +.sp +.LP +\fBes_ili\fR, if set, indicates that the requested logical block length did not +match the logical block length of the data on the medium. +.sp +.LP +\fBes_key\fR indicates generic information describing an error or exception +condition. The following sense keys are defined: +.sp +.ne 2 +.mk +.na +\fB\fBKEY_NO_SENSE\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that there is no specific sense key information to be reported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_RECOVERABLE_ERROR\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that the last command completed successfully with some recovery +action performed by the target. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_NOT_READY\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that the logical unit addressed cannot be accessed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_MEDIUM_ERROR\fR \fR +.ad +.sp .6 +.RS 4n +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_HARDWARE_ERROR\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that the target detected a non-recoverable hardware failure while +performing the command or during a self test. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_ILLEGAL_REQUEST\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that there was an illegal parameter in the \fBCDB\fR or in the +additional parameters supplied as data for some commands. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_UNIT_ATTENTION\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that the removable medium might have been changed or the target has +been reset. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_WRITE_PROTECT/KEY_DATA_PROTECT\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that a command that reads or writes the medium was attempted on a +block that is protected from this operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_BLANK_CHECK\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that a write-once device or a sequential access device encountered +blank medium or format-defined end-of-data indication while reading or a +write-once device encountered a non-blank medium while writing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_VENDOR_UNIQUE\fR \fR +.ad +.sp .6 +.RS 4n +This sense key is available for reporting vendor-specific conditions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_COPY_ABORTED\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that a \fBCOPY\fR, \fBCOMPARE\fR, and \fBCOPY AND VERIFY\fR command +was aborted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_ABORTED_COMMAND\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that the target aborted the command. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_EQUAL\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that a \fBSEARCH\fR \fBDATA\fR command has satisfied an equal +comparison. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_VOLUME_OVERFLOW\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that a buffered peripheral device has reached the end-of-partition +and data might remain in the buffer that has not been written to the medium. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_MISCOMPARE\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that the source data did not match the data read from the medium. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKEY_RESERVE\fR \fR +.ad +.sp .6 +.RS 4n +Indicates that the target is currently reserved by a different initiator. +.RE + +.sp +.LP +\fBes_info_{1,2,3,4}\fR is device-type or command specific. +.sp +.LP +\fBes_add_len\fR indicates the number of additional sense bytes to follow. +.sp +.LP +\fBes_cmd_info\fR contains information that depends on the command that was +executed. +.sp +.LP +\fBes_add_code\fR (\fBASC\fR) indicates further information related to the +error or exception condition reported in the sense key field. +.sp +.LP +\fBes_qual_code\fR (\fBASCQ)\fR indicates detailed information related to the +additional sense code. +.sp +.LP +\fBes_fru_code\fR (\fBFRU\fR) indicates a device-specific mechanism to unit +that has failed. +.sp +.LP +\fBes_skey_specific\fR is defined when the value of the sense-key specific +valid bit (bit 7) is \fB1\fR. This field is reserved for sense keys not defined +above. +.SH SEE ALSO +.sp +.LP +\fBscsi_device\fR(9S) +.sp +.LP +\fIANSI Small Computer System Interface-2 (SCSI-2)\fR +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/scsi_hba_tran.9s b/usr/src/man/man9s/scsi_hba_tran.9s new file mode 100644 index 0000000000..d357de164d --- /dev/null +++ b/usr/src/man/man9s/scsi_hba_tran.9s @@ -0,0 +1,392 @@ +'\" te +.\" Copyright (c) 2006 Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_hba_tran 9S "30 May 2006" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +scsi_hba_tran \- SCSI Host Bus Adapter (HBA) driver transport vector structure +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +A \fBscsi_hba_tran_t\fR structure defines vectors that an \fBHBA\fR driver +exports to \fBSCSA\fR interfaces so that \fBHBA\fR specific functions can be +executed. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +dev_info_t *tran_hba_dip; /* HBAs dev_info + pointer */ +void *tran_hba_private; /* HBA softstate */ +void *tran_tgt_private; /* HBA target private + pointer */ +struct scsi_device *tran_sd; /* scsi_device */ +int (*tran_tgt_init)( ); /* Transport target */ + Initialization */ +int (*tran_tgt_probe)( ); /* Transport target + probe */ +void (*tran_tgt_free)( ); /* Transport target + free */ +int (*tran_start)( ); /* Transport start */ +int (*tran_reset)( ); /* Transport reset */ +int (*tran_abort)( ); /* Transport abort */ +int (*tran_getcap)( ); /* Capability + retrieval */ +int (*tran_setcap)( ); /* Capability + establishment */ +struct scsi_pkt *(*tran_init_pkt)( ); /* Packet and DMA + allocation */ +void (*tran_destroy_pkt)( ); /* Packet and DMA */ + deallocation */ +void (*tran_dmafree)( ); /* DMA deallocation */ +void (*tran_sync_pkt)( ); /* Sync DMA */ +void (*tran_reset_notify)( );/* Bus reset + notification */ +int (*tran_bus_reset)( ); /* Reset bus only */ +int (*tran_quiesce)( ); /* Quiesce a bus */ +int (*tran_unquiesce)( ); /* Unquiesce a bus */ +int (*tran_setup_pkt)( ); /* Initialization + for pkt */ +int (*tran_teardown_pkt)( );/* Deallocation */ +int (*tran_pkt_constructor) ( ); + /* Constructor */ +int (*tran_pkt_destructor) ( ); + /* Destructor */ +int tran_hba_len; /* # bytes for + pkt_ha_private */ +int tran_interconnect_type; /* transport + interconnect */ +.fi +.in -2 + +.sp +.ne 2 +.mk +.na +\fB\fBtran_hba_dip\fR\fR +.ad +.RS 26n +.rt +\fBdev_info\fR pointer to the \fBHBA\fR that supplies the \fBscsi_hba_tran\fR +structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_hba_private\fR\fR +.ad +.RS 26n +.rt +Private pointer that the \fBHBA\fR driver can use to refer to the device's soft +state structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_tgt_private\fR\fR +.ad +.RS 26n +.rt +Private pointer that the \fBHBA\fR can use to refer to per-target specific +data. This field can only be used when the \fBSCSI_HBA_TRAN_CLONE\fR flag is +specified in \fBscsi_hba_attach\fR(9F). In this case, the \fBHBA\fR driver must +initialize this field in its \fBtran_tgt_init\fR(9E) entry point. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_sd\fR\fR +.ad +.RS 26n +.rt +Pointer to \fBscsi_device\fR(9S) structure if cloning; otherwise \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_tgt_init\fR\fR +.ad +.RS 26n +.rt +Function entry that allows per-target \fBHBA\fR initialization, if necessary. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_tgt_probe\fR\fR +.ad +.RS 26n +.rt +Function entry that allows per-target \fBscsi_probe\fR(9F) customization, if +necessary. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_tgt_free\fR\fR +.ad +.RS 26n +.rt +Function entry that allows per-target \fBHBA\fR deallocation, if necessary. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_start\fR\fR +.ad +.RS 26n +.rt +Function entry that starts a \fBSCSI\fR command execution on the \fBHBA\fR +hardware. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_reset\fR\fR +.ad +.RS 26n +.rt +Function entry that resets a \fBSCSI\fR bus or target device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_abort\fR\fR +.ad +.RS 26n +.rt +Function entry that aborts one \fBSCSI\fR command, or all pending \fBSCSI\fR +commands. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_getcap\fR\fR +.ad +.RS 26n +.rt +Function entry that retrieves a \fBSCSI\fR capability. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_setcap\fR\fR +.ad +.RS 26n +.rt +Function entry that sets a \fBSCSI\fR capability. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_init_pkt\fR\fR +.ad +.RS 26n +.rt +Function entry that allocates a \fBscsi_pkt\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_destroy_pkt\fR\fR +.ad +.RS 26n +.rt +Function entry that frees a \fBscsi_pkt\fR structure allocated by +\fBtran_init_pkt\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_dmafree\fR\fR +.ad +.RS 26n +.rt +Function entry that frees \fBDMA\fR resources that were previously allocated by +\fBtran_init_pkt\fR. Not called for \fBHBA\fR drivers that provide a +\fBtran_setup_pkt\fR entry point. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_sync_pkt\fR\fR +.ad +.RS 26n +.rt +Synchronizes data in \fIpkt\fR after a data transfer has been completed. Not +called for \fBHBA\fR drivers that provide a \fBtran_setup_pkt\fR entry point. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_reset_notify\fR\fR +.ad +.RS 26n +.rt +Function entry that allows a target to register a bus reset notification +request with the \fBHBA\fR driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_bus_reset\fR\fR +.ad +.RS 26n +.rt +Function entry that resets the \fBSCSI\fR bus without resetting targets. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_quiesce\fR\fR +.ad +.RS 26n +.rt +Function entry that waits for all outstanding commands to complete and blocks +(or queues) any \fBI/O\fR requests issued. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_unquiesce\fR\fR +.ad +.RS 26n +.rt +Function entry that allows \fBI/O\fR activities to resume on the \fBSCSI\fR +bus. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_setup_pkt\fR\fR +.ad +.RS 26n +.rt +Optional entry point that initializes a \fBscsi_pkt\fR structure. See +\fBtran_setup_pkt\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_teardown_pkt\fR\fR +.ad +.RS 26n +.rt +Entry point that releases resources allocated by \fBtran_setup_pkt\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_pkt_constructor\fR\fR +.ad +.RS 26n +.rt +Additional optional entry point that performs the actions of a constructor. See +\fBtran_setup_pkt\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_pkt_destructor\fR\fR +.ad +.RS 26n +.rt +Additional optional entry point that performs the actions of a destructor. See +\fBtran_setup_pkt\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_hba_len\fR\fR +.ad +.RS 26n +.rt +Size of \fBpkt_ha_private\fR. See \fBtran_setup_pkt\fR(9E). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtran_interconnect_type\fR\fR +.ad +.RS 26n +.rt +Integer value that denotes the interconnect type of the transport as defined in +the \fBservices.h\fR header file. +.RE + +.SH SEE ALSO +.sp +.LP +\fBtran_abort\fR(9E), \fBtran_bus_reset\fR(9E), \fBtran_destroy_pkt\fR(9E), +\fBtran_dmafree\fR(9E), \fBtran_getcap\fR(9E), \fBtran_init_pkt\fR(9E), +\fBtran_quiesce\fR(9E), \fBtran_reset\fR(9E), \fBtran_reset_notify\fR(9E), +\fBtran_setcap\fR(9E), \fBtran_setup_pkt\fR(9E), \fBtran_start\fR(9E), +\fBtran_sync_pkt\fR(9E), \fBtran_tgt_free\fR(9E), \fBtran_tgt_init\fR(9E), +\fBtran_tgt_probe\fR(9E), \fBtran_unquiesce\fR(9E), \fBddi_dma_sync\fR(9F), +\fBscsi_hba_attach\fR(9F), \fBscsi_hba_pkt_alloc\fR(9F), +\fBscsi_hba_pkt_free\fR(9F), \fBscsi_probe\fR(9F), \fBscsi_device\fR(9S), +\fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/scsi_inquiry.9s b/usr/src/man/man9s/scsi_inquiry.9s new file mode 100644 index 0000000000..9d2a3aa676 --- /dev/null +++ b/usr/src/man/man9s/scsi_inquiry.9s @@ -0,0 +1,494 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. , All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_inquiry 9S "5 Nov 2008" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +scsi_inquiry \- SCSI inquiry structure +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBscsi_inquiry\fR 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 +\fBscsi_device\fR(9S) structure and typically filled in by +\fBscsi_probe\fR(9F). +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +Lines that start with an 'X' will be deleted before submission; +they are being classified as unstable at this time. + +uchar_t inq_dtype; /* Periph. qualifier, dev. type */ +uchar_t inq_rmb :1; /* Removable media */ +uchar_t inq_qual :7; /* Dev. type qualifier */ +uchar_t inq_iso :2; /* ISO version */ +uchar_t inq_ecma :3; /* EMCA version */ +uchar_t inq_ansi :3; /* ANSII version */ +uchar_t inq_aenc :1; /* Async event notif. cap. */ +uchar_t inq_trmiop :1; /* Supports TERMINATE I/O PROC msg */ +uchar_t inq_normaca :1; /* setting NACA bit supported */ +uchar_t inq_hisup :1; /* hierarchical addressing model */ +uchar_t inq_rdf :4; /* Response data format */ +uchar_t inq_len /* Additional length */ +uchar_t inq_sccs :1; /* embedded storage array */ +Xuchar_t inq_acc :1; /* access controls coordinator */ +uchar_t inq_tpgse :1; /* explicit asymmetric lun access */ +uchar_t inq_tpgsi :1; /* implicit asymmetric lun access */ +Xuchar_t inq_3pc :1; /* third-party copy */ +Xuchar_t inq_protect :1; /* supports protection information */ +uchar_t inq_bque :1; /* basic queueing */ +uchar_t inq_encserv :1; /* embedded enclosure services */ +uchar_t inq_dualp :1; /* dual port device */ +uchar_t inq_mchngr :1; /* embedded/attached to medium chngr */ +uchar_t inq_addr16 :1; /* SPI: supports 16 bit wide SCSI addr */ +uchar_t inq_wbus16 :1; /* SPI: Supports 16 bit wide data xfers */ +uchar_t inq_sync :1; /* SPI: Supports synchronous data xfers */ +uchar_t inq_linked :1; /* Supports linked commands */ +uchar_t inq_cmd_que :1; /* Supports command queueing */ +uchar_t inq_sftre :1; /* Supports Soft Reset option */ +char inq_vid[8]; /* Vendor ID */ +char inq_pid[16]; /* Product ID */ +char inq_revision[4]; /* Revision level */ +uchar_t inq_clk :2; /* SPI3 clocking */ +uchar_t inq_qas :1; /* SPI3: quick arb sel */ +uchar_t inq_ius :1; /* SPI3: information units */ +.fi +.in -2 + +.sp +.LP +\fBinq_dtype\fR identifies the type of device. Bits 0 - 4 represent the +Peripheral Device Type and bits 5 - 7 represent the Peripheral Qualifier. The +following values are appropriate for Peripheral Device Type field: +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_DIRECT\fR\fR +.ad +.RS 20n +.rt +Direct-access device (for example, magnetic disk). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_SEQUENTIAL\fR\fR +.ad +.RS 20n +.rt +Sequential-access device (for example, magnetic tape). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_PRINTER\fR\fR +.ad +.RS 20n +.rt +Printer device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_PROCESSOR\fR\fR +.ad +.RS 20n +.rt +Processor device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_WORM\fR\fR +.ad +.RS 20n +.rt +Write-once device (for example, some optical disks). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_RODIRECT\fR\fR +.ad +.RS 20n +.rt +CD-ROM device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_SCANNER\fR\fR +.ad +.RS 20n +.rt +Scanner device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_OPTICAL\fR\fR +.ad +.RS 20n +.rt +Optical memory device (for example, some optical disks). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_CHANGER\fR\fR +.ad +.RS 20n +.rt +Medium Changer device (for example, jukeboxes). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_COMM\fR\fR +.ad +.RS 20n +.rt +Communications device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_ARRAY_CTRL\fR\fR +.ad +.RS 20n +.rt +Array controller device (for example, \fBRAID\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_ESI\fR\fR +.ad +.RS 20n +.rt +Enclosure services device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_RBC\fR\fR +.ad +.RS 20n +.rt +Simplified direct-access device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_OCRW\fR\fR +.ad +.RS 20n +.rt +Optical card reader/writer device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_BRIDGE\fR\fR +.ad +.RS 20n +.rt +Bridge. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_OSD\fR\fR +.ad +.RS 20n +.rt +Object-based storage device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_UNKNOWN\fR\fR +.ad +.RS 20n +.rt +Unknown or no device type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDTYPE_MASK\fR\fR +.ad +.RS 20n +.rt +Mask to isolate Peripheral Device Type field. +.RE + +.sp +.LP +The following values are appropriate for the Peripheral Qualifier field: +.sp +.ne 2 +.mk +.na +\fB\fBDPQ_POSSIBLE\fR\fR +.ad +.RS 17n +.rt +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 +\fBINQUIRY\fR data. This peripheral qualifier does not imply that the device is +ready for access by the initiator. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDPQ_SUPPORTED\fR\fR +.ad +.RS 17n +.rt +The target is capable of supporting the specified peripheral device type on +this logical unit. However, the physical device is not currently connected to +this logical unit. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDPQ_NEVER\fR\fR +.ad +.RS 17n +.rt +The target is not capable of supporting a physical device on this logical unit. +For this peripheral qualifier, the peripheral device type shall be set to +\fBDTYPE_UNKNOWN\fR to provide compatibility with previous versions of +\fBSCSI\fR. For all other peripheral device type values, this peripheral +qualifier is reserved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDPQ_VUNIQ\fR\fR +.ad +.RS 17n +.rt +This is a vendor-unique qualifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDPQ_MASK\fR\fR +.ad +.RS 17n +.rt +Mask to isolate Peripheral Qualifier field. +.RE + +.sp +.LP +\fBDTYPE_NOTPRESENT\fR is the peripheral qualifier \fBDPQ_NEVER\fR and the +peripheral device type \fBDTYPE_UNKNOWN\fR combined. +.sp +.LP +\fBinq_rmb\fR, if set, indicates that the medium is removable. +.sp +.LP +\fBinq_qual\fR is a device type qualifier. +.sp +.LP +\fBinq_iso\fR indicates \fBISO \fRversion. +.sp +.LP +\fBinq_ecma\fR indicates \fBECMA \fRversion. +.sp +.LP +\fBinq_ansi\fR indicates \fBANSI \fRversion. +.sp +.LP +\fBinq_aenc\fR, if set, indicates that the device supports asynchronous event +notification capability as defined in \fBSCSI-2 \fRspecification. +.sp +.LP +\fBinq_trmiop\fR, if set, indicates that the device supports the \fBTERMINATE +I/O PROCESS\fRmessage. +.sp +.LP +\fBinq_normaca\fR, if set, indicates that the device supports setting the +\fBNACA\fR bit to 1 in \fBCDB\fR. +.sp +.LP +\fBinq_hisip\fR, if set, indicates the \fBSCSI\fR target device uses the +hierarchical addressing model to assign \fBLUN\fRs to logical units. +.sp +.LP +\fBinq_rdf\fR, if set, indicates the \fBINQUIRY\fR data response data format: +"\fBRDF_LEVEL0\fR" means that this structure complies with the \fBSCSI-1\fR +spec, "\fBRDF_CCS\fR" means that this structure complies with the \fBCCS\fR +pseudo-spec, and "\fBRDF_SCSI2\fR" means that the structure complies with the +\fBSCSI-2\fR/3 spec. +.sp +.LP +\fBinq_len\fR, if set, is the additional length field that specifies the length +in bytes of the parameters. +.sp +.LP +\fBinq_sccs\fR, if set, indicates the target device contains an embedded +storage array controller component. +.sp +.LP +\fBinq_acc\fR, if set, indicates that the logical unit contains an access +controls coordinator (this structure member will be deleted before submission. +It is being classified as unstable at this time). +.sp +.LP +\fBinq_tpgse\fR, if set, indicates that implicit asymmetric logical unit access +is supported. +.sp +.LP +\fBinq_tpgsi\fR, if set, indicates that explicit asymmetric logical unit access +is supported. +.sp +.LP +\fBinq_3pc\fR, if set, indicates that the \fBSCSI\fR target device supports +third-party copy commands (this structure member will be deleted before +submission. It is being classified as unstable at this time). +.sp +.LP +\fBinq_protect\fR, if set, indicates that the logical unit supports protection +information (this structure member will be deleted before submission. It is +being classified as unstable at this time). +.sp +.LP +\fBinq_bque\fR, if set, indicates that the logical unit supports basic task +management. +.sp +.LP +\fBinq_encserv\fR, if set, indicates that the device contains an embedded +enclosure services component (\fBses\fR(7D)). +.sp +.LP +\fBinq_dualp\fR, if set, indicates that the \fBSCSI\fR target device supports +two or more ports. +.sp +.LP +\fBinq_mchngr\fR, if set, indicates that the \fBSCSI\fR target device supports +commands to control an attached media changer. +.sp +.LP +\fBinq_addr16\fR, if set, indicates that the device supports 16-bit wide +\fBSCSI\fR addresses. +.sp +.LP +\fBinq_wbus16\fR, if set, indicates that the device supports 16-bit wide data +transfers. +.sp +.LP +\fBinq_sync\fR, if set, indicates that the device supports synchronous data +transfers. +.sp +.LP +\fBinq_linked\fR, if set, indicates that the device supports linked commands +for this logical unit. +.sp +.LP +\fBinq_cmdque\fR, if set, indicates that the device supports tagged command +queueing. +.sp +.LP +\fBinq_sftre\fR, if reset, indicates that the device responds to the +\fBRESET\fR condition with the hard \fBRESET\fR alternative. If this bit is +set, this indicates that the device responds with the soft \fBRESET\fR +alternative. +.sp +.LP +\fBinq_vid\fR contains eight bytes of \fBASCII \fRdata identifying the vendor +of the product. +.sp +.LP +\fBinq_pid\fR contains sixteen bytes of \fBASCII \fRdata as defined by the +vendor. +.sp +.LP +\fBinq_revision\fR contains four bytes of \fBASCII \fRdata as defined by the +vendor. +.sp +.LP +\fBinq_clk\fR clocking of the \fBSPI3\fR target port. +.sp +.LP +\fBinq_gas\fR the \fBSPI3\fR target port supports quick arbitration and +selection. +.sp +.LP +\fBinq_ius\fR the \fBSPI3\fR target device supports information unit transfers. +.SH SEE ALSO +.sp +.LP +\fBscsi_probe\fR(9F), \fBscsi_device\fR(9S) +.sp +.LP +\fIANSI Small Computer System Interface-2 (SCSI-2)\fR +.sp +.LP +\fIANSI SCSI Primary Commands-3 (SPC-3)\fR +.sp +.LP +http://t10.org/drafts.htm#spc3 +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/scsi_pkt.9s b/usr/src/man/man9s/scsi_pkt.9s new file mode 100644 index 0000000000..fcc6d29102 --- /dev/null +++ b/usr/src/man/man9s/scsi_pkt.9s @@ -0,0 +1,840 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_pkt 9S "11 Jan 2009" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +scsi_pkt \- SCSI packet structure +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +A \fBscsi_pkt\fR structure defines the packet that is allocated by +\fBscsi_init_pkt\fR(9F). The target driver fills in some information and passes +it to \fBscsi_transport\fR(9F) for execution on the target. The host bus +adapter (\fBHBA\fR) fills in other information as the command is processed. +When the command completes or can be taken no further, the completion function +specified in the packet is called with a pointer to the packet as its argument. +From fields within the packet, the target driver can determine the success or +failure of the command. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +opaque_t pkt_ha_private; /* private data for + host adapter */ +struct scsi_address pkt_address; /* destination packet */ +opaque_t pkt_private; /* private data + for target driver */ +void (*pkt_comp)(struct scsi_pkt *); /* callback */ +uint_t pkt_flags; /* flags */ +int pkt_time; /* time allotted to + complete command */ +uchar_t *pkt_scbp; /* pointer to + status block */ +uchar_t *pkt_cdbp; /* pointer to + command block */ +ssize_t pkt_resid; /* number of bytes + not transferred */ +uint_t pkt_state; /* state of command */ +uint_t pkt_statistics; /* statistics */ +uchar_t pkt_reason; /* reason completion + called */ +uint_t pkt_cdblen; /* length of pkt_cdbp */ +uint_t pkt_scdblen; /* length of pkt_scbp */ +uint_t pkt_tgtlen; /* length of pkt_private */ +uint_t pkt_numcookies; /* number of DMA cookies */ +ddi_dma_cookie_t *pkt_cookies; /* array of DMA cookies */ +uint_t pkt_dma_flags; /* DMA flags */ +.fi +.in -2 + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_ha_private\fR\fR +.ad +.RS 18n +.rt +Opaque pointer that the HBA uses to reference a private data structure that +transfers \fBscsi_pkt\fR requests. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_address\fR\fR +.ad +.RS 18n +.rt +Initialized by \fBscsi_init_pkt\fR(9F), \fBpkt_address\fR records the intended +route and the recipient of a request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_private\fR\fR +.ad +.RS 18n +.rt +Reserved for the use of the target driver, \fBpkt_private\fR is not changed by +the HBA driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_comp\fR\fR +.ad +.RS 18n +.rt +Specifies the command completion callback routine. When the host adapter driver +has gone as far as it can in transporting a command to a \fBSCSI\fR target, and +the command has either run to completion or can go no further for some other +reason, the host adapter driver calls the function pointed to by this field and +passes 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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_flags\fR\fR +.ad +.RS 18n +.rt +Provides additional information about how the target driver expects the command +to be executed. See \fBpkt_flag Definitions\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_time\fR\fR +.ad +.RS 18n +.rt +Set by the target driver to represent the maximum time allowed in seconds for +this command to complete. Timeout starts when the command is transmitted on the +\fBSCSI\fR bus. The \fBpkt_time\fR may be \fB0\fR if no timeout is required. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_scbp\fR\fR +.ad +.RS 18n +.rt +Points to either a struct \fBscsi_status\fR(9S) or, if \fBauto-rqsense\fR is +enabled and \fBpkt_state\fR includes \fBSTATE_ARQ_DONE\fR, a struct +\fBscsi_arq_status\fR. If \fBscsi_status\fR is returned, the \fBSCSI\fR status +byte resulting from the requested command is available. If +\fBscsi_arq_status\fR(9S) is returned, the sense information is also available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_cdbp\fR\fR +.ad +.RS 18n +.rt +Points to a kernel-addressable buffer with a length specified by a call to the +proper resource allocation routine, \fBscsi_init_pkt\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_resid\fR\fR +.ad +.RS 18n +.rt +Contains a residual count, either the number of data bytes that have not been +transferred (\fBscsi_transport\fR(9F)) or the number of data bytes for which +DMA resources could not be allocated \fBscsi_init_pkt\fR(9F). In the latter +case, partial DMA resources can be allocated only if \fBscsi_init_pkt\fR(9F) is +called with the \fBPKT_DMA_PARTIAL\fR flag. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_state\fR\fR +.ad +.RS 18n +.rt +Has bit positions that represent the six most important states that a +\fBSCSI\fR command can go through. See \fBpkt_state Definitions\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_statistics\fR\fR +.ad +.RS 18n +.rt +Maintains some transport-related statistics. See \fBpkt_statistics +Definitions\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_reason\fR\fR +.ad +.RS 18n +.rt +Contains a completion code that indicates why the \fBpkt_comp\fR function was +called. See \fBpkt_reason Definitions\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_cdblen\fR\fR +.ad +.RS 18n +.rt +Length of buffer pointed to by \fBpkt_cdbp\fR. See \fBtran_setup_pkt\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_scblen\fR\fR +.ad +.RS 18n +.rt +Length of buffer pointed to by \fBpkt_scbp\fR. See \fBtran_setup_pkt\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_tgtlen\fR\fR +.ad +.RS 18n +.rt +Length of buffer pointed to by \fBpkt_private\fR. See \fBtran_setup_pkt\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_numcookies\fR\fR +.ad +.RS 18n +.rt +Length \fBpkt_cookies\fR array. See \fBtran_setup_pkt\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_cookies\fR\fR +.ad +.RS 18n +.rt +Array of DMA cookies. See \fBtran_setup_pkt\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_dma_flags\fR\fR +.ad +.RS 18n +.rt +DMA flags used, such as \fBDDI_DMA_READ\fR and \fBDDI_DMA_WRITE\fR. See +\fBtran_setup_pkt\fR. +.RE + +.sp +.LP +The host adapter driver will update the \fBpkt_resid\fR, \fBpkt_reason\fR, +\fBpkt_state\fR, and \fBpkt_statistics\fR fields. +.SS "\fBpkt_flags\fR Definitions" +.sp +.LP +The appropriate definitions for the structure member \fBpkt_flags\fR are: +.sp +.ne 2 +.mk +.na +\fB\fBFLAG_NOINTR\fR\fR +.ad +.RS 30n +.rt +Run command with no command completion callback. Command is complete upon +return from \fBscsi_transport\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFLAG_NODISCON\fR\fR +.ad +.RS 30n +.rt +Run command without disconnects. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFLAG_NOPARITY\fR\fR +.ad +.RS 30n +.rt +Run command without parity checking. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFLAG_HTAG\fR\fR +.ad +.RS 30n +.rt +Run command as the head-of-queue-tagged command. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFLAG_OTAG\fR\fR +.ad +.RS 30n +.rt +Run command as an ordered-queue-tagged command. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFLAG_STAG\fR\fR +.ad +.RS 30n +.rt +Run command as a simple-queue-tagged command. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFLAG_SENSING\fR\fR +.ad +.RS 30n +.rt +Indicates a request sense command. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFLAG_HEAD\fR\fR +.ad +.RS 30n +.rt +Place command at the head of the queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFLAG_RENEGOTIATE_WIDE_SYNC\fR\fR +.ad +.RS 30n +.rt +Before transporting this command, the host adapter should initiate the +renegotiation of wide mode and synchronous transfer speed. Normally, the HBA +driver manages negotiations but under certain conditions forcing a +renegotiation is appropriate. Renegotiation is recommended before Request Sense +and Inquiry commands. Refer to the SCSI 2 standard, sections 6.6.21 and 6.6.23. +.sp +This flag should not be set for every packet as this will severely impact +performance. +.RE + +.SS "\fBpkt_reason\fR Definitions" +.sp +.LP +The appropriate definitions for the structure member \fBpkt_reason\fR are: +.sp +.ne 2 +.mk +.na +\fB\fBCMD_CMPLT\fR\fR +.ad +.RS 20n +.rt +No transport errors; normal completion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_INCOMPLETE\fR\fR +.ad +.RS 20n +.rt +Transport stopped with abnormal state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_DMA_DERR\fR\fR +.ad +.RS 20n +.rt +\fBDMA\fRd irection error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_TRAN_ERR\fR\fR +.ad +.RS 20n +.rt +Unspecified transport error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_RESET\fR\fR +.ad +.RS 20n +.rt +\fBSCSI\fR bus reset destroyed command. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_ABORTED\fR\fR +.ad +.RS 20n +.rt +Command transport aborted on request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_TIMEOUT\fR\fR +.ad +.RS 20n +.rt +Command timed out. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_DATA_OVR\fR\fR +.ad +.RS 20n +.rt +Data overrun. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_CMD_OVR\fR\fR +.ad +.RS 20n +.rt +Command overrun. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_STS_OVR\fR\fR +.ad +.RS 20n +.rt +Status overrun. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_BADMSG\fR\fR +.ad +.RS 20n +.rt +Message not command complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_NOMSGOUT\fR\fR +.ad +.RS 20n +.rt +Target refused to go to message out phase. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_XID_FAIL\fR\fR +.ad +.RS 20n +.rt +Extended identify message rejected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_IDE_FAIL\fR\fR +.ad +.RS 20n +.rt +"Initiator Detected Error" message rejected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_ABORT_FAIL\fR\fR +.ad +.RS 20n +.rt +Abort message rejected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_REJECT_FAIL\fR\fR +.ad +.RS 20n +.rt +Reject message rejected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_NOP_FAIL\fR\fR +.ad +.RS 20n +.rt +"No Operation" message rejected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_PER_FAIL\fR\fR +.ad +.RS 20n +.rt +"Message Parity Error" message rejected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_BDR_FAIL\fR\fR +.ad +.RS 20n +.rt +"Bus Device Reset" message rejected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_ID_FAIL\fR\fR +.ad +.RS 20n +.rt +Identify message rejected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_UNX_BUS_FREE\fR\fR +.ad +.RS 20n +.rt +Unexpected bus free phase. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_TAG_REJECT\fR\fR +.ad +.RS 20n +.rt +Target rejected the tag message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCMD_DEV_GONE\fR\fR +.ad +.RS 20n +.rt +The device has been removed. +.RE + +.SS "pkt_state Definitions" +.sp +.LP +The appropriate definitions for the structure member \fBpkt_state\fR are: +.sp +.ne 2 +.mk +.na +\fB\fBSTATE_GOT_BUS\fR\fR +.ad +.RS 22n +.rt +Bus arbitration succeeded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATE_GOT_TARGET\fR\fR +.ad +.RS 22n +.rt +Target successfully selected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATE_SENT_CMD\fR\fR +.ad +.RS 22n +.rt +Command successfully sent. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATE_XFERRED_DATA\fR\fR +.ad +.RS 22n +.rt +Data transfer took place. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATE_GOT_STATUS\fR\fR +.ad +.RS 22n +.rt +Status received. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATE_ARQ_DONE\fR\fR +.ad +.RS 22n +.rt +The command resulted in a check condition and the host adapter driver executed +an automatic request sense command. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATE_XARQ_DONE\fR\fR +.ad +.RS 22n +.rt +The command requested in extra sense data using a \fBPKT_XARQ\fR flag got a +check condition. The host adapter driver was able to successfully request and +return this. The \fBscsi_pkt.pkt_scbp->sts_rqpkt_resid\fR returns the sense +data residual based on the \fIstatuslen\fR parameter of the +\fBscsi_init_pkt\fR(9F) call. The sense data begins at +\fBscsi_pkt.pkt_scbp->sts_sensedata\fR. +.RE + +.SS "pkt_statistics Definitions" +.sp +.LP +The definitions that are appropriate for the structure member +\fBpkt_statistics\fR are: +.sp +.ne 2 +.mk +.na +\fB\fBSTAT_DISCON\fR\fR +.ad +.RS 18n +.rt +Device disconnect. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTAT_SYNC\fR\fR +.ad +.RS 18n +.rt +Command did a synchronous data transfer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTAT_PERR\fR\fR +.ad +.RS 18n +.rt +\fBSCSI\fR parity error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTAT_BUS_RESET\fR\fR +.ad +.RS 18n +.rt +Bus reset. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTAT_DEV_RESET\fR\fR +.ad +.RS 18n +.rt +Device reset. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTAT_ABORTED\fR\fR +.ad +.RS 18n +.rt +Command was aborted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTAT_TIMEOUT\fR\fR +.ad +.RS 18n +.rt +Command timed out. +.RE + +.SH SEE ALSO +.sp +.LP +\fBtran_init_pkt\fR(9E), \fBtran_setup_pkt\fR(9E), \fBscsi_arq_status\fR(9S), +\fBscsi_init_pkt\fR(9F), \fBscsi_transport\fR(9F), \fBscsi_status\fR(9S), +\fBscsi_hba_pkt_comp\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +HBA drivers should signal \fBscsi_pkt\fR completion by calling +\fBscsi_hba_pkt_comp\fR(9F). This is mandatory for HBA drivers that implement +\fBtran_setup_pkt\fR(9E). Failure to comply results in undefined behavior. diff --git a/usr/src/man/man9s/scsi_status.9s b/usr/src/man/man9s/scsi_status.9s new file mode 100644 index 0000000000..8b91c70bd5 --- /dev/null +++ b/usr/src/man/man9s/scsi_status.9s @@ -0,0 +1,190 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. +.\" , All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_status 9S "30 Aug 1995" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +scsi_status \- SCSI status structure +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBSCSI-2\fRstandard defines a status byte that is normally sent by the +target to the initiator during the status phase at the completion of each +command. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +uchar sts_scsi2 :1; /* SCSI-2 modifier bit */ +uchar sts_is :1; /* intermediate status sent */ +uchar sts_busy :1; /* device busy or reserved */ +uchar sts_cm :1; /* condition met */ +ucha sts_chk :1; /* check condition */ +.fi +.in -2 + +.sp +.LP +\fBsts_chk\fR indicates that a contingent allegiance condition has occurred. +.sp +.LP +\fBsts_cm\fR is returned whenever the requested operation is satisfied +.sp +.LP +\fBsts_busy\fR indicates that the target is busy. This status is returned +whenever a target is unable to accept a command from an otherwise acceptable +initiator (that is, no reservation conflicts). The recommended initiator +recovery action is to issue the command again later. +.sp +.LP +\fBsts_is\fR is returned for every successfully completed command in a series +of linked commands (except the last command), unless the command is terminated +with a check condition status, reservation conflict, or command terminated +status. Note that host bus adapter drivers may not support linked commands (see +\fBscsi_ifsetcap\fR(9F)). If \fBsts_is\fR and \fBsts_busy\fR are both set, then +a reservation conflict has occurred. +.sp +.LP +\fBsts_scsi2\fR is the \fBSCSI-2 \fRmodifier bit. If \fBsts_scsi2\fR and +\fBsts_chk\fR are both set, this indicates a command terminated status. If +\fBsts_scsi2\fR and \fBsts_busy\fR are both set, this indicates that the +command queue in the target is full. +.sp +.LP +For accessing the status as a byte, the following values are appropriate: +.sp +.ne 2 +.mk +.na +\fB\fBSTATUS_GOOD\fR \fR +.ad +.sp .6 +.RS 4n +This status indicates that the target has successfully completed the command. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATUS_CHECK\fR \fR +.ad +.sp .6 +.RS 4n +This status indicates that a contingent allegiance condition has occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATUS_MET\fR \fR +.ad +.sp .6 +.RS 4n +This status is returned when the requested operations are satisfied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATUS_BUSY\fR \fR +.ad +.sp .6 +.RS 4n +This status indicates that the target is busy. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATUS_INTERMEDIATE\fR \fR +.ad +.sp .6 +.RS 4n +This status is returned for every successfully completed command in a series of +linked commands. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATUS_SCSI2\fR \fR +.ad +.sp .6 +.RS 4n +This is the \fBSCSI-2 \fRmodifier bit. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATUS_INTERMEDIATE_MET\fR \fR +.ad +.sp .6 +.RS 4n +This status is a combination of \fBSTATUS_MET\fR and \fBSTATUS_INTERMEDIATE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATUS_RESERVATION_CONFLICT\fR \fR +.ad +.sp .6 +.RS 4n +This status is a combination of \fBSTATUS_INTERMEDIATE\fR and +\fBSTATUS_BUSY\fR, and it is returned whenever an initiator attempts to access +a logical unit or an extent within a logical unit is reserved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATUS_TERMINATED\fR \fR +.ad +.sp .6 +.RS 4n +This status is a combination of \fBSTATUS_SCSI2\fR and \fBSTATUS_CHECK,\fR and +it is returned whenever the target terminates the current \fBI/O\fR process +after receiving a terminate \fBI/O\fR process message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSTATUS_QFULL\fR \fR +.ad +.sp .6 +.RS 4n +This status is a combination of \fBSTATUS_SCSI2\fR and \fBSTATUS_BUSY\fR, and +it is returned when the command queue in the target is full. +.RE + +.SH SEE ALSO +.sp +.LP +\fBscsi_ifgetcap\fR(9F), \fBscsi_init_pkt\fR(9F), +\fBscsi_extended_sense\fR(9S), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9s/streamtab.9s b/usr/src/man/man9s/streamtab.9s new file mode 100644 index 0000000000..d5436a41a4 --- /dev/null +++ b/usr/src/man/man9s/streamtab.9s @@ -0,0 +1,52 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH streamtab 9S "11 Apr 1991" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +streamtab \- STREAMS entity declaration structure +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH DESCRIPTION +.sp +.LP +Each STREAMS driver or module must have a \fBstreamtab\fR structure. +.sp +.LP +\fBstreamtab\fR is made up of \fBqinit\fR structures for both the read and +write queue portions of each module or driver. Multiplexing drivers require +both upper and lower \fBqinit\fR structures. The \fBqinit\fR structure contains +the entry points through which the module or driver routines are called. +.sp +.LP +Normally, the read \fBQUEUE\fR contains the \fBopen\fR and \fBclose\fR +routines. Both the read and write queue can contain \fBput\fR and service +procedures. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +struct qinit *st_rdinit; /* read QUEUE */ +struct qinit *st_wrinit; /* write QUEUE */ +struct qinit *st_muxrinit; /* lower read QUEUE*/ +struct qinit *st_muxwinit; /* lower write QUEUE*/ +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBqinit\fR(9S) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9s/stroptions.9s b/usr/src/man/man9s/stroptions.9s new file mode 100644 index 0000000000..3c00ba8c13 --- /dev/null +++ b/usr/src/man/man9s/stroptions.9s @@ -0,0 +1,323 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH stroptions 9S "14 Nov 1996" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +stroptions \- options structure for M_SETOPTS message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/stropts.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI) +.SH DESCRIPTION +.sp +.LP +The \fBM_SETOPTS\fR message contains a \fBstroptions\fR structure and is used +to control options in the stream head. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +uint_t so_flags; /* options to set */ +short so_readopt; /* read option */ +ushort_t so_wroff; /* write offset */ +ssize_t so_minpsz; /* minimum read packet size */ +ssize_t so_maxpsz; /* maximum read packet size */ +size_t so_hiwat; /* read queue high water mark */ +size_t so_lowat; /* read queue low water mark */ +unsigned char so_band; /* band for water marks */ +ushort_t so_erropt; /* error option */ +.fi +.in -2 + +.sp +.LP +The following are the flags that can be set in the \fBso_flags\fR bit mask in +the \fBstroptions\fR structure. Note that multiple flags can be set. +.sp +.ne 2 +.mk +.na +\fB\fBSO_READOPT\fR\fR +.ad +.RS 21n +.rt +Set read option. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_WROFF\fR\fR +.ad +.RS 21n +.rt +Set write offset. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_MINPSZ\fR\fR +.ad +.RS 21n +.rt +Set minimum packet size +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_MAXPSZ\fR\fR +.ad +.RS 21n +.rt +Set maximum packet size. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_HIWAT\fR\fR +.ad +.RS 21n +.rt +Set high water mark. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_LOWAT\fR\fR +.ad +.RS 21n +.rt +Set low water mark. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_MREADON\fR\fR +.ad +.RS 21n +.rt +Set read notification ON. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_MREADOFF\fR\fR +.ad +.RS 21n +.rt +Set read notification OFF. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_NDELON\fR\fR +.ad +.RS 21n +.rt +Old TTY semantics for NDELAY reads and writes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_NDELOFFSTREAMS\fR\fR +.ad +.RS 21n +.rt +Semantics for NDELAY reads and writes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_ISTTY\fR\fR +.ad +.RS 21n +.rt +The stream is acting as a terminal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_ISNTTY\fR\fR +.ad +.RS 21n +.rt +The stream is not acting as a terminal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_TOSTOP\fR\fR +.ad +.RS 21n +.rt +Stop on background writes to this stream. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_TONSTOP\fR\fR +.ad +.RS 21n +.rt +Do not stop on background writes to this stream. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_BAND\fR\fR +.ad +.RS 21n +.rt +Water marks affect band. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSO_ERROPT\fR\fR +.ad +.RS 21n +.rt +Set error option. +.RE + +.sp +.LP +When \fBSO_READOPT\fR is set, the \fBso_readopt\fR field of the +\fBstroptions\fR structure can take one of the following values. See +\fBread\fR(2). +.sp +.ne 2 +.mk +.na +\fB\fBRNORM\fR\fR +.ad +.RS 9n +.rt +Read message normal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRMSGD\fR\fR +.ad +.RS 9n +.rt +Read message discard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRMSGN\fR\fR +.ad +.RS 9n +.rt +Read message, no discard. +.RE + +.sp +.LP +When \fBSO_BAND\fR is set, \fBso_band\fR determines to which band +\fBso_hiwat\fR and \fBso_lowat\fR apply. +.sp +.LP +When \fBSO_ERROPT\fR is set, the \fBso_erropt\fR field of the \fBstroptions\fR +structure can take a value that is either none or one of: +.sp +.ne 2 +.mk +.na +\fB\fBRERRNORM\fR\fR +.ad +.RS 18n +.rt +Persistent read errors; default. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRERRNONPERSIST\fR\fR +.ad +.RS 18n +.rt +Non-persistent read errors. +.RE + +.sp +.LP +\fBOR'ed \fRwith either none or one of: +.sp +.ne 2 +.mk +.na +\fB\fBWERRNORM\fR\fR +.ad +.RS 18n +.rt +Persistent write errors; default. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWERRNONPERSIST\fR\fR +.ad +.RS 18n +.rt +Non-persistent write errors. +.RE + +.SH SEE ALSO +.sp +.LP +\fBread\fR(2), \fBstreamio\fR(7I) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9s/tuple.9s b/usr/src/man/man9s/tuple.9s new file mode 100644 index 0000000000..c067c5a534 --- /dev/null +++ b/usr/src/man/man9s/tuple.9s @@ -0,0 +1,256 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. +.\" , All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH tuple 9S "20 Dec 1996" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +tuple \- card information structure (CIS) access structure +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI Specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBtuple_t\fR structure is the basic data structure provided by card +services to manage \fBPC\fR card information. A \fBPC\fR card provides +identification and configuration information through its card information +structure (\fBCIS\fR). A \fBPC \fRcard driver accesses a \fBPC \fRcard's \fBCIS +\fRthrough various card services functions. +.sp +.LP +The \fBCIS\fR information allows \fBPC\fR cards to be self-identifying: the +\fBCIS\fR provides information to the system so that it can identify the proper +\fBPC\fR card driver for the \fBPC\fR card, and provides configuration +information so that the driver can allocate appropriate resources to configure +the \fBPC\fR card for proper operation in the system. +.sp +.LP +The \fBCIS \fRinformation is contained on the \fBPC\fR card in a linked list of +tuple data structures called a \fBCIS \fRchain. Each tuple has a one-byte type +and a one-byte link, an offset to the next tuple in the list. A \fBPC\fR card +can have one or more \fBCIS \fRchains. +.sp +.LP +A multi-function \fBPC\fR card that complies with the \fBPC\fR Card 95 +MultiFunction Metaformat specification will have one or more global \fBCIS\fR +chains that collectively are referred to as the global \fBCIS\fR. These +\fBPC\fR Cards will also have one or more per-function \fBCIS\fR chains. Each +per-function collection of \fBCIS\fR chains is referred to as a +function-specific \fBCIS\fR. +.sp +.LP +To examine a \fBPC\fR card's \fBCIS\fR, first a \fBPC\fR card driver must +locate the desired tuple by calling \fBcsx_GetFirstTuple\fR(9F). Once the first +tuple is located, subsequent tuples may be located by calling +\fBcsx_GetNextTuple\fR(9F). See \fBcsx_GetFirstTuple\fR(9F). The linked list of +tuples may be inspected one by one, or the driver may narrow the search by +requesting only tuples of a particular type. +.sp +.LP +Once a tuple has been located, the \fBPC\fR card driver may inspect the tuple +data. The most convenient way to do this for standard tuples is by calling one +of the number of tuple-parsing utility functions; for custom tuples, the driver +may get access to the raw tuple data by calling \fBcsx_GetTupleData\fR(9F). +.sp +.LP +Solaris \fBPC\fR card drivers do not need to be concerned with which \fBCIS +\fRchain a tuple appears in. On a multi-function \fBPC\fR card, the client will +get the tuples from the global \fBCIS \fRfollowed by the tuples in the +function-specific \fBCIS\fR. The caller will not get any tuples from a +function-specific \fBCIS \fRthat does not belong to the caller's function. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBtuple_t\fR are: +.sp +.in +2 +.nf +uint32_t Socket; /* socket number */ +uint32_t Attributes; /* tuple attributes */ +cisdata_t DesiredTuple; /* tuple to search for */ +cisdata_t TupleOffset; /* tuple data offset */ +cisdata_t TupleDataMax; /* max tuple data size */ +cisdata_t TupleDataLen; /* actual tuple data length */ +cisdata_t TupleData[CIS_MAX_TUPLE_DATA_LEN]; + /* body tuple data */ +cisdata_t TupleCode; /* tuple type code */ +cisdata_t TupleLink; /* tuple link */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR \fR +.ad +.RS 17n +.rt +Not used in Solaris, but for portability with other card services +implementations, it should be set to the logical socket number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR \fR +.ad +.RS 17n +.rt +This field is bit-mapped. The following bits are defined: +.sp +.ne 2 +.mk +.na +\fB\fBTUPLE_RETURN_LINK\fR \fR +.ad +.sp .6 +.RS 4n +Return link tuples if set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTUPLE_RETURN_IGNORED_TUPLES\fR \fR +.ad +.sp .6 +.RS 4n +Return ignored tuples if set. Ignored tuples are those tuples in a +multi-function \fBPC\fR card's global \fBCIS\fR chain that are duplicates of +the same tuples in a function-specific \fBCIS \fRchain. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTUPLE_RETURN_NAME\fR \fR +.ad +.sp .6 +.RS 4n +Return tuple name string using the \fBcsx_ParseTuple\fR(9F) function if set. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDesiredTuple\fR \fR +.ad +.RS 17n +.rt +This field is the requested tuple type code to be returned when calling +\fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +\fBRETURN_FIRST_TUPLE\fR is used to return the first tuple regardless of tuple +type. \fBRETURN_NEXT_TUPLE\fR is used to return the next tuple regardless of +tuple type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTupleOffset\fR \fR +.ad +.RS 17n +.rt +This field allows partial tuple information to be retrieved, starting at the +specified offset within the tuple. This field must only be set before calling +\fBcsx_GetTupleData\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTupleDataMax\fR \fR +.ad +.RS 17n +.rt +This field is the size of the tuple data buffer that card services uses to +return raw tuple data from \fBcsx_GetTupleData\fR(9F). It can be larger than +the number of bytes in the tuple data body. Card services ignores any value +placed here by the client. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTupleDataLen\fR \fR +.ad +.RS 17n +.rt +This field is the actual size of the tuple data body. It represents the number +of tuple data body bytes returned by \fBcsx_GetTupleData\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTupleData\fR \fR +.ad +.RS 17n +.rt +This field is an array of bytes containing the raw tuple data body contents +returned by \fBcsx_GetTupleData\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTupleCode\fR \fR +.ad +.RS 17n +.rt +This field is the tuple type code and is returned by +\fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F) when a tuple matching +the \fBDesiredTuple\fR field is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTupleLink\fR \fR +.ad +.RS 17n +.rt +This field is the tuple link, the offset to the next tuple, and is returned by +\fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F) when a tuple matching +the \fBDesiredTuple\fR field is returned. +.RE + +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_ParseTuple\fR(9F), \fBcsx_Parse_CISTPL_BATTERY\fR(9F), +\fBcsx_Parse_CISTPL_BYTEORDER\fR(9F), \fBcsx_Parse_CISTPL_CFTABLE_ENTRY\fR(9F), +\fBcsx_Parse_CISTPL_CONFIG\fR(9F), \fBcsx_Parse_CISTPL_DATE\fR(9F), +\fBcsx_Parse_CISTPL_DEVICE\fR(9F), \fBcsx_Parse_CISTPL_FUNCE\fR(9F), +\fBcsx_Parse_CISTPL_FUNCID\fR(9F), \fBcsx_Parse_CISTPL_JEDEC_C\fR(9F), +\fBcsx_Parse_CISTPL_MANFID\fR(9F), \fBcsx_Parse_CISTPL_SPCL\fR(9F), +\fBcsx_Parse_CISTPL_VERS_1\fR(9F), \fBcsx_Parse_CISTPL_VERS_2\fR(9F) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9s/uio.9s b/usr/src/man/man9s/uio.9s new file mode 100644 index 0000000000..fd8fdb3f32 --- /dev/null +++ b/usr/src/man/man9s/uio.9s @@ -0,0 +1,98 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc., All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH uio 9S "26Mar 2009" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +uio \- scatter/gather I/O request structure +.SH SYNOPSIS +.LP +.nf +#include <sys/uio.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI) +.SH DESCRIPTION +.sp +.LP +A \fBuio\fR structure describes an \fBI/O \fRrequest that can be broken up +into different data storage areas (scatter/gather I/O). A request is a list of +\fBiovec\fR structures (base-length pairs) indicating where in user space or +kernel space the \fBI/O \fRdata is to be read or written. +.sp +.LP +The contents of \fBuio\fR structures passed to the driver through the entry +points should not be written by the driver. The \fBuiomove\fR(9F) function +takes care of all overhead related to maintaining the state of the \fBuio\fR +structure. +.sp +.LP +\fBuio\fR structures allocated by the driver should be initialized to zero +before use, by \fBbzero\fR(9F), \fBkmem_zalloc\fR(9F), or an equivalent. +.SH STRUCTURE MEMBERS +.sp +.in +2 +.nf +iovec_t *uio_iov; /* pointer to start of iovec */ + /* list for uio struc. */ +int uio_iovcnt; /* number of iovecs in list */ +off_t uio_offset; /* 32-bit offset into file where + /* data is xferred. See NOTES. */ +offset_t uio_loffset; /* 64-bit offset into file where */ + /* data is xferred. See NOTES. */ +uio_seg_t uio_segflg; /* ID's type of I/O transfer: */ + /* UIO_SYSSPACE: kernel <-> kernel */ + /* UIO_USERSPACE: kernel <-> user */ +uint16_t uio_fmode; /* file mode flags (not driver setable) */ +daddr_t uio_limit; /* 32-bit ulimit for file (max. block */ + /* offset). not driver setable. */ + /* See NOTES. */ +diskaddr_t uio_llimit; /* 64-bit ulimit for file (max. block */ + /* offset). not driver setable. */ + /* See NOTES */ +ssize_t uio_resid; /* residual count */ +.fi +.in -2 + +.sp +.LP +The \fBuio_iov\fR member is a pointer to the beginning of the \fBiovec\fR(9S) +list for the \fBuio\fR. When the \fBuio\fR structure is passed to the driver +through an entry point, the driver should not set \fBuio_iov\fR. When the +\fBuio\fR structure is created by the driver, \fBuio_iov\fR should be +initialized by the driver and not written to afterward. +.SH SEE ALSO +.sp +.LP +\fBaread\fR(9E), \fBawrite\fR(9E), \fBread\fR(9E), \fBwrite\fR(9E), +\fBbzero\fR(9F), \fBkmem_zalloc\fR(9F), \fBuiomove\fR(9F), \fBcb_ops\fR(9S), +\fBiovec\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Only one structure, \fBuio_offset\fR or \fBuio_loffset\fR, should be +interpreted by the driver. Which field the driver interprets is dependent upon +the settings in the \fBcb_ops\fR(9S) structure. +.sp +.LP +Only one structure, \fBuio_limit\fR or \fBuio_llimit\fR, should be interpreted +by the driver. Which field the driver interprets is dependent upon the settings +in the \fBcb_ops\fR(9S) structure. +.sp +.LP +When performing \fBI/O \fRon a seekable device, the driver should not modify +either the \fBuio_offset\fR or the \fBuio_loffset\fR field of the \fBuio\fR +structure. \fBI/O \fRto such a device is constrained by the maximum offset +value. When performing \fBI/O \fRon a device on which the concept of position +has no relevance, the driver may preserve the \fBuio_offset\fR or +\fBuio_loffset\fR, perform the \fBI/O \fRoperation, then restore the +\fBuio_offset\fR or \fBuio_loffset\fR to the field's initial value. \fBI/O +\fRperformed to a device in this manner is not constrained. diff --git a/usr/src/man/man9s/usb_bulk_request.9s b/usr/src/man/man9s/usb_bulk_request.9s new file mode 100644 index 0000000000..0828b2885a --- /dev/null +++ b/usr/src/man/man9s/usb_bulk_request.9s @@ -0,0 +1,277 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_bulk_request 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_bulk_request \- USB bulk request structure +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +A bulk request (that is, a request sent through a bulk pipe) is used to +transfer large amounts of data in reliable but non-time-critical fashion. +Please refer to Section \fI5.8\fR of the \fIUSB 2.0\fR specification for +information on bulk transfers. (The \fIUSB 2.0\fR specification is available at +\fIwww.usb.org\fR.) +.sp +.LP +The fields in the usb_bulk_req_t are used to format a bulk request. Please see +below for acceptable combinations of flags and attributes. +.sp +.LP +The usb_bulk_req_t fields are: +.sp +.in +2 +.nf +uint_t bulk_len; /* number of bytes to xfer */ + /* Please see */ + /* usb_pipe_get_max_bulk_xfer_size(9F) */ + /* for maximum size */ +mblk_t *bulk_data; /* the data for the data phase */ + /* IN or OUT: allocated by client */ +uint_t bulk_timeout; /* xfer timeout value in secs */ + /* If set to zero, defaults to 5 sec */ +usb_opaque_t bulk_client_private; /* Client specific information */ +usb_req_attrs_t bulk_attributes; /* xfer-attributes */ + +/* Normal callback function, called upon completion. */ +void (*bulk_cb)( + usb_pipe_handle_t ph, struct usb_bulk_req *req); + +/* Exception callback function, for error handling. */ +void (*bulk_exc_cb)( + usb_pipe_handle_t ph, struct usb_bulk_req *req); + +/* set by USBA/HCD framework on completion */ +usb_cr_t bulk_completion_reason; /* overall success status */ + /* See usb_completion_reason(9S) */ +usb_cb_flags_t bulk_cb_flags; /* recovery done by callback hndlr */ + /* See usb_callback_flags(9S) */ +.fi +.in -2 + +.sp +.LP +Request attributes define special handling for transfers. The following +attributes are valid for bulk requests: +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_SHORT_XFER_OK\fR +.ad +.RS 27n +.rt +USB framework accepts transfers where less data is received than expected. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_AUTOCLEARING\fR +.ad +.RS 27n +.rt +USB framework resets pipe and clears functional stalls automatically on +exception. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_PIPE_RESET\fR +.ad +.RS 27n +.rt +USB framework resets pipe automatically on exception. +.RE + +.sp +.LP +Please see \fBusb_request_attributes\fR(9S) for more information. +.sp +.LP +Bulk transfers/requests are subject to the following constraints and caveats: +.sp +.LP +1) The following table indicates combinations of \fBusb_pipe_bulk_xfer()\fR +flags argument and fields of the usb_bulk_req_t request argument (X = don't +care). +.br +.in +2 + +.in -2 +.sp +.in +2 +.nf +Flags Type Attributes Data Timeout Semantics +--------------------------------------------------------------- + X X X ==NULL X illegal + + X X ONE_XFER X X illegal + + no sleep IN !SHORT_XFER_OK !=NULL 0 See note (A) + + no sleep IN !SHORT_XFER_OK !=NULL > 0 See note (B) + + sleep IN !SHORT_XFER_OK !=NULL 0 See note (C) + + sleep IN !SHORT_XFER_OK !=NULL > 0 See note (D) + + no sleep IN SHORT_XFER_OK !=NULL 0 See note (E) + + no sleep IN SHORT_XFER_OK !=NULL > 0 See note (F) + + sleep IN SHORT_XFER_OK !=NULL 0 See note (G) + + sleep IN SHORT_XFER_OK !=NULL > 0 See note (H) + + X OUT SHORT_XFER_OK X X illegal + + no sleep OUT X !=NULL 0 See note (I) + + no sleep OUT X !=NULL > 0 See note (J) + + sleep OUT X !=NULL 0 See note (K) + + sleep OUT X !=NULL > 0 See note (L) +.fi +.in -2 + +.sp +.LP +Table notes: +.br +.in +2 +A). Fill buffer, no timeout, callback when bulk_len is transferred. +.in -2 +.br +.in +2 +B). Fill buffer, with timeout; callback when bulk_len is transferred. +.in -2 +.br +.in +2 +C). Fill buffer, no timeout, unblock when bulk_len is transferred; no callback. +.in -2 +.br +.in +2 +D). Fill buffer, with timeout; unblock when bulk_len is transferred or a +timeout occurs; no callback. +.in -2 +.br +.in +2 +E) Fill buffer, no timeout, callback when bulk_len is transferred or first +short packet is received. +.in -2 +.br +.in +2 +F). Fill buffer, with timeout; callback when bulk_len is transferred or first +short packet is received. +.in -2 +.br +.in +2 +G). Fill buffer, no timeout, unblock when bulk_len is transferred or first +short packet is received; no callback. +.in -2 +.br +.in +2 +H). Fill buffer, with timeout; unblock when bulk_len is transferred, first +short packet is received, or a timeout occurs; no callback. +.in -2 +.br +.in +2 +I). Empty buffer, no timeout; callback when bulk_len is transferred. +.in -2 +.br +.in +2 +J) Empty buffer, with timeout; callback when bulk_len is transferred or a +timeout occurs. +.in -2 +.br +.in +2 +K). Empty buffer, no timeout; unblock when bulk_len is transferred; no +callback. +.in -2 +.br +.in +2 +L). Empty buffer, with timeout; unblock when bulk_len is transferred or a +timeout occurs; no callback. +.in -2 +.sp +.LP +2) bulk_len must be > 0. bulk_data must not be NULL. +.sp +.LP +3) Bulk_residue is set for both READ and WRITE. If it is set to 0, it means +that all of the data was transferred successfully. In case of WRITE it +contains data not written and in case of READ it contains the data NOT read so +far. A residue can only occur because of timeout or bus/device error. (Note +that a short transfer for a request where the USB_ATTRS_SHORT_XFER_OK attribute +is not set is considered a device error.) An exception callback is made and +completion_reason will be non-zero. +.sp +.LP +4) Splitting large Bulk xfers: Due to internal constraints, the USBA framework +can only do a limited size bulk data xfer per request. A client driver may +first determine this limitation by calling the USBA interface +(usb_pipe_get_max_bulk_xfer_size(9F)) and then restrict itself to doing +transfers in multiples of this fixed size. This forces a client driver to do +data xfers in a loop for a large request, splitting it into multiple chunks of +fixed size. +.sp +.LP +The bulk_completion_reason indicates the status of the transfer. See +\fBusb_completion_reason\fR(9S) for usb_cr_t definitions. +.sp +.LP +The bulk_cb_flags are set prior to calling the exception callback handler to +summarize recovery actions taken and errors encountered during recovery. See +\fBusb_callback_flags\fR(9S) for usb_cb_flags_t definitions. +.sp +.LP +--- Callback handling --- +.sp +.LP +All usb request types share the same callback handling. See +\fBusb_callback_flags\fR(9S) for details. +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBusb_alloc_request\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F), +\fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_get_max_bulk_transfer_size\fR(9F), +\fBusb_pipe_intr_xfer\fR(9F), \fBusb_pipe_isoc_xfer\fR(9F), +\fBusb_callback_flags\fR(9S), \fBusb_completion_reason\fR(9S), +\fBusb_ctrl_request\fR(9S), \fBusb_intr_request\fR(9S), +\fBusb_isoc_request\fR(9S), \fBusb_request_attributes\fR(9S) diff --git a/usr/src/man/man9s/usb_callback_flags.9s b/usr/src/man/man9s/usb_callback_flags.9s new file mode 100644 index 0000000000..244549db6b --- /dev/null +++ b/usr/src/man/man9s/usb_callback_flags.9s @@ -0,0 +1,365 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_callback_flags 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_callback_flags \- USB callback flag definitions +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +If the USB framework detects an error during a request execution, it calls the +client driver's exception callback handler to report what happened. Callback +flags (which are set prior to calling the exception callback handler) detail +errors discovered during the exception recovery process, and summarize recovery +actions taken by the USBA framework. +.sp +.LP +Information from the callback flags supplements information from the original +transport error. For transfers, the original transport error status is returned +to the callback handler through the original request (whose completion reason +field contains any transport error indication). For command completion +callbacks, the callback's rval argument contains the transport error status. A +completion reason of \fBUSB_CR_OK\fR means the transfer completed with no +errors detected. +.sp +.LP +The usb_cb_flags_t enumerated type contains the following definitions: +.sp +.ne 2 +.mk +.na +\fBUSB_CB_NO_INFO\fR +.ad +.RS 27n +.rt +No additional errors discovered or recovery actions taken. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CB_FUNCTIONAL_STALL\fR +.ad +.RS 27n +.rt +A functional stall occurred during the transfer. A functional stall is +usually caused by a hardware error, and must be explicitly cleared. A +functional stall is fatal if it cannot be cleared. The default control pipe +never shows a functional stall. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CB_STALL_CLEARED\fR +.ad +.RS 27n +.rt +A functional stall has been cleared by the USBA framework. This can +happen if USB_ATTRS_AUTOCLEARING is set in the request's xxxx_attributes field. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CB_PROTOCOL_STALL\fR +.ad +.RS 27n +.rt +A protocol stall has occurred during the transfer. A protocol stall is caused +usually by an invalid or misunderstood command. It is cleared automatically +when the device is given its next command. The USBA framework +treats stalls detected on default pipe transfers as protocol stalls. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CB_RESET_PIPE\fR +.ad +.RS 27n +.rt +A pipe with a stall has been reset automatically via autoclearing, or via an +explicit call to \fBusb_pipe_reset\fR(9F). Resetting a pipe consists of +stopping all transactions on a pipe, setting the pipe to the idle state, and if +the pipe is not the default pipe, flushing all pending requests. The request +which has the error, plus all pending requests which are flushed, show +USB_CB_RESET_PIPE set in the usb_cb_flags_t when their exception callback is +called. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CB_ASYNC_REQ_FAILED\fR +.ad +.RS 27n +.rt +Resources could not be allocated to process callbacks +asynchronously. Callbacks receiving this flag must not block, since those +callbacks are executing in a context which holds resources shared by the rest +of the system. Note that exception callbacks with USB_CB_ASYNC_REQ_FAILED set +may execute out of order from the requests which preceded them. Normal +callbacks may be already queued when an exception hits that the USBA is unable +to queue. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CB_SUBMIT_FAILED\fR +.ad +.RS 27n +.rt +A queued request was submitted to the host controller driver and +was rejected. The usb_completion_reason shows why the request was rejected by +the host controller. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CB_NO_RESOURCES\fR +.ad +.RS 27n +.rt +Insufficient resources were available for recovery to proceed. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CB_INTR_CONTEXT\fR +.ad +.RS 27n +.rt +Callback is executing in interrupt context and should not block. +.RE + +.sp +.LP +The usb_cb_flags_t enumerated type defines a bitmask. Multiple bits can be set, +reporting back multiple statuses to the exception callback handler. +.SS "CALLBACK HANDLER" +.sp +.LP +The USBA framework supports callback handling as a way of asynchronous client +driver notification. There are three kinds of callbacks: Normal completion +transfer callback, exception (error) completion transfer callback, and command +completion callback, each described below. +.sp +.LP +Callback handlers are called whenever they are specified in a request or +command, regardless of whether or not that request or command specifies the +USB_FLAGS_SLEEP flag. (USB_FLAGS_SLEEP tells the request or command to block +until completed.) Callback handlers must be specified whenever an asynchronous +transfer is requested. +.SS "PIPE POLICY" +.sp +.LP +Each pipe is associated with a pool of threads that are used to run callbacks +associated with requests on that pipe. All transfer completion callbacks for a +particular pipe are run serially by a single thread. +.sp +.LP +Pipes taking requests with callbacks which can block must have their pipe +policy properly initialized. If a callback blocks on a condition that is only +met by another thread associated with the same pipe, there must be sufficient +threads available. Otherwise that callback thread will block forever. +Similarly, problems will ensue when callbacks overlap and there are not enough +threads to handle the number of overlapping callbacks. +.sp +.LP +The pp_max_async_reqs field of the pipe_policy provides a hint of how many +threads to allocate for asynchronous processing of request callbacks on a pipe. +Set this value high enough per pipe to accommodate all of the pipe's possible +asynchronous conditions. The pipe_policy is passed to \fBusb_pipe_open\fR(9F). +.sp +.LP +Transfer completion callbacks (normal completion and exception): +.sp +.LP +Most transfer completion callbacks are allowed to block, but only under certain +conditions: +.RS +4 +.TP +1. +No callback is allowed to block if the callback flags show +USB_CB_INTR_CONTEXT set, since that flag indicates that the callback is running +in interrupt context instead of kernel context. Isochronous normal completion +callbacks, plus those with USB_CB_ASYNC_REQ_FAILED set, execute in interrupt +context. +.RE +.RS +4 +.TP +2. +Any callback except for isochronous normal completion can block for +resources (for example to allocate memory). +.RE +.RS +4 +.TP +3. +No callback can block for synchronous completion of a command (for example, +a call to \fBusb_pipe_close\fR(9F) with the USB_FLAGS_SLEEP flag passed) done +on the same pipe. The command could wait for all callbacks to complete, +including the callback which issued that command, causing all operations on the +pipe to deadlock. Note that asynchronous commands can start from a callback, +providing that the pipe's policy pp_max_async_reqs field is initialized to +accommodate them. +.RE +.RS +4 +.TP +4. +Avoid callbacks that block for synchronous completion of commands done on +other pipes. Such conditions can cause complex dependencies and unpredictable +results. +.RE +.RS +4 +.TP +5. +No callback can block waiting for a synchronous transfer request to +complete. (Note that making an asynchronous request to start a new transfer or +start polling does not block, and is OK.) +.RE +.RS +4 +.TP +6. +No callback can block waiting for another callback to complete. (This is +because all callbacks are done by a single thread.) +.RE +.RS +4 +.TP +7. +Note that if a callback blocks, other callbacks awaiting processing can +backup behind it, impacting system resources. +.RE +.sp +.LP +A transfer request can specify a non-null normal-completion callback. Such +requests conclude by calling the normal-completion callback when the transfer +completes normally. Similarly, a transfer request can specify a non-null +exception callback. Such requests conclude by calling the exception callback +when the transfer completes abnormally. Note that the same callback can be used +for both normal completion and exception callback handling. A completion reason +of USB_CR_OK defines normal completion. +.sp +.LP +All request-callbacks take as arguments a usb_pipe_handle_t and a pointer to +the request: +.sp +.in +2 +.nf +xxxx_cb(usb_pipe_handle_t ph, struct usb_ctrl_req *req); +.fi +.in -2 + +.sp +.LP +Such callbacks can retrieve saved state or other information from the private +area of the pipe handle. (See \fBusb_pipe_set_private\fR(9F).) Handlers also +have access to the completion reason (usb_cr_t) and callback flags +(usb_cb_flags_t) through the request argument they are passed. +.sp +.LP +Request information follows. In the data below, \fIxxxx\fR below represents the +type of request (ctrl, intr, isoc or bulk.) +.sp +.in +2 +.nf + Request structure name is usb_xxxx_req_t. + + Normal completion callback handler field is xxxx_cb. + + Exception callback handler field is xxxx_exc_cb. + + Completion reason field is xxxx_completion_reason. + + Callback flags field is xxxx_cb_flags. +.fi +.in -2 + +.SS "COMMAND COMPLETION CALLBACKS" +.sp +.LP +Calls to some non-transfer functions can be set up for callback notification. +These include \fBusb_pipe_close\fR(9F), \fBusb_pipe_reset\fR(9F), +\fBusb_pipe_drain_reqs\fR(9F), \fBusb_set_cfg\fR(9F), \fBusb_set_alt_if\fR(9F) +and \fBusb_clr_feature\fR(9F). +.sp +.LP +The signature of a command completion callback is as follows: +.sp +.in +2 +.nf + command_cb( + usb_pipe_handle_t cb_pipe_handle, + usb_opaque_t arg, + int rval, + usb_cb_flags_t flags); +.fi +.in -2 + +.sp +.LP +As with transfer completion callbacks, command completion callbacks take a +usb_pipe_handle_t to retrieve saved state or other information from the pipe's +private area. Also, command completion callbacks are provided with an +additional user-definable argument (usb_opaque_t arg), the return status of the +executed command (int rval), and the callback flags (usb_cb_flags_t flags). +.sp +.LP +The rval argument is roughly equivalent to the completion reason of a transfer +callback, indicating the overall status. See the return values of the relevant +function for possible rval values which can be passed to the callback. +.sp +.LP +The callback flags can be checked when rval indicates failure status. Just as +for transfer completion callbacks, callback flags return additional information +on execution events. +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBusb_alloc_request\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F), +\fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_intr_xfer\fR(9F), +\fBusb_pipe_isoc_xfer\fR(9F), \fBusb_bulk_request\fR(9S), +\fBusb_ctrl_request\fR(9S), \fBusb_intr_request\fR(9S), +\fBusb_isoc_request\fR(9S) diff --git a/usr/src/man/man9s/usb_cfg_descr.9s b/usr/src/man/man9s/usb_cfg_descr.9s new file mode 100644 index 0000000000..461ba9ee18 --- /dev/null +++ b/usr/src/man/man9s/usb_cfg_descr.9s @@ -0,0 +1,94 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_cfg_descr 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_cfg_descr \- USB configuration descriptor +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBusb_cfg_descr_t\fR configuration descriptor defines attributes of a +configuration. A configuration contains one or more interfaces. A configuration +descriptor acts as a header for the group of other descriptors describing the +subcomponents (for example, interfaces and endpoints) of a configuration. +Please refer to Section \fI9.6.3\fR of the \fIUSB 2.0\fR specification. The +\fIUSB 2.0\fR specification is available at \fIwww.usb.org\fR. +.sp +.LP +One or more configuration descriptors are retrieved from a USB device during +device enumeration. They can be accessed via \fBusb_get_dev_data\fR(9F). +.sp +.LP +A configuration descriptor has the following fields: +.sp +.in +2 +.nf +uint8_t bLength Size of this descriptor + in bytes. + +uint8_t bDescriptorType Set to USB_DESCR_TYPE_CFG. + +uint16_t wTotalLength Total length of data returned + including this and all other + descriptors in this configuration. + +uint8_t bNumInterfaces Number of interfaces in this + configuration. + +uint8_t bConfigurationValue ID of this configuration + (1-based). + +uint8_t iConfiguration Index of optional configuration + string. Valid if > 0. + +uint8_t bmAttributes Configuration characteristics + (See below). + +uint8_t bMaxPower Maximum power consumption, in + 2mA units. + +Configuration descriptors define the following bmAttributes: + USB_CFG_ATTR_SELFPWR - Set if config not using bus power. + USB_CFG_ATTR_REMOTE_WAKEUP - Set if config supports rem wakeup. +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_alt_if\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_dev_data\fR(9F), \fBusb_get_string_descr\fR(9F), +\fBusb_parse_data\fR(9F), \fBusb_ctrl_request\fR(9S), \fBusb_dev_descr\fR(9S), +\fBusb_dev_qlf_descr\fR(9S), \fBusb_ep_descr\fR(9S), \fBusb_if_descr\fR(9S), +\fBusb_other_speed_cfg_descr\fR(9S), \fBusb_string_descr\fR(9S) diff --git a/usr/src/man/man9s/usb_client_dev_data.9s b/usr/src/man/man9s/usb_client_dev_data.9s new file mode 100644 index 0000000000..8d3d4f4661 --- /dev/null +++ b/usr/src/man/man9s/usb_client_dev_data.9s @@ -0,0 +1,313 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_client_dev_data 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_client_dev_data \- Device configuration information +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The usb_client_dev_data_t structure carries all device configuration +information. It is provided to a USB client driver through a call to +\fBusb_get_dev_data\fR(9F). Most USBA functions require information which comes +from this structure. +.sp +.LP +The usb_client_dev_data_t structure fields are: +.sp +.in +2 +.nf + usb_pipe_handle_t dev_default_ph; /* deflt ctrl pipe handle */ + + ddi_iblock_cookie_t dev_iblock_cookie;/* for calls to mutex_init */ + /* for mutexes used by intr */ + /* context callbacks. */ + + usb_dev_descr_t *dev_descr; /* parsed* dev. descriptor */ + + char *dev_mfg; /* manufacturer's ID string */ + + char *dev_product; /* product ID string */ + + char *dev_serial; /* serial num. string */ + + usb_reg_parse_lvl_t dev_parse_level; /* Parse level */ + /* reflecting the tree */ + /* (if any) returned through */ + /* the dev_cfg array. */ + + usb_cfg_data_t *dev_cfg; /* parsed* descr tree.*/ + + uint_t dev_n_cfg; /* num cfgs in parsed descr. */ + /* tree, dev_cfg array below.*/ + + usb_cfg_data_t *dev_curr_cfg; /* Pointer to the tree config*/ + /* corresponding to the cfg */ + /* active at the time of the */ + /* usb_get_dev_data() call */ + + int dev_curr_if; /* First active interface in */ + /* tree under driver's control.*/ + + /* Always zero when driver */ + /* controls whole device. */ + +* A parsed descriptor is in a struct whose fields' have been adjusted + to the host processor. This may include endianness adjustment (the USB + standard defines that devices report in little-endian bit order) or + structure padding as necessary. +.fi +.in -2 + +.sp +.LP +dev_parse_level represents the extent of the device represented by the tree +returned by the dev_cfg field and has the following possible values: +.sp +.ne 2 +.mk +.na +\fBUSB_PARSE_LVL_NONE\fR +.ad +.RS 22n +.rt +Build no tree. dev_n_cfg returns 0, dev_cfg and dev_curr_cfg are returned NULL, +the dev_curr_xxx fields are invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_PARSE_LVL_IF\fR +.ad +.RS 22n +.rt +Parse configured interface only, if configuration# and interface properties are +set (as when different interfaces are viewed by the OS as different device +instances). If an OS device instance is set up to represent an entire physical +device, this works like USB_PARSE_LVL_ALL. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_PARSE_LVL_CFG\fR +.ad +.RS 22n +.rt +Parse entire configuration of configured interface only. This is like +USB_PARSE_LVL_IF except entire configuration is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_PARSE_LVL_ALL\fR +.ad +.RS 22n +.rt +Parse entire device (all configurations), even when driver is bound to a single +interface of a single configuration. +.RE + +.sp +.LP +The default control pipe handle is used mainly for control commands and device +setup. +.sp +.LP +The dev_iblock_cookie is used to initialize client driver mutexes which are +used in interrupt-context callback handlers. (All callback handlers called +with USB_CB_INTR_CONTEXT in their usb_cb_flags_t arg execute in interrupt +context.) This cookie is used in lieu of one returned by +\fBddi_get_iblock_cookie\fR(9F). Mutexes used in other handlers or under other +conditions should initialize per \fBmutex_init\fR(9F). +.sp +.LP +The parsed standard USB device descriptor is used for device type +identification. +.sp +.LP +The several ID strings, including the manufacturer's ID, product ID, and serial +number may be used to identify the device in messages or to compare it to other +devices. +.sp +.LP +The descriptor tree, returned by dev_cfg, makes a device's parsed standard USB +descriptors available to the driver. The tree is designed to be easily +traversed to get any or all standard \fIUSB 2.0\fR descriptors. (See the "Tree +Structure" section of this manpage below.) dev_n_cfg returns the number of +configurations in the tree. Note that this value may differ from the number of +configurations returned in the device descriptor. +.sp +.LP +A returned parse_level field of USB_PARSE_LVL_ALL indicates that all +configurations are represented in the tree. This results when USB_PARSE_LVL_ALL +is explicitly requested by the caller in the flags argument to +\fBusb_get_dev_data()\fR, or when the whole device is seen by the system for +the current OS device node (as opposed to only a single configuration for that +OS device node). USB_PARSE_LVL_CFG is returned when one entire configuration is +returned in the tree. USB_PARSE_LVL_IF is returned when one interface of one +configuration is returned in the tree. In the latter two cases, the returned +configuration is at dev_cfg[USB_DEV_DEFAULT_CONFIG_INDEX]. +USB_PARSE_LVL_NONE is returned when no tree is returned. Note that the value of +this field can differ from the parse_level requested as an argument to +\fBusb_get_dev_data()\fR. +.SS "TREE STRUCTURE" +.sp +.LP +The root of the tree is dev_cfg, an array of usb_cfg_data_t configuration +nodes, each representing one device configuration. The array index does +not correspond to a configuration's value; use the bConfigurationValue field of +the configuration descriptor within to find out the proper number for a given +configuration. +.sp +.LP +The size of the array is returned in dev_n_cfg. The array itself is not NULL +terminated. +.sp +.LP +When USB_PARSE_LVL_ALL is returned in dev_parse_level, index 0 pertains to the +first valid configuration. This pertains to device configuration 1 as USB +configuration 0 is not defined. When dev_parse_level returns USB_PARSE_LVL_CFG +or USB_PARSE_LVL_IF, index 0 pertains to the device's one configuration +recognized by the system. (Note that the configuration level is the only +descriptor level in the tree where the index value does not correspond to the +descriptor's value.) +.sp +.LP +Each usb_cfg_data_t configuration node contains a parsed usb configuration +descriptor (usb_cfg_descr_t cfg_descr) a pointer to its string description +(char *cfg_str) and string size (cfg_strsize), a pointer to an array of +interface nodes (usb_if_data_t *cfg_if), and a pointer to an array of +class/vendor (cv) descriptor nodes (usb_cvs_data_t *cfg_cvs). The interface +node array size is kept in cfg_n_if, and the cv node array size is kept in +cfg_n_cvs; neither array is NULL terminated. When USB_PARSE_LVL_IF is returned +in dev_parse_level, the only interface (or alternate group) included in the +tree is that which is recognized by the system for the current OS device node. +.sp +.LP +Each interface can present itself potentially in one of several alternate ways. +An alternate tree node (usb_alt_if_data_t) represents an alternate +representation. Each usb_if_data_t interface node points to an array of +alternate nodes (usb_alt_if_data_t *if_alt) and contains the size of +the array (if_n_alt). +.sp +.LP +Each interface alternate node holds an interface descriptor (usb_if_descr_t +altif_descr), a pointer to its string description (char *altif_str), and has +its own set of endpoints and bound cv descriptors. The pointer to the array of +endpoints is usb_ep_data_t *altif_ep); the endpoint array size is altif_n_ep. +The pointer to the array of cv descriptors is usb_cvs_data_t *altif_cvs; the cv +descriptor array size is altif_n_cvs. +.sp +.LP +Each endpoint node holds an endpoint descriptor (usb_ep_descr_t ep_descr), a +pointer to an array of cv descriptors for that endpoint (usb_cvs_data_t +*ep_cvs), and the size of that array (ep_n_cvs). An endpoint descriptor may be +passed to \fBusb_pipe_open\fR(9F) to establish a logical connection for data +transfer. +.sp +.LP +Class and vendor descriptors (cv descriptors) are grouped with the +configuration, interface or endpoint descriptors they immediately follow in the +raw data returned by the device. Tree nodes representing such descriptors +(usb_cvs_data_t) contain a pointer to the raw data (uchar_t *cvs_buf) and the +size of the data (uint_t cvs_buf_len). +.sp +.LP +Configuration and interface alternate nodes return string descriptions. Note +that all string descriptions returned have a maximum length of USB_MAXSTRINGLEN +bytes and are in English ASCII. +.SH EXAMPLES +.sp +.LP +In the following example, a device's configuration data, including the +following descriptor tree, is retrieved by \fBusb_get_dev_data\fR(9F) into +usb_client_dev_data_t *reg_data: +.sp +.in +2 +.nf + config 1 + iface 0 + alt 0 + endpt 0 + config 2 + iface 0 + iface 1 + alt 0 + endpt 0 + cv 0 + alt 1 + endpt 0 + endpt 1 + cv 0 + endpt 2 + alt 2 + endpt 0 + cv 0 + + and suppose that the C/V data is of the following format: + + typedef struct cv_data { + char char1; + short short1; + char char2; + } cv_data_t; + + Parse the data of C/V descriptor 0, second configuration + (index 1), iface 1, alt 2, endpt 0. + + usb_client_dev_data_t reg_data; + usb_cvs_data_t *cv_node; + cv_data_t parsed_data; + + cv_node = + ®_data->dev_cfg[1].cfg_if[1].if_alt[2].altif_ep[0].ep_cvs[0]; + (void)usb_parse_data("csc", + (void *)(&cv_node->cvs_buf), cv_node->cvs_buf_len, + &parsed_data, sizeof(cv_data_t)); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBusb_get_alt_if\fR(9F), \fBusb_get_cfg\fR(9F), \fBusb_get_dev_data\fR(9F), +\fBusb_get_string_descr\fR(9F), \fBusb_lookup_ep_data\fR(9F), +\fBusb_parse_data\fR(9F), \fBusb_pipe_open\fR(9F), \fBusb_cfg_descr\fR(9S), +\fBusb_if_descr\fR(9S), \fBusb_ep_descr\fR(9S), \fBusb_string_descr\fR(9S) diff --git a/usr/src/man/man9s/usb_completion_reason.9s b/usr/src/man/man9s/usb_completion_reason.9s new file mode 100644 index 0000000000..9a3fdacbcf --- /dev/null +++ b/usr/src/man/man9s/usb_completion_reason.9s @@ -0,0 +1,305 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_completion_reason 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_completion_reason \- USB completion reason definitions +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +If an error occurs during execution of a USB request, the USBA framework calls +a client driver's exception callback handler to relay what happened. The host +controller reports transport errors to the exception callback handler through +the handler's request argument's completion reason (usb_cr_t) field. A +completion reason of USB_CR_OK means the transfer completed with no errors +detected. +.sp +.LP +The usb_cr_t enumerated type contains the following definitions: +.sp +.ne 2 +.mk +.na +\fBUSB_CR_OK\fR +.ad +.RS 27n +.rt +The transfer completed without any errors being detected. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_CRC\fR +.ad +.RS 27n +.rt +CRC error was detected. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_BITSTUFFING\fR +.ad +.RS 27n +.rt +Bit stuffing violation was detected. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_DATA_TOGGLE_MM\fR +.ad +.RS 27n +.rt +Data toggle packet identifier did not match expected value. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_STALL\fR +.ad +.RS 27n +.rt +The device endpoint indicated that it is stalled. If autoclearing is enabled +for the request (request attributes has USB_ATTRS_AUTOCLEARING set), check the +callback flags (usb_cb_flags_t) in the callback handler to determine whether +the stall is a functional stall (USB_CB_FUNCTIONAL_STALL) or a protocol stall +(USB_CB_PROTOCOL_STALL). Please see \fBusb_request_attributes\fR(9S) for more +information on autoclearing. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_DEV_NOT_RESP\fR +.ad +.RS 27n +.rt +Host controller timed out while waiting for device to respond. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_PID_CHECKFAILURE\fR +.ad +.RS 27n +.rt +Check bits on the packet identifier returned from the device were +not as expected. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_UNEXP_PID\fR +.ad +.RS 27n +.rt +Packet identifier received was not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_DATA_OVERRUN\fR +.ad +.RS 27n +.rt +Amount of data returned exceeded either the maximum packet size of the endpoint +or the remaining buffer size. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_DATA_UNDERRUN\fR +.ad +.RS 27n +.rt +Amount of data returned was not sufficient to fill the specified buffer and the +USB_ATTRS_SHORT_XFER_OK attribute was not set. Please see +\fBusb_request_attributes\fR(9S) for more information on allowance of short +transfers. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_BUFFER_OVERRUN\fR +.ad +.RS 27n +.rt +A device sent data faster than the system could digest it. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_BUFFER_UNDERRUN\fR +.ad +.RS 27n +.rt +The host controller could not get data from the system fast enough to keep up +with the required USB data rate. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_TIMEOUT\fR +.ad +.RS 27n +.rt +A timeout specified in a control, bulk, or one-time interrupt request has +expired. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_NOT_ACCESSED\fR +.ad +.RS 27n +.rt +Request was not accessed nor processed by the host controller. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_NO_RESOURCES\fR +.ad +.RS 27n +.rt +No resources were available to continue servicing a periodic interrupt or +isochronous request. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_STOPPED_POLLING\fR +.ad +.RS 27n +.rt +Servicing of the current periodic request cannot continue because polling on an +interrupt-IN or isochronous-IN endpoint has stopped. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_PIPE_CLOSING\fR +.ad +.RS 27n +.rt +Request was not started because the pipe to which it was queued was closing or +closed. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_PIPE_RESET\fR +.ad +.RS 27n +.rt +Request was not started because the pipe to which it was queued was reset. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_NOT_SUPPORTED\fR +.ad +.RS 27n +.rt +Request or command is not supported. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_FLUSHED\fR +.ad +.RS 27n +.rt +Request was not completed because the pipe to which it was queued went to an +error state, became stalled, was reset or was closed. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CR_HC_HARDWARE_ERR\fR +.ad +.RS 27n +.rt +Request could not be completed due to a general host controller +hardware error. +.RE + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBusb_alloc_request\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F), +\fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_intr_xfer\fR(9F), +\fBusb_pipe_isoc_xfer\fR(9F), \fBusb_bulk_request\fR(9S), +\fBusb_ctrl_request\fR(9S), \fBusb_intr_request\fR(9S), +\fBusb_isoc_request\fR(9S). diff --git a/usr/src/man/man9s/usb_ctrl_request.9s b/usr/src/man/man9s/usb_ctrl_request.9s new file mode 100644 index 0000000000..617f9f2734 --- /dev/null +++ b/usr/src/man/man9s/usb_ctrl_request.9s @@ -0,0 +1,193 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_ctrl_request 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_ctrl_request \- USB control pipe request structure +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +A control request is used to send device commands (or requests) and to read +status. Please refer to Section\fI 5.5\fR of the \fIUSB 2.0\fR specification +for information on control pipes. For information on formatting requests, see +Section \fI9.3\fR of the \fIUSB 2.0\fR specification. The USB 2.0 specification +is available at \fIwww.usb.org\fR. +.SH STRUCTURE MEMBERS +.sp +.LP +The fields in the usb_ctrl_req_t are used to format a control request: +.sp +.in +2 +.nf + uint8_t ctrl_bmRequestType; /* characteristics of request */ + uint8_t ctrl_bRequest; /* specific request */ + uint16_t ctrl_wValue; /* varies according to request */ + uint16_t ctrl_wIndex; /* index or offset */ + uint16_t ctrl_wLength; /* number of bytes to xfer */ + mblk_t *ctrl_data; /* data for the data phase */ + /* IN or OUT: allocated by client */ + uint_t ctrl_timeout; /* time until USBA framework */ + /* retires req, in seconds */ + /* If set to zero, defaults to 5 sec */ + usb_opaque_t ctrl_client_private; /* client private info */ + usb_req_attrs_t ctrl_attributes; /* attrib. for this req */ + + /* Normal callback function, called upon completion. */ + void (*ctrl_cb)( + usb_pipe_handle_t ph, struct usb_ctrl_req *req); + + /* Exception callback function, for error handling. */ + void (*ctrl_exc_cb)( + usb_pipe_handle_t ph, struct usb_ctrl_req *req); + usb_cr_t ctrl_completion_reason; /* overall success status */ + /* See usb_completion_reason(9S) */ + usb_cb_flags_t ctrl_cb_flags; /* recovery done by callback hndlr */ + /* See \fBusb_callback_flags(9S)\fR */ +.fi +.in -2 + +.sp +.LP +Request attributes define special handling for transfers. The following +attributes are valid for control requests: +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_SHORT_XFER_OK\fR +.ad +.RS 27n +.rt +Accept transfers where less data is received than expected. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_AUTOCLEARING\fR +.ad +.RS 27n +.rt +Have USB framework reset pipe and clear functional stalls automatically on +exception. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_PIPE_RESET\fR +.ad +.RS 27n +.rt +Have USB framework reset pipe automatically on exception. +.RE + +.sp +.LP +Please see \fBusb_request_attributes\fR(9S) for more information. +.sp +.LP +The following definitions directly pertain to fields in the USB control request +structure. (See Section \fI 9.3\fR of the \fIUSB 2.0\fR specification.) +.sp +.in +2 +.nf +Direction bitmasks of a control request's ctrl_bmRequestType field +(USB 2.0 spec, section 9.3.1) + + USB_DEV_REQ_HOST_TO_DEV | Host to device direction + USB_DEV_REQ_DEV_TO_HOST | Device to host direction + USB_DEV_REQ_DIR_MASK | Bitmask of direction bits + +Request type bitmasks of a control request's ctrl_bmRequestType field +(USB 2.0 spec, section 9.3.1) + + USB_DEV_REQ_TYPE_STANDARD | USB 2.0 defined command + | for all USB devices + USB_DEV_REQ_TYPE_CLASS | USB 2.0 defined + | class-specific command + USB_DEV_REQ_TYPE_VENDOR | Vendor-specific command + USB_DEV_REQ_TYPE_MASK | Bitmask of request type bits + +Recipient bitmasks of a control request's ctrl_bmRequestType field +(USB 2.0 spec, section 9.3.1) + + USB_DEV_REQ_RCPT_DEV | Request is for device + USB_DEV_REQ_RCPT_IF | Request is for interface + USB_DEV_REQ_RCPT_EP | Request is for endpoint + USB_DEV_REQ_RCPT_OTHER | Req is for other than above + USB_DEV_REQ_RCPT_MASK | Bitmask of request recipient bits + +Standard requests (USB 2.0 spec, section 9.4) + USB_REQ_GET_STATUS | Get status of device, endpoint + |or interface (9.4.5) + USB_REQ_CLEAR_FEATURE | Clear feature specified by + |wValue field (9.4.1) + USB_REQ_SET_FEATURE | Set feature specified by + | wValue field (9.4.9) + USB_REQ_SET_ADDRESS | Set address specified by + | wValue field (9.4.6) + USB_REQ_GET_DESCR | Get descr for item/idx in + | wValue field (9.4.3) + USB_REQ_SET_DESCR | Set descr for item/idx in + | wValue field (9.4.8) + USB_REQ_GET_CFG | Get current device + | configuration (9.4.2) + USB_REQ_SET_CFG | Set current device + | configuration (9.4.7) + USB_REQ_GET_IF | Get alternate interface + | setting (9.4.4) + USB_REQ_SET_IF | Set alternate interface + | setting (9.4.10) + USB_REQ_SYNC_FRAME | Set and report an endpoint's + | sync frame (9.4.11) + +Unicode language ID, used as wIndex for USB_REQ_SET/GET_DESCRIPTOR + + USB_LANG_ID | Unicode English Lang ID for + | parsing str descr +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBusb_alloc_request\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F), +\fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_intr_xfer\fR(9F), +\fBusb_pipe_isoc_xfer\fR(9F), \fBusb_bulk_request\fR(9S), +\fBusb_callback_flags\fR(9S), \fBusb_completion_reason\fR(9S), +\fBusb_intr_request\fR(9S), \fBusb_isoc_request\fR(9S), +\fBusb_request_attributes\fR(9S) diff --git a/usr/src/man/man9s/usb_dev_descr.9s b/usr/src/man/man9s/usb_dev_descr.9s new file mode 100644 index 0000000000..63ea514436 --- /dev/null +++ b/usr/src/man/man9s/usb_dev_descr.9s @@ -0,0 +1,127 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_dev_descr 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_dev_descr \- USB device descriptor +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBusb_dev_descr_t\fR device descriptor defines device-wide attributes. +Please refer to Section \fI9.6.1\fR of the \fIUSB 2.0\fR specification. The +\fIUSB 2.0\fR specification is available at \fIwww.usb.org\fR. +.sp +.LP +The device descriptor is retrieved from a USB device during device enumeration +and can be accessed via \fBusb_get_dev_data\fR(9F). +.sp +.LP +A device descriptor contains the following fields: +.sp +.in +2 +.nf + uint8_t bLength Size of this descriptor, + in bytes. + + uint8_t bDescriptorType Set to USB_DESCR_TYPE_DEV. + + uint16_t bcdUSB USB specification release + number supported, in bcd. + + uint8_t bDeviceClass Class code (see below). + + uint8_t bDeviceSubClass Subclass code (see USB 2.0 + specification of applicable + device class for information.) + + uint8_t bDeviceProtocol Protocol code (see USB 2.0 + specification of applicable + device class for information.) + + uint8_t bMaxPacketSize0 Maximum packet size of + endpoint 0. + + uint16_t idVendor vendor ID value. + + uint16_t idProduct product ID value. + + uint16_t bcdDevice Device release number in + binary coded decimal. + + uint8_t iManufacturer Index of optional manufacturer + description string. + Valid if > 0. + + uint8_t iProduct Index of optional product + description string. + Valid if > 0. + + uint8_t iSerialNumber Index of optional serial + number string. + Valid if > 0. + + uint8_t bNumConfigurations Number of available + configurations. + + + Device descriptors bDeviceClass values: + + USB_CLASS_PER_INTERFACE Class information is at + interface level. + + USB_CLASS_COMM CDC control device class. + + USB_CLASS_DIAG Diagnostic device class. + + USB_CLASS_HUB HUB device class. + + USB_CLASS_MISC MISC device class. + + USB_CLASS_VENDOR_SPEC Vendor-specific class. + + USB_CLASS_WIRELESS Wireless controller + device class. + + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_alt_if\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_dev_data\fR(9F), \fBusb_get_string_descr\fR(9F), +\fBusb_parse_data\fR(9F), \fBusb_cfg_descr\fR(9S), \fBusb_ctrl_request\fR(9S), +\fBusb_dev_qlf_descr\fR(9S), \fBusb_ep_descr\fR(9S), \fBusb_if_descr\fR(9S), +\fBusb_other_speed_cfg_descr\fR(9S), \fBusb_string_descr\fR(9S) diff --git a/usr/src/man/man9s/usb_dev_qlf_descr.9s b/usr/src/man/man9s/usb_dev_qlf_descr.9s new file mode 100644 index 0000000000..76c23f99c8 --- /dev/null +++ b/usr/src/man/man9s/usb_dev_qlf_descr.9s @@ -0,0 +1,91 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_dev_qlf_descr 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_dev_qlf_descr \- USB device qualifier descriptor +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The device qualifier descriptor \fBusb_dev_qlf_descr_t\fR defines how fields of +a high speed device's device descriptor would look if that device is run at a +different speed. If a high-speed device is running currently at full/high +speed, fields of this descriptor reflect how device descriptor fields would +look if speed was changed to high/full. Please refer to section \fI9.6.2\fR of +the \fIUSB 2.0\fR specification. The \fIUSB 2.0\fR specification is available +at \fIwww.usb.org\fR. +.sp +.LP +A device descriptor contains the following fields: +.sp +.in +2 +.nf +uint8_t bLength Size of this descriptor. + +uint8_t bDescriptorType Set to USB_DESCR_TYPE_DEV_QLF. + +uint16_t bcdUSB USB specification release + number in binary coded decimal. + +uint8_t bDeviceClass Device class code. + (See \fBusb_dev_descr(9s)\fR.) + +uint8_t bDeviceSubClass Device subclass code.(See + USB 2.0 specification of + applicable device class for + information.) + +uint8_t bDeviceProtocol Protocol code.(See + USB 2.0 specification of + applicable device class for + information.) + +uint8_t bMaxPacketSize0 Maximum packet size of + endpoint 0. + +uint8_t bNumConfigurations Number of available + configurations. + +uint8_t bReserved Reserved. +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_alt_if\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_dev_data\fR(9F), \fBusb_get_string_descr\fR(9F). +\fBusb_parse_data\fR(9F), \fBusb_ctrl_request\fR(9S), \fBusb_cfg_descr\fR(9S), +\fBusb_dev_descr\fR(9S), \fBusb_ep_descr\fR(9S), \fBusb_if_descr\fR(9S), +\fBusb_other_speed_cfg_descr\fR(9S), \fBusb_string_descr\fR(9S) diff --git a/usr/src/man/man9s/usb_ep_descr.9s b/usr/src/man/man9s/usb_ep_descr.9s new file mode 100644 index 0000000000..353e5e1a84 --- /dev/null +++ b/usr/src/man/man9s/usb_ep_descr.9s @@ -0,0 +1,148 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_ep_descr 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_ep_descr \- USB endpoint descriptor +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBusb_ep_descr_t\fR endpoint descriptor defines endpoint attributes. An +endpoint is a uniquely addressable portion of a USB device that is a source or +sink of data. +.sp +.LP +Please refer to Section \fI9.6.6\fR of the \fIUSB 2.0\fR specification. The +\fIUSB 2.0\fR specification is available at \fIwww.usb.org\fR. +.sp +.LP +One or more endpoint descriptors are retrieved from a USB device during device +enumeration. They can be accessed via \fBusb_get_dev_data\fR(9F). +.sp +.LP +A endpoint descriptor has the following fields: +.sp +.in +2 +.nf +uint8_t bLength Size of this descriptor + in bytes. + +uint8_t bDescriptorType Set to USB_DESCR_TYPE_EP. + +uint8_t bEndpointAddress Endpoint address. + +uint8_t bmAttributes Endpoint attrib. (see below.) + +uint16_t wMaxPacketSize Maximum pkt size. + +uint8_t bInterval Polling interval for interrupt + and isochro. endpoints. + NAK rate for high-speed control + and bulk endpoints. + +Endpoint descriptor bEndpointAddress bitmasks contain address number +and direction fields as follows: + USB_EP_NUM_MASK Address bits + USB_EP_DIR_MASK Direction bit + USB_EP_DIR_OUT OUT towards device + USB_EP_DIR_IN IN towards host + +Endpoint descriptor transfer type bmAttributes values and mask: + USB_EP_ATTR_CONTROL Endpoint supports control transfers + USB_EP_ATTR_ISOCH Endpoint supports isochronous xfers + USB_EP_ATTR_BULK Endpoint supports bulk transfers + USB_EP_ATTR_INTR Endpoint supports interrupt transfers + USB_EP_ATTR_MASK bmAttributes transfer-type bit field + +Endpoint descriptor synchronization type bmAttributes values and mask +for isochronous endpoints: + USB_EP_SYNC_NONE Endpoint supports no synchronization + USB_EP_SYNC_ASYNC Endpoint supports asynchronous sync + USB_EP_SYNC_ADPT Endpoint supports adaptive sync + USB_EP_SYNC_SYNC Endpoint supports synchronous sync + USB_EP_SYNC_MASK bmAttributes sync type bit field + +Endpoint descriptor feedback type bmAttributes values and mask for +isochronous endpoints: + USB_EP_USAGE_DATA Data endpoint + USB_EP_USAGE_FEED Feedback endpoint + USB_EP_USAGE_IMPL Implicit feedback data endpoint + USB_EP_USAGE_MASK bmAttributes feedback type bit fld + +Endpoint descriptor additional-transaction-opportunities- +per-microframe wMaxPacketSize values and mask for high speed +isochronous and interrupt endpoints: + USB_EP_MAX_PKTSZ_MASK Mask for packetsize bits + USB_EP_MAX_XACTS_MASK Bits for additional transfers per + microframe + USB_EP_MAX_XACTS_SHIFT Left-shift this number of bits to + get to additional-transfers-per- + microframe bitfield + +Endpoint descriptor polling bInterval range values: + USB_EP_MIN_HIGH_CONTROL_INTRVL Min NAK rate for highspd ctrl e/p + USB_EP_MAX_HIGH_CONTROL_INTRVL Max NAK rate for highspd ctrl e/p + + USB_EP_MIN_HIGH_BULK_INTRVL Min NAK rate for highspd bulk e/p + USB_EP_MAX_HIGH_BULK_INTRVL Max NAK rate for highspd bulk e/p + + USB_EP_MIN_LOW_INTR_INTRVL Min poll interval, lowspd intr e/p + USB_EP_MAX_LOW_INTR_INTRVL Max poll interval, lowspd intr e/p + + USB_EP_MIN_FULL_INTR_INTRVL Min poll interval, fullspd intr e/p + USB_EP_MAX_FULL_INTR_INTRVL Max poll interval, fullspd intr e/p + +Note that for the following polling bInterval range values, the interval +is 2**(value-1). See Section 9.6.6 of the USB 2.0 specification. + + USB_EP_MIN_HIGH_INTR_INTRVL Min poll interval, highspd intr e/p + USB_EP_MAX_HIGH_INTR_INTRVL Max poll interval, highspd intr e/p + + USB_EP_MIN_FULL_ISOCH_INTRVL Min poll interval, fullspd isoc e/p + USB_EP_MAX_FULL_ISOCH_INTRVL Max poll interval, fullspd isoc e/p + + USB_EP_MIN_HIGH_ISOCH_INTRVL Min poll interval, highspd isoc e/p + USB_EP_MAX_HIGH_ISOCH_INTRVL Max poll interval, highspd isoc e/p + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_alt_if\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_dev_data\fR(9F), \fBusb_get_string_descr\fR(9F), +\fBusb_parse_data\fR(9F), \fBusb_cfg_descr\fR(9S), \fBusb_ctrl_request\fR(9S), +\fBusb_dev_descr\fR(9S), \fBusb_dev_qlf_descr\fR(9S), \fBusb_if_descr\fR(9S), +\fBusb_other_speed_cfg_descr\fR(9S), \fBusb_string_descr\fR(9S) diff --git a/usr/src/man/man9s/usb_if_descr.9s b/usr/src/man/man9s/usb_if_descr.9s new file mode 100644 index 0000000000..9a5f53b4e3 --- /dev/null +++ b/usr/src/man/man9s/usb_if_descr.9s @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_if_descr 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_if_descr \- USB interface descriptor +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBusb_if_descr_t\fR interface descriptor defines attributes of an +interface. A configuration contains one or more interfaces. An interface +contains one or more endpoints. +.sp +.LP +Please refer to Section \fI9.6.5\fR of the \fIUSB 2.0\fR specification. The +\fIUSB 2.0\fR specification is available at \fIwww.usb.org\fR. +.sp +.LP +One or more configuration descriptors are retrieved from a USB device during +device enumeration. They can be accessed via \fBusb_get_dev_data\fR(9F). +.sp +.LP +A interface descriptor has the following fields: +.sp +.in +2 +.nf +uint8_t bLength Size of this descriptor + in bytes. + +uint8_t bDescriptorType Set to USB_DESCR_TYPE_IF. + +uint8_t bInterfaceNumber Interface number (0-based). + +uint8_t bAlternateSetting Alternate setting number for + this interface and its + endpoints (0-based). + +uint8_t bNumEndpoints Number of endpoints, + excluding endpoint 0. + +uint8_t bInterfaceClass Interface Class code + (see below). + +uint8_t bInterfaceSubClass Sub class code. (See USB 2.0 + specification of applicable + interface class for information.) + +uint8_t bInterfaceProtocol Protocol code. (See USB 2.0 + specification of applicable + interface class for information.) + +uint8_t iInterface Index of optional string + describing this interface + Valid if > 0. Pass to + usb_get_string_descr(9F) to + retrieve string. + +USB 2.0 specification interface descriptor bInterfaceClass field +values are as follows: + + USB_CLASS_APP Application-specific interface class + + USB_CLASS_AUDIO Audio interface class + + USB_CLASS_CCID Chip/Smartcard interface class + + USB_CLASS_CDC_CTRL CDC control interface class + + USB_CLASS_CDC_DATA CDC data interface class + + USB_CLASS_SECURITY Content security interface class + + USB_CLASS_DIAG Diagnostic interface class + + USB_CLASS_HID HID interface class + + USB_CLASS_HUB HUB interface class + + USB_CLASS_MASS_STORAGE Mass storage interface class + + USB_CLASS_PHYSICAL Physical interface class + + USB_CLASS_PRINTER Printer interface class + + USB_CLASS_VENDOR_SPEC Vendor-specific interface class + + USB_CLASS_WIRELESS Wireless interface class + + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_alt_if\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_dev_data\fR(9F), \fBusb_get_string_descr\fR(9F), +\fBusb_parse_data\fR(9F), \fBusb_cfg_descr\fR(9S), \fBusb_ctrl_request\fR(9S), +\fBusb_dev_descr\fR(9S), \fBusb_dev_qlf_descr\fR(9S), \fBusb_ep_descr\fR(9S), +\fBusb_other_speed_cfg_descr\fR(9S), \fBusb_string_descr\fR(9S) diff --git a/usr/src/man/man9s/usb_intr_request.9s b/usr/src/man/man9s/usb_intr_request.9s new file mode 100644 index 0000000000..82427b3dc1 --- /dev/null +++ b/usr/src/man/man9s/usb_intr_request.9s @@ -0,0 +1,300 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_intr_request 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_intr_request \- USB interrupt request structure +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +An interrupt request (that is, a request sent through an interrupt pipe), is +used to transfer small amounts of data infrequently, but with bounded +service periods. (Data flows in either direction.) Please refer to Section +\fI5.7\fR of the \fIUSB 2.0\fR specification for information on interrupt +transfers. (The \fIUSB 2.0\fR specification is available at \fIwww.usb.org\fR.) +.sp +.LP +The fields in the usb_intr_req_t are used to format an interrupt request. +Please see below for acceptable combinations of flags and attributes. +.sp +.LP +The usb_intr_req_t fields are: +.sp +.in +2 +.nf + ushort_t intr_len; /* Size of pkt. Must be set */ + /* Max size is 8K for low/full speed */ + /* Max size is 20K for high speed */ + mblk_t *intr_data; /* Data for the data phase */ + /* IN: zero-len mblk alloc by client */ + /* OUT: allocated by client */ + usb_opaque_t intr_client_private; /* client specific information */ + uint_t intr_timeout; /* only with ONE TIME POLL, in secs */ + /* If set to zero, defaults to 5 sec */ + usb_req_attrs_t intr_attributes; + + /* Normal callback function, called upon completion. */ + void (*intr_cb)( + usb_pipe_handle_t ph, struct usb_intr_req *req); + + /* Exception callback function, for error handling. */ + void (*intr_exc_cb)( + usb_pipe_handle_t ph, struct usb_intr_req *req); + + /* set by USBA/HCD on completion */ + usb_cr_t intr_completion_reason; /* overall completion status */ + /* See usb_completion_reason(9S) */ + usb_cb_flags_t intr_cb_flags; /* recovery done by callback hndlr */ + /* See usb_callback_flags(9S) */ +.fi +.in -2 + +.sp +.LP +Request attributes define special handling for transfers. The following +attributes are valid for interrupt requests: +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_SHORT_XFER_OK\fR +.ad +.RS 27n +.rt +Accept transfers where less data is received than expected. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_AUTOCLEARING\fR +.ad +.RS 27n +.rt +Have USB framework reset pipe and clear functional stalls automatically on +exception. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_PIPE_RESET\fR +.ad +.RS 27n +.rt +Have USB framework reset pipe automatically on exception. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_ONE_XFER\fR +.ad +.RS 27n +.rt +Perform a single IN transfer. Do not start periodic transfers with this +request. +.RE + +.sp +.LP +Please see \fBusb_request_attributes\fR(9S) for more information. +.sp +.in +2 +.nf +Interrupt transfers/requests are subject to the following +constraints and caveats: + +1) The following table indicates combinations of + usb_pipe_intr_xfer() flags argument and fields + of the usb_intr_req_t request argument (X = don't care): + + "none" as attributes in the table below indicates + neither ONE_XFER nor SHORT_XFER_OK + + flags Type attributes data timeout semantics + ---------------------------------------------------------------- + X IN X !=NULL X illegal + + X IN !ONE_XFER X !=0 illegal + + X IN !ONE_XFER NULL 0 See table note (A) + + no sleep IN ONE_XFER NULL 0 See table note (B) + + no sleep IN ONE_XFER NULL !=0 See table note (C) + + sleep IN ONE_XFER NULL 0 See table note (D) + + sleep IN ONE_XFER NULL !=0 See table note (E) + + X OUT X NULL X illegal + + X OUT ONE_XFER X X illegal + + X OUT SHORT_XFER_OK X X illegal + + no sleep OUT none !=NULL 0 See table note (F) + + no sleep OUT none !=NULL !=0 See table note (G) + + sleep OUT none !=NULL 0 See table note (H) + + sleep OUT none !=NULL !=0 See table note (I) + + Table notes: + + A) Continuous polling, new data is returned in cloned request + structures via continous callbacks, original request is + returned on stop polling. + + B) One time poll, no timeout, callback when data is + received. + + C) One time poll, with timeout, callback when data + is received. + + D) One time poll, no timeout, one callback, unblock + when transfer completes. + + E) One time poll, timeout, one callback, unblock when + transfer completes or timeout occurs. + + F) Transfer until data exhausted, no timeout, callback + when done. + + G) Transfer until data exhausted, timeout, callback + when done. + + H) Transfer until data exhausted, no timeout, unblock + when data is received. + + I) Transfer until data exhausted, timeout, unblock + when data is received. + + + 2) USB_FLAGS_SLEEP indicates here just to wait for + resources, except when ONE_XFER is set, in which case it + also waits for completion before returning. + + 3) Reads (IN): + + a) The client driver does *not* provide a data buffer. + By default, a READ request would mean continuous + polling for data IN. The USBA framework allocates a + new data buffer for each poll. intr_len specifies + the amount of 'periodic data' for each poll. + + b) The USBA framework issues a callback to the client + at the end of a polling interval when there is data to + return. Each callback returns its data in a new request + cloned from the original. Note that the amount of data + read IN is either intr_len or "wMaxPacketSize" in length. + + c) Normally, the HCD keeps polling the interrupt endpoint + forever even if there is no data to be read IN. A + client driver may stop this polling by calling + usb_pipe_stop_intr_polling(9F). + + d) If a client driver chooses to pass USB_ATTRS_ONE_XFER + as 'xfer_attributes' the HCD polls for data until + some data is received. The USBA framework reads in + the data, does a callback, and stops polling for any + more data. In this case, the client + driver need not explicitly call + usb_pipe_stop_intr_polling(). + + e) All requests with USB_ATTRS_ONE_XFER require callbacks + to be specified. + + f) When continuous polling is stopped, the original + request is returned with USB_CR_STOPPED_POLLING. + + g) If the USB_ATTRS_SHORT_XFER_OK attribute is not set + and a short transfer is received while polling, + an error is assumed and polling is stopped. In this + case or the case of other errors, the error must be cleared + and polling restarted by the client driver. Setting the + USB_ATTRS_AUTOCLEARING attribute will clear the error + but not restart polling. (NOTE: Polling can be + restarted from an exception callback corresponding to + an original request. Please see usb_pipe_intr_xfer(9F) + for more information. + + 4) Writes (OUT): + + a) A client driver provides the data buffer, and + data, needed for intr write. + + b) Unlike read (see previous section), there + is no continuous write mode. + + c) The USB_ATTRS_ONE_XFER attribute is illegal. + By default USBA keeps writing intr data until + the provided data buffer has been + written out. The USBA framework does ONE + callback to the client driver. + + d) Queueing is supported. + + The intr_completion_reason indicates the status + of the transfer. See usb_completion_reason(9S) for + usb_cr_t definitions. + + The intr_cb_flags are set prior to calling the + exception callback handler, to summarize recovery actions + taken and errors encountered during + recovery. See usb_callback_flags(9S) for + usb_cb_flags_t definitions. + + --- Callback handling --- + + All usb request types share the same callback + handling. Please see usb_callback_flags(9S) for a + description of use and operation. +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBusb_alloc_request\fR(9F), \fBusb_pipe_ctrl_xfer\fR(9F), +\fBusb_pipe_bulk_xfer\fR(9F), \fBusb_pipe_intr_xfer\fR(9F), +\fBusb_pipe_isoc_xfer\fR(9F), \fBusb_bulk_request\fR(9S), +\fBusb_callback_flags\fR(9S), \fBusb_completion_reason\fR(9S), +\fBusb_ctrl_request\fR(9S), \fBusb_isoc_request\fR(9S), +\fBusb_request_attributes\fR(9S) diff --git a/usr/src/man/man9s/usb_isoc_request.9s b/usr/src/man/man9s/usb_isoc_request.9s new file mode 100644 index 0000000000..195b6feab6 --- /dev/null +++ b/usr/src/man/man9s/usb_isoc_request.9s @@ -0,0 +1,270 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_isoc_request 9S "28 Dec 2006" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_isoc_request \- USB isochronous request structure +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +A request sent through an isochronous pipe is used to transfer large amounts of +packetized data with relative unreliability, but with bounded service periods. +A packet is guaranteed to be tried within a bounded time period, but is not +retried upon failure. Isochronous transfers are supported on both USB 1.1 and +USB 2.0 devices. For further information, see section \fI5.6\fR of the \fIUSB +2.0\fR specification available at \fIwww.usb.org\fR. +.sp +.LP +This section provides information on acceptable combinations of flags and +attributes with additional details. The following fields of the usb_isoc_req_t +are used to format an isochronous request. +.sp +.in +2 +.nf +usb_frame_number_t + isoc_frame_no; /* frame num to start sending req. */ +ushort_t isoc_pkts_count; /* num USB pkts in this request */ +/* + * The sum of all pkt lengths in an isoc request. Recommend to set it to + * zero, so the sum of isoc_pkt_length in the isoc_pkt_descr list will be + * used automatically and no check will be apply to this element. + */ +ushort_t isoc_pkts_length; +ushort_t isoc_error_count;/* num pkts completed w/errs */ +usb_req_attrs_t isoc_attributes;/* request-specific attrs */ +mblk_t *isoc_data; /* data to xfer */ + /* IN or OUT: alloc. by client. */ + /* Size=total of all pkt lengths. */ +usb_opaque_t isoc_client_private; /* for client driver excl use. */ +struct usb_isoc_pkt_descr /* (see below) */ + *isoc_pkt_descr; + +/* + * Normal callback function, called upon completion. + * This function cannot block as it executes in soft interrupt context. + */ +void (*isoc_cb)( + usb_pipe_handle_t ph, struct usb_isoc_req *req); + +/* Exception callback function, for error handling. */ +void (*isoc_exc_cb)( + usb_pipe_handle_t ph, struct usb_isoc_req *req); + +usb_cr_t isoc_completion_reason; /* overall completion status */ + /* set by USBA framework */ + /* See usb_completion_reason(9S) */ +usb_cb_flags_t isoc_cb_flags; /* recovery done by callback hndlr */ + /* set by USBA on exception. */ + /* See usb_callback_flags(9S) */ +.fi +.in -2 + +.sp +.LP +A \fBusb_isoc_pkt_descr_t\fR describes the status of an isochronous packet +transferred within a frame or microframe. The following fields of a +\fBusb_isoc_pkt_descr_t\fR packet descriptor are used within an +\fBusb_isoc_req_t\fR. The \fBisoc_pkt_length\fR is set by the client driver to +the amount of data managed by the packet for input or output. The latter two +fields are set by the \fBUSBA\fR framework to indicate status. Any packets with +an \fBisoc_completion_reason\fR, other than \fBUSB_CR_OK\fR, are reflected in +the \fBisoc_error_count\fR of the \fBusb_isoc_req_t\fR. +.sp +.in +2 +.nf + ushort_t isoc_pkt_length; /* number bytes to transfer */ + ushort_t isoc_pkt_actual_length; /* actual number transferred */ + usb_cr_t isoc_pkt_status; /* completion status */ +.fi +.in -2 + +.sp +.LP +If two multi-frame \fBisoc\fR requests that both specify the +\fBUSB_ATTRS_ISOC_XFER_ASAP\fR attribute are scheduled closely together, the +first frame of the second request is queued to start after the last frame of +the first request. +.sp +.LP +No stalls are seen in isochronous transfer exception callbacks. Because +transfers are not retried upon failure, isochronous transfers continue +regardless of errors. +.sp +.LP +Request attributes define special handling for transfers. The following +attributes are valid for isochronous requests: +.sp +.ne 2 +.mk +.na +\fB\fBUSB_ATTRS_ISOC_START_FRAME\fR\fR +.ad +.RS 30n +.rt +Start transferring at the starting frame number specified in the +\fBisoc_frame_no\fR field of the request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUSB_ATTRS_ISOC_XFER_ASAP\fR\fR +.ad +.RS 30n +.rt +Start transferring as soon as possible. The \fBUSBA\fR framework picks an +immediate frame number to map to the starting frame number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUSB_ATTRS_SHORT_XFER_OK\fR\fR +.ad +.RS 30n +.rt +Accept transfers where less data is received than expected. +.RE + +.sp +.LP +The \fBusb_isoc_req_t\fR contains an array of descriptors that describe +isochronous packets. One isochronous packet is sent per frame or microframe. +Because packets that comprise a transfer are sent across consecutive frames or +microframes, \fBUSB_ATTRS_ONE_XFER\fR is invalid. +.sp +.LP +See \fBusb_request_attributes\fR(9S) for more information. +.sp +.LP +Isochronous transfers/requests are subject to the following constraints and +caveats: +.sp +.in +2 +.nf +1) The following table indicates combinations of usb_pipe_isoc_xfer + flags argument and fields of the usb_isoc_req_t request argument + (X = don't care). (Note that attributes considered in this table + are ONE_XFER, START_FRAME, XFER_ASAP, and SHORT_XFER, and that + some transfer types are characterized by multiple table entries.) + +Flags Type Attributes Data Semantics +--------------------------------------------------------------- +X X X NULL illegal + +X X ONE_XFER X illegal + +X X ISOC_START_FRAME X illegal + & ISOC_XFER_ASAP + +X X !ISOC_START_FRAME X illegal + & !ISOC_XFER_ASAP + +X OUT SHORT_XFER_OK X illegal + +X IN X !=NULL See table note (A) + +X X ISOC_START_FRAME !=NULL See table note (B) + +X X ISOC_XFER_ASAP !=NULL See table note (C) + +Table notes: + + A) continuous polling, new data is returned in + cloned request structures via continous callbacks, + original request is returned on stop polling + + B) invalid if the current_frame number is past + "isoc_frame_no" or "isoc_frame_no" == 0 + + C)"isoc_frame_no" is ignored. The USBA framework + determines which frame to insert and start + the transfer. + +2) USB_FLAGS_SLEEP indicates to wait for resources but + not for completion. + +3) For polled reads: + + A. The USBA framework accepts a request which + specifies the size and number of packets to fill + with data. The packets get filled one packet per + (1 ms) frame/(125 us) microframe. All requests + have an implicit USB_ATTRS_SHORT_XFER_OK attribute + set, since transfers continue in spite of any en- + countered. The amount of data read per packet will + match the isoc_pkt_length field of the packet + descriptor unless a short transfer occurs. The + actual size is returned in the + isoc_pkt_actual_length field of the packet + descriptor. When all packets of the request have + been processed, a normal callback is done to sig- + nal the completion of the original request. + + B. When continuous polling is stopped, the original + request is returned in an exception callback with a + completion reason of USB_CR_STOPPED_POLLING. + (NOTE: Polling can be restarted from an exception + callback corresponding to an original request. + Please see usb_pipe_isoc_xfer(9F) for more information. + + C. Callbacks must be specified. + + The isoc_completion_reason indicates the status of the transfer. See + usb_completion_reason(9s) for usb_cr_t definitions. + + The isoc_cb_flags are set prior to calling the exception + callback handler to summarize recovery actions taken and + errors encountered during recovery. See usb_callback_flags(9s) + for usb_cb_flags_t definitions. + +--- Callback handling --- +All usb request types share the same callback handling. Please see +usb_callback_flags(9s) for a description of use and operation. +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_alloc_request\fR(9F), +\fBusb_get_current_frame_number\fR(9F), +\fBusb_get_max_pkts_per_isoc_request\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F), +\fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_intr_xfer\fR(9F), +\fBusb_pipe_isoc_xfer\fR(9F), \fBusb_bulk_request\fR(9S), +\fBusb_callback_flags\fR(9S), \fBusb_completion_reason\fR(9S), +\fBusb_ctrl_request\fR(9S), \fBusb_intr_request\fR(9S), +\fBusb_request_attributes\fR(9S) diff --git a/usr/src/man/man9s/usb_other_speed_cfg_descr.9s b/usr/src/man/man9s/usb_other_speed_cfg_descr.9s new file mode 100644 index 0000000000..8c28bdbfbe --- /dev/null +++ b/usr/src/man/man9s/usb_other_speed_cfg_descr.9s @@ -0,0 +1,91 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_other_speed_cfg_descr 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_other_speed_cfg_descr \- USB other speed configuration descriptor +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBusb_other_speed_cfg_descr_t\fR configuration descriptor defines how +fields of a high speed device's configuration descriptor change if that device +is run at its other speed. Fields of this descriptor reflect configuration +descriptor field changes if a device's speed is changed from full to high +speed, or from high to full speed. +.sp +.LP +Please refer to Section \fI9.6.4\fR of the \fIUSB 2.0\fR specification. The +\fIUSB 2.0\fR specification is available at \fIwww.usb.org\fR. +.sp +.LP +This descriptor has the following fields: +.sp +.in +2 +.nf +uint8_t bLength Size of this descriptor, + in bytes. + +uint8_t bDescriptorType Set to USB_DESCR_TYPE_OTHER_SPEED_CFG. + +uint16_t wTotalLength Total length of data returned */ + including all descriptors in + the current other-speed + configuration. + +uint8_t bNumInterfaces Number of interfaces in + the selected configuration. + +uint8_t bConfigurationValue ID of the current other-speed + configuration (1-based). + +uint8_t iConfiguration Configuration value. + Valid if > 0. Pass to + usb_get_string_descr(9F) + to retrieve string. + +uint8_t bmAttributes Configuration characteristics + [See usb_cfg_descr(9S).] + +uint8_t bMaxPower Maximum power consumption + in 2mA units. +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_alt_if\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_dev_data\fR(9F), \fBusb_get_string_descr\fR(9F), +\fBusb_parse_data\fR(9F), \fBusb_cfg_descr\fR(9S), \fBusb_ctrl_request\fR(9S), +\fBusb_dev_descr\fR(9S), \fBusb_dev_qlf_descr\fR(9S) diff --git a/usr/src/man/man9s/usb_request_attributes.9s b/usr/src/man/man9s/usb_request_attributes.9s new file mode 100644 index 0000000000..58a140685a --- /dev/null +++ b/usr/src/man/man9s/usb_request_attributes.9s @@ -0,0 +1,214 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_request_attributes 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_request_attributes \- Definition of USB request attributes +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +Request attributes specify how the USBA framework handles request execution. +Request attributes are specified in the request's *_attributes field and belong +to the enumerated type usb_req_attrs_t. +.sp +.LP +Supported request attributes are: +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_SHORT_XFER_OK\fR +.ad +.RS 30n +.rt +Use this attribute when the maximum transfer size is known, but it is +possible for the request to receive a smaller amount of data. This attribute +tells the USBA framework to accept without error transfers which are shorter +than expected. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_PIPE_RESET\fR +.ad +.RS 30n +.rt +Have the USB framework reset the pipe automatically if an error occurs +during the transfer. Do not attempt to clear any stall. The USB_CB_RESET_PIPE +callback flag is passed to the client driver's exception handler to show the +pipe has been reset. Pending requests on pipes which are reset are flushed +unless the pipe is the default pipe. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_AUTOCLEARING\fR +.ad +.RS 30n +.rt +Have the USB framework reset the pipe and clear functional stalls automatically +if an error occurs during the transfer. The callback flags passed to the client +driver's exception handler show the status after the attempt to clear the +stall. +.sp +USB_CB_FUNCTIONAL_STALL is set in the callback flags to indicate that a +functional stall occurred. USB_CB_STALL_CLEARED is also set if the stall is +cleared. The default pipe never shows a functional stall if the +USB_ATTRS_AUTOCLEARING attribute is set. If USB_CB_FUNCTIONAL_STALL is seen +when autoclearing is enabled, the device has a fatal error. +.sp +USB_CB_PROTOCOL_STALL is set without USB_CB_STALL_CLEARED in the callback flags +to indicate that a protocol stall was seen but was not explicitly cleared. +Protocol stalls are cleared automatically when a subsequent command is issued. +.sp +Autoclearing a stalled default pipe is not allowed. The USB_CB_PROTOCOL_STALL +callback flag is set in the callback flags to indicate the default pipe is +stalled. +.sp +Autoclearing is not allowed when the request is USB_REQ_GET_STATUS on the +default pipe. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_ONE_XFER\fR +.ad +.RS 30n +.rt +Applies only to interrupt-IN requests. Without this flag, interrupt-IN requests +start periodic polling of the interrupt pipe. This flag specifies to perform +only a single transfer. Do not start periodic transfers with this request. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_ISOC_START_FRAME\fR +.ad +.RS 30n +.rt +Applies only to isochronous requests and specifies that a request be started at +a given frame number. The starting frame number is provided in the +isoc_frame_no field of the usb_isoc_req_t. Please see +\fBusb_isoc_request\fR(9S) for more information about isochronous requests. +.sp +USB_ATTRS_ISOC_START_FRAME can be used to delay a transfer by a few frames, +allowing transfers to an endpoint to sync up with another source. (For +example, synching up audio endpoints to a video source.) The number of a +suitable starting frame in the near future can be found by adding an offset +number of frames (usually between four and ten) to the current frame number +returned from \fBusb_get_current_frame_number\fR(9F). Note that requests with +starting frames which have passed are rejected. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_ATTRS_ISOC_XFER_ASAP\fR +.ad +.RS 30n +.rt +Applies only to isochronous requests and specifies that a request start as soon +as possible. The host controller driver picks a starting frame number which +immediately follows the last frame of the last queued request. The +isoc_frame_no of the usb_isoc_req_t is ignored. Please see +\fBusb_isoc_request\fR(9S) for more information about isochronous requests. +.RE + +.SH EXAMPLES +.sp +.in +2 +.nf + /* + * Allocate, initialize and issue a synchronous bulk-IN request. + * Allow for short transfers. + */ + + struct buf *bp; + usb_bulk_req_t bulk_req; + mblk_t *mblk; + + bulk_req = usb_alloc_bulk_req(dip, bp->b_bcount, USB_FLAGS_SLEEP); + + bulk_req->bulk_attributes = + USB_ATTRS_AUTOCLEARING | USB_ATTRS_SHORT_XFER_OK; + + if ((rval = usb_pipe_bulk_xfer(pipe, bulk_req, USB_FLAGS_SLEEP)) != + USB_SUCCESS) { + cmn_err (CE_WARN, "%s%d: Error reading bulk data.", + ddi_driver_name(dip), ddi_get_instance(dip)); + } + + mblk = bulk_req->bulk_data; + bcopy(mblk->rptr, buf->b_un.b_addr, mblk->wptr - mblk->rptr); + bp->b_resid = bp->b_count - (mblk->wptr = mblk->rptr); + ... + ... + + ---- + + usb_pipe_handle_t handle; + usb_frame_number_t offset = 10; + usb_isoc_req_t *isoc_req; + + isoc_req = usb_alloc_isoc_req(...); + ... + ... + isoc_req->isoc_frame_no = usb_get_current_frame_number(dip) + offset; + isoc_req->isoc_attributes = USB_ATTRS_ISOC_START_FRAME; + ... + ... + if (usb_pipe_isoc_xfer(handle, isoc_req, 0) != USB_SUCCESS) { + ... + } +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See attributes(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBusb_alloc_request\fR(9F), \fBusb_get_current_frame_number\fR(9F), +\fBusb_pipe_bulk_xfer\fR(9F), \fBusb_pipe_ctrl_xfer\fR(9F), +\fBusb_pipe_intr_xfer\fR(9F), \fBusb_pipe_isoc_xfer\fR(9F), +\fBusb_bulk_request\fR(9S), \fBusb_callback_flags\fR(9S), +\fBusb_ctrl_request\fR(9S), \fBusb_intr_request\fR(9S), +\fBusb_isoc_request\fR(9S), \fBusb_completion_reason\fR(9S) diff --git a/usr/src/man/man9s/usb_string_descr.9s b/usr/src/man/man9s/usb_string_descr.9s new file mode 100644 index 0000000000..30e40f860e --- /dev/null +++ b/usr/src/man/man9s/usb_string_descr.9s @@ -0,0 +1,70 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_string_descr 9S "5 Jan 2004" "SunOS 5.11" "Data Structures for Drivers" +.SH NAME +usb_string_descr \- USB string descriptor +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBusb_string_descr_t\fR string descriptor defines the attributes of a +string, including size and Unicode language ID. Other USB descriptors may have +string descriptor index fields which refer to specific string descriptors +retrieved as part of a device's configuration. +.sp +.LP +Please refer to Section \fI9.6.7\fR of the \fIUSB 2.0\fR specification. The +\fIUSB 2.0\fR specification is available at \fIwww.usb.org\fR. +.sp +.LP +A string descriptor has the following fields: +.sp +.in +2 +.nf +uint8_t bLength Size of this descriptor, + in bytes. + +uint8_t bDescriptorType Set to USB_DESCR_TYPE_STRING. + +uint16_t bString[1]; Variable length Unicode encoded + string. +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_alt_if\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_dev_data\fR(9F), \fBusb_get_string_descr\fR(9F), +\fBusb_parse_data\fR(9F), \fBusb_ctrl_request\fR(9S) |