diff options
Diffstat (limited to 'usr/src/man/man9e')
50 files changed, 9897 insertions, 0 deletions
diff --git a/usr/src/man/man9e/Intro.9e b/usr/src/man/man9e/Intro.9e new file mode 100644 index 0000000000..13a9deeb4a --- /dev/null +++ b/usr/src/man/man9e/Intro.9e @@ -0,0 +1,499 @@ +'\" 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 9E "15 May 2001" "SunOS 5.11" "Driver Entry Points" +.SH NAME +Intro, intro \- overview of device driver interfaces and introduction to driver +entry points +.SH DESCRIPTION +.sp +.LP +This page provides an overview of device driver interfaces and all of the +Section 9 man pages (9E, 9F, 9P, and 9S). This overview is followed by an +introduction to Section 9E, the driver entry-point routines. +.SS "Overview of Device Driver Interfaces" +.sp +.LP +Section 9 provides reference information needed to write device drivers for the +Solaris operating environment. It describes the interfaces provided by the +Device Driver Interface and the Driver-Kernel Interface (DDI/DKI). +.SS "Porting" +.sp +.LP +Software is usually considered portable if it can be adapted to run in a +different environment more cheaply than it can be rewritten. The new +environment may include a different processor, operating system, and even the +language in which the program is written, if a language translator is +available. Likewise the new environment might include multiple processors. More +often, however, software is ported between environments that share an operating +system, processor, and source language. The source code is modified to +accommodate the differences in compilers or processors or releases of the +operating system. +.sp +.LP +In the past, device drivers did not port easily for one or more of the +following reasons: +.RS +4 +.TP +.ie t \(bu +.el o +To enhance functionality, members had been added to kernel data structures +accessed by drivers, or the sizes of existing members had been redefined. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The calling or return syntax of kernel functions had changed. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Driver developers did not use existing kernel functions where available, or +relied on undocumented side effects that were not maintained in the next +release. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Architecture-specific code had been scattered throughout the driver when it +could have been isolated. +.RE +.sp +.LP +Operating systems are periodically reissued to customers as a way to improve +performance, fix bugs, and add new features. This is probably the most common +threat to compatibility encountered by developers responsible for maintaining +software. Another common problem is upgrading hardware. As new hardware is +developed, customers occasionally decide to upgrade to faster, more capable +computers of the same family. Although they may run the same operating system +as those being replaced, architecture-specific code may prevent the software +from porting. +.SS "Scope of Interfaces" +.sp +.LP +Although application programs have all of the porting problems mentioned, +developers attempting to port device drivers have special challenges. Before +describing the DDI/DKI, it is necessary to understand the position of device +drivers in operating systems. +.sp +.LP +Device drivers are kernel modules that control data transferred to and received +from peripheral devices but are developed independently from the rest of the +kernel. If the goal of achieving complete freedom in modifying the kernel is to +be reconciled with the goal of binary compatibility with existing drivers, the +interaction between drivers and the kernel must be rigorously regulated. This +driver/kernel service interface is the most important of the three +distinguishable interfaces for a driver, summarized as follows: +.RS +4 +.TP +.ie t \(bu +.el o +Driver-Kernel. I/O System calls result in calls to driver entry point routines. +These make up the kernel-to-driver part of the service interface, described in +Section 9E. Drivers may call any of the functions described in Section 9F. +These are the driver-to-kernel part of the interface. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Driver-Hardware. All drivers (except software drivers) must include code for +interrupt handling, and may also perform direct memory access (DMA). These and +other hardware-specific interactions make up the driver/hardware interface. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Driver-Boot/Configuration Software. The interaction between the driver and the +boot and configuration software is the third interface affecting drivers. +.RE +.SS "Scope of the DDI/DKI" +.sp +.LP +The primary goal of the DDI/DKI is to facilitate both source and binary +portability across successive releases of the operating systems on a particular +machine. In addition, it promotes source portability across implementations of +UNIX on different machines, and applies only to implementations based on System +V Release 4. The DDI/DKI consists of several sections: +.RS +4 +.TP +.ie t \(bu +.el o +DDI/DKI Architecture Independent - These interfaces are supported on all +implementations of System V Release 4. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +DKI-only - These interfaces are part of System V Release 4, and may not be +supported in future releases of System V. There are only two interfaces in this +class, \fBsegmap\fR(9E) and \fBhat_getkpfnum\fR(9F) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Solaris DDI - These interfaces specific to Solaris. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Solaris SPARC specific DDI - These interfaces are specific to the SPARC +processor, and may not be available on other processors supported by Solaris. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Solaris x86 specific DDI - These interfaces are specific to the x86 processor, +and may not be available on other processors supported by Solaris. +.RE +.sp +.LP +To achieve the goal of source and binary compatibility, the functions, +routines, and structures specified in the DDI/DKI must be used according to +these rules. +.RS +4 +.TP +.ie t \(bu +.el o +Drivers cannot access system state structures (for example, \fBu\fR and +\fBsysinfo\fR) directly. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +For structures external to the driver that may be accessed directly, only the +utility functions provided in Section 9F should be used. More generally, these +functions should be used wherever possible. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The headers \fB<sys/ddi.h>\fR and \fB<sys/sunddi.h>\fR must be the last header +files included by the driver. +.RE +.SS "Audience" +.sp +.LP +Section 9 is for software engineers responsible for creating, modifying, or +maintaining drivers that run on this operating system and beyond. It assumes +that the reader is familiar with system internals and the C programming +language. +.SS "PCMCIA Standard" +.sp +.LP +The \fIPC\fR \fICard\fR \fI95\fR \fIStandard\fR is listed under the \fBSEE\fR +\fBALSO\fR heading in some Section 9 reference pages. This refers to +documentation published by the Personal Computer Memory Card International +Association (PCMCIA) and the Japan Electronic Industry Development Association +(JEIDA). +.SS "How to Use Section 9" +.sp +.LP +Section 9 is divided into the following subsections: +.sp +.ne 2 +.mk +.na +\fB\fB9E\fR \fR +.ad +.RS 7n +.rt +Driver Entry Points - contains reference pages for all driver entry point +routines. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB9F\fR \fR +.ad +.RS 7n +.rt +Kernel Functions - contains reference pages for all driver support routines. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB9P\fR \fR +.ad +.RS 7n +.rt +Driver Properties - contains reference pages for driver properties. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB9S\fR \fR +.ad +.RS 7n +.rt +Data Structures - contains reference pages for driver-related structures. +.RE + +.SS "Compatibility Note" +.sp +.LP +Sun Microsystem's implementation of the DDI/DKI was designed to provide binary +compatibility for third-party device drivers across currently supported +hardware platforms across minor releases of the operating system. However, +unforeseen technical issues may force changes to the binary interface of the +DDI/DKI. We cannot therefore promise or in any way assure that +DDI/DKI-compliant device drivers will continue to operate correctly on future +releases. +.SS "Introduction to Section 9E" +.sp +.LP +Section 9E describes the entry-point routines a developer can include in a +device driver. These are called entry-point because they provide the calling +and return syntax from the kernel into the driver. Entry-points are called, for +instance, in response to system calls, when the driver is loaded, or in +response to \fBSTREAMS\fR events. +.sp +.LP +Kernel functions usable by the driver are described in section 9F. +.sp +.LP +In this section, reference pages contain the following headings: +.RS +4 +.TP +.ie t \(bu +.el o +\fBNAME\fR describes the routine's purpose. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBSYNOPSIS\fR summarizes the routine's calling and return syntax. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBINTERFACE LEVEL\fR describes any architecture dependencies. It also +indicates whether the use of the entry point is required, optional, or +discouraged. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBARGUMENTS\fR describes each of the routine's arguments. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBDESCRIPTION\fR provides general information about the routine. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBRETURN VALUES\fR describes each of the routine's return values. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBSEE ALSO\fR gives sources for further information. +.RE +.SS "Overview of Driver Entry-Point Routines and Naming Conventions" +.sp +.LP +By convention, a prefix string is added to the driver routine names. For a +driver with the prefix \fIprefix\fR, the driver code may contain routines named +\fIprefix\fRopen, \fIprefix\fRclose, \fIprefix\fRread, \fIprefix\fRwrite, and +so forth. All global variables associated with the driver should also use the +same prefix. +.sp +.LP +All routines and data should be declared as \fBstatic\fR. +.sp +.LP +Every driver MUST include <\fBsys/ddi.h\fR> and <\fBsys/sunddi.h\fR>, in that +order, and after all other include files. +.sp +.LP +The following table summarizes the STREAMS driver entry points described in +this section. +.sp + +.sp +.TS +tab(); +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBRoutine\fR\fBType\fR +_ +\fBput\fRDDI/DKI +\fBsrv\fRDDI/DKI +.TE + +.sp +.LP +The following table summarizes the driver entry points described in this +section. +.sp + +.sp +.TS +tab(); +cw(2.18i) cw(3.32i) +lw(2.18i) lw(3.32i) +. +\fBRoutine\fR\fBType \fR +_ +\fB_fini\fRSolaris DDI +\fB_info\fRSolaris DDI +\fB_init\fRSolaris DDI +\fBaread\fRSolaris DDI +\fBattach\fRSolaris DDI +\fBawrite\fRSolaris DDI +\fBchpoll\fRDDI/DKI +\fBclose\fRDDI/DKI +\fBdetach\fRSolaris DDI +\fBdevmap\fRSolaris DDI +\fBdevmap_access\fRSolaris DDI +\fBdevmap_contextmgt\fRSolaris DDI +\fBdevmap_dup\fRSolaris DDI +\fBdevmap_map\fRSolaris DDI +\fBdevmap_unmap\fRSolaris DDI +\fBdump\fRSolaris DDI +\fBgetinfo\fRSolaris DDI +\fBidentify\fRSolaris DDI +\fBioctl\fRDDI/DKI +\fBks_update\fRSolaris DDI +\fBmapdev_access\fRSolaris DDI +\fBmapdev_dup\fRSolaris DDI +\fBmapdev_free\fRSolaris DDI +\fBmmap\fRDKI only +\fBopen\fRDDI/DKI +\fBpower\fRSolaris DDI +\fBprint\fRDDI/DKI +\fBprobe\fRSolaris DDI +\fBprop_op\fRSolaris DDI +\fBread\fRDDI/DKI +\fBsegmap\fRDKI only +\fBstrategy\fRDDI/DKI +\fBtran_abort\fRSolaris DDI +\fBtran_destroy_pkt\fRSolaris DDI +\fBtran_dmafree\fRSolaris DDI +\fBtran_getcap\fRSolaris DDI +\fBtran_init_pkt\fRSolaris DDI +\fBtran_reset\fRSolaris DDI +\fBtran_reset_notify\fRSolaris DDI +\fBtran_setcap\fRSolaris DDI +\fBtran_start\fRSolaris DDI +\fBtran_sync_pkt\fRSolaris DDI +\fBtran_tgt_free\fRSolaris DDI +\fBtran_tgt_init\fRSolaris DDI +\fBtran_tgt_probe\fRSolaris DDI +\fBwrite\fRDDI/DKI +.TE + +.sp +.LP +The following table lists the error codes returned by a driver routine when it +encounters an error. The error values are listed in alphabetic order and are +defined in \fBsys/errno.h\fR. In the driver \fBopen\fR(9E), \fBclose\fR(9E), +\fBioctl\fR(9E), \fBread\fR(9E), and \fBwrite\fR(9E) routines, errors are +passed back to the user by calling \fBbioerror\fR(9F) to set \fBb_flags\fR to +the proper error code. In the driver \fBstrategy\fR(9E) routine, errors are +passed back to the user by setting the \fBb_error\fR member of the +\fBbuf\fR(9S) structure to the error code. For \fBSTREAMS\fR \fBioctl\fR +routines, errors should be sent upstream in an \fBM_IOCNAK\fR message. For +\fBSTREAMS\fR \fBread()\fR and \fBwrite()\fR routines, errors should be sent +upstream in an \fBM_ERROR\fR message. The driver \fBprint\fR routine should not +return an error code because the function that it calls, \fBcmn_err\fR(9F), is +declared as \fBvoid\fR (no error is returned). +.sp + +.sp +.TS +tab(); +cw(1.69i) cw(3.81i) +lw(1.69i) lw(3.81i) +. +Error ValueError Description +_ +EAGAINT{ +Kernel resources, such as the buf structure or cache memory, are not available at this time (device may be busy, or the system resource is not available). This is used in open, ioctl, read, write, and strategy. +T} +_ +EFAULTT{ +An invalid address has been passed as an argument; memory addressing error. This is used in open, close, ioctl, read, write, and strategy. +T} +_ +EINTRT{ +Sleep interrupted by signal. This is used in open, close, ioctl, read, write, and strategy. +T} +_ +EINVALT{ +An invalid argument was passed to the routine. This is used in open, ioctl, read, write, and strategy. +T} +_ +EIOT{ +A device error occurred; an error condition was detected in a device status register (the I/O request was valid, but an error occurred on the device). This is used in open, close, ioctl, read, write, and strategy. +T} +_ +ENXIOT{ +An attempt was made to access a device or subdevice that does not exist (one that is not configured); an attempt was made to perform an invalid I/O operation; an incorrect minor number was specified. This is used in open, close, ioctl, read, write, and strategy. +T} +_ +EPERMT{ +A process attempting an operation did not have required permission. This is used in open, ioctl, read, write, and strategy. +T} +_ +EROFST{ +An attempt was made to open for writing a read-only device. This is used in open. +T} +.TE + +.sp +.LP +The table below cross references error values to the driver routines from which +the error values can be returned. +.sp + +.sp +.TS +tab() box; +cw(1.08i) |cw(1.11i) |cw(1.12i) |cw(2.18i) +lw(1.08i) |lw(1.11i) |lw(1.12i) |lw(2.18i) +. +opencloseioctlread, write and strategy +_ +EAGAINEFAULTEAGAINEAGAIN +EFAULTEINTREFAULTEFAULT +EINTREIOEINTREINTR +EINVALENXIOEINVALEINVAL +EIOEIOEIO +ENXIOENXIOENXIO +EPERMEPERM +EROFS +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(9F), \fBIntro\fR(9S) diff --git a/usr/src/man/man9e/Makefile b/usr/src/man/man9e/Makefile new file mode 100644 index 0000000000..d22c318716 --- /dev/null +++ b/usr/src/man/man9e/Makefile @@ -0,0 +1,122 @@ +# +# 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 = 9e + +MANFILES = Intro.9e \ + _fini.9e \ + aread.9e \ + attach.9e \ + awrite.9e \ + chpoll.9e \ + close.9e \ + csx_event_handler.9e \ + detach.9e \ + devmap.9e \ + devmap_access.9e \ + devmap_contextmgt.9e \ + devmap_dup.9e \ + devmap_map.9e \ + devmap_unmap.9e \ + dump.9e \ + getinfo.9e \ + gld.9e \ + identify.9e \ + ioctl.9e \ + ks_snapshot.9e \ + ks_update.9e \ + mmap.9e \ + open.9e \ + power.9e \ + print.9e \ + probe.9e \ + prop_op.9e \ + put.9e \ + quiesce.9e \ + read.9e \ + segmap.9e \ + srv.9e \ + strategy.9e \ + tran_abort.9e \ + tran_bus_reset.9e \ + tran_dmafree.9e \ + tran_getcap.9e \ + tran_init_pkt.9e \ + tran_quiesce.9e \ + tran_reset.9e \ + tran_reset_notify.9e \ + tran_setup_pkt.9e \ + tran_start.9e \ + tran_sync_pkt.9e \ + tran_tgt_free.9e \ + tran_tgt_init.9e \ + tran_tgt_probe.9e \ + write.9e + +MANSOFILES = _info.9e \ + _init.9e \ + gldm_get_stats.9e \ + gldm_intr.9e \ + gldm_ioctl.9e \ + gldm_reset.9e \ + gldm_send.9e \ + gldm_set_mac_addr.9e \ + gldm_set_multicast.9e \ + gldm_set_promiscuous.9e \ + gldm_start.9e \ + gldm_stop.9e \ + intro.9e \ + tran_destroy_pkt.9e \ + tran_pkt_constructor.9e \ + tran_pkt_destructor.9e \ + tran_setcap.9e \ + tran_teardown_pkt.9e \ + tran_unquiesce.9e + +MANFILES += $(MANSOFILES) + +intro.9e := SOSRC = man9e/Intro.9e + +_info.9e := SOSRC = man9e/_fini.9e +_init.9e := SOSRC = man9e/_fini.9e + +gldm_get_stats.9e := SOSRC = man9e/gld.9e +gldm_intr.9e := SOSRC = man9e/gld.9e +gldm_ioctl.9e := SOSRC = man9e/gld.9e +gldm_reset.9e := SOSRC = man9e/gld.9e +gldm_send.9e := SOSRC = man9e/gld.9e +gldm_set_mac_addr.9e := SOSRC = man9e/gld.9e +gldm_set_multicast.9e := SOSRC = man9e/gld.9e +gldm_set_promiscuous.9e := SOSRC = man9e/gld.9e +gldm_start.9e := SOSRC = man9e/gld.9e +gldm_stop.9e := SOSRC = man9e/gld.9e + +tran_setcap.9e := SOSRC = man9e/tran_getcap.9e + +tran_destroy_pkt.9e := SOSRC = man9e/tran_init_pkt.9e + +tran_unquiesce.9e := SOSRC = man9e/tran_quiesce.9e + +tran_pkt_constructor.9e := SOSRC = man9e/tran_setup_pkt.9e +tran_pkt_destructor.9e := SOSRC = man9e/tran_setup_pkt.9e +tran_teardown_pkt.9e := SOSRC = man9e/tran_setup_pkt.9e + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) + + diff --git a/usr/src/man/man9e/_fini.9e b/usr/src/man/man9e/_fini.9e new file mode 100644 index 0000000000..b9677f09d7 --- /dev/null +++ b/usr/src/man/man9e/_fini.9e @@ -0,0 +1,185 @@ +'\" 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 _fini 9E "22 Jan 2002" "SunOS 5.11" "Driver Entry Points" +.SH NAME +_fini, _info, _init \- loadable module configuration entry points +.SH SYNOPSIS +.LP +.nf +#include <sys/modctl.h> + + + +\fBint\fR \fB_fini\fR(void) +.fi + +.LP +.nf +\fBint\fR \fB_info\fR(\fBstruct modinfo *\fR\fImodinfop\fR); +.fi + +.LP +.nf +\fBint\fR \fB_init\fR(void) +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). These entry points are required. You must +write them. +.SH PARAMETERS +.SS "_info(\|)" +.sp +.ne 2 +.mk +.na +\fB\fImodinfop\fR \fR +.ad +.RS 13n +.rt +A pointer to an opaque \fBmodinfo\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fB_init()\fR initializes a loadable module. It is called before any other +routine in a loadable module. \fB_init()\fR returns the value returned by +\fBmod_install\fR(9F). The module may optionally perform some other work before +the \fBmod_install\fR(9F) call is performed. If the module has done some setup +before the \fBmod_install\fR(9F) function is called, then it should be prepared +to undo that setup if \fBmod_install\fR(9F) returns an error. +.sp +.LP +\fB_info()\fR returns information about a loadable module. \fB_info()\fR +returns the value returned by \fBmod_info\fR(9F). +.sp +.LP +\fB_fini()\fR prepares a loadable module for unloading. It is called when the +system wants to unload a module. If the module determines that it can be +unloaded, then \fB_fini()\fR returns the value returned by +\fBmod_remove\fR(9F). Upon successful return from \fB_fini()\fR no other +routine in the module will be called before \fB_init()\fR is called. +.SH RETURN VALUES +.sp +.LP +\fB_init()\fR should return the appropriate error number if there is an error, +otherwise it should return the return value from \fBmod_install\fR(9F). +.sp +.LP +\fB_info()\fR should return the return value from \fBmod_info\fR(9F) +.sp +.LP +\fB_fini()\fR should return the return value from \fBmod_remove\fR(9F). +\fB_fini()\fR is permitted to return \fBEBUSY\fR prior to calling +\fBmod_remove\fR(9F) if the driver should not be unloaded. Driver global +resources, such as mutexes and calls to \fBddi_soft_state_fini\fR(9F), should +only be destroyed in \fB_fini()\fR after \fBmod_remove()\fR returns +successfully. +.SH EXAMPLES +.LP +\fBExample 1 \fRInitializing and Freeing a Mutex +.sp +.LP +The following example demonstrates how to initialize and free a +\fBmutex\fR(9F). + +.sp +.in +2 +.nf +#include <sys/modctl.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> +static struct dev_ops drv_ops; +/* + * Module linkage information for the kernel. + */ +static struct modldrv modldrv = { + &mod_driverops, /* Type of module. This one is a driver */ + "Sample Driver", + &drv_ops /* driver ops */ +}; + +static struct modlinkage modlinkage = { + MODREV_1, + &modldrv, + NULL +}; + + +/* + * Global driver mutex + */ +static kmutex_t xx_global_mutex; + + +int +_init(void) +{ + int i; + + /* + * Initialize global mutex before mod_install'ing driver. + * If mod_install() fails, must clean up mutex initialization + */ + mutex_init(&xx_global_mutex, NULL, + MUTEX_DRIVER, (void *)NULL); + + if ((i = mod_install(&modlinkage)) != 0) { + mutex_destroy(&xx_global_mutex); + } + + return (i); +} + +int +_info(struct modinfo *modinfop) +{ + return (mod_info(&modlinkage, modinfop)); +} + + +int +_fini(void) +{ + int i; + + /* + * If mod_remove() is successful, we destroy our global mutex + */ + if ((i = mod_remove(&modlinkage)) == 0) { + mutex_destroy(&xx_global_mutex); + } + return (i); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBadd_drv\fR(1M), \fBmod_info\fR(9F), \fBmod_install\fR(9F), +\fBmod_remove\fR(9F), \fBmutex\fR(9F), \fBmodldrv\fR(9S), \fBmodlinkage\fR(9S), +\fBmodlstrmod\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +Do not change the structures referred to by the \fBmodlinkage\fR structure +after the call to \fBmod_install()\fR, as the system may copy or change them. +.SH NOTES +.sp +.LP +Even though the identifiers \fB_fini()\fR, \fB_info()\fR, and \fB_init()\fR +appear to be declared as globals, their scope is restricted by the kernel to +the module that they are defined in. +.SH BUGS +.sp +.LP +On some implementations \fB_info()\fR may be called before \fB_init()\fR. diff --git a/usr/src/man/man9e/aread.9e b/usr/src/man/man9e/aread.9e new file mode 100644 index 0000000000..9fde07cc96 --- /dev/null +++ b/usr/src/man/man9e/aread.9e @@ -0,0 +1,126 @@ +'\" te +.\" Copyright (c) 2008, 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 aread 9E "28 Mar 1997" "SunOS 5.11" "Driver Entry Points" +.SH NAME +aread \- asynchronous read from a device +.SH SYNOPSIS +.LP +.nf +#include <sys/uio.h> +#include <sys/aio_req.h> +#include <sys/cred.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> +int\fIprefix\fR + +\fB\fR\fBaread\fR(\fBdev_t\fR \fIdev\fR, \fBstruct aio_req *\fR\fIaio_reqp\fR, \fBcred_t *\fR\fIcred_p\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRspecific (Solaris DDI). This entry point is \fIoptional\fR. +Drivers that do not support an \fBaread()\fR entry point should use +\fBnodev\fR(9F) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR \fR +.ad +.RS 13n +.rt +Device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaio_reqp\fR \fR +.ad +.RS 13n +.rt +Pointer to the \fBaio_req\fR(9S) structure that describes where the data is to +be stored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcred_p\fR \fR +.ad +.RS 13n +.rt +Pointer to the credential structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The driver's \fBaread()\fR routine is called to perform an asynchronous read. +\fBgetminor\fR(9F) can be used to access the minor number component of the +\fIdev\fR argument. \fBaread()\fR may use the credential structure pointed to +by \fIcred_p\fR to check for superuser access by calling \fBdrv_priv\fR(9F). +The \fBaread()\fR routine may also examine the \fBuio\fR(9S) structure through +the \fBaio_req\fR structure pointer, \fIaio_reqp\fR. \fBaread()\fR must call +\fBaphysio\fR(9F) with the \fBaio_req\fR pointer and a pointer to the driver's +\fBstrategy\fR(9E) routine. +.sp +.LP +No fields of the \fBuio\fR(9S) structure pointed to by \fBaio_req\fR, other +than \fBuio_offset\fR or \fBuio_loffset\fR, may be modified for non-seekable +devices. +.SH RETURN VALUES +.sp +.LP +The \fBaread()\fR routine should return \fB0\fR for success, or the appropriate +error number. +.SH CONTEXT +.sp +.LP +This function is called from user context only. +.SH EXAMPLES +.LP +\fBExample 1 \fRThe following is an example of an \fBaread()\fR routine: +.sp +.in +2 +.nf +static int +xxaread(dev_t dev, struct aio_req *aio, cred_t *cred_p) +{ + int instance; + struct xxstate *xsp; + instance = getminor(dev); + xsp = ddi_get_soft_state(statep, instance); + /*Verify soft state structure has been allocated */ + if (xsp == NULL) + return (ENXIO); + return (aphysio(xxstrategy, anocancel, + dev, B_READ, xxminphys, aio)); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBread\fR(2), \fBaioread\fR(3C), \fBawrite\fR(9E), \fBread\fR(9E), +\fBstrategy\fR(9E), \fBwrite\fR(9E), \fBanocancel\fR(9F), \fBaphysio\fR(9F), +\fBddi_get_soft_state\fR(9F), \fBdrv_priv\fR(9F), \fBgetminor\fR(9F), +\fBminphys\fR(9F), \fBnodev\fR(9F), \fBaio_req\fR(9S), \fBcb_ops\fR(9S), +\fBuio\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH BUGS +.sp +.LP +There is no way other than calling \fBaphysio\fR(9F) to accomplish an +asynchronous read. diff --git a/usr/src/man/man9e/attach.9e b/usr/src/man/man9e/attach.9e new file mode 100644 index 0000000000..b98b9d0379 --- /dev/null +++ b/usr/src/man/man9e/attach.9e @@ -0,0 +1,180 @@ +'\" 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 attach 9E "7 Jan 2004" "SunOS 5.11" "Driver Entry Points" +.SH NAME +attach \- Attach a device to the system, or resume it +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBattach\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_attach_cmd_t\fR \fIcmd\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 7n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmd\fR\fR +.ad +.RS 7n +.rt +Attach type. Possible values are \fBDDI_ATTACH\fR and \fBDDI_RESUME\fR. Other +values are reserved. The driver must return \fBDDI_FAILURE\fR if reserved +values are passed to it. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBattach\fR(9E) function is the device-specific initialization entry +point. This entry point is \fBrequired\fR and must be written. +.SS "DDI_ATTACH" +.sp +.LP +The \fBDDI_ATTACH\fR command must be provided in the \fBattach\fR(9E) entry +point. \fBDDI_ATTACH\fR is used to initialize a given device instance. When +\fBattach\fR(9E) is called with \fIcmd\fR set to \fBDDI_ATTACH\fR, all normal +kernel services (such as \fBkmem_alloc\fR(9F)) are available for use by the +driver. Device interrupts are not blocked when attaching a device to the +system. +.sp +.LP +The \fBattach\fR(9E) function is called once for each instance of the device on +the system with \fIcmd\fR set to \fBDDI_ATTACH\fR. Until \fBattach\fR(9E) +succeeds, the only driver entry point which may be called is \fBgetinfo\fR(9E). +See the \fIWriting Device Drivers\fR for more information. The instance number +may be obtained using \fBddi_get_instance\fR(9F). +.sp +.LP +At attach time, all components of a power-manageable device are assumed to be +at unknown levels. Before using the device, the driver needs to bring the +required component(s) to a known power level. The \fBpm_raise_power\fR(9F) +function can be used to set the power level of a component. This function must +not be called before data structures referenced in \fBpower\fR(9E) have been +initialized. +.SS "DDI_RESUME" +.sp +.LP +The \fBattach()\fR function may be called with \fIcmd\fR set to +\fBDDI_RESUME\fR after \fBdetach\fR(9E) has been successfully called with +\fIcmd\fR set to \fBDDI_SUSPEND\fR. +.sp +.LP +When called with \fIcmd\fR set to \fBDDI_RESUME\fR, \fBattach()\fR must restore +the hardware state of a device (power may have been removed from the device), +allow pending requests to continue, and service new requests. In this case, the +driver must not make any assumptions about the state of the hardware, but must +restore the state of the device except for the power level of components. +.sp +.LP +If the device driver uses the automatic device Power Management interfaces +(driver exports the \fBpm-components\fR(9P) property), the Power Management +framework sets its notion of the power level of each component of a device to +\fBunknown\fR while processing a \fBDDI_RESUME\fR command. +.sp +.LP +The driver can deal with components during \fBDDI_RESUME\fR in one of the +following ways: +.RS +4 +.TP +1. +If the driver can determine the power level of the component without having +to power it up (for example, by calling \fBddi_peek\fR(9F) or some other +device-specific method) then it should notify the power level to the framework +by calling \fBpm_power_has_changed\fR(9F). +.RE +.RS +4 +.TP +2. +The driver must also set its own notion of the power level of the component +to \fBunknown\fR. The system will consider the component idle or busy based on +the most recent call to \fBpm_idle_component\fR(9F) or +\fBpm_busy_component\fR(9F) for that component. If the component is idle for +sufficient time, the framework will call into the driver's \fBpower\fR(9E) +entry point to turn the component off. If the driver needs to access the +device, then it must call \fBpm_raise_power\fR(9F) to bring the component up to +the level needed for the device access to succeed. The driver must honor any +request to set the power level of the component, since it cannot make any +assumption about what power level the component has (or it should have called +\fBpm_power_has_changed\fR(9F) as outlined above). As a special case of this, +the driver may bring the component to a known state because it wants to perform +an operation on the device as part of its \fBDDI_RESUME\fR processing (such as +loading firmware so that it can detect hot-plug events). +.RE +.SH RETURN VALUES +.sp +.LP +The \fBattach()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Successful completion +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Operation failed +.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 +\fBcpr\fR(7), \fBpm\fR(7D), \fBpm\fR(9P), \fBpm-components\fR(9P), +\fBdetach\fR(9E), \fBgetinfo\fR(9E), \fBidentify\fR(9E), \fBopen\fR(9E), +\fBpower\fR(9E), \fBprobe\fR(9E), \fBddi_add_intr\fR(9F), +\fBddi_create_minor_node\fR(9F), \fBddi_get_instance\fR(9F), +\fBddi_map_regs\fR(9F), \fBkmem_alloc\fR(9F), \fBpm_raise_power\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/awrite.9e b/usr/src/man/man9e/awrite.9e new file mode 100644 index 0000000000..93da0bfd46 --- /dev/null +++ b/usr/src/man/man9e/awrite.9e @@ -0,0 +1,130 @@ +'\" te +.\" Copyright (c) 2008, 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 awrite 9E "28 Mar 1997" "SunOS 5.11" "Driver Entry Points" +.SH NAME +awrite \- asynchronous write to a device +.SH SYNOPSIS +.LP +.nf +#include <sys/uio.h> +#include <sys/aio_req.h> +#include <sys/cred.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBintprefix\fR\fBawrite\fR(\fBdev_t\fR \fIdev\fR, \fBstruct aio_req *\fR\fIaio_reqp\fR, + \fBcred_t *\fR\fIcred_p\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRspecific (Solaris DDI). This entry point is optional. Drivers +that do not support an \fBawrite()\fR entry point should use \fBnodev\fR(9F) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 12n +.rt +Device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaio_reqp\fR\fR +.ad +.RS 12n +.rt +Pointer to the \fBaio_req\fR(9S) structure that describes where the data is +stored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcred_p\fR\fR +.ad +.RS 12n +.rt +Pointer to the credential structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The driver's \fBawrite()\fR routine is called to perform an asynchronous write. +\fBgetminor\fR(9F) can be used to access the minor number component of the +\fIdev\fR argument. \fBawrite()\fR may use the credential structure pointed to +by \fIcred_p\fR to check for superuser access by calling \fBdrv_priv\fR(9F). +The \fBawrite()\fR routine may also examine the \fBuio\fR(9S) structure +through the \fBaio_req\fR structure pointer, \fBaio_reqp\fR. \fBawrite()\fR +must call \fBaphysio\fR(9F) with the \fBaio_req\fR pointer and a pointer to the +driver's \fBstrategy\fR(9E) routine. +.sp +.LP +No fields of the \fBuio\fR(9S) structure pointed to by \fBaio_req\fR, other +than \fBuio_offset\fR or \fBuio_loffset\fR, may be modified for non-seekable +devices. +.SH RETURN VALUES +.sp +.LP +The \fBawrite()\fR routine should return \fB0\fR for success, or the +appropriate error number. +.SH CONTEXT +.sp +.LP +This function is called from user context only. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing the \fBawrite()\fR routine: +.sp +.LP +The following is an example of an \fBawrite()\fR routine: + +.sp +.in +2 +.nf +static int +xxawrite(dev_t dev, struct aio_req *aio, cred_t *cred_p) +{ + int instance; + struct xxstate *xsp; + + instance = getminor(dev); + xsp = ddi_get_soft_state(statep, instance); + /*Verify soft state structure has been allocated */ + if (xsp == NULL) + return (ENXIO); + return (aphysio(xxstrategy, anocancel, dev, B_WRITE, \e + xxminphys, aio)); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBwrite\fR(2), \fBaiowrite\fR(3C), \fBaread\fR(9E), \fBread\fR(9E), +\fBstrategy\fR(9E), \fBwrite\fR(9E), \fBanocancel\fR(9F), \fBaphysio\fR(9F), +\fBddi_get_soft_state\fR(9F), \fBdrv_priv\fR(9F), \fBgetminor\fR(9F), +\fBminphys\fR(9F), \fBnodev\fR(9F), \fBaio_req\fR(9S), \fBcb_ops\fR(9S), +\fBuio\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH BUGS +.sp +.LP +There is no way other than calling \fBaphysio\fR(9F) to accomplish an +asynchronous write. diff --git a/usr/src/man/man9e/chpoll.9e b/usr/src/man/man9e/chpoll.9e new file mode 100644 index 0000000000..1dbf19d5a7 --- /dev/null +++ b/usr/src/man/man9e/chpoll.9e @@ -0,0 +1,244 @@ +'\" te +.\" Copyright (c) 2008, 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 chpoll 9E "7 May 2008" "SunOS 5.11" "Driver Entry Points" +.SH NAME +chpoll \- poll entry point for a non-STREAMS character driver +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/poll.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBchpoll\fR(\fBdev_t\fR \fIdev\fR, \fBshort\fR \fIevents\fR, \fBint\fR \fIanyyet\fR, + \fBshort *\fR\fIreventsp\fR, \fBstruct pollhead **\fR\fIphpp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This entry point is optional. Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 12n +.rt +The device number for the device to be polled. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevents\fR\fR +.ad +.RS 12n +.rt +The events that may occur. Valid events are: +.sp +.ne 2 +.mk +.na +\fB\fBPOLLIN\fR\fR +.ad +.RS 14n +.rt +Data other than high priority data may be read without blocking. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOLLOUT\fR\fR +.ad +.RS 14n +.rt +Normal data may be written without blocking. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOLLPRI\fR\fR +.ad +.RS 14n +.rt +High priority data may be received without blocking. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOLLHUP\fR\fR +.ad +.RS 14n +.rt +A device hangup has occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOLLERR\fR\fR +.ad +.RS 14n +.rt +An error has occurred on the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOLLRDNORM\fR\fR +.ad +.RS 14n +.rt +Normal data (priority band = 0) may be read without blocking. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOLLRDBAND\fR\fR +.ad +.RS 14n +.rt +Data from a non-zero priority band may be read without blocking +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOLLWRNORM\fR\fR +.ad +.RS 14n +.rt +The same as \fBPOLLOUT\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPOLLWRBAND\fR\fR +.ad +.RS 14n +.rt +Priority data (priority band > 0) may be written. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIanyyet\fR\fR +.ad +.RS 12n +.rt +A flag that is non-zero if any other file descriptors in the \fBpollfd\fR array +have events pending. The \fBpoll\fR(2) system call takes a pointer to an array +of \fBpollfd\fR structures as one of its arguments. See the \fBpoll\fR(2) +reference page for more details. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreventsp\fR\fR +.ad +.RS 12n +.rt +A pointer to a bitmask of the returned events satisfied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIphpp\fR\fR +.ad +.RS 12n +.rt +A pointer to a pointer to a \fBpollhead\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBchpoll()\fR entry point routine is used by non-STREAMS character device +drivers that wish to support polling. The driver must implement the polling +discipline itself. The following rules must be followed when implementing the +polling discipline: +.RS +4 +.TP +1. +Implement the following algorithm when the \fBchpoll()\fR entry point is +called: +.sp +.in +2 +.nf +if (events_are_satisfied_now) { + *reventsp = satisfied_events & events; +} else { + *reventsp = 0; + if (!anyyet) + *phpp = &my_local_pollhead_structure; +} +return (0); +.fi +.in -2 + +.RE +.RS +4 +.TP +2. +Allocate an instance of the \fBpollhead\fR structure. This instance may be +tied to the per-minor data structure defined by the driver. The \fBpollhead\fR +structure should be treated as a "black box" by the driver. Initialize the +\fBpollhead\fR structure by filling it with zeroes. The size of this structure +is guaranteed to remain the same across releases. +.RE +.RS +4 +.TP +3. +Call the \fBpollwakeup()\fR function with \fBevents\fR listed above whenever +pollable \fBevents\fR which the driver should monitor occur. This function can +be called with multiple events at one time. The \fBpollwakup()\fR can be called +regardless of whether or not the \fBchpoll()\fR entry is called; it should be +called every time the driver detects the pollable event. The driver must not +hold any mutex across the call to \fBpollwakeup\fR(9F) that is acquired in its +\fBchpoll()\fR entry point, or a deadlock may result. +.RE +.SH RETURN VALUES +.sp +.LP +\fBchpoll()\fR should return \fB0\fR for success, or the appropriate error +number. +.SH SEE ALSO +.sp +.LP +\fBpoll\fR(2), \fBnochpoll\fR(9F), \fBpollwakeup\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/close.9e b/usr/src/man/man9e/close.9e new file mode 100644 index 0000000000..a792f7e24a --- /dev/null +++ b/usr/src/man/man9e/close.9e @@ -0,0 +1,334 @@ +'\" te +.\" Copyright 2003 AT&T +.\" 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 close 9E "24 Apr 2008" "SunOS 5.11" "Driver Entry Points" +.SH NAME +close \- relinquish access to a device +.SH SYNOPSIS +.SS "Block and Character" +.LP +.nf +#include <sys/types.h> +#include <sys/file.h> +#include <sys/errno.h> +#include <sys/open.h> +#include <sys/cred.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBclose\fR(\fBdev_t\fR \fIdev\fR, \fBint\fR \fIflag\fR, \fBint\fR \fIotyp\fR, \fBcred_t *\fR\fIcred_p\fR); +.fi + +.SS "STREAMS" +.LP +.nf +#include <sys/types.h> +#include <sys/stream.h> +#include <sys/file.h> +#include <sys/errno.h> +#include <sys/open.h> +#include <sys/cred.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBclose\fR(\fBqueue_t *\fR\fIq\fR, \fBint\fR \fIflag\fR, \fBcred_t *\fR\fIcred_p\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). This entry point is \fIrequired\fR +for block devices. +.SH PARAMETERS +.SS "Block and Character" +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 11n +.rt +Device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 11n +.rt +File status flag, as set by the \fBopen\fR(2) or modified by the +\fBfcntl\fR(2) system calls. The flag is for information only\(emthe file +should always be closed completely. Possible values are: \fBFEXCL\fR, +\fBFNDELAY\fR, \fBFREAD,\fR \fBFKLYR,\fR and \fBFWRITE\fR. Refer to +\fBopen\fR(9E) for more information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIotyp\fR\fR +.ad +.RS 11n +.rt +Parameter supplied so that the driver can determine how many times a device was +opened and for what reasons. The flags assume the \fBopen()\fR routine may be +called many times, but the \fBclose()\fR routine should only be called on the +last \fBclose()\fR of a device. +.sp +.ne 2 +.mk +.na +\fB\fBOTYP_BLK\fR\fR +.ad +.RS 12n +.rt +Close was through block interface for the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBOTYP_CHR\fR\fR +.ad +.RS 12n +.rt +Close was through the raw/character interface for the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBOTYP_LYR\fR\fR +.ad +.RS 12n +.rt +Close a layered process (a higher-level driver called the \fBclose()\fR routine +of the device). +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fI*cred_p\fR\fR +.ad +.RS 11n +.rt +Pointer to the user credential structure. +.RE + +.SS "STREAMS" +.sp +.ne 2 +.mk +.na +\fB\fI*q\fR\fR +.ad +.RS 11n +.rt +Pointer to \fBqueue\fR(9S) structure used to reference the read side of the +driver. (A queue is the central node of a collection of structures and +routines pointed to by a queue.) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 11n +.rt +File status flag. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fI*cred_p\fR\fR +.ad +.RS 11n +.rt +Pointer to the user credential structure. +.RE + +.SH DESCRIPTION +.sp +.LP +For STREAMS drivers, the \fBclose()\fR routine is called by the kernel through +the \fBcb_ops\fR(9S) table entry for the device. (Modules use the \fBfmodsw\fR +table.) A non-null value in the \fBd_str\fR field of the \fBcb_ops\fR entry +points to a \fBstreamtab\fR structure, which points to a \fBqinit\fR(9S) +containing a pointer to the \fBclose()\fR routine. Non-STREAMS \fBclose()\fR +routines are called directly from the \fBcb_ops\fR table. +.sp +.LP +\fBclose()\fR ends the connection between the user process and the device, and +prepares the device (hardware and software) so that it is ready to be opened +again. +.sp +.LP +A device may be opened simultaneously by multiple processes and the +\fBopen()\fR driver routine is called for each open. For all \fIotyp\fR values +other than \fBOTYP_LYR\fR, the kernel calls the \fBclose()\fR routine when the +last-reference occurs. For \fBOTYP_LYR\fR each close operation will call the +driver. +.sp +.LP +Kernel accounting for last-reference occurs at (\fIdev\fR, \fIotyp\fR) +granularity. Note that a device is referenced once its associated +\fBopen\fR(9E) routine is entered, and thus \fBopen\fR(9E)'s which have not +yet completed will prevent \fBclose()\fR from being called. The driver's +\fBclose()\fR call associated with the last-reference going away is typically +issued as result of a \fBclose\fR(2), \fBexit\fR(2), \fBmunmap\fR(2), or +\fBumount\fR(2). However, a failed \fBopen\fR(9E) call can cause this +last-reference \fBclose()\fR call to be issued as a result of an \fBopen\fR(2) +or \fBmount\fR(2). +.sp +.LP +The kernel provides \fBopen()\fR \fBclose()\fR exclusion guarantees to the +driver at the same \fIdevp\fR, \fIotyp\fR granularity as last-reference +accounting. The kernel delays new calls to the \fBopen()\fR driver routine +while the last-reference \fBclose()\fR call is executing. For example, a driver +that blocks in \fBclose()\fR will not see new calls to \fBopen()\fR until it +returns from \fBclose()\fR. This effectively delays invocation of other +\fBcb_ops\fR(9S) driver entry points that also depend on an \fBopen\fR(9E) +established device reference. If the driver has indicated that an \fBEINTR\fR +return is safe via the \fBD_OPEN_RETURNS_EINTR\fR \fBcb_flag\fR, then a delayed +\fBopen()\fR may be interrupted by a signal, resulting in an \fBEINTR\fR return +from \fBopen()\fR prior to calling \fBopen\fR(9E). +.sp +.LP +Last-reference accounting and \fBopen()\fR \fBclose()\fR exclusion typically +simplify driver writing. In some cases, however, they might be an impediment +for certain types of drivers. To overcome any impediment, the driver can change +minor numbers in \fBopen\fR(9E), as described below, or implement multiple +minor nodes for the same device. Both techniques give the driver control over +when \fBclose()\fR calls occur and whether additional \fBopen()\fR calls will +be delayed while \fBclose()\fR is executing. +.sp +.LP +In general, a \fBclose()\fR routine should always check the validity of the +minor number component of the \fIdev\fR parameter. The routine should also +check permissions as necessary, by using the user credential structure (if +pertinent), and the appropriateness of the \fIflag\fR and \fIotyp\fR +parameter values. +.sp +.LP +\fBclose()\fR could perform any of the following general functions: +.RS +4 +.TP +.ie t \(bu +.el o +disable interrupts +.RE +.RS +4 +.TP +.ie t \(bu +.el o +hang up phone lines +.RE +.RS +4 +.TP +.ie t \(bu +.el o +rewind a tape +.RE +.RS +4 +.TP +.ie t \(bu +.el o +deallocate buffers from a private buffering scheme +.RE +.RS +4 +.TP +.ie t \(bu +.el o +unlock an unsharable device (that was locked in the \fBopen()\fR routine) +.RE +.RS +4 +.TP +.ie t \(bu +.el o +flush buffers +.RE +.RS +4 +.TP +.ie t \(bu +.el o +notify a device of the close +.RE +.RS +4 +.TP +.ie t \(bu +.el o +deallocate any resources allocated on open +.RE +.sp +.LP +The \fBclose()\fR routines of STREAMS drivers and modules are called when a +stream is dismantled or a module popped. The steps for dismantling a stream are +performed in the following order. First, any multiplexor links present are +unlinked and the lower streams are closed. Next, the following steps are +performed for each module or driver on the stream, starting at the head and +working toward the tail: +.RS +4 +.TP +1. +The write queue is given a chance to drain. +.RE +.RS +4 +.TP +2. +The \fBclose()\fR routine is called. +.RE +.RS +4 +.TP +3. +The module or driver is removed from the stream. +.RE +.SH RETURN VALUES +.sp +.LP +\fBclose()\fR should return \fB0\fR for success, or the appropriate error +number. Return errors rarely occur, but if a failure is detected, the driver +should decide whether the severity of the problem warrants either displaying a +message on the console or, in worst cases, triggering a system panic. +Generally, a failure in a \fBclose()\fR routine occurs because a problem +occurred in the associated device. +.SH NOTES +.sp +.LP +If you use \fBqwait_sig\fR(9F), \fBcv_wait_sig\fR(9F) or +\fBcv_timedwait_sig\fR(9F), you should note that \fBclose()\fR may be called in +contexts in which signals cannot be received. The \fBddi_can_receive_sig\fR(9F) +function is provided to determine when this hazard exists. +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBfcntl\fR(2), \fBopen\fR(2), \fBumount\fR(2), +\fBdetach\fR(9E), \fBopen\fR(9E), \fBddi_can_receive_sig\fR(9F), +\fBcb_ops\fR(9S), \fBqinit\fR(9S), \fBqueue\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9e/csx_event_handler.9e b/usr/src/man/man9e/csx_event_handler.9e new file mode 100644 index 0000000000..719161fe32 --- /dev/null +++ b/usr/src/man/man9e/csx_event_handler.9e @@ -0,0 +1,617 @@ +'\" te +.\" Copyright (c) 1996, 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 csx_event_handler 9E "22 Nov 1996" "SunOS 5.11" "Driver Entry Points" +.SH NAME +csx_event_handler \- PC Card driver event handler +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t prefix\fR\fBevent_handler\fR(\fBevent_t\fR \fIevent\fR, \fBint32_t\fR \fIpriority\fR, + \fBevent_callback_args_t *\fR\fIargs\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIevent\fR\fR +.ad +.RS 12n +.rt +The event. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpriority\fR\fR +.ad +.RS 12n +.rt +The priority of the event. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIargs\fR\fR +.ad +.RS 12n +.rt +A pointer to the \fBevent_callback_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +Each instance of a \fBPC \fRCard driver must register an event handler to +manage events associated with its \fBPC \fRCard. The driver event handler is +registered using the \fBevent_handler\fR field of the \fBclient_req_t\fR +structure passed to \fBcsx_RegisterClient\fR(9F). The driver may also supply a +parameter to be passed to its event handler function using the +\fBevent_callback_args.client_data\fR field. Typically, this argument is the +driver instance's soft state pointer. The driver also registers which events it +is interested in receiving through the \fBEventMask\fR field of the +\fBclient_req_t\fR structure. +.sp +.LP +Each event is delivered to the driver with a priority, \fIpriority\fR. High +priority events with \fBCS_EVENT_PRI_HIGH\fR set in \fIpriority\fR are +delivered above lock level, and the driver must use its high-level event mutex +initialized with the \fBiblk_cookie\fR returned by \fBcsx_RegisterClient\fR(9F) +to protect such events. Low priority events with \fBCS_EVENT_PRI_LOW\fR set in +\fIpriority\fR are delivered below lock level, and the driver must use its +low-level event mutex initialized with a \fBNULL \fRinterrupt cookie to protect +these events. +.sp +.LP +\fBcsx_RegisterClient\fR(9F) registers the driver's event handler, but no +events begin to be delivered to the driver until after a successful call to +\fBcsx_RequestSocketMask\fR(9F). +.sp +.LP +In all cases, Card Services delivers an event to each driver instance +associated with a function on a multiple function \fBPC \fRCard. +.SS "Event Indications" +.sp +.LP +The events and their indications are listed below; they are always delivered as +low priority unless otherwise noted: +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_REGISTRATION_COMPLETE\fR\fR +.ad +.sp .6 +.RS 4n +A registration request processed in the background has been completed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_CARD_INSERTION\fR\fR +.ad +.sp .6 +.RS 4n +A \fBPC \fRCard has been inserted in a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_CARD_READY\fR\fR +.ad +.sp .6 +.RS 4n +A \fBPC \fRCard's \fBREADY \fRline has transitioned from the busy to ready +state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_CARD_REMOVAL\fR\fR +.ad +.sp .6 +.RS 4n +A \fBPC \fRCard has been removed from a socket. This event is delivered twice; +first as a high priority event, followed by delivery as a low priority event. +As a high priority event, the event handler should only note that the \fBPC +\fRCard is no longer present to prevent accesses to the hardware from +occurring. As a low priority event, the event handler should release the +configuration and free all \fBI/O\fR, window and \fBIRQ \fRresources for use by +other \fBPC \fRCards. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_BATTERY_LOW\fR\fR +.ad +.sp .6 +.RS 4n +The battery on a \fBPC \fRCard is weak and is in need of replacement. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_BATTERY_DEAD\fR\fR +.ad +.sp .6 +.RS 4n +The battery on a \fBPC \fRCard is no longer providing operational voltage. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_PM_RESUME\fR\fR +.ad +.sp .6 +.RS 4n +Card Services has received a resume notification from the system's Power +Management software. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_PM_SUSPEND\fR\fR +.ad +.sp .6 +.RS 4n +Card Services has received a suspend notification from the system's Power +Management software. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_CARD_LOCK\fR\fR +.ad +.sp .6 +.RS 4n +A mechanical latch has been manipulated preventing the removal of the \fBPC +\fRCard from the socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_CARD_UNLOCK\fR\fR +.ad +.sp .6 +.RS 4n +A mechanical latch has been manipulated allowing the removal of the \fBPC +\fRCard from the socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_EJECTION_REQUEST\fR\fR +.ad +.sp .6 +.RS 4n +A request that the \fBPC \fRCard be ejected from a socket using a motor-driven +mechanism. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_EJECTION_COMPLETE\fR\fR +.ad +.sp .6 +.RS 4n +A motor has completed ejecting a \fBPC \fRCard from a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_ERASE_COMPLETE\fR\fR +.ad +.sp .6 +.RS 4n +A queued erase request that is processed in the background has been completed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_INSERTION_REQUEST\fR\fR +.ad +.sp .6 +.RS 4n +A request that a \fBPC \fRCard be inserted into a socket using a motor-driven +mechanism. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_INSERTION_COMPLETE\fR\fR +.ad +.sp .6 +.RS 4n +A motor has completed inserting a \fBPC \fRCard in a socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_CARD_RESET\fR\fR +.ad +.sp .6 +.RS 4n +A hardware reset has occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_RESET_REQUEST\fR\fR +.ad +.sp .6 +.RS 4n +A request for a physical reset by a client. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_RESET_COMPLETE\fR\fR +.ad +.sp .6 +.RS 4n +A reset request that is processed in the background has been completed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_RESET_PHYSICAL\fR\fR +.ad +.sp .6 +.RS 4n +A reset is about to occur. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_CLIENT_INFO\fR\fR +.ad +.sp .6 +.RS 4n +A request that the client return its client information data. If +\fBGET_CLIENT_INFO_SUBSVC(args->client_info.Attributes)\fR is equal to +\fBCS_CLIENT_INFO_SUBSVC_CS\fR, the driver should fill in the other fields in +the \fBclient_info\fR structure as described below, and return +\fBCS_SUCCESS\fR. Otherwise, it should return \fBCS_UNSUPPORTED_EVENT.\fR +.sp +.ne 2 +.mk +.na +\fB\fBargs->client_data.Attributes\fR\fR +.ad +.sp .6 +.RS 4n +Must be \fBOR\fR'ed with \fBCS_CLIENT_INFO_VALID\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBargs->client_data.Revision\fR\fR +.ad +.sp .6 +.RS 4n +Must be set to a driver-private version number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBargs->client_data.CSLevel\fR\fR +.ad +.sp .6 +.RS 4n +Must be set to \fBCS_VERSION\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBargs->client_data.RevDate\fR\fR +.ad +.sp .6 +.RS 4n +Must be set to the revision date of the \fBPC \fRCard driver, using +\fBCS_CLIENT_INFO_MAKE_DATE(\fIday\fR,\fR \fImonth\fR, \fIyear\fR). \fIday\fR +must be the day of the month, \fImonth\fR must be the month of the year, and +\fIyear\fR must be the year, offset from a base of 1980. For example, this +field could be set to a revision date of July 4 1997 with +\fBCS_CLIENT_INFO_MAKE_DATE(4, 7, 17)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBargs->client_data.ClientName\fR\fR +.ad +.sp .6 +.RS 4n +A string describing the \fBPC \fRCard driver should be copied into this space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBargs->client_data.VendorName\fR\fR +.ad +.sp .6 +.RS 4n +A string supplying the name of the \fBPC \fRCard driver vendor should be copied +into this space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBargs->client_data.DriverName\fR\fR +.ad +.sp .6 +.RS 4n +A string supplying the name of the \fBPC \fRCard driver will be copied into +this space by Card Services after the \fBPC \fRCard driver has successfully +processed this event; the driver does not need to initialize this field. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_WRITE_PROTECT\fR\fR +.ad +.sp .6 +.RS 4n +The write protect status of the \fBPC \fRCard in the indicated socket has +changed. The current write protect state of the \fBPC \fRCard is in the +\fBargs->info\fR field: +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_WRITE_PROTECT_WPOFF\fR\fR +.ad +.sp .6 +.RS 4n +Card is not write protected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_EVENT_WRITE_PROTECT_WPON\fR\fR +.ad +.sp .6 +.RS 4n +Card is write protected. +.RE + +.RE + +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBevent_callback_args_t\fR are: +.sp +.in +2 +.nf +void *info; /* event-specific information */ +void *client_data; /* driver-private data */ +client_info_t client_info; /* client information*/ +.fi +.in -2 + +.sp +.LP +The structure members of \fBclient_info_t\fR are: +.sp +.in +2 +.nf +unit32_t Attributes; /* attributes */ +unit32_t Revisions; /* version number */ +uint32_t CSLevel; /* Card Services version */ +uint32_t RevDate; /* revision date */ +char ClientName[CS_CLIENT_INFO_MAX_NAME_LEN]; + /*PC Card driver description */ +char VendorName[CS_CLIENT_INFO_MAX_NAME_LEN]; + /*PC Card driver vendor name */ +char DriverName[MODMAXNAMELEN]; + /* PC Card driver name */ +.fi +.in -2 + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 24n +.rt +The event was handled successfully. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_EVENT\fR\fR +.ad +.RS 24n +.rt +Driver does not support this event. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_FAILURE\fR\fR +.ad +.RS 24n +.rt +Error occurred while handling this event. +.RE + +.SH CONTEXT +.sp +.LP +This function is called from high-level interrupt context in the case of high +priority events, and from kernel context in the case of low priority events. +.SH EXAMPLES +.sp +.in +2 +.nf +static int +xx_event(event_t event, int priority, event_callback_args_t *args) +{ + int rval; + struct xxx *xxx = args->client_data; + client_info_t *info = &args->client_info; + + switch (event) { + case CS_EVENT_REGISTRATION_COMPLETE: + ASSERT(priority & CS_EVENT_PRI_LOW); + mutex_enter(&xxx->event_mutex); + xxx->card_state |= XX_REGISTRATION_COMPLETE; + mutex_exit(&xxx->event_mutex); + rval = CS_SUCCESS; + break; + + case CS_EVENT_CARD_READY: + ASSERT(priority & CS_EVENT_PRI_LOW); + rval = xx_card_ready(xxx); + mutex_exit(&xxx->event_mutex); + break; + + case CS_EVENT_CARD_INSERTION: + ASSERT(priority & CS_EVENT_PRI_LOW); + mutex_enter(&xxx->event_mutex); + rval = xx_card_insertion(xxx); + mutex_exit(&xxx->event_mutex); + break; + + case CS_EVENT_CARD_REMOVAL: + if (priority & CS_EVENT_PRI_HIGH) { + mutex_enter(&xxx->hi_event_mutex); + xxx->card_state &= ~XX_CARD_PRESENT; + mutex_exit(&xxx->hi_event_mutex); + } else { + mutex_enter(&xxx->event_mutex); + rval = xx_card_removal(xxx); + mutex_exit(&xxx->event_mutex); + } + break; + + case CS_EVENT_CLIENT_INFO: + ASSERT(priority & CS_EVENT_PRI_LOW); + if (GET_CLIENT_INFO_SUBSVC_CS(info->Attributes) == + CS_CLIENT_INFO_SUBSVC_CS) { + info->Attributes |= CS_CLIENT_INFO_VALID; + info->Revision = 4; + info->CSLevel = CS_VERSION; + info->RevDate = CS_CLIENT_INFO_MAKE_DATE(4, 7, 17); + (void)strncpy(info->ClientName, + "WhizBang Ultra Zowie PC card driver", + CS_CLIENT_INFO_MAX_NAME_LEN) + + "ACME PC card drivers, Inc.", + CS_CLIENT_INFO_MAX_NAME_LEN); + rval = CS_SUCCESS; + } else { + rval = CS_UNSUPPORTED_EVENT; + } + break; + + + case CS_EVENT_WRITE_PROTECT: + ASSERT(priority & CS_EVENT_PRI_LOW); + mutex_enter(&xxx->event_mutex); + if (args->info == CS_EVENT_WRITE_PROTECT_WPOFF) { + xxx->card_state &= ~XX_WRITE_PROTECTED; + } else { + xxx->card_state |= XX_WRITE_PROTECTED; + } + mutex_exit(&xxx->event_mutex); + rval = CS_SUCCESS; + break; + + default: + rval = CS_UNSUPPORTED_EVENT; + break; + } + + return (rval); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBcsx_Event2Text\fR(9F), \fBcsx_RegisterClient\fR(9F), +\fBcsx_RequestSocketMask\fR(9F) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9e/detach.9e b/usr/src/man/man9e/detach.9e new file mode 100644 index 0000000000..20da374295 --- /dev/null +++ b/usr/src/man/man9e/detach.9e @@ -0,0 +1,184 @@ +'\" te +.\" Copyright (c) 2003, 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 detach 9E "7 Dec 2003" "SunOS 5.11" "Driver Entry Points" +.SH NAME +detach \- detach or suspend a device +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR \fBdetach\fR(\fBdev_info_t\fR \fIdip\fR, \fBddi_detach_cmd_t\fR \fIcmd\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 7n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmd\fR\fR +.ad +.RS 7n +.rt +Type of detach; the driver should return \fBDDI_FAILURE\fR if any value other +than \fBDDI_DETACH\fR or \fBDDI_SUSPEND\fR is passed to it. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdetach()\fR function complements the \fBattach\fR(9E) routine. +.SS "DDI_DETACH" +.sp +.LP +If \fIcmd\fR is set to \fBDDI_DETACH\fR, \fBdetach()\fR is used to remove the +state associated with a given instance of a device node prior to the removal of +that instance from the system. +.sp +.LP +The \fBdetach()\fR function will be called once for each instance of the device +for which there has been a successful \fBattach()\fR, once there are no longer +any opens on the device. An attached instance of a driver can be successfully +detached only once. The \fBdetach()\fR function should clean up any per +instance data initialized in \fBattach\fR(9E) and call \fBkmem_free\fR(9F) to +free any heap allocations. For information on how to unregister interrupt +handlers, see \fBddi_add_intr\fR(9F). This should also include putting the +underlying device into a quiescent state so that it will not generate +interrupts. +.sp +.LP +Drivers that set up \fBtimeout\fR(9F) routines should ensure that they are +cancelled before returning \fBDDI_SUCCESS\fR from \fBdetach()\fR. +.sp +.LP +If \fBdetach()\fR determines a particular instance of the device cannot be +removed when requested because of some exceptional condition, \fBdetach()\fR +must return \fBDDI_FAILURE\fR, which prevents the particular device instance +from being detached. This also prevents the driver from being unloaded. A +driver instance failing the detach must ensure that no per instance data or +state is modified or freed that would compromise the system or subsequent +driver operation. +.sp +.LP +The system guarantees that the function will only be called for a particular +\fBdev_info\fR node after (and not concurrently with) a successful +\fBattach\fR(9E) of that device. The system also guarantees that \fBdetach()\fR +will only be called when there are no outstanding \fBopen\fR(9E) calls on the +device. +.SS "DDI_SUSPEND" +.sp +.LP +The \fBDDI_SUSPEND\fR \fIcmd\fR is issued when the entire system is being +suspended and power removed from it or when the system must be made quiescent. +It will be issued only to devices which have a \fBreg\fR property or which +export a \fBpm-hardware-state\fR property with the value needs-suspend-resume. +.sp +.LP +If \fIcmd\fR is set to \fBDDI_SUSPEND\fR, \fBdetach()\fR is used to suspend all +activity of a device before power is (possibly) removed from the device. The +steps associated with suspension must include putting the underlying device +into a quiescent state so that it will not generate interrupts or modify or +access memory. Once quiescence has been obtained, \fBdetach()\fR can be called +with outstanding \fBopen\fR(9E) requests. It must save the hardware state of +the device to memory and block incoming or existing requests until +\fBattach()\fR is called with \fBDDI_RESUME\fR. +.sp +.LP +If the device is used to store file systems, then after \fBDDI_SUSPEND\fR is +issued, the device should still honor \fBdump\fR(9E) requests as this entry +point may be used by suspend-resume operation (see \fBcpr\fR(7)) to save state +file. It must do this, however, without disturbing the saved hardware state of +the device. +.sp +.LP +If the device driver uses automatic device Power Management interfaces (driver +exports \fBpm-components\fR(9P) property), it might need to call +\fBpm_raise_power\fR(9F) if the current power level is lower than required to +complete the \fBdump\fR(9E) request. +.sp +.LP +Before returning successfully from a call to \fBdetach()\fR with a command of +\fBDDI_SUSPEND\fR, the driver must cancel any outstanding timeouts and make any +driver threads quiescent. +.sp +.LP +If \fBDDI_FAILURE\fR is returned for the \fBDDI_SUSPEND\fR \fIcmd\fR, either +the operation to suspend the system or to make it quiescent will be aborted. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +For \fBDDI_DETACH\fR, the state associated with the given device was +successfully removed. For \fBDDI_SUSPEND\fR, the driver was successfully +suspended. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +The operation failed or the request was not understood. The associated state is +unchanged. +.RE + +.SH CONTEXT +.sp +.LP +This function is called from user context only. +.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 +\fBcpr\fR(7), \fBpm\fR(7D), \fBpm\fR(9P), \fBpm-components\fR(9P), +\fBattach\fR(9E), \fBdump\fR(9E), \fBopen\fR(9E), \fBpower\fR(9E), +\fBddi_add_intr\fR(9F), \fBddi_dev_is_needed\fR(9F), \fBddi_map_regs\fR(9F), +\fBkmem_free\fR(9F), \fBpm_raise_power\fR(9F), \fBtimeout\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/devmap.9e b/usr/src/man/man9e/devmap.9e new file mode 100644 index 0000000000..3b53772c73 --- /dev/null +++ b/usr/src/man/man9e/devmap.9e @@ -0,0 +1,323 @@ +'\" 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 devmap 9E "15 Jan 1997" "SunOS 5.11" "Driver Entry Points" +.SH NAME +devmap \- validate and translate virtual mapping for memory mapped device +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBdevmap\fR(\fBdev_t\fR \fIdev\fR, \fBdevmap_cookie_t\fR \fIdhp\fR, \fBoffset_t\fR \fIoff\fR, + \fBsize_t\fR \fIlen\fR, \fBsize_t *\fR\fImaplen\fR, \fBuint_t\fR \fImodel\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR \fR +.ad +.RS 11n +.rt +Device whose memory is to be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdhp\fR \fR +.ad +.RS 11n +.rt +An opaque mapping handle that the system uses to describe the mapping. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoff\fR \fR +.ad +.RS 11n +.rt +User offset within the logical device memory at which the mapping begins. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR \fR +.ad +.RS 11n +.rt +Length (in bytes) of the mapping to be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImaplen\fR \fR +.ad +.RS 11n +.rt +Pointer to length (in bytes) of mapping that has been validated. \fImaplen\fR +is less than or equal to \fIlen\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImodel\fR \fR +.ad +.RS 11n +.rt +The data model type of the current thread. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBdevmap()\fR is a required entry point for character drivers supporting +memory-mapped devices if the drivers use the devmap framework to set up the +mapping. A memory mapped device has memory that can be mapped into a process's +address space. The \fBmmap\fR(2) system call, when applied to a character +special file, allows this device memory to be mapped into user space for direct +access by the user applications. +.sp +.LP +As a result of a \fBmmap\fR(2) system call, the system calls the \fBdevmap()\fR +entry point during the mapping setup when \fBD_DEVMAP\fR is set in the +\fBcb_flag\fR field of the \fBcb_ops\fR(9S) structure, and any of the following +conditions apply: +.RS +4 +.TP +.ie t \(bu +.el o +\fBddi_devmap_segmap\fR(9F) is used as the \fBsegmap\fR(9E) entry point. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBsegmap\fR(9E) entry point is set to \fINULL.\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBmmap\fR(9E) entry point is set to \fINULL.\fR +.RE +.sp +.LP +Otherwise \fBEINVAL\fR will be returned to \fBmmap\fR(2). +.sp +.LP +Device drivers should use \fBdevmap()\fR to validate the user mappings to the +device, to translate the logical offset, \fIoff\fR, to the corresponding +physical offset within the device address space, and to pass the mapping +information to the system for setting up the mapping. +.sp +.LP +\fIdhp\fR is a device mapping handle that the system uses to describe a mapping +to a memory that is either contiguous in physical address space or in kernel +virtual address space. The system may create multiple mapping handles in one +\fBmmap\fR(2) system call (for example, if the mapping contains multiple +physically discontiguous memory regions). +.sp +.LP +\fImodel\fR returns the C Language Type Model which the current thread expects. +It is set to \fBDDI_MODEL_ILP32\fR if the current thread expects 32-bit ( +\fIILP32\fR) semantics, or \fBDDI_MODEL_LP64\fR if the current thread expects +64-bit ( \fILP64\fR) semantics. \fImodel\fR is used in combination with +\fBddi_model_convert_from\fR(9F) to determine whether there is a data model +mismatch between the current thread and the device driver. The device driver +might have to adjust the shape of data structures before exporting them to a +user thread which supports a different data model. +.sp +.LP +\fBdevmap()\fR should return \fBEINVAL\fR if the logical offset, \fIoff\fR, is +out of the range of memory exported by the device to user space. If \fIoff\fR + +\fIlen\fR exceeds the range of the contiguous memory, \fBdevmap()\fR should +return the length from \fIoff\fR to the end of the contiguous memory region. +The system will repeatedly call \fBdevmap()\fR until the original mapping +length is satisfied. The driver sets \fI*maplen\fR to the validated length +which must be either less than or equal to \fIlen\fR. +.sp +.LP +The \fBdevmap()\fR entry point must initialize the mapping parameters before +passing them to the system through either \fBdevmap_devmem_setup\fR(9F) (if the +memory being mapped is device memory) or \fBdevmap_umem_setup\fR(9F) (if the +memory being mapped is kernel memory). The \fBdevmap()\fR entry point +initializes the mapping parameters by mapping the control callback structure +(see \fBdevmap_callback_ctl\fR(9S)), the device access attributes, mapping +length, maximum protection possible for the mapping, and optional mapping +flags. See \fBdevmap_devmem_setup\fR(9F) and \fBdevmap_umem_setup\fR(9F) for +further information on initializing the mapping parameters. +.sp +.LP +The system will copy the driver's \fBdevmap_callback_ctl\fR(9S) data into its +private memory so the drivers do not need to keep the data structure after the +return from either \fBdevmap_devmem_setup\fR(9F) or +\fBdevmap_umem_setup\fR(9F). +.sp +.LP +For device mappings, the system establishes the mapping to the physical address +that corresponds to \fIoff\fR by passing the register number and the offset +within the register address space to \fBdevmap_devmem_setup\fR(9F). +.sp +.LP +For kernel memory mapping, the system selects a user virtual address that is +aligned with the kernel address being mapped for cache coherence. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB0\fR \fR +.ad +.RS 12n +.rt +Successful completion. +.RE + +.sp +.ne 2 +.mk +.na +\fBNon-zero\fR +.ad +.RS 12n +.rt +An error occurred. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRImplementing the \fBdevmap()\fR Entry Point +.sp +.LP +The following is an example of the implementation for the \fBdevmap()\fR entry +point. For mapping device memory, \fBdevmap()\fR calls +\fBdevmap_devmem_setup\fR(9F) with the register number, \fIrnumber\fR, and the +offset within the register, \fIroff\fR. For mapping kernel memory, the driver +must first allocate the kernel memory using \fBddi_umem_alloc\fR(9F). For +example, \fBddi_umem_alloc\fR(9F) can be called in the \fBattach\fR(9E) +routine. The resulting kernel memory cookie is stored in the driver soft state +structure, which is accessible from the \fBdevmap()\fR entry point. See +\fBddi_soft_state\fR(9F). \fBdevmap()\fR passes the cookie obtained from +\fBddi_umem_alloc\fR(9F) and the offset within the allocated kernel memory to +\fBdevmap_umem_setup\fR(9F). The corresponding \fBddi_umem_free\fR(9F) can be +made in the \fBdetach\fR(9E) routine to free up the kernel memory. + +.sp +.in +2 +.nf +\&.\|.\|. +#define MAPPING_SIZE 0x2000 /* size of the mapping */ +#define MAPPING_START 0x70000000 /* logical offset at beginning + of the mapping */ +static +struct devmap_callback_ctl xxmap_ops = { + DEVMAP_OPS_REV, /* devmap_ops version number */ + xxmap_map, /* devmap_ops map routine */ + xxmap_access, /* devmap_ops access routine */ + xxmap_dup, /* devmap_ops dup routine */ + xxmap_unmap, /* devmap_ops unmap routine */ +}; + + +static int +xxdevmap(dev_t dev, devmap_cookie_t dhp, offset_t off, size_t len, + size_t *maplen, uint_t model) +{ + int instance; + struct xxstate *xsp; + struct ddi_device_acc_attr *endian_attr; + struct devmap_callback_ctl *callbackops = NULL; + ddi_umem_cookie_t cookie; + dev_info_t *dip; + offset_t roff; + offset_t koff; + uint_t rnumber; + uint_t maxprot; + uint_t flags = 0; + size_t length; + int err; + + /* get device soft state */ + instance = getminor(dev); + xsp = ddi_get_soft_state(statep, instance); + if (xsp == NULL) + return (-1); + + dip = xsp->dip; + /* check for a valid offset */ + if ( \fIoff is invalid\fR ) + return (-1); + /* check if len is within the range of contiguous memory */ + if ( \fB(\fR\fIoff\fR\fB + \fR\fIlen\fR\fB)\fR \fIis contiguous\fR\fB\&.)\fR + length = len; + else + length = MAPPING_START + MAPPING_SIZE - off; + + /* device access attributes */ + endian_attr = xsp->endian_attr; + + if ( \fI off is referring to a device memory. \fR ) { + /* assign register related parameters */ + rnumber = XXX; /* index to register set at off */ + roff = XXX; /* offset of rnumber at local bus */ + callbackops = &xxmap_ops; /* do all callbacks for this mapping */ + maxprot = PROT_ALL; /* allowing all access */ + if ((err = devmap_devmem_setup(dhp, dip, callbackops, rnumber, roff, + length, maxprot, flags, endian_attr)) < 0) + + + return (err); + + } else if (\fI off is referring to a kernel memory.\fR) { + cookie = xsp->cookie; /* cookie is obtained from + ddi_umem_alloc(9F) */ + koff = XXX; /* offset within the kernel memory. */ + callbackops = NULL; /* don't do callback for this mapping */ + maxprot = PROT_ALL; /* allowing all access */ + if ((err = devmap_umem_setup(dhp, dip, callbackops, cookie, koff, + length, maxprot, flags, endian_attr)) < 0) + return (err); + } + + *maplen = length; + return (0); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBmmap\fR(2), \fBattach\fR(9E), \fBdetach\fR(9E), \fBmmap\fR(9E), +\fBsegmap\fR(9E), \fBddi_devmap_segmap\fR(9F), +\fBddi_model_convert_from\fR(9F), \fBddi_soft_state\fR(9F), +\fBddi_umem_alloc\fR(9F), \fBddi_umem_free\fR(9F), +\fBdevmap_devmem_setup\fR(9F), \fBdevmap_setup\fR(9F), +\fBdevmap_umem_setup\fR(9F), \fBcb_ops\fR(9S), \fBdevmap_callback_ctl\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/devmap_access.9e b/usr/src/man/man9e/devmap_access.9e new file mode 100644 index 0000000000..a1d34105f2 --- /dev/null +++ b/usr/src/man/man9e/devmap_access.9e @@ -0,0 +1,300 @@ +'\" te +.\" Copyright (c) 1996, 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_access 9E "17 Jan 1997" "SunOS 5.11" "Driver Entry Points" +.SH NAME +devmap_access \- device mapping access entry point +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBdevmap_access\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBvoid *\fR\fIpvtp\fR, + \fBoffset_t\fR \fIoff\fR, \fBsize_t\fR \fIlen\fR, \fBuint_t\fR \fItype\fR, \fBuint_t\fR \fIrw\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIdhp\fR \fR +.ad +.RS 9n +.rt +An opaque mapping handle that the system uses to describe the mapping. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpvtp\fR \fR +.ad +.RS 9n +.rt +Driver private mapping data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoff\fR \fR +.ad +.RS 9n +.rt +User offset within the logical device memory at which the access begins. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR \fR +.ad +.RS 9n +.rt +Length (in bytes) of the memory being accessed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR \fR +.ad +.RS 9n +.rt +Type of access operation. Possible values are: +.sp +.ne 2 +.mk +.na +\fB\fBDEVMAP_ACCESS\fR \fR +.ad +.RS 18n +.rt +Memory access. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDEVMAP_LOCK\fR \fR +.ad +.RS 18n +.rt +Lock the memory being accessed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDEVMAP_UNLOCK\fR \fR +.ad +.RS 18n +.rt +Unlock the memory being accessed. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrw\fR \fR +.ad +.RS 9n +.rt +Direction of access. Possible values are: +.sp +.ne 2 +.mk +.na +\fB\fBDEVMAP_READ\fR \fR +.ad +.RS 17n +.rt +Read access attempted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDEVMAP_WRITE\fR \fR +.ad +.RS 17n +.rt +Write access attempted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDEVMAP_EXEC\fR \fR +.ad +.RS 17n +.rt +Execution access attempted. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdevmap_access()\fR entry point is an optional routine. It notifies +drivers whenever an access is made to a mapping described by \fIdhp\fR that +has not been validated or does not have sufficient protection for the access. +The system expects \fBdevmap_access()\fR to call either +\fBdevmap_do_ctxmgt\fR(9F) or \fBdevmap_default_access\fR(9F) to load the +memory address translations before it returns. For mappings that support +context switching, device drivers should call \fBdevmap_do_ctxmgt\fR(9F). For +mappings that do not support context switching, the drivers should call +\fBdevmap_default_access\fR(9F). +.sp +.LP +In \fBdevmap_access()\fR, drivers perform memory access related operations +such as context switching, checking the availability of the memory object, and +locking and unlocking the memory object being accessed. The +\fBdevmap_access()\fR entry point is set to \fINULL\fR if no operations need +to be performed. +.sp +.LP +\fIpvtp\fR is a pointer to the driver's private mapping data that was allocated +and initialized in the \fBdevmap_map\fR(9E) entry point. +.sp +.LP +\fIoff\fR and \fIlen\fR define the range to be affected by the operations in +\fBdevmap_access()\fR. \fItype\fR defines the type of operation that device +drivers should perform on the memory object. If \fBtype\fR is either +\fBDEVMAP_LOCK\fR or \fBDEVMAP_UNLOCK,\fR the length passed to either +\fBdevmap_do_ctxmgt\fR(9F) or \fBdevmap_default_access\fR(9F) must be same as +\fIlen\fR. \fIrw\fR specifies the direction of access on the memory object. +.sp +.LP +A non-zero return value from \fBdevmap_access()\fR may result in a +\fBSIGSEGV\fR or \fBSIGBUS\fR signal being delivered to the process. +.SH RETURN VALUES +.sp +.LP +\fBdevmap_access()\fR returns the following values: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR \fR +.ad +.RS 12n +.rt +Successful completion. +.RE + +.sp +.ne 2 +.mk +.na +\fBNon-zero\fR +.ad +.RS 12n +.rt +An error occurred. The return value from \fBdevmap_do_ctxmgt\fR(9F) or +\fBdevmap_default_access\fR(9F) should be returned. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBdevmap_access()\fR entry point +.sp +.LP +The following is an example of the \fBdevmap_access()\fR entry point. If the +mapping supports context switching, \fBdevmap_access()\fR calls +\fBdevmap_do_ctxmgt\fR(9F). Otherwise, \fBdevmap_access()\fR calls +\fBdevmap_default_access\fR(9F). + +.sp +.in +2 +.nf +\&.\|.\|. +#define OFF_DO_CTXMGT 0x40000000 +#define OFF_NORMAL 0x40100000 +#define CTXMGT_SIZE 0x100000 +#define NORMAL_SIZE 0x100000 + +/* + * Driver devmap_contextmgt(9E) callback function. + */ +static int +xx_context_mgt(devmap_cookie_t dhp, void *pvtp, offset_t offset, + size_t length, uint_t type, uint_t rw) +{ + ...... + /* + * see devmap_contextmgt(9E) for an example + */ +} + +/* + * Driver devmap_access(9E) entry point + */ +static int +xxdevmap_access(devmap_cookie_t dhp, void *pvtp, offset_t off, + size_t len, uint_t type, uint_t rw) +{ + offset_t diff; + int err; + + /* + * check if \fIoff\fR is within the range that supports + * context management. + */ + if ((diff = off - OFF_DO_CTXMG) >= 0 && diff < CTXMGT_SIZE) { + /* + * calculates the length for context switching + */ + if ((len + off) > (OFF_DO_CTXMGT + CTXMGT_SIZE)) + return (-1); + /* + * perform context switching + */ + err = devmap_do_ctxmgt(dhp, pvtp, off, len, type, + rw, xx_context_mgt); + /* + * check if \fI off \fRis within the range that does normal + * memory mapping. + */ + } else if ((diff = off - OFF_NORMAL) >= 0 && diff < NORMAL_SIZE) { + if ((len + off) > (OFF_NORMAL + NORMAL_SIZE)) + return (-1); + err = devmap_default_access(dhp, pvtp, off, len, type, rw); + } else + return (-1); + + return (err); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBdevmap_map\fR(9E), \fBdevmap_default_access\fR(9F), +\fBdevmap_do_ctxmgt\fR(9F), \fBdevmap_callback_ctl\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/devmap_contextmgt.9e b/usr/src/man/man9e/devmap_contextmgt.9e new file mode 100644 index 0000000000..c8be6828b4 --- /dev/null +++ b/usr/src/man/man9e/devmap_contextmgt.9e @@ -0,0 +1,267 @@ +'\" te +.\" Copyright (c) 1996, 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_contextmgt 9E "16 Jan 1997" "SunOS 5.11" "Driver Entry Points" +.SH NAME +devmap_contextmgt \- driver callback function for context management +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBdevmap_contextmgt\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBvoid *\fR\fIpvtp\fR, + \fBoffset_t\fR \fIoff\fR, \fBsize_t\fR \fIlen\fR, \fBuint_t\fR \fItype\fR, \fBuint_t\fR \fIrw\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIdhp\fR \fR +.ad +.RS 9n +.rt +An opaque mapping handle that the system uses to describe the mapping. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpvtp\fR \fR +.ad +.RS 9n +.rt +Driver private mapping data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoff\fR \fR +.ad +.RS 9n +.rt +User offset within the logical device memory at which the access begins. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR \fR +.ad +.RS 9n +.rt +Length (in bytes) of the memory being accessed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR \fR +.ad +.RS 9n +.rt +Type of access operation. Possible values are: +.sp +.ne 2 +.mk +.na +\fB\fBDEVMAP_ACCESS\fR \fR +.ad +.RS 18n +.rt +Memory access. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDEVMAP_LOCK\fR \fR +.ad +.RS 18n +.rt +Lock the memory being accessed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDEVMAP_UNLOCK\fR \fR +.ad +.RS 18n +.rt +Unlock the memory being accessed. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrw\fR \fR +.ad +.RS 9n +.rt +Direction of access. Possible values are: +.sp +.ne 2 +.mk +.na +\fB\fBDEVMAP_READ\fR \fR +.ad +.RS 17n +.rt +Read access attempted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDEVMAP_WRITE\fR \fR +.ad +.RS 17n +.rt +Write access attempted. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +\fBdevmap_contextmgt()\fR is a driver-supplied function that performs device +context switching on a mapping. Device drivers pass \fBdevmap_contextmgt()\fR +as an argument to \fBdevmap_do_ctxmgt\fR(9F) in the \fBdevmap_access\fR(9E) +entry point. The system will call \fBdevmap_contextmgt()\fR when memory is +accessed. The system expects \fBdevmap_contextmgt()\fR to load the memory +address translations of the mapping by calling \fBdevmap_load\fR(9F) before +returning. +.sp +.LP +\fIdhp\fR uniquely identifies the mapping and is used as an argument to +\fBdevmap_load\fR(9F) to validate the mapping. \fIoff\fR and \fIlen\fR define +the range to be affected by the operations in \fBdevmap_contextmgt()\fR. +.sp +.LP +The driver must check if there is already a mapping established at \fIoff\fR +that needs to be unloaded. If a mapping exists at \fIoff\fR, +\fBdevmap_contextmgt()\fR must call \fBdevmap_unload\fR(9F) on the current +mapping. \fBdevmap_unload\fR(9F) must be followed by \fBdevmap_load()\fR on the +mapping that generated this call to \fBdevmap_contextmgt()\fR. +\fBdevmap_unload\fR(9F) unloads the current mapping so that a call to +\fBdevmap_access\fR(9E), which causes the system to call +\fBdevmap_contextmgt()\fR, will be generated the next time the mapping is +accessed. +.sp +.LP +\fIpvtp\fR is a pointer to the driver's private mapping data that was allocated +and initialized in the \fBdevmap_map\fR(9E) entry point. \fItype\fR defines the +type of operation that device drivers should perform on the memory object. If +\fItype\fR is either \fBDEVMAP_LOCK\fR or \fBDEVMAP_UNLOCK\fR, the length +passed to either \fBdevmap_unload\fR(9F) or \fBdevmap_load\fR(9F) must be same +as \fIlen\fR. \fIrw\fR specifies the access direction on the memory object. +.sp +.LP +A non-zero return value from \fBdevmap_contextmgt()\fR will be returned to +\fBdevmap_access\fR(9E) and will cause the corresponding operation to fail. The +failure may result in a \fBSIGSEGV\fR or \fBSIGBUS\fR signal being delivered to +the process. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB0\fR \fR +.ad +.RS 12n +.rt +Successful completion. +.RE + +.sp +.ne 2 +.mk +.na +\fBNon-zero\fR +.ad +.RS 12n +.rt +An error occurred. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRmanaging a device context +.sp +.LP +The following shows an example of managing a device context. + +.sp +.in +2 +.nf +struct xxcontext cur_ctx; +static int +xxdevmap_contextmgt(devmap_cookie_t dhp, void *pvtp, offset_t off, + size_t len, uint_t type, uint_t rw) +{ + devmap_cookie_t cur_dhp; + struct xxpvtdata *p; + struct xxpvtdata *pvp = (struct xxpvtdata *)pvtp; + struct xx_softc *softc = pvp->softc; + int err; + + mutex_enter(&softc->mutex); + + /* + * invalidate the translations of current context before + * switching context. + */ + if (cur_ctx != NULL && cur_ctx != pvp->ctx) { + p = cur_ctx->pvt; + cur_dhp = p->dhp; + if ((err = devmap_unload(cur_dhp, off, len)) != 0) + return (err); + } + /* Switch device context - device dependent*/ + ... + /* Make handle the new current mapping */ + cur_ctx = pvp->ctx; + + /* + * Load the address translations of the calling context. + */ + err = devmap_load(pvp->dhp, off, len, type, rw); + + mutex_exit(&softc->mutex); + + return (err); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBdevmap_access\fR(9E), \fBdevmap_do_ctxmgt\fR(9F) \fBdevmap_load\fR(9F), +\fBdevmap_unload\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/devmap_dup.9e b/usr/src/man/man9e/devmap_dup.9e new file mode 100644 index 0000000000..e2be810fd9 --- /dev/null +++ b/usr/src/man/man9e/devmap_dup.9e @@ -0,0 +1,145 @@ +'\" te +.\" Copyright (c) 1996, 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_dup 9E "21 Jan 1997" "SunOS 5.11" "Driver Entry Points" +.SH NAME +devmap_dup \- device mapping duplication entry point +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h + + + +\fB int prefix\fR\fBdevmap_dup\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBvoid *\fR\fIpvtp\fR, + \fBdevmap_cookie_t\fR \fInew_dhp\fR, \fBvoid **\fR\fInew_pvtp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIdhp\fR \fR +.ad +.RS 13n +.rt +An opaque mapping handle that the system uses to describe the mapping currently +being duplicated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpvtp\fR \fR +.ad +.RS 13n +.rt +Driver private mapping data for the mapping currently being duplicated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInew_dhp\fR \fR +.ad +.RS 13n +.rt +An opaque data structure that the system uses to describe the duplicated device +mapping. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInew_pvtp\fR \fR +.ad +.RS 13n +.rt +A pointer to be filled in by device drivers with the driver private mapping +data for the duplicated device mapping. +.RE + +.SH DESCRIPTION +.sp +.LP +The system calls \fBdevmap_dup()\fR when a device mapping is duplicated, such +as during the execution of the \fBfork\fR(2) system call. The system expects +\fBdevmap_dup()\fR to generate new driver private data for the new mapping, and +to set \fInew_pvtp\fR to point to it. \fInew_dhp\fR is the handle of the new +mapped object. +.sp +.LP +A non-zero return value from \fBdevmap_dup()\fR will cause a corresponding +operation such as \fBfork()\fR to fail. +.SH RETURN VALUES +.sp +.LP +\fBdevmap_dup()\fR returns the following values: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR \fR +.ad +.RS 12n +.rt +Successful completion. +.RE + +.sp +.ne 2 +.mk +.na +\fBNon-zero\fR +.ad +.RS 12n +.rt +An error occurred. +.RE + +.SH EXAMPLES +.sp +.in +2 +.nf +static int +xxdevmap_dup(devmap_cookie_t dhp, void *pvtp, \e + devmap_cookie_t new_dhp, + void **new_pvtp) +{ + struct xxpvtdata *prvtdata; + struct xxpvtdata *p = (struct xxpvtdata *)pvtp; + struct xx_softc *softc = p->softc; + mutex_enter(&softc->mutex); + /* Allocate a new private data structure */ + prvtdata = kmem_alloc(sizeof (struct xxpvtdata), KM_SLEEP); + /* Return the new data */ + prvtdata->off = p->off; + prvtdata->len = p->len; + prvtdata->ctx = p->ctx; + prvtdata->dhp = new_dhp; + prvtdata->softc = p->softc; + *new_pvtp = prvtdata; + mutex_exit(&softc->mutex); + return (0); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBfork\fR(2), \fBdevmap_callback_ctl\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/devmap_map.9e b/usr/src/man/man9e/devmap_map.9e new file mode 100644 index 0000000000..e94d758535 --- /dev/null +++ b/usr/src/man/man9e/devmap_map.9e @@ -0,0 +1,217 @@ +'\" te +.\" Copyright (c) 1996, 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_map 9E "7 Jan 1997" "SunOS 5.11" "Driver Entry Points" +.SH NAME +devmap_map \- device mapping create entry point +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBdevmap_map\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBdev_t\fR \fIdev\fR, + \fBuint_t\fR \fIflags\fR, \fBoffset_t\fR \fIoff\fR, \fBsize_t\fR \fIlen\fR, \fBvoid **\fR\fIpvtp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIdhp\fR \fR +.ad +.RS 10n +.rt +An opaque mapping handle that the system uses to describe the mapping currently +being created. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR \fR +.ad +.RS 10n +.rt +The device whose memory is to be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR \fR +.ad +.RS 10n +.rt +Flags indicating type of mapping. Possible values are: +.sp +.ne 2 +.mk +.na +\fB\fBMAP_PRIVATE\fR \fR +.ad +.RS 16n +.rt +Changes are private. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMAP_SHARED\fR \fR +.ad +.RS 16n +.rt +Changes should be shared. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoff\fR \fR +.ad +.RS 10n +.rt +User offset within the logical device memory at which the mapping begins. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR \fR +.ad +.RS 10n +.rt +Length (in bytes) of the memory to be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpvtp\fR \fR +.ad +.RS 10n +.rt +A pointer to be filled in by device drivers with the driver private mapping +data. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdevmap_map()\fR entry point is an optional routine that allows drivers +to perform additional processing or to allocate private resources during the +mapping setup time. For example, in order for device drivers to support +context switching, the drivers allocate private mapping data and associate the +private data with the mapping parameters in the \fBdevmap_map()\fR entry point. +.sp +.LP +The system calls \fBdevmap_map()\fR after the user mapping to device physical +memory has been established. (For example, after the \fBdevmap\fR(9E) entry +point is called.) +.sp +.LP +\fBdevmap_map()\fR receives a pointer to the driver private data for this +mapping in \fIpvtp\fR. The system expects the driver to allocate its private +data and set \fI*pvtp\fR to the allocated data. The driver must store +\fIoff\fR and \fIlen\fR, which define the range of the mapping, in its private +data. Later, when the system calls \fBdevmap_unmap\fR(9E), the driver will use +the \fIoff\fR and \fIlen\fR stored in \fIpvtp\fR to check if the entire +mapping, or just a part of it, is being unmapped. If only a part of the mapping +is being unmapped, the driver must allocate a new private data for the +remaining mapping before freeing the old private data. The driver will receive +\fI*pvtp\fR in subsequent event notification callbacks. +.sp +.LP +If the driver support context switching, it should store the mapping handle +\fIdhp\fR in its private data \fI*pvtp\fR for later use in +\fBdevmap_unload\fR(9F). +.sp +.LP +For a driver that supports context switching, \fIflags\fR indicates whether or +not the driver should allocate a private context for the mapping. For +example, a driver may allocate a memory region to store the device context if +\fIflags\fR is set to \fBMAP_PRIVATE\fR. +.SH RETURN VALUES +.sp +.LP +\fBdevmap_map()\fR returns the following values: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR \fR +.ad +.RS 12n +.rt +Successful completion. +.RE + +.sp +.ne 2 +.mk +.na +\fBNon-zero\fR +.ad +.RS 12n +.rt +An error occurred. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fR \fBdevmap_map()\fRimplementation +.sp +.LP +The following shows an example implementation for \fBdevmap_map()\fR. + +.sp +.in +2 +.nf +static int +xxdevmap_map(devmap_cookie_t dhp, dev_t dev, uint_t flags, \e + offset_t off,size_t len, void **pvtp) +{ + struct xx_resources *pvt; + struct xx_context *this_context; + struct xx_softc *softc; + softc = ddi_get_soft_state(statep, getminor(dev)); + + this_context = get_context(softc, off, len); + + /* allocate resources for the mapping - Device dependent */ + pvt = kmem_zalloc(sizeof (struct xx_resources), KM_SLEEP); + + pvt->off = off; + pvt->len = len; + pvt->dhp = dhp; + pvt->ctx = this_context; + *pvtp = pvt; +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBdevmap_unmap\fR(9E), \fBdevmap_unload\fR(9F), \fBdevmap_callback_ctl\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/devmap_unmap.9e b/usr/src/man/man9e/devmap_unmap.9e new file mode 100644 index 0000000000..68a690e485 --- /dev/null +++ b/usr/src/man/man9e/devmap_unmap.9e @@ -0,0 +1,218 @@ +'\" te +.\" Copyright (c) 1996, 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_unmap 9E "21 Jan 1997" "SunOS 5.11" "Driver Entry Points" +.SH NAME +devmap_unmap \- device mapping unmap entry point +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid prefix\fR\fBdevmap_unmap\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBvoid *\fR\fIpvtp\fR, + \fBoffset_t\fR \fIoff\fR, \fBsize_t\fR\fIlen\fR, \fBdevmap_cookie_t\fR \fInew_dhp1\fR, + \fBvoid **\fR\fInew_pvtp1\fR, \fBdevmap_cookie_t\fR\fInew_dhp2\fR, \fBvoid **\fR\fInew_pvtp2\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIdhp\fR \fR +.ad +.RS 14n +.rt +An opaque mapping handle that the system uses to describe the mapping. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpvtp\fR \fR +.ad +.RS 14n +.rt +Driver private mapping data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoff\fR \fR +.ad +.RS 14n +.rt +User offset within the logical device memory at which the unmapping begins. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR \fR +.ad +.RS 14n +.rt +Length (in bytes) of the memory being unmapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInew_dhp1\fR \fR +.ad +.RS 14n +.rt +The opaque mapping handle that the system uses to describe the new region that +ends at (\fIoff\fR - 1) . \fInew_dhp1\fR may be \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInew_pvtp1\fR \fR +.ad +.RS 14n +.rt +A pointer to be filled in by the driver with the driver private mapping data +for the new region that ends at (\fIoff\fR - 1); ignored if \fInew_dhp1\fR is +\fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInew_dhp2\fR \fR +.ad +.RS 14n +.rt +The opaque mapping handle that the system uses to describe the new region that +begins at (\fIoff \fR + \fIlen\fR); \fInew_dhp2\fR may be \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInew_pvtp2\fR \fR +.ad +.RS 14n +.rt +A pointer to be filled in by the driver with the driver private mapping data +for the new region that begins at (\fIoff\fR + \fIlen\fR); ignored if +\fInew_dhp2\fR is \fINULL\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBdevmap_unmap()\fR is called when the system removes the mapping in the range +[ \fIoff\fR, \fIoff\fR + \fIlen\fR ], such as in the \fBmunmap\fR(2) or +\fBexit\fR(2) system calls. Device drivers use \fBdevmap_unmap()\fR to free up +the resources allocated in \fBdevmap_map\fR(9E). +.sp +.LP +\fIdhp\fR is the mapping handle that uniquely identifies the mapping. The +driver stores the mapping attributes in the driver's private data, \fIpvtp\fR, +when the mapping is created. See \fBdevmap_map\fR(9E) for details. +.sp +.LP +\fIoff\fR and \fIlen\fR define the range to be affected by +\fBdevmap_unmap()\fR. This range is within the boundary of the mapping +described by \fIdhp\fR. +.sp +.LP +If the range [ \fIoff\fR, \fIoff\fR + \fIlen\fR ] covers the entire mapping, +the system passes \fINULL\fR to \fInew_dhp1\fR, \fInew_pvtp1\fR, +\fInew_dhp2\fR, and \fInew_pvtp2\fR. The system expects device drivers to free +all resources allocated for this mapping. +.sp +.LP +If \fIoff\fR is at the beginning of the mapping and \fIlen\fR does not cover +the entire mapping, the system sets \fINULL\fR to \fInew_dhp1\fR and to +\fInew_pvtp1\fR. The system expects the drivers to allocate new driver private +data for the region that starts at \fIoff\fR + \fIlen\fR and to set +\fI*new_pvtp2\fR to point to it. \fInew_dhp2\fR is the mapping handle of the +newly mapped object. +.sp +.LP +If \fIoff\fR is not at the beginning of the mapping, but \fIoff\fR + \fIlen\fR +is at the end of the mapping the system passes \fINULL\fR to \fInew_dhp2\fR +and \fInew_pvtp2\fR. The system then expects the drivers to allocate new driver +private data for the region that begins at the beginning of the mapping (for +example, stored in \fIpvtp\fR) and to set \fI*new_pvtp1\fR to point to it. +\fInew_dhp1\fR is the mapping handle of the newly mapped object. +.sp +.LP +The drivers should free up the driver private data, \fIpvtp\fR, previously +allocated in \fBdevmap_map\fR(9E) before returning to the system. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBdevmap_unmap()\fR implementation +.sp +.in +2 +.nf +static void +xxdevmap_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) +{ + struct xxpvtdata *ptmp; + struct xxpvtdata *p = (struct xxpvtdata *)pvtp; + struct xx_softc *softc = p->softc; + mutex_enter(&softc->mutex); + /* + * If new_dhp1 is not NULL, create a new driver private data + * for the region from the beginning of old mapping to off. + */ + if (new_dhp1 != NULL) { + ptmp = kmem_zalloc(sizeof (struct xxpvtdata), KM_SLEEP); + ptmp->dhp = new_dhp1; + ptmp->off = pvtp->off; + ptmp->len = off - pvtp->off; + *new_pvtp1 = ptmp; + } + + /* + * If new_dhp2 is not NULL, create a new driver private data + * for the region from off+len to the end of the old mapping. + */ + if (new_dhp2 != NULL) { + ptmp = kmem_zalloc(sizeof (struct xxpvtdata), KM_SLEEP); + ptmp->off = off + len; + ptmp->len = pvpt->len - (off + len - pvtp->off); + ptmp->dhp = new_dhp2; + *new_pvtp2 = ptmp; + } + + /* Destroy the driver private data - Device dependent */ + ... + kmem_free(pvtp, sizeof (struct xxpvtdata)); + mutex_exit(&softc->mutex); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBexit\fR(2), \fBmunmap\fR(2), \fBdevmap_map\fR(9E), +\fBdevmap_callback_ctl\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/dump.9e b/usr/src/man/man9e/dump.9e new file mode 100644 index 0000000000..d11ffa77a2 --- /dev/null +++ b/usr/src/man/man9e/dump.9e @@ -0,0 +1,99 @@ +'\" te +.\" Copyright (c) 1992, 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 dump 9E "9 Oct 2001" "SunOS 5.11" "Driver Entry Points" +.SH NAME +dump \- dump memory to device during system failure +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBdump\fR(\fBdev_t\fR \fIdev\fR, \fBcaddr_t\fR \fIaddr\fR, \fBdaddr_t\fR \fIblkno\fR, \fBint\fR \fInblk\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris specific (Solaris DDI). This entry point is \fBrequired\fR. For drivers +that do not implement \fBdump()\fR routines, \fBnodev\fR(9F) should be used. +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR \fR +.ad +.RS 10n +.rt +Device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR \fR +.ad +.RS 10n +.rt +Address for the beginning of the area to be dumped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIblkno\fR \fR +.ad +.RS 10n +.rt +Block offset to dump memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInblk\fR \fR +.ad +.RS 10n +.rt +Number of blocks to dump. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBdump()\fR is used to dump a portion of virtual address space directly to a +device in the case of system failure. It can also be used for checking the +state of the kernel during a checkpoint operation. The memory area to be dumped +is specified by \fIaddr\fR (base address) and \fInblk\fR (length). It is dumped +to the device specified by \fIdev\fR starting at offset \fIblkno\fR. Upon +completion \fBdump()\fR returns the status of the transfer. +.sp +.LP +When the system is panicking, the calls of functions scheduled by +\fBtimeout\fR(9F) and \fBddi_trigger_softintr\fR(9F) will never occur. Neither +can delay(9F) be relied upon, since it is implemented via \fBtimeout()\fR. See +\fBddi_in_panic\fR(9F). +.sp +.LP +\fBdump()\fR is called at interrupt priority. +.SH RETURN VALUES +.sp +.LP +\fBdump()\fR returns \fB0\fR on success, or the appropriate error number. +.SH SEE ALSO +.sp +.LP +\fBcpr\fR(7), \fBnodev\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/getinfo.9e b/usr/src/man/man9e/getinfo.9e new file mode 100644 index 0000000000..bb80b58ec2 --- /dev/null +++ b/usr/src/man/man9e/getinfo.9e @@ -0,0 +1,175 @@ +'\" te +.\" Copyright (c) 2004, 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 getinfo 9E "16 Jan 2008" "SunOS 5.11" "Driver Entry Points" +.SH NAME +getinfo \- get device driver information +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBgetinfo\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_info_cmd_t\fR \fIcmd\fR, + \fBvoid *\fR\fIarg\fR, \fBvoid **\fR\fIresultp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). This entry point is \fBrequired\fR for +drivers which export \fBcb_ops\fR(9S) entry points. +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 11n +.rt +Do not use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmd\fR\fR +.ad +.RS 11n +.rt +Command argument - valid command values are \fBDDI_INFO_DEVT2DEVINFO\fR and +\fBDDI_INFO_DEVT2INSTANCE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 11n +.rt +Command specific argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIresultp\fR\fR +.ad +.RS 11n +.rt +Pointer to where the requested information is stored. +.RE + +.SH DESCRIPTION +.sp +.LP +When \fIcmd\fR is set to \fBDDI_INFO_DEVT2DEVINFO\fR, \fBgetinfo()\fR should +return the \fBdev_info_t\fR pointer associated with the \fBdev_t\fR \fIarg\fR. +The \fBdev_info_t\fR pointer should be returned in the field pointed to by +\fIresultp\fR. +.sp +.LP +When \fIcmd\fR is set to \fBDDI_INFO_DEVT2INSTANCE\fR, \fBgetinfo()\fR should +return the instance number associated with the \fBdev_t\fR \fIarg\fR. The +instance number should be returned in the field pointed to by \fIresultp\fR. +.sp +.LP +Drivers which do not export \fBcb_ops\fR(9S) entry points are not required to +provide a \fBgetinfo()\fR entry point, and may use \fBnodev\fR(9F) in the +\fBdevo_getinfo\fR field of the \fBdev_ops\fR(9S) structure. A \fBSCSI HBA +\fRdriver is an example of a driver which is not required to provide +\fBcb_ops\fR(9S) entry points. +.SH RETURN VALUES +.sp +.LP +\fBgetinfo()\fR should return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +on success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +on failure. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBgetinfo()\fR implementation +.sp +.in +2 +.nf +/*ARGSUSED*/ +static int +rd_getinfo(dev_info_t *dip, ddi_info_cmd_t infocmd, void *arg, \e +void **resultp) +{ + /* Note that in this simple example + * the minor number is the instance + * number. */ + + devstate_t *sp; + int error = DDI_FAILURE; + switch (infocmd) { + case DDI_INFO_DEVT2DEVINFO: + if ((sp = ddi_get_soft_state(statep, + getminor((dev_t) arg))) != NULL) { + *resultp = sp->devi; + error = DDI_SUCCESS; + } else + *result = NULL; + break; + + case DDI_INFO_DEVT2INSTANCE: + *resultp = (void *) (uintptr_t) getminor((dev_t) arg); + error = DDI_SUCCESS; + break; + } + + return (error); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBddi_no_info\fR(9F), \fBnodev\fR(9F), \fBcb_ops\fR(9S), \fBdev_ops\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Non-\fBgld\fR(7D)-based DLPI network streams drivers are encouraged to switch +to \fBgld\fR(7D). Failing this, a driver that creates DLPI style-2 minor +nodes must specify CLONE_DEV for its style-2 \fBddi_create_minor_node\fR(9F) +nodes and use \fBqassociate\fR(9F). A driver that supports both style-1 and +style-2 minor nodes should return DDI_FAILURE for DDI_INFO_DEVT2INSTANCE and +DDI_INFO_DEVT2DEVINFO \fBgetinfo()\fR calls to style-2 minor nodes. (The +correct association is already established by \fBqassociate\fR(9F)). A driver +that only supports style-2 minor nodes can use \fBddi_no_info\fR(9F) for its +\fBgetinfo()\fR implementation. For drivers that do not follow these rules, the +results of a \fBmodunload\fR(1M) of the driver or a \fBcfgadm\fR(1M) remove of +hardware controlled by the driver are undefined. diff --git a/usr/src/man/man9e/gld.9e b/usr/src/man/man9e/gld.9e new file mode 100644 index 0000000000..23aad25060 --- /dev/null +++ b/usr/src/man/man9e/gld.9e @@ -0,0 +1,453 @@ +'\" 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 gld 9E "3 Jan 2001" "SunOS 5.11" "Driver Entry Points" +.SH NAME +gld, gldm_reset, gldm_start, gldm_stop, gldm_set_mac_addr, gldm_set_multicast, +gldm_set_promiscuous, gldm_send, gldm_intr, gldm_get_stats, gldm_ioctl \- +Generic LAN Driver entry points +.SH SYNOPSIS +.LP +.nf +#include <sys/gld.h> + +\fBint\fR \fBprefix_reset\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR); +.fi + +.LP +.nf +\fBint\fR \fBprefix_start\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR); +.fi + +.LP +.nf +\fBint\fR \fBprefix_stop\fR(\fBgld_mac_info_t *\fR + \fImacinfo\fR); +.fi + +.LP +.nf +\fBint\fR \fBprefix_set_mac_addr\fR(\fBgld_mac_info_t *\fR + \fImacinfo\fR, \fBunsigned char *\fR\fImacaddr\fR); +.fi + +.LP +.nf +\fBint\fR \fBprefix_set_multicast\fR(\fBgld_mac_info_t *\fR + \fImacinfo\fR, \fBunsigned char *\fR\fImulticastaddr\fR, + \fBint\fR \fImultiflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBprefix_set_promiscuous\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR, + \fBint\fR \fIpromiscflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBprefix_send\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR, + \fBmblk_t *\fR\fImp\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBprefix_intr\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR); +.fi + +.LP +.nf +\fBint\fR \fBprefix_get_stats\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR, + \fBstruct gld_stats *\fR\fIstats\fR); +.fi + +.LP +.nf +\fBint\fR \fBprefix_ioctl\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR, + \fBqueue_t *\fR\fIq\fR, \fBmblk_t *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImacinfo\fR \fR +.ad +.RS 18n +.rt +Pointer to a \fBgld_mac_info\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImacaddr\fR \fR +.ad +.RS 18n +.rt +Pointer to the beginning of a character array containing a valid MAC address. +The array will be of the length specified by the driver in the +\fBgldm_addrlen\fR element of the \fBgld_mac_info\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImulticastaddr\fR \fR +.ad +.RS 18n +.rt +Pointer to the beginning of a character array containing a multicast, group, or +functional address. The array will be of the length specified by the driver in +the \fBgldm_addrlen\fR element of the \fBgld_mac_info\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImultiflag\fR \fR +.ad +.RS 18n +.rt +A flag indicating whether reception of the multicast address is to be enabled +or disabled. This argument is specified as \fBGLD_MULTI_ENABLE\fR or +\fBGLD_MULTI_DISABLE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpromiscflag\fR \fR +.ad +.RS 18n +.rt +A flag indicating what type of promiscuous mode, if any, is to be enabled. This +argument is specified as \fBGLD_MAC_PROMISC_PHYS\fR, +\fBGLD_MAC_PROMISC_MULTI\fR, or \fBGLD_MAC_PROMISC_NONE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR \fR +.ad +.RS 18n +.rt +Pointer to a STREAMS message block containing the packet to be transmitted or +the ioctl to be executed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstats\fR \fR +.ad +.RS 18n +.rt +Pointer to a \fBgld_stats\fR(9S) structure to be filled in with the current +values of statistics counters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIq\fR \fR +.ad +.RS 18n +.rt +Pointer to the \fBqueue\fR(9S) structure to be used in the reply to the ioctl. +.RE + +.SH DESCRIPTION +.sp +.LP +These entry points must be implemented by a device-specific network driver +designed to interface with the Generic LAN Driver (GLD). +.sp +.LP +As described in \fBgld\fR(7D), the main data structure for communication +between the device-specific driver and the GLD module is the +\fBgld_mac_info\fR(9S) structure. Some of the elements in that structure are +function pointers to the entry points described here. The device-specific +driver must, in its \fBattach\fR(9E) routine, initialize these function +pointers before calling \fBgld_register\fR(\|). +.sp +.LP +\fBgldm_reset\fR(\|) resets the hardware to its initial state. +.sp +.LP +\fBgldm_start\fR(\|) enables the device to generate interrupts and prepares the +driver to call \fBgld_recv\fR(\|) for delivering received data packets to GLD. +.sp +.LP +\fBgldm_stop\fR(\|) disables the device from generating any interrupts and +stops the driver from calling \fBgld_recv\fR(\|) for delivering data packets to +GLD. GLD depends on the \fBgldm_stop\fR(\|) routine to ensure that the device +will no longer interrupt, and it must do so without fail. +.sp +.LP +\fBgldm_set_mac_addr\fR(\|) sets the physical address that the hardware is to +use for receiving data. This function should program the device to the passed +MAC address \fImacaddr\fR. +.sp +.LP +\fBgldm_set_multicast\fR(\|) enables and disables device-level reception of +specific multicast addresses. If the third argument \fImultiflag\fR is set to +\fBGLD_MULTI_ENABLE\fR, then the function sets the interface to receive packets +with the multicast address pointed to by the second argument; if +\fImultiflag\fR is set to \fBGLD_MULTI_DISABLE\fR, the driver is allowed to +disable reception of the specified multicast address. +.sp +.LP +This function is called whenever GLD wants to enable or disable reception of a +multicast, group, or functional address. GLD makes no assumptions about how the +device does multicast support and calls this function to enable or disable a +specific multicast address. Some devices may use a hash algorithm and a bitmask +to enable collections of multicast addresses; this is allowed, and GLD will +filter out any superfluous packets that are not required. If disabling an +address could result in disabling more than one address at the device level, it +is the responsibility of the device driver to keep whatever information it +needs to avoid disabling an address that GLD has enabled but not disabled. +.sp +.LP +\fBgldm_set_multicast\fR(\|) will not be called to enable a particular +multicast address that is already enabled, nor to disable an address that is +not currently enabled. GLD keeps track of multiple requests for the same +multicast address and only calls the driver's entry point when the first +request to enable, or the last request to disable a particular multicast +address is made. +.sp +.LP +\fBgldm_set_promiscuous\fR(\|) enables and disables promiscuous mode. This +function is called whenever GLD wants to enable or disable the reception of all +packets on the medium, or all multicast packets on the medium. If the second +argument \fIpromiscflag\fR is set to the value of \fBGLD_MAC_PROMISC_PHYS\fR, +then the function enables physical-level promiscuous mode, resulting in the +reception of all packets on the medium. If \fIpromiscflag\fR is set to +\fBGLD_MAC_PROMISC_MULTI\fR, then reception of all multicast packets will be +enabled. If \fIpromiscflag\fR is set to \fBGLD_MAC_PROMISC_NONE\fR, then +promiscuous mode is disabled. +.sp +.LP +In the case of a request for promiscuous multicast mode, drivers for devices +that have no multicast-only promiscuous mode must set the device to physical +promiscuous mode to ensure that all multicast packets are received. In this +case the routine should return \fBGLD_SUCCESS\fR. The GLD software will filter +out any superfluous packets that are not required. +.sp +.LP +For forward compatibility, \fBgldm_set_promiscuous\fR(\|) routines should treat +any unrecognized values for \fIpromiscflag\fR as though they were +\fBGLD_MAC_PROMISC_PHYS\fR. +.sp +.LP +\fBgldm_send()\fR queues a packet to the device for transmission. This routine +is passed a STREAMS message containing the packet to be sent. The message may +comprise multiple message blocks, and the send routine must chain through all +the message blocks in the message to access the entire packet to be sent. The +driver should be prepared to handle and skip over any zero-length message +continuation blocks in the chain. The driver should check to ensure that the +packet does not exceed the maximum allowable packet size, and must pad the +packet, if necessary, to the minimum allowable packet size. If the send routine +successfully transmits or queues the packet, it should return +\fBGLD_SUCCESS\fR. +.sp +.LP +The send routine should return \fBGLD_NORESOURCES\fR if it cannot immediately +accept the packet for transmission; in this case GLD will retry it later. If +\fBgldm_send\fR(\|) ever returns \fBGLD_NORESOURCES\fR, the driver must, at a +later time when resources have become available, call \fBgld_sched\fR(\|) to +inform GLD that it should retry packets that the driver previously failed to +queue for transmission. (If the driver's \fBgldm_stop\fR(\|) routine is called, +the driver is absolved from this obligation until it later again returns +\fBGLD_NORESOURCES\fR from its \fBgldm_send\fR(\|) routine; however, extra +calls to \fBgld_sched\fR(\|) will not cause incorrect operation.) +.sp +.LP +If the driver's send routine returns \fBGLD_SUCCESS\fR, then the driver is +responsible for freeing the message when the driver and the hardware no longer +need it. If the send routine copied the message into the device, or into a +private buffer, then the send routine may free the message after the copy is +made. If the hardware uses DMA to read the data directly out of the message +data blocks, then the driver must not free the message until the hardware has +completed reading the data. In this case the driver will probably free the +message in the interrupt routine, or in a buffer-reclaim operation at the +beginning of a future send operation. If the send routine returns anything +other than \fBGLD_SUCCESS\fR, then the driver must not free the message. +.sp +.LP +\fBgldm_intr()\fR is called when the device might have interrupted. Since it is +possible to share interrupts with other devices, the driver must check the +device status to determine whether it actually caused an interrupt. If the +device that the driver controls did not cause the interrupt, then this routine +must return \fBDDI_INTR_UNCLAIMED\fR. Otherwise it must service the interrupt +and should return \fBDDI_INTR_CLAIMED\fR. If the interrupt was caused by +successful receipt of a packet, this routine should put the received packet +into a STREAMS message of type \fBM_DATA\fR and pass that message to +\fBgld_recv\fR(\|). +.sp +.LP +\fBgld_recv()\fR will pass the inbound packet upstream to the appropriate next +layer of the network protocol stack. It is important to correctly set the +\fBb_rptr\fR and \fBb_wptr\fR members of the STREAMS message before calling +\fBgld_recv\fR(\|). +.sp +.LP +The driver should avoid holding mutex or other locks during the call to +\fBgld_recv\fR(\|). In particular, locks that could be taken by a transmit +thread may not be held during a call to \fBgld_recv\fR(\|): the interrupt +thread that calls \fBgld_recv\fR(\|) may in some cases carry out processing +that includes sending an outgoing packet, resulting in a call to the driver's +\fBgldm_send\fR(\|) routine. If the \fBgldm_send\fR(\|) routine were to try to +acquire a mutex being held by the \fBgldm_intr\fR(\|) routine at the time it +calls \fBgld_recv\fR(\|), this could result in a panic due to recursive mutex +entry. +.sp +.LP +The interrupt code should increment statistics counters for any errors. This +includes failure to allocate a buffer needed for the received data and any +hardware-specific errors such as CRC errors or framing errors. +.sp +.LP +\fBgldm_get_stats\fR(\|) gathers statistics from the hardware and/or driver +private counters, and updates the \fBgld_stats\fR(9S) structure pointed to by +\fIstats\fR. This routine is called by GLD when it gets a request for +statistics, and provides the mechanism by which GLD acquires device dependent +statistics from the driver before composing its reply to the statistics +request. See \fBgld_stats\fR(9S) and \fBgld\fR(7D) for a description of the +defined statistics counters. +.sp +.LP +\fBgldm_ioctl\fR(\|) implements any device-specific ioctl commands. This +element may be specified as \fINULL\fR if the driver does not implement any +ioctl functions. The driver is responsible for converting the message block +into an ioctl reply message and calling the \fBqreply\fR(9F) function before +returning \fBGLD_SUCCESS\fR. This function should always return +\fBGLD_SUCCESS\fR; any errors the driver may wish to report should be returned +via the message passed to \fBqreply\fR(9F). If the \fBgldm_ioctl\fR element is +specified as \fINULL\fR, GLD will return a message of type \fBM_IOCNAK\fR with +an error of \fBEINVAL\fR. +.SH RETURN VALUES +.sp +.LP +\fBgldm_intr\fR(\|) must return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_INTR_CLAIMED\fR \fR +.ad +.RS 23n +.rt +if and only if the device definitely interrupted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_INTR_UNCLAIMED\fR \fR +.ad +.RS 23n +.rt +if the device did not interrupt. +.RE + +.sp +.LP +The other functions must return: +.sp +.ne 2 +.mk +.na +\fB\fBGLD_SUCCESS\fR \fR +.ad +.RS 21n +.rt +on success. \fBgldm_stop\fR(\|) and \fBgldm_ioctl\fR(\|) should always return +this value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLD_NORESOURCES\fR \fR +.ad +.RS 21n +.rt +if there are insufficient resources to carry out the request at this time. Only +\fBgldm_set_mac_addr\fR(\|), \fBgldm_set_multicast\fR(\|), +\fBgldm_set_promiscuous\fR(\|), and \fBgldm_send\fR(\|) may return this value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLD_NOLINK\fR \fR +.ad +.RS 21n +.rt +if \fBgldm_send\fR(\|) is called when there is no physical connection to a +network or link partner. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLD_NOTSUPPORTED\fR \fR +.ad +.RS 21n +.rt +if the requested function is not supported. Only \fBgldm_set_mac_addr\fR(\|), +\fBgldm_set_multicast\fR(\|), and \fBgldm_set_promiscuous\fR(\|) may return +this value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLD_BADARG\fR \fR +.ad +.RS 21n +.rt +if the function detected an unsuitable argument, for example, a bad multicast +address, a bad MAC address, or a bad packet or packet length. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLD_FAILURE\fR \fR +.ad +.RS 21n +.rt +on hardware failure. +.RE + +.SH SEE ALSO +.sp +.LP +\fBgld\fR(7D), \fBgld\fR(9F), \fBgld_mac_info\fR(9S), \fBgld_stats\fR(9S), +\fBdlpi\fR(7P), \fBattach\fR(9E), \fBddi_add_intr\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/identify.9e b/usr/src/man/man9e/identify.9e new file mode 100644 index 0000000000..3fd8ee4ffd --- /dev/null +++ b/usr/src/man/man9e/identify.9e @@ -0,0 +1,40 @@ +'\" te +.\" Copyright (c) 2003, 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 identify 9E "11 Apr 2003" "SunOS 5.11" "Driver Entry Points" +.SH NAME +identify \- determine if a driver is associated with a device +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). This entry point is no longer supported. +\fBnulldev\fR(9F) must be specified in the \fBdev_ops\fR(9S) structure. +.SH SEE ALSO +.sp +.LP +\fBnulldev\fR(9F), \fBdev_ops\fR(9S) +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Stability LevelObsolete +.TE + +.SH WARNING +.sp +.LP +For Solaris 10 and later versions, drivers must remove the \fBidentify(9e)\fR +implementation to recompile. Otherwise, the compiler generates errors about +DDI_IDENTIFIED and DDI_NOT_IDENTIFIED. diff --git a/usr/src/man/man9e/ioctl.9e b/usr/src/man/man9e/ioctl.9e new file mode 100644 index 0000000000..710dd3f250 --- /dev/null +++ b/usr/src/man/man9e/ioctl.9e @@ -0,0 +1,307 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 1996, 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 ioctl 9E "3 Dec 1996" "SunOS 5.11" "Driver Entry Points" +.SH NAME +ioctl \- control a character device +.SH SYNOPSIS +.LP +.nf +#include <sys/cred.h> +#include <sys/file.h> +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBioctl\fR(\fBdev_t\fR \fIdev\fR, \fBint\fR \fIcmd\fR, \fBintptr_t\fR \fIarg\fR, \fBint\fR \fImode\fR, + \fBcred_t *\fR\fIcred_p\fR, \fBint *\fR\fIrval_p\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). This entry point is \fBoptional\fR. +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 10n +.rt +Device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmd\fR\fR +.ad +.RS 10n +.rt +Command argument the driver \fBioctl()\fR routine interprets as the operation +to be performed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 10n +.rt +Passes parameters between a user program and the driver. When used with +terminals, the argument is the address of a user program structure containing +driver or hardware settings. Alternatively, the argument may be a value that +has meaning only to the driver. The interpretation of the argument is driver +dependent and usually depends on the command type; the kernel does not +interpret the argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImode\fR\fR +.ad +.RS 10n +.rt +A bit field that contains: +.RS +4 +.TP +.ie t \(bu +.el o +Information set when the device was opened. The driver may use it to determine +if the device was opened for reading or writing. The driver can make this +determination by checking the \fBFREAD\fR or \fBFWRITE\fR flags. See the +\fIflag\fR argument description of the \fBopen()\fR routine for further +values. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Information on whether the caller is a 32-bit or 64-bit thread. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +In some circumstances address space information about the \fIarg\fR argument. +See below. +.RE +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcred_p\fR\fR +.ad +.RS 10n +.rt +Pointer to the user credential structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrval_p\fR\fR +.ad +.RS 10n +.rt +Pointer to return value for calling process. The driver may elect to set the +value which is valid only if the \fBioctl()\fR succeeds. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBioctl()\fR provides character-access drivers with an alternate entry point +that can be used for almost any operation other than a simple transfer of +characters in and out of buffers. Most often, \fBioctl()\fR is used to control +device hardware parameters and establish the protocol used by the driver in +processing data. +.sp +.LP +The kernel determines that this is a character device, and looks up the entry +point routines in \fBcb_ops\fR(9S). The kernel then packages the user request +and arguments as integers and passes them to the driver's \fBioctl()\fR +routine. The kernel itself does no processing of the passed command, so it is +up to the user program and the driver to agree on what the arguments mean. +.sp +.LP +I/O control commands are used to implement the terminal settings passed from +\fBttymon\fR(1M) and \fBstty\fR(1), to format disk devices, to implement a +trace driver for debugging, and to clean up character queues. Since the kernel +does not interpret the command type that defines the operation, a driver is +free to define its own commands. +.sp +.LP +Drivers that use an \fBioctl()\fR routine typically have a command to ``read'' +the current \fBioctl()\fR settings, and at least one other that sets new +settings. Drivers can use the \fImode\fR argument to determine if the device +unit was opened for reading or writing, if necessary, by checking the +\fBFREAD\fR or \fBFWRITE\fR setting. +.sp +.LP +If the third argument, \fIarg\fR, is a pointer to a user buffer, the driver +can call the \fBcopyin\fR(9F) and \fBcopyout\fR(9F) functions to transfer data +between kernel and user space. +.sp +.LP +Other kernel subsystems may need to call into the drivers \fBioctl()\fR +routine. Drivers that intend to allow their \fBioctl()\fR routine to be used +in this way should publish the \fBddi-kernel-ioctl\fR property on the +associated devinfo node(s). +.sp +.LP +When the \fBddi-kernel-ioctl\fR property is present, the \fImode\fR argument is +used to pass address space information about \fIarg\fR through to the driver. +If the driver expects \fIarg\fR to contain a buffer address, and the +\fBFKIOCTL\fR flag is set in \fImode\fR, then the driver should assume that it +is being handed a kernel buffer address. Otherwise, \fIarg\fR may be the +address of a buffer from a user program. The driver can use +\fBddi_copyin\fR(9F) and \fBddi_copyout\fR(9F) perform the correct type of copy +operation for either kernel or user address spaces. See the example on +\fBddi_copyout\fR(9F). +.sp +.LP +Drivers have to interact with 32-bit and 64-bit applications. If a device +driver shares data structures with the application (for example, through +exported kernel memory) and the driver gets recompiled for a 64-bit kernel but +the application remains 32-bit, binary layout of any data structures will be +incompatible if they contain longs or pointers. The driver needs to know +whether there is a model mismatch between the current thread and the kernel and +take necessary action. The \fImode\fR argument has additional bits set to +determine the C Language Type Model which the current thread expects. +\fImode\fR has \fBFILP32\fR set if the current thread expects 32-bit ( +\fIILP32\fR) semantics, or \fBFLP64\fR if the current thread expects 64-bit ( +\fILP64\fR) semantics. \fImode\fR is used in combination with +\fBddi_model_convert_from\fR(9F) and the \fBFMODELS\fR mask to determine +whether there is a data model mismatch between the current thread and the +device driver (see the example below). The device driver might have to adjust +the shape of data structures before exporting them to a user thread which +supports a different data model. +.sp +.LP +To implement I/O control commands for a driver the following two steps are +required: +.RS +4 +.TP +1. +Define the I/O control command names and the associated value in the +driver's header and comment the commands. +.RE +.RS +4 +.TP +2. +Code the \fBioctl()\fR routine in the driver that defines the functionality +for each I/O control command name that is in the header. +.RE +.sp +.LP +The \fBioctl()\fR routine is coded with instructions on the proper action to +take for each command. It is commonly a \fBswitch\fR statement, with each +\fBcase\fR definition corresponding to an \fBioctl()\fR name to identify the +action that should be taken. However, the command passed to the driver by the +user process is an integer value associated with the command name in the +header. +.SH RETURN VALUES +.sp +.LP +\fBioctl()\fR should return \fB0\fR on success, or the appropriate error +number. The driver may also set the value returned to the calling process +through \fIrval_p\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBioctl()\fR entry point +.sp +.LP +The following is an example of the \fBioctl()\fR entry point and how to support +32-bit and 64-bit applications with the same device driver. + +.sp +.in +2 +.nf +struct passargs32 { + int len; + caddr32_t addr; +}; + +struct passargs { + int len; + caddr_t addr; +}; + +xxioctl(dev_t dev, int cmd, intptr_t arg, int mode, + cred_t *credp, int *rvalp) { + struct passargs pa; + +#ifdef _MULTI_DATAMODEL + switch (ddi_model_convert_from(mode & FMODELS)) { + case DDI_MODEL_ILP32: + { + struct passargs32 pa32; + + ddi_copyin(arg, &pa32, sizeof (struct passargs32),\e + mode); + pa.len = pa32.len; + pa.address = pa32.address; + break; + } + case DDI_MODEL_NONE: + ddi_copyin(arg, &pa, sizeof (struct passargs),\e + mode); + break; + } +#else /* _MULTI_DATAMODEL */ + ddi_copyin(arg, &pa, sizeof (struct passargs), mode); +#endif /* _MULTI_DATAMODEL */ + + do_ioctl(&pa); + .\|.\|.\|. +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBstty\fR(1), \fBttymon\fR(1M), \fBdkio\fR(7I), \fBfbio\fR(7I), +\fBtermio\fR(7I), \fBopen\fR(9E), \fBput\fR(9E), \fBsrv\fR(9E), +\fBcopyin\fR(9F), \fBcopyout\fR(9F), \fBddi_copyin\fR(9F), +\fBddi_copyout\fR(9F), \fBddi_model_convert_from\fR(9F), \fBcb_ops\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +Non-STREAMS driver \fBioctl()\fR routines must make sure that user data is +copied into or out of the kernel address space explicitly using +\fBcopyin\fR(9F), \fBcopyout\fR(9F), \fBddi_copyin\fR(9F), or +\fBddi_copyout\fR(9F), as appropriate. +.sp +.LP +It is a severe error to simply dereference pointers to the user address space, +even when in user context. +.sp +.LP +Failure to use the appropriate copying routines can result in panics under load +on some platforms, and reproducible panics on others. +.SH NOTES +.sp +.LP +STREAMS drivers do not have \fBioctl()\fR routines. The stream head converts +I/O control commands to \fBM_IOCTL\fR messages, which are handled by the +driver's \fBput\fR(9E) or \fBsrv\fR(9E) routine. diff --git a/usr/src/man/man9e/ks_snapshot.9e b/usr/src/man/man9e/ks_snapshot.9e new file mode 100644 index 0000000000..3d62faefdf --- /dev/null +++ b/usr/src/man/man9e/ks_snapshot.9e @@ -0,0 +1,217 @@ +'\" 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 ks_snapshot 9E "4 Dec 2002" "SunOS 5.11" "Driver Entry Points" +.SH NAME +ks_snapshot \- take a snapshot of kstat data +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kstat.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fB_ks_snapshot\fR(\fBkstat_t *\fR\fIksp\fR, \fBvoid *\fR\fIbuf\fR, \fBint\fR \fIrw\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIksp\fR \fR +.ad +.RS 8n +.rt +Pointer to a \fBkstat\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuf\fR \fR +.ad +.RS 8n +.rt +Pointer to a buffer to copy the snapshot into. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrw\fR \fR +.ad +.RS 8n +.rt +Read/Write flag. Possible values are: +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_READ\fR\fR +.ad +.RS 15n +.rt +Copy driver statistics from the driver to the buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_WRITE\fR\fR +.ad +.RS 15n +.rt +Copy statistics from the buffer to the driver. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBkstat\fR mechanism allows for an optional \fBks_snapshot()\fR function +to copy \fBkstat\fR data. This is the routine that is called to marshall the +\fBkstat\fR data to be copied to user-land. A driver can opt to use a custom +snapshot routine rather than the default snapshot routine; to take advantage of +this feature, set the \fBks_snapshot\fR field before calling +\fBkstat_install\fR(9F). +.sp +.LP +The \fBks_snapshot()\fR function must have the following structure: +.sp +.in +2 +.nf +static int +xx_kstat_snapshot(kstat_t *ksp, void *buf, int rw) +{ + if (rw == KSTAT_WRITE) { +/* set the native stats to the values in buf */ +/* return EACCES if you don't support this */ + } else { +/* copy the kstat-specific data into buf */ + } + return (0); +} +.fi +.in -2 +.sp + +.sp +.LP +In general, the \fBks_snapshot()\fR routine might need to refer to +provider-private data; for example, it might need a pointer to the provider's +raw statistics. The \fBks_private\fR field is available for this purpose. Its +use is entirely at the provider's discretion. +.sp +.LP +No \fBkstat\fR locking should be done inside the \fBks_update()\fR routine. The +caller will already be holding the \fBkstat\fR's \fBks_lock\fR (to ensure +consistent data) and will prevent the \fBkstat\fR from being removed. +.RS +4 +.TP +1. +\fBks_snaptime\fR must be set (via \fBgethrtime\fR(9F)) to timestamp the +data. +.RE +.RS +4 +.TP +2. +Data gets copied from the \fBkstat\fR to the buffer on \fBKSTAT_READ\fR, and +from the buffer to the \fBkstat\fR on \fBKSTAT_WRITE\fR. +.RE +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 10n +.rt +Success +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +.rt +If \fBKSTAT_WRITE\fR is not allowed +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR\fR +.ad +.RS 10n +.rt +For any other error +.RE + +.SH CONTEXT +.sp +.LP +This function is called from user context only. +.SH EXAMPLES +.LP +\fBExample 1 \fRNamed \fBkstat\fRs with Long Strings (\fBKSTAT_DATA_STRING\fR) +.sp +.in +2 +.nf +static int +xxx_kstat_snapshot(kstat_t *ksp, void *buf, int rw) +{ + if (rw == KSTAT_WRITE) { + return (EACCES); + } else { + kstat_named_t *knp = buf; + char *end = knp + ksp->ks_ndata; + uint_t i; + + bcopy(ksp->ks_data, buf, + sizeof (kstat_named_t) * ksp->ks_ndata); +/* + * Now copy the strings to the end of the buffer, and + * update the pointers appropriately. + */ + for (i = 0; i < ksp->ks_ndata; i++, knp++) + if (knp->data_type == KSTAT_DATA_STRING && + KSTAT_NAMED_STR_PTR(knp) != NULL) { + bcopy(KSTAT_NAMED_STR_PTR(knp), end, + KSTAT_NAMED_STR_BUFLEN(knp)); + KSTAT_NAMED_STR_PTR(knp) = end; + end += KSTAT_NAMED_STR_BUFLEN(knp); + } + } + return (0); +} +.fi +.in -2 +.sp + +.SH SEE ALSO +.sp +.LP +\fBks_update\fR(9E), \fBkstat_create\fR(9F), \fBkstat_install\fR(9F), +\fBkstat\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/ks_update.9e b/usr/src/man/man9e/ks_update.9e new file mode 100644 index 0000000000..ebbb410a1b --- /dev/null +++ b/usr/src/man/man9e/ks_update.9e @@ -0,0 +1,155 @@ +'\" te +.\" Copyright (c) 1994, 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 ks_update 9E "27 May 1994" "SunOS 5.11" "Driver Entry Points" +.SH NAME +ks_update \- dynamically update kstats +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kstat.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fB_ks_update\fR(\fBkstat_t *\fR\fIksp\fR, \fBint\fR \fIrw\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIksp\fR \fR +.ad +.RS 8n +.rt +Pointer to a \fBkstat\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrw\fR \fR +.ad +.RS 8n +.rt +Read/Write flag. Possible values are +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_READ\fR \fR +.ad +.RS 16n +.rt +Update \fBkstat\fR structure statistics from the driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_WRITE\fR \fR +.ad +.RS 16n +.rt +Update driver statistics from the kstat structure. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The kstat mechanism allows for an optional \fBks_update()\fR function to update +kstat data. This is useful for drivers where the underlying device keeps cheap +hardware statistics, but extraction is expensive. Instead of constantly +keeping the kstat data section up to date, the driver can supply a +\fBks_update()\fR function which updates the kstat's data section on demand. To +take advantage of this feature, set the \fBks_update\fR field before calling +\fBkstat_install\fR(9F). +.sp +.LP +The \fBks_update()\fR function must have the following structure: +.sp +.in +2 +.nf +static int +xx_kstat_update(kstat_t *ksp, int rw) +{ + if (rw == KSTAT_WRITE) { + /* update the native stats from ksp->ks_data */ + /* return EACCES if you don't support this */ + } else { + /* update ksp->ks_data from the native stats */ + } + return (0); +} +.fi +.in -2 + +.sp +.LP +In general, the \fBks_update()\fR routine may need to refer to provider-private +data; for example, it may need a pointer to the provider's raw statistics. The +\fBks_private\fR field is available for this purpose. Its use is entirely at +the provider's discretion. +.sp +.LP +No \fBkstat\fR locking should be done inside the \fBks_update()\fR routine. +The caller will already be holding the \fBkstat's\fR \fBks_lock\fR (to ensure +consistent data) and will prevent the \fBkstat\fR from being removed. +.SH RETURN VALUES +.sp +.LP +\fBks_update()\fR should return +.sp +.ne 2 +.mk +.na +\fB\fB0\fR \fR +.ad +.RS 11n +.rt +For success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR \fR +.ad +.RS 11n +.rt +If \fBKSTAT_WRITE\fR is not allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEIO\fR \fR +.ad +.RS 11n +.rt +For any other error. +.RE + +.SH SEE ALSO +.sp +.LP +\fBkstat_create\fR(9F), \fBkstat_install\fR(9F), \fBkstat\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/mmap.9e b/usr/src/man/man9e/mmap.9e new file mode 100644 index 0000000000..d19a087a04 --- /dev/null +++ b/usr/src/man/man9e/mmap.9e @@ -0,0 +1,286 @@ +'\" te +.\" Copyright 1989 AT&T +.\" 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 mmap 9E "27 Sep 2002" "SunOS 5.11" "Driver Entry Points" +.SH NAME +mmap \- check virtual mapping for memory mapped device +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/cred.h> +#include <sys/mman.h> +#include <sys/ddi.h> + + + +\fBint prefix\fR\fBmmap\fR(\fBdev_t\fR \fIdev\fR, \fBoff_t\fR \fIoff\fR, \fBint\fR \fIprot\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. \fBdevmap\fR(9E) should be used instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR \fR +.ad +.RS 9n +.rt +Device whose memory is to be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoff\fR \fR +.ad +.RS 9n +.rt +Offset within device memory at which mapping begins. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprot\fR \fR +.ad +.RS 9n +.rt +A bit field that specifies the protections this page of memory will receive. +Possible settings are: +.sp +.ne 2 +.mk +.na +\fB\fBPROT_READ\fR \fR +.ad +.RS 15n +.rt +Read access will be granted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_WRITE\fR \fR +.ad +.RS 15n +.rt +Write access will be granted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_EXEC\fR \fR +.ad +.RS 15n +.rt +Execute access will be granted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_USER\fR \fR +.ad +.RS 15n +.rt +User-level access will be granted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_ALL\fR \fR +.ad +.RS 15n +.rt +All access will be granted. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +Future releases of Solaris will provide this function for binary and source +compatibility. However, for increased functionality, use \fBdevmap\fR(9E) +instead. See \fBdevmap\fR(9E) for details. +.sp +.LP +The \fBmmap()\fR entry point is a required entry point for character drivers +supporting memory-mapped devices. A memory mapped device has memory that can be +mapped into a process's address space. The \fBmmap\fR(2) system call, when +applied to a character special file, allows this device memory to be mapped +into user space for direct access by the user application. +.sp +.LP +The \fBmmap()\fR entry point is called as a result of an \fBmmap\fR(2) system +call, and also as a result of a page fault. \fBmmap()\fR is called to translate +the offset \fIoff\fR in device memory to the corresponding physical page frame +number. +.sp +.LP +The \fBmmap()\fR entry point checks if the offset \fIoff\fR is within the range +of pages exported by the device. For example, a device that has 512 bytes of +memory that can be mapped into user space should not support offsets greater +than 512. If the offset does not exist, then \fB-1\fR is returned. If the +offset does exist, \fBmmap()\fR returns the value returned by +\fBhat_getkpfnum\fR(9F) for the physical page in device memory containing the +offset \fIoff\fR. +.sp +.LP +\fBhat_getkpfnum\fR(9F) accepts a kernel virtual address as an argument. A +kernel virtual address can be obtained by calling \fBddi_regs_map_setup\fR(9F) +in the driver's \fBattach\fR(9E) routine. The corresponding +\fBddi_regs_map_free\fR(9F) call can be made in the driver's \fBdetach\fR(9E) +routine. Refer to the example below \fImmap Entry Point\fR for more +information. +.sp +.LP +\fBmmap()\fR should only be supported for memory-mapped devices. See +\fBsegmap\fR(9E) for further information on memory-mapped device drivers. +.sp +.LP +If a device driver shares data structures with the application, for example +through exported kernel memory, and the driver gets recompiled for a 64-bit +kernel but the application remains 32-bit, the binary layout of any data +structures will be incompatible if they contain longs or pointers. The driver +needs to know whether there is a model mismatch between the current thread and +the kernel and take necessary action. \fBddi_mmap_get_model\fR(9F) can be use +to get the C Language Type Model which the current thread expects. In +combination with \fBddi_model_convert_from\fR(9F) the driver can determine +whether there is a data model mismatch between the current thread and the +device driver. The device driver might have to adjust the shape of data +structures before exporting them to a user thread which supports a different +data model. See \fBddi_mmap_get_model\fR(9F) for an example. +.SH RETURN VALUES +.sp +.LP +If the protection and offset are valid for the device, the driver should return +the value returned by \fBhat_getkpfnum\fR(9F), for the page at offset \fIoff\fR +in the device's memory. If not, \fB-1\fR should be returned. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBmmap()\fR Entry Point +.sp +.LP +The following is an example of the \fBmmap()\fR entry point. If offset +\fIoff\fR is valid, \fBhat_getkpfnum\fR(9F) is called to obtain the page frame +number corresponding to this offset in the device's memory. In this example, +\fBxsp\(->regp\(->csr\fR is a kernel virtual address which maps to device +memory. \fBddi_regs_map_setup\fR(9F) can be used to obtain this address. For +example, \fBddi_regs_map_setup\fR(9F) can be called in the driver's +\fBattach\fR(9E) routine. The resulting kernel virtual address is stored in the +\fBxxstate\fR structure, which is accessible from the driver's \fBmmap()\fR +entry point. See \fBddi_soft_state\fR(9F). The corresponding +\fBddi_regs_map_free\fR(9F) call can be made in the driver's \fBdetach\fR(9E) +routine. + +.sp +.in +2 +.nf +struct reg { + uint8_t csr; + uint8_t data; +}; +struct xxstate { + .\|.\|. + struct reg *regp + .\|.\|. +}; + +struct xxstate *xsp; +\&.\|.\|. + +static int +xxmmap(dev_t dev, off_t off, int prot) +{ + int instance; + struct xxstate *xsp; + + /* No write access */ + if (prot & PROT_WRITE) + return (-1); + + instance = getminor(dev); + xsp = ddi_get_soft_state(statep, instance); + if (xsp == NULL) + return (-1); + + /* check for a valid offset */ + if ( off is invalid ) + return (-1); + return (hat_getkpfnum (xsp->regp->csr + off)); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Stability LevelObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBmmap\fR(2), \fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E), +\fBdevmap\fR(9E), \fBsegmap\fR(9E), \fBddi_btop\fR(9F), +\fBddi_get_soft_state\fR(9F), \fBddi_mmap_get_model\fR(9F), +\fBddi_model_convert_from\fR(9F), \fBddi_regs_map_free\fR(9F), +\fBddi_regs_map_setup\fR(9F), \fBddi_soft_state\fR(9F), \fBdevmap_setup\fR(9F), +\fBgetminor\fR(9F), \fBhat_getkpfnum\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +For some devices, mapping device memory in the driver's \fBattach\fR(9E) +routine and unmapping device memory in the driver's \fBdetach\fR(9E) routine is +a sizeable drain on system resources. This is especially true for devices with +a large amount of physical address space. +.sp +.LP +One alternative is to create a mapping for only the first page of device memory +in \fBattach\fR(9E). If the device memory is contiguous, a kernel page frame +number may be obtained by calling \fBhat_getkpfnum\fR(9F) with the kernel +virtual address of the first page of device memory and adding the desired page +offset to the result. The page offset may be obtained by converting the byte +offset \fIoff\fR to pages. See \fBddi_btop\fR(9F). +.sp +.LP +Another alternative is to call \fBddi_regs_map_setup\fR(9F) and +\fBddi_regs_map_free\fR(9F) in \fBmmap()\fR. These function calls would bracket +the call to \fBhat_getkpfnum\fR(9F). +.sp +.LP +However, note that the above alternatives may not work in all cases. The +existence of intermediate nexus devices with memory management unit translation +resources that are not locked down may cause unexpected and undefined behavior. diff --git a/usr/src/man/man9e/open.9e b/usr/src/man/man9e/open.9e new file mode 100644 index 0000000000..9d73b7d4c0 --- /dev/null +++ b/usr/src/man/man9e/open.9e @@ -0,0 +1,366 @@ +'\" te +.\" Copyright 1989 AT&T +.\" 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 open 9E "24 Apr 2008" "SunOS 5.11" "Driver Entry Points" +.SH NAME +open \- gain access to a device +.SH SYNOPSIS +.SS "Block and Character" +.LP +.nf +#include <sys/types.h> +#include <sys/file.h> +#include <sys/errno.h> +#include <sys/open.h> +#include <sys/cred.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBopen\fR(\fBdev_t *\fR\fIdevp\fR, \fBint\fR \fIflag\fR, \fBint\fR \fIotyp\fR, + \fBcred_t *\fR\fIcred_p\fR); +.fi + +.SS "STREAMS" +.LP +.nf +#include <sys/file.h> +#include <sys/stream.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBopen\fR(\fBqueue_t *\fR\fIq\fR, \fBdev_t *\fR\fIdevp\fR, \fBint\fR \fIoflag\fR, \fBint\fR \fIsflag\fR, + \fBcred_t *\fR\fIcred_p\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). This entry point is required, but +it can be \fBnulldev\fR(9F) +.SH PARAMETERS +.SS "Block and Character" +.sp +.ne 2 +.mk +.na +\fB\fIdevp\fR\fR +.ad +.RS 10n +.rt +Pointer to a device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 10n +.rt +A bit field passed from the user program \fBopen\fR(2) system call that +instructs the driver on how to open the file. Valid settings are: +.sp +.ne 2 +.mk +.na +\fB\fBFEXCL\fR\fR +.ad +.RS 11n +.rt +Open the device with exclusive access; fail all other attempts to open the +device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFNDELAY\fR\fR +.ad +.RS 11n +.rt +Open the device and return immediately. Do not block the open even if something +is wrong. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFREAD\fR\fR +.ad +.RS 11n +.rt +Open the device with read-only permission, If \fBOR\fRed with \fBFWRITE\fR, +allow both read and write access. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFWRITE\fR\fR +.ad +.RS 11n +.rt +Open a device with write-only permission. If ORed with \fBFREAD\fR, allow both +read and write access. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIotyp\fR\fR +.ad +.RS 10n +.rt +Parameter supplied for driver to determine how many times a device was opened +and for what reasons. For \fBOTYP_BLK\fR and \fBOTYP_CHR\fR, the \fBopen()\fR +function can be called many times, but the \fBclose\fR(9E) function is called +only when the last reference to a device is removed. If the device is accessed +through file descriptors, it is done by a call to \fBclose\fR(2) or +\fBexit\fR(2). If the device is accessed through memory mapping, it is done by +a call to \fBmunmap\fR(2) or \fBexit\fR(2). For \fBOTYP_LYR\fR, there is +exactly one \fBclose\fR(9E) for each \fBopen()\fR operation that is called. +This permits software drivers to exist above hardware drivers and removes any +ambiguity from the hardware driver regarding how a device is used. +.sp +.ne 2 +.mk +.na +\fB\fBOTYP_BLK\fR\fR +.ad +.RS 12n +.rt +Open occurred through block interface for the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBOTYP_CHR\fR\fR +.ad +.RS 12n +.rt +Open occurred through the raw/character interface for the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBOTYP_LYR\fR\fR +.ad +.RS 12n +.rt +Open a layered process. This flag is used when one driver calls another +driver's \fBopen()\fR or \fBclose\fR(9E) function. The calling driver ensures +that there is one-layered close for each layered open. This flag applies to +both block and character devices. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcred_p\fR\fR +.ad +.RS 10n +.rt +Pointer to the user credential structure. +.RE + +.SS "STREAMS" +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 10n +.rt +A pointer to the read \fBqueue\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdevp\fR\fR +.ad +.RS 10n +.rt +Pointer to a device number. For \fBSTREAMS \fRmodules, \fIdevp\fR always points +to the device number associated with the driver at the end (tail) of the +stream. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoflag\fR\fR +.ad +.RS 10n +.rt +Valid \fIoflag\fR values are \fBFEXCL\fR, \fBFNDELAY\fR, \fBFREAD\fR, and +\fBFWRITEL\fR \(em the same as those listed above for \fIflag.\fR. For +\fBSTREAMS\fR modules, \fIoflag\fR is always set to \fB0\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsflag\fR\fR +.ad +.RS 10n +.rt +Valid values are as follows: +.sp +.ne 2 +.mk +.na +\fB\fBCLONEOPEN\fR\fR +.ad +.RS 13n +.rt +Indicates that the \fBopen()\fR function is called through the clone driver. +The driver should return a unique device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMODOPEN\fR\fR +.ad +.RS 13n +.rt +Modules should be called with \fIsflag\fR set to this value. Modules should +return an error if they are called with \fIsflag\fR set to a different value. +Drivers should return an error if they are called with \fIsflag\fR set to this +value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 13n +.rt +Indicates a driver is opened directly, without calling the clone driver. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcred_p\fR\fR +.ad +.RS 10n +.rt +Pointer to the user credential structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The driver's \fBopen()\fR function is called by the kernel during an +\fBopen\fR(2) or a \fBmount\fR(2) on the special file for the device. A device +can be opened simultaneously by multiple processes and the \fBopen()\fR driver +operation is called for each open. Note that a device is referenced once its +associated \fBopen\fR(9E) function is entered, and thus \fBopen\fR(9E) +operations which have not yet completed will prevent \fBclose\fR(9E) from being +called. The function should verify that the minor number component of +\fI*devp\fR is valid, that the type of access requested by \fIotyp\fR and +\fIflag\fR is appropriate for the device, and, if required, check permissions +using the user credentials pointed to by \fIcred_p\fR. +.sp +.LP +The kernel provides \fBopen()\fR \fBclose()\fR exclusion guarantees to the +driver at *\fIdevp\fR, \fIotyp\fR granularity. This delays new \fBopen()\fR +calls to the driver while a last-reference \fBclose()\fR call is executing. If +the driver has indicated that an \fBEINTR\fR returns safe via the +\fBD_OPEN_RETURNS_EINTR\fR \fBcb_ops\fR(9S) \fBcb_flag\fR, a delayed +\fBopen()\fR may be interrupted by a signal that results in an \fBEINTR\fR +return. +.sp +.LP +Last-reference accounting and \fBopen()\fR \fBclose()\fR exclusion typically +simplify driver writing. In some cases, however, they might be an impediment +for certain types of drivers. To overcome any impediment, the driver can change +minor numbers in \fBopen\fR(9E), as described below, or implement multiple +minor nodes for the same device. Both techniques give the driver control over +when \fBclose()\fR calls occur and whether additional \fBopen()\fR calls will +be delayed while \fBclose()\fR is executing. +.sp +.LP +The \fBopen()\fR function is passed a pointer to a device number so that the +driver can change the minor number. This allows drivers to dynamically create +minor instances of the device. An example of this might be a pseudo-terminal +driver that creates a new pseudo-terminal whenever it is opened. A driver that +chooses the minor number dynamically, normally creates only one minor device +node in \fBattach\fR(9E) with \fBddi_create_minor_node\fR(9F). It then changes +the minor number component of \fI*devp\fR using \fBmakedevice\fR(9F) and +\fBgetmajor\fR(9F). The driver needs to keep track of available minor numbers +internally. A driver that dynamically creates minor numbers might want to avoid +returning the original minor number since returning the original minor will +result in postponed dynamic opens when original minor \fBclose()\fR call +occurs. +.sp +.in +2 +.nf +*devp = makedevice(getmajor(*devp), new_minor); +.fi +.in -2 + +.SH RETURN VALUES +.sp +.LP +The \fBopen()\fR function should return \fB0\fR for success, or the appropriate +error number. +.SH SEE ALSO +.sp +.LP +\fBclose\fR(2), \fBexit\fR(2), \fBmmap\fR(2), \fBmount\fR(2), \fBmunmap\fR(2), +\fBopen\fR(2), \fBIntro\fR(9E), \fBattach\fR(9E), \fBclose\fR(9E), +\fBddi_create_minor_node\fR(9F), \fBgetmajor\fR(9F), \fBgetminor\fR(9F), +\fBmakedevice\fR(9F), \fBnulldev\fR(9F), \fBcb_ops\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH WARNINGS +.sp +.LP +Do not attempt to change the major number. +.sp +.LP +When a driver modifies the device number passed in, it must not change the +major number portion of the device number. Unless CLONEOPEN is specified, the +modified device number must map to the same driver instance indicated by the +driver's getinfo(9e) implementation. In other words, cloning across different +drivers is not supported. Cloning across different instances of the same driver +in only permitted if the driver specified in \fBCLONE_DEV\fR in +\fBddi_create_minor_node\fR(9F) is not supported. diff --git a/usr/src/man/man9e/power.9e b/usr/src/man/man9e/power.9e new file mode 100644 index 0000000000..ce53db2070 --- /dev/null +++ b/usr/src/man/man9e/power.9e @@ -0,0 +1,150 @@ +'\" te +.\" Copyright (c) 2003, 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 power 9E "12 Dec 2003" "SunOS 5.11" "Driver Entry Points" +.SH NAME +power \- power a device attached to the system +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBpower\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint\fR \fIcomponent\fR, \fBint\fR \fIlevel\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). This entry point is required. If the driver +writer does not supply this entry point, the value \fBNULL\fR must be used in +the \fBcb_ops\fR(9S) structure instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 13n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcomponent\fR\fR +.ad +.RS 13n +.rt +Component of the driver to be managed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlevel\fR\fR +.ad +.RS 13n +.rt +Desired component power level. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpower\fR(9E) function is the device-specific Power Management entry +point. This function is called when the system wants the driver to set the +power level of \fIcomponent\fR to \fIlevel\fR. +.sp +.LP +The \fIlevel\fR argument is the driver-defined power level to which the +component needs to be set. Except for power level \fB0\fR, which is interpreted +by the framework to mean "powered off," the interpretation of \fIlevel\fR is +entirely up to the driver. +.sp +.LP +The \fIcomponent\fR argument is the component of the device to be +power-managed. The interpretation of \fIcomponent\fR is entirely up to the +driver. +.sp +.LP +When a requested power transition would cause the device to lose state, the +driver must save the state of the device in memory. When a requested power +transition requires state to be restored, the driver must restore that state. +.sp +.LP +If a requested power transition for one component requires another component to +change power state before it can be completed, the driver must call +\fBpm_raise_power\fR(9F) to get the other component changed, and the +\fBpower\fR(9E) entry point must support being re-entered. +.sp +.LP +If the system requests an inappropriate power transition for the device (for +example, a request to power down a device which has just become busy), then the +power level should not be changed and power should return \fBDDI_FAILURE\fR. +.SH RETURN VALUES +.sp +.LP +The \fBpower()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Successfully set the power to the requested \fIlevel\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Failed to set the power to the requested \fIlevel\fR. +.RE + +.SH CONTEXT +.sp +.LP +The \fBpower()\fR function is called from user or kernel context only. +.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 +\fBattach\fR(9E), \fBdetach\fR(9E), \fBpm_busy_component\fR(9F), +\fBpm_idle_component\fR(9F), \fBpm_raise_power\fR(9F), \fBcb_ops\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fIUsing Power Management\fR diff --git a/usr/src/man/man9e/print.9e b/usr/src/man/man9e/print.9e new file mode 100644 index 0000000000..fcd917aecb --- /dev/null +++ b/usr/src/man/man9e/print.9e @@ -0,0 +1,72 @@ +'\" 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 print 9E "15 Sep 1992" "SunOS 5.11" "Driver Entry Points" +.SH NAME +print \- display a driver message on system console +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBprint\fR(\fBdev_t\fR \fIdev\fR, \fBchar *\fR\fIstr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). This entry point is required for +block devices. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR \fR +.ad +.RS 8n +.rt +Device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstr\fR \fR +.ad +.RS 8n +.rt +Pointer to a character string describing the problem. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBprint()\fR routine is called by the kernel when it has detected an +exceptional condition (such as out of space) in the device. To display the +message on the console, the driver should use the \fBcmn_err\fR(9F) kernel +function. The driver should print the message along with any driver specific +information. +.SH RETURN VALUES +.sp +.LP +The \fBprint()\fR routine should return \fB0\fR for success, or the +appropriate error number. The \fBprint\fR routine can fail if the driver +implemented a non-standard \fBprint()\fR routine that attempted to perform +error logging, but was unable to complete the logging for whatever reason. +.SH SEE ALSO +.sp +.LP +\fBcmn_err\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/probe.9e b/usr/src/man/man9e/probe.9e new file mode 100644 index 0000000000..73f639c82e --- /dev/null +++ b/usr/src/man/man9e/probe.9e @@ -0,0 +1,124 @@ +'\" 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 probe 9E "18 Nov 1992" "SunOS 5.11" "Driver Entry Points" +.SH NAME +probe \- determine if a non-self-identifying device is present +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBstatic intprefix\fR\fBprobe\fR(\fBdev_info_t *\fR\fIdip\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). This entry point is required for +non-self-identifying devices. You must write it for such devices. For +self-identifying devices, \fBnulldev\fR(9F) should be specified in the +\fBdev_ops\fR(9S) structure if a probe routine is not necessary. +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR \fR +.ad +.RS 8n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBprobe()\fR determines whether the device corresponding to \fIdip\fR actually +exists and is a valid device for this driver. \fBprobe()\fR is called after +\fBidentify\fR(9E) and before \fBattach\fR(9E) for a given \fIdip\fR. For +example, the \fBprobe()\fR routine can map the device registers using +\fBddi_map_regs\fR(9F) then attempt to access the hardware using +\fBddi_peek\fR(9F) or \fBddi_poke\fR(9F) and determine if the device exists. +Then the device registers should be unmapped using \fBddi_unmap_regs\fR(9F). +.sp +.LP +To probe a device that was left powered off after the last \fBdetach()\fR, it +might be necessary to power it up. If so, the driver must power up the device +by accessing device registers directly. \fBpm_raise_power\fR(9F) will be not be +available until \fBattach\fR(9E). The framework ensures that the ancestors of +the node being probed and all relevant platform-specific power management +hardware is at full power at the time that \fBprobe()\fR is called. +.sp +.LP +\fBprobe()\fR should only probe the device. It should not change any software +state and should not create any software state. Device initialization should be +done in \fBattach\fR(9E). +.sp +.LP +For a self-identifying device, this entry point is not necessary. However, if a +device exists in both self-identifying and non-self-identifying forms, a +\fBprobe()\fR routine can be provided to simplify the driver. +\fBddi_dev_is_sid\fR(9F) can then be used to determine whether \fBprobe()\fR +needs to do any work. See \fBddi_dev_is_sid\fR(9F) for an example. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROBE_SUCCESS\fR \fR +.ad +.RS 23n +.rt +If the probe was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROBE_FAILURE\fR \fR +.ad +.RS 23n +.rt +If the probe failed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROBE_DONTCARE\fR \fR +.ad +.RS 23n +.rt +If the probe was unsuccessful, yet \fBattach\fR(9E) should still be called. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROBE_PARTIAL\fR \fR +.ad +.RS 23n +.rt +If the instance is not present now, but may be present in the future. +.RE + +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBidentify\fR(9E), \fBddi_dev_is_sid\fR(9F), +\fBddi_map_regs\fR(9F), \fBddi_peek\fR(9F), \fBddi_poke\fR(9F), +\fBnulldev\fR(9F), \fBdev_ops\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/prop_op.9e b/usr/src/man/man9e/prop_op.9e new file mode 100644 index 0000000000..bb9d965b7f --- /dev/null +++ b/usr/src/man/man9e/prop_op.9e @@ -0,0 +1,277 @@ +'\" 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 prop_op 9E "8 Jul 1996" "SunOS 5.11" "Driver Entry Points" +.SH NAME +prop_op \- report driver property information +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBprop_op\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, + \fBddi_prop_op_t\fR \fIprop_op\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBcaddr_t\fR \fIvaluep\fR, + \fBint *\fR\fIlengthp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). This entry point is required, but it can be +\fBddi_prop_op\fR(9F). +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 12n +.rt +Device number associated with this device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 12n +.rt +A pointer to the device information structure for this device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprop_op\fR\fR +.ad +.RS 12n +.rt +Property operator. Valid operators are: +.sp +.ne 2 +.mk +.na +\fB\fBPROP_LEN\fR \fR +.ad +.RS 26n +.rt +Get property length only. (\fIvaluep\fR unaffected). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROP_LEN_AND_VAL_BUF\fR\fR +.ad +.RS 26n +.rt +Get length and value into caller's buffer. (\fIvaluep\fR used as input). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROP_LEN_AND_VAL_ALLOC\fR\fR +.ad +.RS 26n +.rt +Get length and value into allocated buffer. (\fIvaluep\fR returned as pointer +to pointer to allocated buffer). +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 12n +.rt +The only possible flag value is: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_DONTPASS\fR\fR +.ad +.RS 21n +.rt +Do not pass request to parent if property not found. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 12n +.rt +Pointer to name of property to be interrogated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvaluep\fR \fR +.ad +.RS 12n +.rt +If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_BUF\fR, this should be a pointer to +the user's buffer. If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_ALLOC\fR, this +should be the \fIaddress\fR of a pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlengthp\fR \fR +.ad +.RS 12n +.rt +On exit, *\fIlengthp\fR will contain the property length. If \fIprop_op\fR is +\fBPROP_LEN_AND_VAL_BUF\fR then \fIlengthp\fR should point to an \fBint\fR that +contains the length of caller's buffer, before calling \fBprop_op()\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBprop_op()\fR is an entry point which reports the values of certain +properties of the driver or device to the system. Each driver must have a +\fIprefix\fR \fBprop_op\fR entry point, but most drivers that do not need to +create or manage their own properties can use \fBddi_prop_op()\fR for this +entry point. Then the driver can use \fBddi_prop_update\fR(9F) to create +properties for its device. +.SH RETURN VALUES +.sp +.LP +\fBprop_op()\fR should return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_SUCCESS\fR \fR +.ad +.RS 27n +.rt +Property found and returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NOT_FOUND\fR \fR +.ad +.RS 27n +.rt +Property not found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_UNDEFINED\fR \fR +.ad +.RS 27n +.rt +Prop explicitly undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NO_MEMORY\fR \fR +.ad +.RS 27n +.rt +Property found, but unable to allocate memory. \fIlengthp\fR has the correct +property length. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_BUF_TOO_SMALL\fR \fR +.ad +.RS 27n +.rt +Property found, but the supplied buffer is too small. \fIlengthp\fR has the +correct property length. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBprop_op()\fR to Report Property Information +.sp +.LP +In the following example, \fBprop_op()\fR intercepts requests for the +\fItemperature\fR property. The driver tracks changes to \fItemperature\fR +using a variable in the state structure in order to avoid frequent calls to +\fBddi_prop_update\fR(9F). The \fItemperature\fR property is only updated when +a request is made for this property. It then uses the system routine +\fBddi_prop_op\fR(9F) to process the property request. If the property request +is not specific to a device, the driver does not intercept the request. This is +indicated when the value of the \fIdev\fR parameter is equal to +\fBDDI_DEV_T_ANY\fR. + +.sp +.in +2 +.nf +int temperature; /* current device temperature */ + . + . + . +static int +xxprop_op(dev_t dev, dev_info_t *dip, ddi_prop_op_t prop_op, + int flags, char *name, caddr_t valuep, int *lengthp) +{ + int instance; + struct xxstate *xsp; + if (dev == DDI_DEV_T_ANY) + goto skip; + instance = getminor(dev); + xsp = ddi_get_soft_state(statep, instance); + if (xsp == NULL) + return (DDI_PROP_NOT_FOUND); + if (strcmp(name, "temperature") == 0) { + ddi_prop_update_int(dev, dip,\e + "temperature", temperature); + } + /* other cases... */ + skip: + return (ddi_prop_op(dev, dip, prop_op, flags,\e + name, valuep, lengthp)); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(9E), \fBddi_prop_op\fR(9F), \fBddi_prop_update\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/put.9e b/usr/src/man/man9e/put.9e new file mode 100644 index 0000000000..18d23a511a --- /dev/null +++ b/usr/src/man/man9e/put.9e @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (c) 1992, 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 put 9E "12 Nov 1992" "SunOS 5.11" "Driver Entry Points" +.SH NAME +put \- receive messages from the preceding queue +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/stream.h> +#include <sys/stropts.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBrput\fR(\fBqueue_t *\fR\fIq\fR, \fBmblk_t\fR \fI*mp\fR/* read side */ +.fi + +.LP +.nf +\fBint prefix\fR\fBwput\fR(\fBqueue_t *\fR\fIq\fR, \fBmblk_t\fR \fI*mp\fR/* write side */ +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). This entry point is required for +\fBSTREAMS. \fR +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR \fR +.ad +.RS 7n +.rt +Pointer to the \fBqueue\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR \fR +.ad +.RS 7n +.rt +Pointer to the message block. +.RE + +.SH DESCRIPTION +.sp +.LP +The primary task of the \fBput()\fR routine is to coordinate the passing of +messages from one queue to the next in a stream. The \fBput()\fR routine is +called by the preceding stream component (stream module, driver, or stream +head). \fBput()\fR routines are designated ``write'' or ``read'' depending on +the direction of message flow. +.sp +.LP +With few exceptions, a streams module or driver must have a \fBput()\fR +routine. One exception is the read side of a driver, which does not need a +\fBput()\fR routine because there is no component downstream to call it. The +\fBput()\fR routine is always called before the component's corresponding +\fBsrv\fR(9E) (service) routine, and so \fBput()\fR should be used for the +immediate processing of messages. +.sp +.LP +A \fBput()\fR routine must do at least one of the following when it receives a +message: +.RS +4 +.TP +.ie t \(bu +.el o +pass the message to the next component on the stream by calling the +\fBputnext\fR(9F) function; +.RE +.RS +4 +.TP +.ie t \(bu +.el o +process the message, if immediate processing is required (for example, to +handle high priority messages); or +.RE +.RS +4 +.TP +.ie t \(bu +.el o +enqueue the message (with the \fBputq\fR(9F) function) for deferred processing +by the service \fBsrv\fR(9E) routine. +.RE +.sp +.LP +Typically, a \fBput()\fR routine will switch on message type, which is +contained in the \fBdb_type\fR member of the \fBdatab\fR structure pointed to +by \fImp\fR. The action taken by the \fBput()\fR routine depends on the message +type. For example, a \fBput()\fR routine might process high priority messages, +enqueue normal messages, and handle an unrecognized \fBM_IOCTL\fR message by +changing its type to \fBM_IOCNAK\fR (negative acknowledgement) and sending it +back to the stream head using the \fBqreply\fR(9F) function. +.sp +.LP +The \fBputq\fR(9F) function can be used as a module's \fBput()\fR routine when +no special processing is required and all messages are to be enqueued for the +\fBsrv\fR(9E) routine. +.SH RETURN VALUES +.sp +.LP +Ignored. +.SH CONTEXT +.sp +.LP +\fBput()\fR routines do not have user context. +.SH SEE ALSO +.sp +.LP +\fBsrv\fR(9E), \fBputctl\fR(9F), \fBputctl1\fR(9F), \fBputnext\fR(9F), +\fBputnextctl\fR(9F), \fBputnextctl1\fR(9F), \fBputq\fR(9F), \fBqreply\fR(9F), +\fBqueue\fR(9S), \fBstreamtab\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9e/quiesce.9e b/usr/src/man/man9e/quiesce.9e new file mode 100644 index 0000000000..35937f7714 --- /dev/null +++ b/usr/src/man/man9e/quiesce.9e @@ -0,0 +1,125 @@ +'\" 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 quiesce 9E "16 Sep 2008" "SunOS 5.11" "Driver Entry Points" +.SH NAME +quiesce \- quiesce a device +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint prefix\fR\fBquiesce\fR(\fBdev_info_t\fR \fI*dip\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_quiesce_not_needed\fR(\fBdev_info_t\fR \fI*dip\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 7n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBquiesce()\fR function quiesces a device so that the device no longer +generates interrupts, modifies or accesses memory. The driver should reset the +device to a hardware state from which the device can be correctly configured by +the driver's \fBattach()\fR routine without a system power cycle or being +configured by the firmware. For devices with a defined reset state +configuration, the driver should return that device to that state as part of +the quiesce operation. Fast Reboot, where firmware is bypassed when booting to +a new OS image, is such a case. +.sp +.LP +\fBquiesce()\fR is only called for an attached device instance as one of the +final operations of a reboot sequence, and no other thread can be active for +this device. The system guarantees that no other driver entry point is active +or invoked while \fBquiesce()\fR is invoked. The system also guarantees that no +timeout or \fBtaskq\fR is invoked. The system is single-threaded and can not be +interrupted. Therefore, the driver's \fBquiesce()\fR implementation must not +use locks or timeouts, or rely on them being called. The driver must discard +all outstanding \fBI/O\fR instead of waiting for completion. At the conclusion +of the \fBquiesce()\fR operation, the driver must guarantee that the device no +longer has access to memory or interrupts. +.sp +.LP +The only \fBDDI\fR interfaces that can be called by the \fBquiesce()\fR +implementation are non-blocking functions, such as the \fBddi_get*()\fR and +\fBddi_put*()\fR functions. +.sp +.LP +If \fBquiesce()\fR determines a particular instance of the device cannot be +quiesced when requested because of some exceptional condition, \fBquiesce()\fR +returns \fBDDI_FAILURE\fR. This rarely happens. +.sp +.LP +If a driver has previously implemented the obsolete \fBreset()\fR interface, +its functionality must be merged into \fBquiesce()\fR. The driver's +\fBreset()\fR routine is no longer called if an implementation of +\fBquiesce()\fR is present. +.sp +.LP +\fBddi_quiesce_not_needed()\fR always returns \fBDDI_SUCCESS\fR. A driver can +set its \fBdevo_quiesce\fR device function to \fBddi_quiesce_not_needed()\fR to +indicate that the device it manages does not need to be quiesced. +.SH RETURN VALUES +.sp +.LP +\fBquiesce()\fR returns the following: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +The device has been successfully quiesced. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +The operation failed. +.RE + +.SH CONTEXT +.sp +.LP +This function is called from kernel context only. +.SH SEE ALSO +.sp +.LP +\fBreboot\fR(1M), \fBuadmin\fR(1M), \fBuadmin\fR(2), \fBattach\fR(9E), +\fBdetach\fR(9E), \fBddi_add_intr\fR(9F), \fBddi_map_regs\fR(9F), +\fBpci_config_setup\fR(9F), \fBtimeout\fR(9F), \fBdev_ops\fR(9S) +.SH NOTES +.sp +.LP +When \fBquiesce()\fR is called, the system is single-threaded, therefore the +driver's \fBquiesce()\fR implementation must not be blocked. For example, the +implementation must not create or tear down mappings, call \fBFMA\fR functions, +or create or cancel callbacks. diff --git a/usr/src/man/man9e/read.9e b/usr/src/man/man9e/read.9e new file mode 100644 index 0000000000..78efdccacb --- /dev/null +++ b/usr/src/man/man9e/read.9e @@ -0,0 +1,118 @@ +'\" 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 read 9E "19 Nov 1997" "SunOS 5.11" "Driver Entry Points" +.SH NAME +read \- read data from a device +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/open.h> +#include <sys/uio.h> +#include <sys/cred.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBread\fR(\fBdev_t\fR \fIdev\fR, \fBstruct uio *\fR\fIuio_p\fR, \fBcred_t *\fR\fIcred_p\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). This entry point is \fIoptional\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR \fR +.ad +.RS 11n +.rt +Device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuio_p\fR \fR +.ad +.RS 11n +.rt +Pointer to the \fBuio\fR(9S) structure that describes where the data is to be +stored in user space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcred_p\fR \fR +.ad +.RS 11n +.rt +Pointer to the user credential structure for the \fBI/O \fRtransaction. +.RE + +.SH DESCRIPTION +.sp +.LP +The driver \fBread()\fR routine is called indirectly through \fBcb_ops\fR(9S) +by the \fBread\fR(2) system call. The \fBread()\fR routine should check the +validity of the minor number component of \fIdev\fR and the user credential +structure pointed to by \fIcred_p\fR (if pertinent). The \fBread()\fR routine +should supervise the data transfer into the user space described by the +\fBuio\fR(9S) structure. +.SH RETURN VALUES +.sp +.LP +The \fBread()\fR routine should return \fB0\fR for success, or the +appropriate error number. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBread()\fR routine using \fBphysio()\fR +.sp +.LP +The following is an example of a \fBread()\fR routine using \fBphysio\fR(9F) to +perform reads from a non-seekable device: + +.sp +.in +2 +.nf + static int + xxread(dev_t dev, struct uio *uiop, cred_t *credp) + { + int rval; + offset_t off; + int instance; + xx_t xx; + + instance = getminor(dev); + xx = ddi_get_soft_state(xxstate, instance); + if (xx == NULL) + return (ENXIO); + off = uiop->uio_loffset; + rval = physio(xxstrategy, NULL, dev, B_READ, + xxmin, uiop); + uiop->uio_loffset = off; + return (rval); + } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBread\fR(2), \fBwrite\fR(9E), \fBphysio\fR(9F), \fBcb_ops\fR(9S), +\fBuio\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/segmap.9e b/usr/src/man/man9e/segmap.9e new file mode 100644 index 0000000000..853f0c0179 --- /dev/null +++ b/usr/src/man/man9e/segmap.9e @@ -0,0 +1,301 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 1995, 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 segmap 9E "14 Jan 1997" "SunOS 5.11" "Driver Entry Points" +.SH NAME +segmap \- map device memory into user space +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/mman.h> +#include <sys/param.h> +#include <sys/vm.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBsegmap\fR(\fBdev_t\fR \fIdev\fR, \fBoff_t\fR \fIoff\fR, \fBstruct as *\fR\fIasp\fR, \fBcaddr_t *\fR\fIaddrp\fR, + \fBoff_t\fR \fIlen\fR, \fBunsigned int\fR \fIprot\fR, \fBunsigned int\fR \fImaxprot\fR, \fBunsigned int\fR \fIflags\fR, + \fBcred_t *\fR\fIcred_p\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 2 (DKI only). +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR \fR +.ad +.RS 12n +.rt +Device whose memory is to be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoff\fR \fR +.ad +.RS 12n +.rt +Offset within device memory at which mapping begins. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIasp\fR \fR +.ad +.RS 12n +.rt +Pointer to the address space into which the device memory should be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddrp\fR \fR +.ad +.RS 12n +.rt +Pointer to the address in the address space to which the device memory should +be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR \fR +.ad +.RS 12n +.rt +Length (in bytes) of the memory to be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprot\fR \fR +.ad +.RS 12n +.rt +A bit field that specifies the protections. Possible settings are: +.sp +.ne 2 +.mk +.na +\fB\fBPROT_READ\fR \fR +.ad +.RS 15n +.rt +Read access is desired. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_WRITE\fR \fR +.ad +.RS 15n +.rt +Write access is desired. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_EXEC\fR \fR +.ad +.RS 15n +.rt +Execute access is desired. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_USER\fR \fR +.ad +.RS 15n +.rt +User-level access is desired (the mapping is being done as a result of a +\fBmmap\fR(2) system call). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_ALL\fR \fR +.ad +.RS 15n +.rt +All access is desired. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImaxprot\fR \fR +.ad +.RS 12n +.rt +Maximum protection flag possible for attempted mapping; the \fBPROT_WRITE\fR +bit may be masked out if the user opened the special file read-only. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR \fR +.ad +.RS 12n +.rt +Flags indicating type of mapping. Possible values are (other bits may be set): +.sp +.ne 2 +.mk +.na +\fB\fBMAP_SHARED\fR \fR +.ad +.RS 16n +.rt +Changes should be shared. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBMAP_PRIVATE\fR \fR +.ad +.RS 16n +.rt +Changes are private. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcred_p\fR \fR +.ad +.RS 12n +.rt +Pointer to the user credentials structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBsegmap()\fR entry point is an optional routine for character drivers +that support memory mapping. The \fBmmap\fR(2) system call, when applied to a +character special file, allows device memory to be mapped into user space for +direct access by the user application. +.sp +.LP +Typically, a character driver that needs to support the \fBmmap\fR(2) system +call supplies either an \fBdevmap\fR(9E) entry point, or both an +\fBdevmap\fR(9E) and a \fBsegmap()\fR entry point routine (see the +\fBdevmap\fR(9E) reference page). If no \fBsegmap()\fR entry point is provided +for the driver, \fBdevmap_setup\fR(9F) is used as a default. +.sp +.LP +A driver for a memory-mapped device would provide a \fBsegmap()\fR entry point +if it: +.RS +4 +.TP +.ie t \(bu +.el o +needs to maintain a separate context for each user mapping. See +\fBdevmap_setup\fR(9F) for details. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +needs to assign device access attributes to the user mapping. +.RE +.sp +.LP +The responsibilities of a \fBsegmap()\fR entry point are: +.RS +4 +.TP +.ie t \(bu +.el o +Verify that the range, defined by \fIoffset\fR and \fIlen\fR, to be mapped is +valid for the device. Typically, this task is performed by calling the +\fBdevmap\fR(9E) entry point. Note that if you are using +\fBddi_devmap_segmap\fR(9F) or \fBdevmap_setup\fR(9F) to set up the mapping, it +will call your \fBdevmap\fR(9E) entry point for you to validate the range to be +mapped. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Assign device access attributes to the mapping. See +\fBddi_devmap_segmap\fR(9F), and \fBddi_device_acc_attr\fR(9S) for details. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Set up device contexts for the user mapping if your device requires context +switching. See \fBdevmap_setup\fR(9F) for details. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Perform the mapping with \fBddi_devmap_segmap\fR(9F), or \fBdevmap_setup\fR(9F) +and return the status if it fails. +.RE +.SH RETURN VALUES +.sp +.LP +The \fBsegmap()\fR routine should return \fB0\fR if the driver is successful +in performing the memory map of its device address space into the specified +address space. +.sp +.LP +The \fBsegmap()\fR must return an error number on failure. For example, valid +error numbers would be \fBENXIO\fR if the offset/length pair specified exceeds +the limits of the device memory, or \fBEINVAL\fR if the driver detects an +invalid type of mapping attempted. +.sp +.LP +If one of the mapping routines \fBddi_devmap_segmap()\fR or +\fBdevmap_setup()\fRfails, you must return the error number returned by the +respective routine. +.SH SEE ALSO +.sp +.LP +\fBmmap\fR(2), \fBdevmap\fR(9E), \fBdevmap_setup\fR(9F), +\fBddi_devmap_segmap\fR(9F), \fBddi_device_acc_attr\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/srv.9e b/usr/src/man/man9e/srv.9e new file mode 100644 index 0000000000..1002ef7060 --- /dev/null +++ b/usr/src/man/man9e/srv.9e @@ -0,0 +1,177 @@ +'\" te +.\" Copyright 1989 AT&T +.\" 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 srv 9E "12 Nov 1992" "SunOS 5.11" "Driver Entry Points" +.SH NAME +srv \- service queued messages +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/stream.h> +#include <sys/stropts.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBintprefix\fR\fBrsrv\fR(\fBqueue_t *\fR\fIq\fR/* read side */ +.fi + +.LP +.nf +\fBintprefix\fR\fBwsrv\fR(\fBqueue_t *\fR\fIq\fR/* write side */ +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). This entry point is required for +\fBSTREAMS\fR. +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 5n +.rt +Pointer to the \fBqueue\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The optional service \fBsrv()\fR routine may be included in a \fBSTREAMS +\fRmodule or driver for many possible reasons, including: +.RS +4 +.TP +.ie t \(bu +.el o +to provide greater control over the flow of messages in a stream; +.RE +.RS +4 +.TP +.ie t \(bu +.el o +to make it possible to defer the processing of some messages to avoid depleting +system resources; +.RE +.RS +4 +.TP +.ie t \(bu +.el o +to combine small messages into larger ones, or break large messages into +smaller ones; +.RE +.RS +4 +.TP +.ie t \(bu +.el o +to recover from resource allocation failure. A module's or driver's +\fBput\fR(9E) routine can test for the availability of a resource, and if it is +not available, enqueue the message for later processing by the \fBsrv()\fR +routine. +.RE +.sp +.LP +A message is first passed to a module's or driver's \fBput\fR(9E) routine, +which may or may not do some processing. It must then either: +.RS +4 +.TP +.ie t \(bu +.el o +Pass the message to the next stream component with \fBputnext\fR(9F). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If a \fBsrv()\fR routine has been included, it may call \fBputq\fR(9F) to place +the message on the queue. +.RE +.sp +.LP +Once a message has been enqueued, the \fBSTREAMS \fRscheduler controls the +service routine's invocation. The scheduler calls the service routines in +\fBFIFO \fRorder. The scheduler cannot guarantee a maximum delay \fBsrv()\fR +routine to be called except that it will happen before any user level process +are run. +.sp +.LP +Every stream component (stream head, module or driver) has limit values it uses +to implement flow control. Each component should check the tunable high and low +water marks to stop and restart the flow of message processing. Flow control +limits apply only between two adjacent components with \fBsrv()\fR routines. +.sp +.LP +\fBSTREAMS \fR messages can be defined to have up to 256 different priorities +to support requirements for multiple bands of data flow. At a minimum, a stream +must distinguish between normal (priority zero) messages and high priority +messages (such as \fBM_IOCACK\fR). High priority messages are always placed at +the head of the \fBsrv()\fR routine's queue, after any other enqueued high +priority messages. Next are messages from all included priority bands, which +are enqueued in decreasing order of priority. Each priority band has its own +flow control limits. If a flow controlled band is stopped, all lower priority +bands are also stopped. +.sp +.LP +Once the \fBSTREAMS \fRscheduler calls a \fBsrv()\fR routine, it must process +all messages on its queue. The following steps are general guidelines for +processing messages. Keep in mind that many of the details of how a \fBsrv()\fR +routine should be written depend of the implementation, the direction of flow +(upstream or downstream), and whether it is for a module or a driver. +.RS +4 +.TP +1. +Use \fBgetq\fR(9F) to get the next enqueued message. +.RE +.RS +4 +.TP +2. +If the message is high priority, process (if appropriate) and pass to the +next stream component with \fBputnext\fR(9F). +.RE +.RS +4 +.TP +3. +If it is not a high priority message (and therefore subject to flow +control), attempt to send it to the next stream component with a \fBsrv()\fR +routine. Use \fBbcanputnext\fR(9F) to determine if this can be done. +.RE +.RS +4 +.TP +4. +If the message cannot be passed, put it back on the queue with +\fBputbq\fR(9F). If it can be passed, process (if appropriate) and pass with +\fBputnext()\fR. +.RE +.SH RETURN VALUES +.sp +.LP +Ignored. +.SH SEE ALSO +.sp +.LP +\fBput\fR(9E), \fBbcanput\fR(9F), \fBbcanputnext\fR(9F), \fBcanput\fR(9F), +\fBcanputnext\fR(9F), \fBgetq\fR(9F), \fBnulldev\fR(9F), \fBputbq\fR(9F), +\fBputnext\fR(9F), \fBputq\fR(9F), \fBqinit\fR(9S), \fBqueue\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH WARNINGS +.sp +.LP +Each stream module must specify a read and a write service \fBsrv()\fR routine. +If a service routine is not needed (because the \fBput()\fR routine processes +all messages), a \fBNULL\fR pointer should be placed in module's +\fBqinit\fR(9S) structure. Do not use \fBnulldev\fR(9F) instead of the +\fBNULL\fR pointer. Use of\fBnulldev\fR(9F) for a \fBsrv()\fR routine can +result in flow control errors. diff --git a/usr/src/man/man9e/strategy.9e b/usr/src/man/man9e/strategy.9e new file mode 100644 index 0000000000..a41040aaca --- /dev/null +++ b/usr/src/man/man9e/strategy.9e @@ -0,0 +1,70 @@ +'\" 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 strategy 9E "6 Nov 2003" "SunOS 5.11" "Driver Entry Points" +.SH NAME +strategy \- perform block I/O +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/buf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBstrategy\fR(\fBstruct buf *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). This entry point is required for +block devices. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR \fR +.ad +.RS 7n +.rt +Pointer to the \fBbuf\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBstrategy()\fR routine is called indirectly (through \fBcb_ops\fR(9S)) by +the kernel to read and write blocks of data on the block device. +\fBstrategy()\fR may also be called directly or indirectly to support the raw +character interface of a block device (\fBread\fR(9E), \fBwrite\fR(9E) and +\fBioctl\fR(9E)). The \fBstrategy()\fR routine's responsibility is to set up +and initiate the transfer. +.sp +.LP +In general, \fBstrategy()\fR should not block. It can, however, perform a +\fBkmem_cache_create\fR(9F) with both the \fBKM_PUSHPAGE\fR and \fBKM_SLEEP\fR +flags set, which might block, without causing deadlock in low memory +situations. +.SH RETURN VALUES +.sp +.LP +The \fBstrategy()\fR function must return \fB0\fR. On an error condition, it +should call \fBbioerror\fR(9F) to set \fBb_flags\fR to the proper error code, +and call \fBbiodone\fR(9F). Note that a partial transfer is not considered to +be an error. +.SH SEE ALSO +.sp +.LP +\fBioctl\fR(9E), \fBread\fR(9E), \fBwrite\fR(9E), \fBbiodone\fR(9F), +\fBbioerror\fR(9F), \fBbuf\fR(9S), \fBcb_ops\fR(9S), +\fBkmem_cache_create\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/tran_abort.9e b/usr/src/man/man9e/tran_abort.9e new file mode 100644 index 0000000000..9f480b2298 --- /dev/null +++ b/usr/src/man/man9e/tran_abort.9e @@ -0,0 +1,116 @@ +'\" 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 tran_abort 9E "17 Aug 2005" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_abort \- abort a SCSI command +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fB int prefix\fR\fBtran_abort\fR(\fBstruct scsi_address *\fR\fIap\fR, + \fBstruct scsi_pkt *\fR\fIpkt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR \fR +.ad +.RS 8n +.rt +Pointer to a \fBscsi_address\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR \fR +.ad +.RS 8n +.rt +Pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_abort()\fR vector in the \fBscsi_hba_tran\fR(9S) structure must be +initialized during the HBA driver's \fBattach\fR(9E) to point to an HBA entry +point to be called when a target driver calls \fBscsi_abort\fR(9F). +.sp +.LP +\fBtran_abort()\fR should attempt to abort the command \fIpkt\fR that has been +transported to the HBA. If \fIpkt\fR is \fBNULL\fR, the HBA driver should +attempt to abort all outstanding packets for the target/logical unit addressed +by \fIap\fR. +.sp +.LP +Depending on the state of a particular command in the transport layer, the HBA +driver may not be able to abort the command. +.sp +.LP +While the abort is taking place, packets issued to the transported layer may or +may not be aborted. +.sp +.LP +For each packet successfully aborted, \fBtran_abort()\fR must set the +\fBpkt_reason\fR to \fBCMD_ABORTED\fR, and \fBpkt_statistics\fR must be +\fBOR'ed\fR with \fBSTAT_ABORTED\fR . +.SH RETURN VALUES +.sp +.LP +\fBtran_abort()\fR must return: +.sp +.ne 2 +.mk +.na +\fB\fB1\fR \fR +.ad +.RS 6n +.rt +upon success or partial success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR \fR +.ad +.RS 6n +.rt +upon failure. +.RE + +.SH CONTEXT +.sp +.LP +The \fBtran_abort()\fR function can be called from user or interrupt context. +This requirement comes from \fBscsi_abort()\fR. +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBscsi_abort\fR(9F), \fBscsi_hba_attach\fR(9F), +\fBscsi_address\fR(9S), \fBscsi_hba_tran\fR(9S), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +If \fBpkt_reason\fR already indicates that an earlier error had occurred, +\fBtran_abort()\fR should not overwrite \fBpkt_reason\fR with +\fBCMD_ABORTED\fR. diff --git a/usr/src/man/man9e/tran_bus_reset.9e b/usr/src/man/man9e/tran_bus_reset.9e new file mode 100644 index 0000000000..923baab297 --- /dev/null +++ b/usr/src/man/man9e/tran_bus_reset.9e @@ -0,0 +1,119 @@ +'\" te +.\" Copyright (c) 1996 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 tran_bus_reset 9E "17 Mar 1999" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_bus_reset \- reset a SCSI bus +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> int \fIprefix\fR + +\fB\fR\fBtran_bus_reset\fR(\fBdev_info_t\fR \fI*hba_dip\fR, \fBint\fR \fIlevel\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhba_dip\fR\fR +.ad +.RS 11n +.rt +The \fBdev_info_t\fR pointer associated with the SCSI HBA. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlevel\fR\fR +.ad +.RS 11n +.rt +The level of reset required. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_bus_reset()\fR vector in the \fBscsi_hba_tran\fR(9S) structure +should be initialized during the HBA driver's \fBattach\fR(9E). It is an HBA +entry point to be called when a user initiates a bus reset through device +control interfaces. +.sp +.LP +\fBtran_bus_reset()\fR must reset the SCSI bus without resetting targets. +.sp +.LP +\fIlevel\fR will be one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBRESET_BUS\fR\fR +.ad +.RS 13n +.rt +Reset the SCSI bus only, not the targets. +.RE + +.sp +.LP +Implementation is hardware specific. If it is not possible to reset the SCSI +bus without changing the state and operating mode of the targets, the HBA +driver should not initialize this vector or return failure. +.SH RETURN VALUES +.sp +.LP +\fBtran_bus_reset()\fR should return: +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 5n +.rt +on success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +on failure. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description 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), \fBtran_quiesce\fR(9E), \fBscsi_hba_tran\fR(9S) diff --git a/usr/src/man/man9e/tran_dmafree.9e b/usr/src/man/man9e/tran_dmafree.9e new file mode 100644 index 0000000000..8e6f1995ce --- /dev/null +++ b/usr/src/man/man9e/tran_dmafree.9e @@ -0,0 +1,75 @@ +'\" te +.\" 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 tran_dmafree 9E "30 Aug 1995" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_dmafree \- SCSI HBA DMA deallocation entry point +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fB void prefix\fR\fBtran_dmafree\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBstruct scsi_pkt *\fR\fIpkt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR\fR +.ad +.RS 8n +.rt +A pointer to a \fIscsi_address\fR structure. See \fBscsi_address\fR(9S). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR \fR +.ad +.RS 8n +.rt +A pointer to a \fIscsi_pkt\fR structure. See \fBscsi_pkt\fR(9S). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_dmafree()\fR vector in the \fIscsi_hba_tran\fR structure must be +initialized during the \fBHBA \fRdriver's \fBattach()\fR to point to an \fBHBA +\fRentry point to be called when a target driver calls \fBscsi_dmafree\fR(9F). +See \fBattach\fR(9E) and \fBscsi_hba_tran\fR(9S). +.sp +.LP +\fBtran_dmafree()\fR must deallocate any \fBDMA \fRresources previously +allocated to this \fIpkt\fR in a call to \fBtran_init_pkt\fR(9E). +\fBtran_dmafree()\fR should not free the structure pointed to by \fIpkt\fR +itself. Since \fBtran_destroy_pkt\fR(9E) must also free \fBDMA \fRresources, +it is important that the \fBHBA \fRdriver keeps accurate note of whether +\fBscsi_pkt\fR(9S) structures have \fBDMA \fRresources allocated. +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBtran_destroy_pkt\fR(9E), \fBtran_init_pkt\fR(9E), +\fBscsi_dmafree\fR(9F), \fBscsi_dmaget\fR(9F), \fBscsi_hba_attach\fR(9F), +\fBscsi_init_pkt\fR(9F), \fBscsi_address\fR(9S), \fBscsi_hba_tran\fR(9S), +\fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +A target driver may call \fBtran_dmafree()\fR on packets for which no \fBDMA +\fRresources were allocated. diff --git a/usr/src/man/man9e/tran_getcap.9e b/usr/src/man/man9e/tran_getcap.9e new file mode 100644 index 0000000000..c4556b02d4 --- /dev/null +++ b/usr/src/man/man9e/tran_getcap.9e @@ -0,0 +1,129 @@ +'\" te +.\" Copyright (c) 1995, 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 tran_getcap 9E "30 Aug 1995" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_getcap, tran_setcap \- get/set SCSI transport capability +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint prefix\fR\fBtran_getcap\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBchar *\fR\fIcap\fR, \fBint\fR \fIwhom\fR); +.fi + +.LP +.nf +\fBint prefix\fR\fBtran_setcap\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBchar *\fR\fIcap\fR, \fBint\fR \fIvalue\fR, + \fBint\fR \fIwhom\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR \fR +.ad +.RS 10n +.rt +Pointer to the \fBscsi_address\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcap\fR \fR +.ad +.RS 10n +.rt +Pointer to the string capability identifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvalue\fR \fR +.ad +.RS 10n +.rt +Defines the new state of the capability. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwhom\fR \fR +.ad +.RS 10n +.rt +Specifies whether all targets or only the specified target is affected. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_getcap()\fR and \fBtran_setcap()\fR vectors in the +\fBscsi_hba_tran\fR(9S) structure must be initialized during the \fBHBA +\fRdriver's \fBattach\fR(9E) to point to \fBHBA \fRentry points to be called +when a target driver calls \fBscsi_ifgetcap\fR(9F) and \fBscsi_ifsetcap\fR(9F). +.sp +.LP +\fBtran_getcap()\fR is called to get the current value of a capability specific +to features provided by the \fBHBA \fRhardware or driver. The name of the +capability \fIcap\fR is the \fINULL\fR terminated capability string. +.sp +.LP +If \fIwhom\fR is non-zero, the request is for the current value of the +capability defined for the target specified by the \fBscsi_address\fR(9S) +structure pointed to by \fIap\fR; if \fIwhom\fR is \fB0\fR, all targets are +affected; else, the target specified by the \fBscsi_address\fR structure +pointed to by \fIap\fR is affected. +.sp +.LP +\fBtran_setcap()\fR is called to set the value of the capability \fIcap\fR to +the value of \fIvalue\fR. If \fIwhom\fR is non-zero, the capability should be +set for the target specified by the \fBscsi_address\fR(9S) structure pointed to +by \fIap\fR; if \fIwhom\fR is \fB0\fR, all targets are affected; else, the +target specified by the \fBscsi_address\fR structure pointed to by \fIap\fR is +affected. It is recommended that \fBHBA \fRdrivers do not support setting +capabilities for all targets, that is, \fIwhom\fR is \fB0\fR. +.sp +.LP +A device may support only a subset of the defined capabilities. +.sp +.LP +Refer to \fBscsi_ifgetcap\fR(9F) for the list of defined capabilities. +.sp +.LP +\fBHBA \fRdrivers should use \fBscsi_hba_lookup_capstr\fR(9F) to match +\fIcap\fR against the canonical capability strings. +.SH RETURN VALUES +.sp +.LP +\fBtran_setcap()\fR must return \fB1\fR if the capability was successfully set +to the new value, \fB0\fR if the \fBHBA \fR driver does not support changing +the capability, and \fB\(mi1\fR if the capability was not defined. +.sp +.LP +\fBtran_getcap()\fR must return the current value of a capability or +\fB\(mi1\fR if the capability was not defined. +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBscsi_hba_attach\fR(9F), \fBscsi_hba_lookup_capstr\fR(9F), +\fBscsi_ifgetcap\fR(9F), \fBscsi_address\fR(9S), \fBscsi_hba_tran\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/tran_init_pkt.9e b/usr/src/man/man9e/tran_init_pkt.9e new file mode 100644 index 0000000000..967e434637 --- /dev/null +++ b/usr/src/man/man9e/tran_init_pkt.9e @@ -0,0 +1,287 @@ +'\" 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 tran_init_pkt 9E "11 Jan 2009" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_init_pkt, tran_destroy_pkt \- SCSI HBA packet preparation and deallocation +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + +\fBstruct scsi_pkt *prefix\fR\fBtran_init_pkt\fR(\fBstruct scsi_address *\fR\fIap\fR, + \fBstruct scsi_pkt *\fR\fIpkt\fR, \fBstruct buf *\fR\fIbp\fR, \fBint\fR \fIcmdlen\fR, + \fBint\fR \fIstatuslen\fR, \fBint\fR \fItgtlen\fR, \fBint\fR\fIflags\fR, \fBint (*\fR\fIcallback\fR, + \fBcaddr_t),caddr_t\fR \fIarg\fR); +.fi + +.LP +.nf +\fBvoid prefix\fR\fBtran_destroy_pkt\fR(\fBstruct scsi_address *\fR\fIap\fR, + \fBstruct scsi_pkt *\fR\fIpkt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR\fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_address\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR\fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_pkt\fR(9S) structure allocated in an earlier call, or +\fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 13n +.rt +Pointer to a \fBbuf\fR(9S) structure if \fBDMA \fRresources are to be allocated +for the \fIpkt\fR, or \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmdlen\fR\fR +.ad +.RS 13n +.rt +The required length for the \fBSCSI \fRcommand descriptor block (\fBCDB\fR) in +bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstatuslen\fR\fR +.ad +.RS 13n +.rt +The required length for the \fBSCSI \fRstatus completion block (\fBSCB\fR) in +bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItgtlen\fR\fR +.ad +.RS 13n +.rt +The length of the packet private area within the \fBscsi_pkt\fR to be allocated +on behalf of the \fBSCSI \fRtarget driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 13n +.rt +Flags for creating the packet. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 13n +.rt +Pointer to either \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 13n +.rt +Always \fINULL\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_init_pkt()\fR and \fBtran_destroy_pkt()\fR vectors in the +\fBscsi_hba_tran\fR structure must be initialized during the \fBHBA \fRdriver's +\fBattach\fR(9E) to point to \fBHBA \fRentry points to be called when a target +driver calls \fBscsi_init_pkt\fR(9F) and \fBscsi_destroy_pkt\fR(9F). +.SS "\fBtran_init_pkt()\fR" +.sp +.LP +\fBtran_init_pkt()\fR is the entry point into the \fBHBA \fRwhich is used to +allocate and initialize a \fBscsi_pkt\fR structure on behalf of a \fBSCSI +\fRtarget driver. If \fIpkt\fR is \fINULL,\fR the \fBHBA \fRdriver must use +\fBscsi_hba_pkt_alloc\fR(9F) to allocate a new \fBscsi_pkt\fR structure. +.sp +.LP +If \fIbp\fR is non-\fINULL\fR, the \fBHBA \fRdriver must allocate appropriate +\fBDMA \fRresources for the \fIpkt\fR, for example, +through\fBddi_dma_buf_setup\fR(9F) or \fBddi_dma_buf_bind_handle\fR(9F). +.sp +.LP +If the \fBPKT_CONSISTENT\fR bit is set in \fIflags\fR, the buffer was allocated +by \fBscsi_alloc_consistent_buf\fR(9F). For packets marked with +\fBPKT_CONSISTENT,\fR the \fBHBA \fRdriver must synchronize any cached data +transfers before calling the target driver's command completion callback. +.sp +.LP +If the \fBPKT_DMA_PARTIAL\fR bit is set in \fIflags\fR, the \fBHBA \fRdriver +should set up partial data transfers, such as setting the \fBDDI_DMA_PARTIAL\fR +bit in the \fIflags\fR argument if interfaces such as +\fBddi_dma_buf_setup\fR(9F) or \fBddi_dma_buf_bind_handle\fR(9F) are used. +.sp +.LP +If only partial \fBDMA \fRresources are available, \fBtran_init_pkt()\fR must +return in the \fBpkt_resid\fR field of \fIpkt\fR the number of bytes of \fBDMA +\fRresources not allocated. +.sp +.LP +If both \fIpkt\fR and \fIbp\fR are non-\fINULL\fR, if the +\fBPKT_DMA_PARTIAL\fR bit is set in \fIflags\fR, and if \fBDMA \fRresources +have already been allocated for the pkt with a previous call to +\fBtran_init_pkt()\fR that returned a non-zero \fBpkt_resid\fR field, this +request is to move the \fBDMA \fRresources for the subsequent piece of the +transfer. +.sp +.LP +The contents of \fBscsi_address\fR(9S) pointed to by \fIap\fR are copied into +the \fBpkt_address\fR field of the \fBscsi_pkt\fR(9S) by +\fBscsi_hba_pkt_alloc\fR(9F). +.sp +.LP +\fItgtlen\fR is the length of the packet private area in the \fBscsi_pkt\fR +structure to be allocated on behalf of the \fBSCSI \fRtarget driver. +.sp +.LP +\fIstatuslen\fR is the required length for the \fBSCSI \fRstatus completion +block. If the requested status length is greater than or equal to +\fBsizeof(struct scsi_arq_status)\fR and the \fBauto_rqsense\fR capability +has been set, automatic request sense (\fBARS\fR) is enabled for this packet. +If the status length is less than \fBsizeof(struct scsi_arq_status)\fR, +automatic request sense must be disabled for this \fIpkt\fR. +.sp +.LP +If the \fBHBA\fR driver is not capable of disabling \fBARQ\fR on a per-packet +basis and \fBtran_init_pkt()\fR is called with a \fIstatuslen\fR that is less +than \fBsizeof(struct scsi_arq_status)\fR, the driver's \fBtran_init_pkt\fR +routine should allocate at least \fBsizeof(struct scsi_arq_status)\fR. If an +\fBARS\fR is needed, upon successful \fBARS\fR done by the \fBHBA\fR driver, +the driver must copy the sense data over and set \fBSTAT_ARQ_DONE\fR in +\fBpkt_state\fR. +.sp +.LP +\fIcmdlen\fR is the required length for the \fBSCSI \fRcommand descriptor +block. +.sp +.LP +Note: \fItgtlen\fR, \fIstatuslen\fR, and \fIcmdlen\fR are used only when the +\fBHBA \fRdriver allocates the \fBscsi_pkt\fR(9S), in other words, when +\fIpkt\fR is \fINULL\fR. +.sp +.LP +\fIcallback\fR indicates what the allocator routines should do when resources +are not available: +.sp +.ne 2 +.mk +.na +\fB\fBNULL_FUNC\fR\fR +.ad +.RS 14n +.rt +Do not wait for resources. Return a \fINULL\fR pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSLEEP_FUNC\fR\fR +.ad +.RS 14n +.rt +Wait indefinitely for resources. +.RE + +.SS "tran_destroy_pkt()" +.sp +.LP +\fBtran_destroy_pkt()\fR is the entry point into the \fBHBA \fRthat must free +all of the resources that were allocated to the \fBscsi_pkt\fR(9S) structure +during \fBtran_init_pkt()\fR. +.SH RETURN VALUES +.sp +.LP +\fBtran_init_pkt()\fR must return a pointer to a \fBscsi_pkt\fR(9S) structure +on success, or \fINULL\fR on failure. +.sp +.LP +If \fIpkt\fR is \fINULL\fR on entry, and \fBtran_init_pkt()\fR allocated a +packet through\fBscsi_hba_pkt_alloc\fR(9F) but was unable to allocate \fBDMA +\fRresources, \fBtran_init_pkt()\fR must free the packet through +\fBscsi_hba_pkt_free\fR(9F) before returning \fINULL\fR. +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBtran_setup_pkt\fR(9E), \fBtran_sync_pkt\fR(9E), +\fBbiodone\fR(9F), \fBbioerror\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), +\fBddi_dma_buf_setup\fR(9F), \fBkmem_cache_create\fR(9F), +\fBscsi_alloc_consistent_buf\fR(9F), \fBscsi_destroy_pkt\fR(9F), +\fBscsi_hba_attach\fR(9F), \fBscsi_hba_pkt_alloc\fR(9F), +\fBscsi_hba_pkt_free\fR(9F), \fBscsi_init_pkt\fR(9F), \fBbuf\fR(9S), +\fBscsi_address\fR(9S), \fBscsi_hba_tran\fR(9S), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +If a \fBDMA\fR allocation request fails with \fBDDI_DMA_NOMAPPING\fR, indicate +the error by calling \fBbioerror\fR(9F) with \fIbp\fR and an error code of +\fBEFAULT\fR. +.sp +.LP +If a \fBDMA \fRallocation request fails with \fBDDI_DMA_TOOBIG,\fR indicate the +error by calling \fBbioerror\fR(9F) with \fIbp\fR and an error code of +\fBEINVAL\fR. +.sp +.LP +For increased performance, an HBA driver may want to provide a cache for +\fBscsi_pkt\fR(9S) allocation. This cache should be implemented by the HBA +driver providing a \fBtran_setup_pkt\fR(9E) implementation. Implementing this +cache by direct use of \fBkmem_cache_create\fR(9F) adds a compile-time +dependency on \fBscsi_pkt()\fR size, which is illegal. diff --git a/usr/src/man/man9e/tran_quiesce.9e b/usr/src/man/man9e/tran_quiesce.9e new file mode 100644 index 0000000000..1d6b2eba8f --- /dev/null +++ b/usr/src/man/man9e/tran_quiesce.9e @@ -0,0 +1,99 @@ +'\" 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 tran_quiesce 9E "31 Jan 1999" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_quiesce, tran_unquiesce \- quiesce and unquiesce a SCSI bus +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + +\fBint prefix\fR\fBtran_quiesce\fR(\fBdev_info_t\fR \fI*hba_dip\fR); +.fi + +.LP +.nf +\fBint prefix\fR\fBtran_unquiesce\fR(\fBdev_info_t\fR \fI*hba_dip\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhba_dip\fR\fR +.ad +.RS 11n +.rt +The \fBdev_info_t\fR pointer associated with the SCSI HBA. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_quiesce()\fR and \fBtran_unquiesce()\fR vectors in the +\fBscsi_hba_tran\fR(9S) structure should be initialized during the HBA driver's +\fBattach\fR(9E). They are HBA entry points to be called when a user initiates +quiesce and unquiesce operations through device control interfaces. +.sp +.LP +\fBtran_quiesce()\fR should wait for all outstanding commands to complete and +blocks (or queues) any I/O requests issued. \fBtran_unquiesce()\fR should allow +I/O activities to resume on the SCSI bus. +.sp +.LP +Implementation is hardware specific. +.SH RETURN VALUES +.sp +.LP +\fBtran_quiesce()\fR and \fBtran_unquiesce()\fR should return: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 12n +.rt +Successful completion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNon-zero\fR\fR +.ad +.RS 12n +.rt +An error occurred. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description 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), \fBtran_bus_reset\fR(9E), \fBscsi_hba_tran\fR(9S) diff --git a/usr/src/man/man9e/tran_reset.9e b/usr/src/man/man9e/tran_reset.9e new file mode 100644 index 0000000000..c43d61067f --- /dev/null +++ b/usr/src/man/man9e/tran_reset.9e @@ -0,0 +1,163 @@ +'\" 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 tran_reset 9E "17 Aug 2005" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_reset \- reset a SCSI bus or target +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fB int prefix\fR\fBtran_reset\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBint\fR \fIlevel\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR \fR +.ad +.RS 10n +.rt +Pointer to the \fBscsi_address\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlevel\fR \fR +.ad +.RS 10n +.rt +The level of reset required. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_reset()\fR vector in the \fBscsi_hba_tran\fR(9S) structure must be +initialized during the \fBHBA\fR driver's \fBattach\fR(9E) to point to an +\fBHBA\fR entry point to be called when a target driver calls +\fBscsi_reset\fR(9F). +.sp +.LP +\fBtran_reset()\fR must reset either the \fBSCSI\fR bus, a \fBSCSI\fR target +device, or a \fBSCSI\fR logical unit as specified by \fIlevel\fR. +.sp +.LP +\fIlevel\fR must be one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBRESET_ALL\fR \fR +.ad +.RS 17n +.rt +Reset the \fBSCSI\fR bus. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRESET_TARGET\fR \fR +.ad +.RS 17n +.rt +Reset the target specified by \fIap\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBRESET_LUN\fR \fR +.ad +.RS 17n +.rt +Reset the logical unit specified by \fIap\fR. +.RE + +.sp +.LP +\fBtran_reset\fR should set the \fBpkt_reason\fR field of all outstanding +packets in the transport layer associated with each target or logical unit that +was successfully reset to \fBCMD_RESET\fR and the \fBpkt_statistics\fR field +must be \fBOR\fR'ed with either \fBSTAT_BUS_RESET\fR (if the SCSI bus was +reset) or \fBSTAT_DEV_RESET\fR (if the target or logical unit was reset). +.sp +.LP +The \fBHBA\fR driver should use a \fBSCSI\fR Bus Device Reset Message to reset +a target device. The HBA driver should use a SCSI Logical Unit Reset Message +to reset a logical unit. +.sp +.LP +Packets that are in the transport layer but not yet active on the bus should be +returned with \fBpkt_reason\fR set to \fBCMD_RESET\fR and \fBpkt_statistics\fR +\fBOR\fR'ed with \fBSTAT_ABORTED\fR. +.sp +.LP +Support for \fBRESET_LUN\fR is optional but strongly encouraged for new and +updated HBA drivers. If an HBA driver provides \fBRESET_LUN\fR support, it must +also create the \fBlun-reset\fR capability with a value of zero for each target +device instance represented by a valid \fIap\fR. The HBA is also required to +provide the means to return the current value of the \fBlun-reset\fR capability +in its \fBtran_getcap\fR(9E) routine, as well as the means to change the value +of the \fBlun_reset\fR capability in its \fBtran_getcap\fR(9E) routine. +.SH RETURN VALUES +.sp +.LP +\fBtran_reset()\fR should return: +.sp +.ne 2 +.mk +.na +\fB\fB1\fR \fR +.ad +.RS 6n +.rt +on success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR \fR +.ad +.RS 6n +.rt +on failure. +.RE + +.SH CONTEXT +.sp +.LP +The \fBtran_reset()\fR function can be called from user or interrupt context. +This requirement comes from \fBscsi_reset()\fR. +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBddi_dma_buf_setup\fR(9F), \fBscsi_hba_attach\fR(9F), +\fBscsi_reset\fR(9F), \fBscsi_address\fR(9S), \fBscsi_hba_tran\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +If \fBpkt_reason\fR already indicates that an earlier error had occurred for a +particular \fIpkt\fR, \fBtran_reset()\fR should not overwrite \fBpkt_reason\fR +with \fBCMD_RESET\fR. diff --git a/usr/src/man/man9e/tran_reset_notify.9e b/usr/src/man/man9e/tran_reset_notify.9e new file mode 100644 index 0000000000..9f10d933b6 --- /dev/null +++ b/usr/src/man/man9e/tran_reset_notify.9e @@ -0,0 +1,130 @@ +'\" te +.\" 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 tran_reset_notify 9E "30 Aug 1995" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_reset_notify \- request to notify SCSI target of bus reset +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint prefix\fR\fBtran_reset_notify\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBint\fR \fIflag\fR, + \fBvoid (*\fR\fIcallback\fR, \fBcaddr_t),caddr_t\fR \fIarg\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR \fR +.ad +.RS 13n +.rt +Pointer to the \fBscsi_address\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR \fR +.ad +.RS 13n +.rt +A flag indicating registration or cancellation of a notification request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR \fR +.ad +.RS 13n +.rt +A pointer to the target driver's reset notification function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR \fR +.ad +.RS 13n +.rt +The callback function argument. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_reset_notify()\fR entry point is called when a target driver +requests notification of a bus reset. +.sp +.LP +The \fBtran_reset_notify()\fR vector in the \fBscsi_hba_tran\fR(9S) structure +may be initialized in the \fBHBA \fRdriver's \fBattach\fR(9E) routine to point +to the \fBHBA \fRentry point to be called when a target driver calls +\fBscsi_reset_notify\fR(9F). +.sp +.LP +The argument \fIflag\fR is used to register or cancel the notification. The +supported values for \fIflag\fR are as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_RESET_NOTIFY\fR \fR +.ad +.RS 22n +.rt +Register \fIcallback\fR as the reset notification function for the target. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_RESET_CANCEL\fR \fR +.ad +.RS 22n +.rt +Cancel the reset notification request for the target. +.RE + +.sp +.LP +The \fBHBA \fRdriver maintains a list of reset notification requests +registered by the target drivers. When a bus reset occurs, the \fBHBA +\fRdriver notifies registered target drivers by calling the callback routine, +\fIcallback\fR, with the argument, \fIarg\fR, for each registered target. +.SH RETURN VALUES +.sp +.LP +For \fBSCSI_RESET_NOTIFY\fR requests, \fBtran_reset_notify()\fR must return +\fBDDI_SUCCESS\fR if the notification request has been accepted, and +\fBDDI_FAILURE\fR otherwise. +.sp +.LP +For \fBSCSI_RESET_CANCEL\fR requests, \fBtran_reset_notify()\fR must return +\fBDDI_SUCCESS\fR if the notification request has been canceled, and +\fBDDI_FAILURE\fR otherwise. +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBscsi_ifgetcap\fR(9F), \fBscsi_reset_notify\fR(9F), +\fBscsi_address\fR(9S), \fBscsi_hba_tran\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/tran_setup_pkt.9e b/usr/src/man/man9e/tran_setup_pkt.9e new file mode 100644 index 0000000000..bf3d9c4c14 --- /dev/null +++ b/usr/src/man/man9e/tran_setup_pkt.9e @@ -0,0 +1,257 @@ +'\" 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 tran_setup_pkt 9E "29 Jan 2009" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_setup_pkt, tran_teardown_pkt, tran_pkt_constructor, tran_pkt_destructor \- +SCSI HBA packet allocation and deallocation +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + +\fBstruct scsi_pkt *\fR\fBprefix_tran_setup_pkt\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR, + \fBint (*\fR\fIcallback\fR) (\fIcaddr_t\fR), \fBcaddr_t\fR \fIarg\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBprefix_tran_teardown_pkt\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR); +.fi + +.LP +.nf +\fBint\fR \fBprefix_tran_pkt_constructor\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR, + \fBscsi_hba_tran_t *\fR\fItranp\fR, \fBint\fR \fIkmflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBprefix_tran_pkt_destructor\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR, + \fBstruct scsi_hba_tran_t *\fR\fItranp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR\fR +.ad +.RS 12n +.rt +Pointer to the \fBscsi_pkt\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 12n +.rt +Flags for associating DMA resources with the packet. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 12n +.rt +Pointer to either \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 12n +.rt +Always \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIkmflags\fR\fR +.ad +.RS 12n +.rt +Either \fBKM_SLEEP\fR or \fBKM_NOSLEEP\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_setup_pkt()\fR and \fBtran_destroy_pkt()\fR vectors in the +\fBscsi_hba_tran\fR(9S) structure are alternatives to the \fBtran_init_pkt()\fR +and \fBtran_destroy_pkt()\fR entry points. They are initialized during the +\fBHBA\fR driver's \fBattach\fR(9E) and they are used when a target driver +calls \fBscsi_init_pkt\fR(9F) and \fBscsi_destroy_pkt\fR(9F). +.SS "tran_setup_pkt(\|)" +.sp +.LP +The \fBtran_setup_pkt()\fR vector is the entry point into the \fBHBA\fR which +is used to initialize \fBHBA\fR specific information in a \fBscsi_pkt\fR +structure on behalf of a SCSI target driver. All fields documented in +\fBscsi_pkt\fR(9S) are initialized. +.sp +.LP +If the \fBHBA\fR driver chose not to preallocate memory for \fBpkt_cdbp\fR +and/or \fBpkt_scbp\fR, it must allocate the requested memory at this time and +point \fBpkt_cdbp\fR and \fBpkt_scbp\fR to the allocated memory. +.sp +.LP +An \fBHBA\fR driver which provides a \fBtran_setup_pkt\fR entry point inspects +the \fBpkt_numcookies\fR and \fBpkt_cookies\fR fields at \fBtran_start\fR time +to set up the transfer. If \fBpkt_numcookies\fR is zero, there are no \fBDMA\fR +resources associated with this packet. If \fBpkt_numcookies\fR is not zero, it +indicates the number of \fBDMA\fR cookies that \fBpkt_cookies\fR points to. +.sp +.LP +The \fBpkt_tgtlen\fR field contains the length of the packet private area +pointed to by \fBpkt_private\fR, allocated on behalf of the SCSI target driver. +.sp +.LP +The \fBpkt_scblen\fR field contains the length of the SCSI status completion +block pointed to by \fBpkt_scbp\fR. If the status length is greater than or +equal to sizeof (\fBstruct\fR \fBscsi_arq_status\fR) and the +\fBauto_rqsensecapability\fR has been set, automatic request sense (\fBARS\fR) +is enabled for this packet. If the status \fBlengthislessthansizeof\fR +(\fBstruct\fR \fBscsi_arq_status\fR), automatic request sense should be +disabled for this pkt if the \fBHBA\fR driver is capable of disabling \fBARQ\fR +on a per-packet basis. +.sp +.LP +The \fBpkt_cdblen\fR field contains the length of the SCSI command descriptor +block. +.sp +.LP +The \fIcallback\fR argument indicates what the allocator routines should do +when resources are not available: +.sp +.ne 2 +.mk +.na +\fB\fBNULL_FUNC\fR\fR +.ad +.RS 14n +.rt +Do not wait for resources. Return a \fINULL\fR pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSLEEP_FUNC\fR\fR +.ad +.RS 14n +.rt +Wait indefinitely for resources. +.RE + +.SS "tran_teardown_pkt(\|)" +.sp +.LP +The \fBtran_teardown_pkt()\fR is the entry point into the \fBHBA\fR that must +free all of the resources that were allocated to the \fBscsi_pkt\fR(9S) +structure during \fBtran_setup_pkt()\fR. +.SS "tran_pkt_constructor(\|) tran_pkt_destructor(\|)" +.sp +.LP +When using \fBtran_pkt_setup()\fR and \fBtran_pkt_teardown()\fR, +\fBtran_pkt_constructor()\fR and \fBtran_pkt_destructor()\fR are additional +optional entry points that perform the actions of a constructor and destructor. +The constructor is called after the following fields in the \fBscsi_pkt\fR +structure have been initialized: +.RS +4 +.TP +.ie t \(bu +.el o +\fBpkt_address\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBpkt_ha_private\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBpkt_cdbp\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBpkt_private\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBpkt_scbp\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBpkt_cdblen\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBpkt_tgtlen\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBpkt_scblen\fR +.RE +.sp +.LP +Allocating and freeing a \fBDMA\fR handle are examples of something that could +be done in the constructor and destructor. See \fBkmem_cache_create\fR(9F) for +additional restrictions on what actions can be performed in a constructor and +destructor. +.sp +.LP +HBA drivers that implement \fBtran_setup_pkt()\fR must signal +\fBscsi_pkt\fR(9S) completion by calling \fBscsi_hba_pkt_comp\fR(9F). Direct +use of the \fBscsi_pkt\fR \fIpkt_comp\fR field is not permitted and results in +undefined behavior. +.SH RETURN VALUES +.sp +.LP +\fBtran_setup_pkt()\fR must return zero on success, and \fB-1\fR on failure. +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBtran_sync_pkt\fR(9E), \fBbioerror\fR(9F), +\fBddi_dma_buf_bind_handle\fR(9F), \fBkmem_cache_create\fR(9F), +\fBscsi_alloc_consistent_buf\fR(9F), \fBscsi_destroy_pkt\fR(9F), +\fBscsi_hba_attach\fR(9F), \fBscsi_hba_pkt_alloc\fR(9F), +\fBscsi_hba_pkt_comp\fR(9F), \fBscsi_hba_pkt_free\fR(9F), +\fBscsi_init_pkt\fR(9F), \fBbuf\fR(9S), \fBscsi_address\fR(9S), +\fBscsi_hba_tran\fR(9S), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/tran_start.9e b/usr/src/man/man9e/tran_start.9e new file mode 100644 index 0000000000..2de673eded --- /dev/null +++ b/usr/src/man/man9e/tran_start.9e @@ -0,0 +1,266 @@ +'\" 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 tran_start 9E "17 Aug 2005" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_start \- request to transport a SCSI command +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint prefix\fR\fBtran_start\fR(\fBstruct scsi_address *\fR\fIap\fR, + \fBstruct scsi_pkt *\fR\fIpkt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR \fR +.ad +.RS 8n +.rt +Pointer to the \fBscsi_pkt\fR(9S) structure that is about to be transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIap\fR \fR +.ad +.RS 8n +.rt +Pointer to a \fBscsi_address\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_start()\fR vector in the \fBscsi_hba_tran\fR(9S) structure must +be initialized during the \fBHBA \fRdriver's \fBattach\fR(9E) to point to an +\fBHBA \fRentry point to be called when a target driver calls +\fBscsi_transport\fR(9F). +.sp +.LP +\fBtran_start()\fR must perform the necessary operations on the \fBHBA +\fRhardware to transport the \fBSCSI \fRcommand in the \fIpkt\fR structure to +the target/logical unit device specified in the \fIap\fR structure. +.sp +.LP +If the flag \fBFLAG_NOINTR\fR is set in \fBpkt_flags\fR in \fIpkt\fR, +\fBtran_start()\fR should not return until the command has been completed. The +command completion callback \fBpkt_comp\fR in \fIpkt\fR must not be called for +commands with \fBFLAG_NOINTR\fR set, since the return is made directly to the +function invoking \fBscsi_transport\fR(9F). +.sp +.LP +When the flag \fBFLAG_NOINTR\fR is not set, \fBtran_start()\fR must queue the +command for execution on the hardware and return immediately. The member +\fBpkt_comp\fR in \fIpkt\fR indicates a callback routine to be called upon +command completion. +.sp +.LP +Refer to \fBscsi_pkt\fR(9S) for other bits in \fBpkt_flags\fR for which the +\fBHBA \fRdriver may need to adjust how the command is managed. +.sp +.LP +If the \fBauto_rqsense\fR capability has been set, and the status length +allocated in \fBtran_init_pkt\fR(9E) is greater than or equal to +\fBsizeof(struct scsi_arq_status)\fR, automatic request sense is enabled for +this \fIpkt\fR. If the command terminates with a Check Condition, the \fBHBA +\fRdriver must arrange for a Request Sense command to be transported to that +target/logical unit, and the members of the \fBscsi_arq_status\fR structure +pointed to by \fBpkt_scbp\fR updated with the results of this Request Sense +command before the \fBHBA \fRdriver completes the command pointed by +\fIpkt\fR. +.sp +.LP +The member \fBpkt_time\fR in \fIpkt\fR is the maximum number of seconds in +which the command should complete. Timeout starts when the command is +transmitted on the \fBSCSI\fR bus. A \fBpkt_time\fR of \fB0\fR means no +timeout should be performed. +.sp +.LP +For a command which has timed out, the \fBHBA \fRdriver must perform some +recovery operation to clear the command in the target, typically an Abort +message, or a Device or Bus Reset. The \fBpkt_reason\fR member of the timed +out \fIpkt\fR should be set to \fBCMD_TIMEOUT,\fR and \fBpkt_statistics\fR +\fBOR\fR'ed with \fBSTAT_TIMEOUT\fR. If the \fBHBA \fRdriver can successfully +recover from the timeout, \fBpkt_statistics\fR must also be \fBOR\fR'ed with +one of \fBSTAT_ABORTED\fR, \fBSTAT_BUS_RESET\fR, or \fBSTAT_DEV_RESET\fR, as +appropriate. This informs the target driver that timeout recovery has already +been successfully accomplished for the timed out command. The \fBpkt_comp\fR +completion callback, if not \fINULL\fR, must also be called at the conclusion +of the timeout recovery. +.sp +.LP +If the timeout recovery was accomplished with an Abort Tag message, only the +timed out packet is affected, and the packet must be returned with +\fBpkt_statistics\fR \fBOR\fR'ed with \fBSTAT_ABORTED\fR and +\fBSTAT_TIMEOUT\fR. +.sp +.LP +If the timeout recovery was accomplished with an Abort message, all commands +active in that target are affected. All corresponding packets must be returned +with \fBpkt_reason\fR, \fBCMD_TIMEOUT\fR, and \fBpkt_statistics\fR +\fBOR\fR'ed with \fBSTAT_TIMEOUT\fR and \fBSTAT_ABORTED\fR. +.sp +.LP +If the timeout recovery was accomplished with a Device Reset, all packets +corresponding to commands active in the target must be returned in the +transport layer for this target. Packets corresponding to commands active in +the target must be returned returned with \fBpkt_reason\fR set to +\fBCMD_TIMEOUT\fR, and \fBpkt_statistics\fR \fBOR\fR'ed with +\fBSTAT_DEV_RESET\fR and \fBSTAT_TIMEOUT\fR. Currently inactive packets queued +for the device should be returned with \fBpkt_reason\fR set to \fBCMD_RESET\fR +and \fBpkt_statistics\fR \fBOR\fR'ed with \fBSTAT_ABORTED\fR. +.sp +.LP +If the timeout recovery was accomplished with a Bus Reset, all packets +corresponding to commands active in the target must be returned in the +transport layer. Packets corresponding to commands active in the target must be +returned with \fBpkt_reason\fR set to \fBCMD_TIMEOUT\fR and +\fBpkt_statistics\fR \fBOR\fR'ed with \fBSTAT_TIMEOUT\fR and +\fBSTAT_BUS_RESET\fR. All queued packets for other targets on this bus must be +returned with \fBpkt_reason\fR set to \fBCMD_RESET\fR and \fBpkt_statistics\fR +\fBOR'ed\fR with \fBSTAT_ABORTED\fR. +.sp +.LP +Note that after either a Device Reset or a Bus Reset, the \fBHBA \fRdriver +must enforce a reset delay time of \fB\&'scsi-reset-delay'\fR milliseconds, +during which time no commands should be sent to that device, or any device on +the bus, respectively. +.sp +.LP +\fBtran_start()\fR should initialize the following members in \fIpkt\fR to +\fB0\fR. Upon command completion, the \fBHBA \fRdriver should ensure that the +values in these members are updated to accurately reflect the states through +which the command transitioned while in the transport layer. +.sp +.ne 2 +.mk +.na +\fB\fBpkt_resid\fR \fR +.ad +.RS 19n +.rt +For commands with data transfer, this member must be updated to indicate the +residual of the data transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_reason\fR\fR +.ad +.RS 19n +.rt +The reason for the command completion. This field should be set to +\fBCMD_CMPLT\fR at the beginning of \fBtran_start()\fR, then updated if the +command ever transitions to an abnormal termination state. To avoid losing +information, do not set \fBpkt_reason\fR to any other error state unless it +still has its original \fBCMD_CMPLT\fR value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_statistics\fR \fR +.ad +.RS 19n +.rt +Bit field of transport-related statistics. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_state\fR \fR +.ad +.RS 19n +.rt +Bit field with the major states through which a \fBSCSI\fR command can +transition. Note: The members listed above, and \fBpkt_hba_private\fR member, +are the only fields in the \fBscsi_pkt\fR(9S) structure which may be modified +by the transport layer. +.RE + +.SH RETURN VALUES +.sp +.LP +\fBtran_start()\fR must return: +.sp +.ne 2 +.mk +.na +\fB\fBTRAN_ACCEPT\fR \fR +.ad +.RS 21n +.rt +The packet was accepted by the transport layer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTRAN_BUSY\fR \fR +.ad +.RS 21n +.rt +The packet could not be accepted because there was already a packet in progress +for this target/logical unit, the \fBHBA \fRqueue was full, or the target +device queue was full. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTRAN_BADPKT\fR \fR +.ad +.RS 21n +.rt +The \fBDMA \fRcount in the packet exceeded the \fBDMA \fRengine's maximum +\fBDMA \fRsize, or the packet could not be accepted for other reasons. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTRAN_FATAL_ERROR\fR \fR +.ad +.RS 21n +.rt +A fatal error has occurred in the \fBHBA. \fR +.RE + +.SH CONTEXT +.sp +.LP +The \fBtran_start()\fR function can be called from user or interupt context. +This requirement comes from \fBscsi_transport()\fR. +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBtran_init_pkt\fR(9E), \fBscsi_hba_attach\fR(9F), +\fBscsi_transport\fR(9F), \fBscsi_address\fR(9S), \fBscsi_arq_status\fR(9S), +\fBscsi_hba_tran\fR(9S), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/tran_sync_pkt.9e b/usr/src/man/man9e/tran_sync_pkt.9e new file mode 100644 index 0000000000..e0c3601e6e --- /dev/null +++ b/usr/src/man/man9e/tran_sync_pkt.9e @@ -0,0 +1,74 @@ +'\" te +.\" Copyright (c) 1993, 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 tran_sync_pkt 9E "1 Nov 1993" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_sync_pkt \- SCSI HBA memory synchronization entry point +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBvoid prefix\fR\fBtran_sync_pkt\fR(\fBstruct scsi_address *\fR\fIap\fR, + \fBstruct scsi_pkt *\fR\fIpkt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR \fR +.ad +.RS 8n +.rt +A pointer to a \fBscsi_address\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR \fR +.ad +.RS 8n +.rt +A pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_sync_pkt()\fR vector in the \fBscsi_hba_tran\fR(9S) structure must +be initialized during the \fBHBA\fR driver's \fBattach\fR(9E) to point to an +\fBHBA\fR driver entry point to be called when a target driver calls +\fBscsi_sync_pkt\fR(9F). +.sp +.LP +\fBtran_sync_pkt()\fR must synchronize a \fBHBA\fR's or device's view of the +data associated with the \fIpkt\fR, typically by calling +\fBddi_dma_sync\fR(9F). The operation may also involve \fBHBA\fR +hardware-specific details, such as flushing \fBI/O\fR caches, or stalling +until hardware buffers have been drained. +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBtran_init_pkt\fR(9E), \fBddi_dma_sync\fR(9F), +\fBscsi_hba_attach\fR(9F), \fBscsi_init_pkt\fR(9F), \fBscsi_sync_pkt\fR(9F), +\fBscsi_address\fR(9S), \fBscsi_hba_tran\fR(9S), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +A target driver may call \fBtran_sync_pkt()\fR on packets for which no +\fBDMA\fR resources were allocated. diff --git a/usr/src/man/man9e/tran_tgt_free.9e b/usr/src/man/man9e/tran_tgt_free.9e new file mode 100644 index 0000000000..42c6f500bc --- /dev/null +++ b/usr/src/man/man9e/tran_tgt_free.9e @@ -0,0 +1,92 @@ +'\" te +.\" Copyright (c) 1995, 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 tran_tgt_free 9E "1 Nov 1993" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_tgt_free \- request to free HBA resources allocated on behalf of a target +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBvoid prefix\fR\fBtran_tgt_free\fR(\fBdev_info_t *\fR\fIhba_dip\fR, \fBdev_info_t *\fR\fItgt_dip\fR, + \fBscsi_hba_tran_t *\fR\fIhba_tran\fR, \fBstruct scsi_device *\fR\fIsd\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhba_dip\fR \fR +.ad +.RS 13n +.rt +Pointer to a \fBdev_info_t\fR structure, referring to the \fBHBA\fR device +instance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItgt_dip\fR \fR +.ad +.RS 13n +.rt +Pointer to a \fBdev_info_t\fR structure, referring to the target device +instance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhba_tran\fR \fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_hba_tran\fR(9S) structure, consisting of the \fBHBA\fR's +transport vectors. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsd\fR \fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_device\fR(9S) structure, describing the target. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_tgt_free()\fR vector in the \fBscsi_hba_tran\fR(9S) structure may +be initialized during the \fBHBA\fR driver's \fBattach\fR(9E) to point to an +\fBHBA\fR driver function to be called by the system when an instance of a +target device is being detached. The \fBtran_tgt_free()\fR vector, if not +\fINULL\fR, is called after the target device instance has returned +successfully from its \fBdetach\fR(9E) entry point, but before the +\fBdev_info\fR node structure is removed from the system. The \fBHBA\fR driver +should release any resources allocated during its \fBtran_tgt_init()\fR or +\fBtran_tgt_probe()\fR initialization performed for this target device +instance. +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBdetach\fR(9E), \fBtran_tgt_init\fR(9E), +\fBtran_tgt_probe\fR(9E), \fBscsi_device\fR(9S), \fBscsi_hba_tran\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/tran_tgt_init.9e b/usr/src/man/man9e/tran_tgt_init.9e new file mode 100644 index 0000000000..d6be9313dd --- /dev/null +++ b/usr/src/man/man9e/tran_tgt_init.9e @@ -0,0 +1,132 @@ +'\" te +.\" Copyright (c) 1995, 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 tran_tgt_init 9E "1 Nov 1993" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_tgt_init \- request to initialize HBA resources on behalf of a particular +target +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBvoid prefix\fR\fBtran_tgt_init\fR(\fBdev_info_t *\fR\fIhba_dip\fR, \fBdev_info_t *\fR\fItgt_dip\fR, + \fBscsi_hba_tran_t *\fR\fIhba_tran\fR, \fBstruct scsi_device *\fR\fIsd\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhba_dip\fR \fR +.ad +.RS 13n +.rt +Pointer to a \fBdev_info_t\fR structure, referring to the \fBHBA\fR device +instance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItgt_dip\fR \fR +.ad +.RS 13n +.rt +Pointer to a \fBdev_info_t\fR structure, referring to the target device +instance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhba_tran\fR \fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_hba_tran\fR(9S) structure, consisting of the \fBHBA\fR's +transport vectors. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsd\fR \fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_device\fR(9S) structure, describing the target. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_tgt_init()\fR vector in the \fBscsi_hba_tran\fR(9S) structure may +be initialized during the \fBHBA\fR driver's \fBattach\fR(9E) to point to an +\fBHBA\fR driver function to be called by the system when an instance of a +target device is being created. The \fBtran_tgt_init()\fR vector, if not +\fINULL\fR,is called after the \fBdev_info\fR node structure is created for +this target device instance, but before \fBprobe\fR(9E) for this instance is +called. Before receiving transport requests from the target driver instance, +the \fBHBA\fR may perform any initialization required for this particular +target during the call of the \fBtran_tgt_init()\fR vector. +.sp +.LP +Note that \fIhba_tran\fR will point to a cloned copy of the +\fBscsi_hba_tran_t\fR structure allocated by the \fBHBA\fR driver if the +\fBSCSI_HBA_TRAN_CLONE\fR flag was specified in the call to +\fBscsi_hba_attach\fR(9F). In this case, the \fBHBA\fR driver may choose to +initialize the \fItran_tgt_private\fR field in the structure pointed to by +\fIhba_tran\fR, to point to the data specific to the particular target device +instance. +.SH RETURN VALUES +.sp +.LP +\fBtran_tgt_init()\fR must return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR \fR +.ad +.RS 16n +.rt +the \fBHBA\fR driver can support the addressed target, and was able to +initialize per-target resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR \fR +.ad +.RS 16n +.rt +the \fBHBA\fR driver cannot support the addressed target, or was unable to +initialize per-target resources. In this event, the initialization of this +instance of the target device will not be continued, the target driver's +\fBprobe\fR(9E) will not be called, and the \fItgt_dip\fR structure destroyed. +.RE + +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBprobe\fR(9E), \fBtran_tgt_free\fR(9E), +\fBtran_tgt_probe\fR(9E), \fBscsi_hba_attach_setup\fR(9F), +\fBscsi_device\fR(9S), \fBscsi_hba_tran\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/tran_tgt_probe.9e b/usr/src/man/man9e/tran_tgt_probe.9e new file mode 100644 index 0000000000..5271c7d36a --- /dev/null +++ b/usr/src/man/man9e/tran_tgt_probe.9e @@ -0,0 +1,111 @@ +'\" te +.\" Copyright (c) 1993, 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 tran_tgt_probe 9E "1 Nov 1993" "SunOS 5.11" "Driver Entry Points" +.SH NAME +tran_tgt_probe \- request to probe SCSI bus for a particular target +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint prefix\fR\fBtran_tgt_probe\fR(\fBstruct scsi_device *\fR\fIsd\fR, \fBint (*\fR\fIwaitfunc\fR, + \fBvoid));\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsd\fR \fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_device\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwaitfunc\fR \fR +.ad +.RS 13n +.rt +Pointer to either \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtran_tgt_probe()\fR vector in the \fBscsi_hba_tran\fR(9S) structure may +be initialized during the \fBHBA \fRdriver's \fBattach\fR(9E) to point to a +function to be called by \fBscsi_probe\fR(9F) when called by a target driver +during \fBprobe\fR(9E) and \fBattach\fR(9E) to probe for a particular \fBSCSI +\fRtarget on the bus. In the absence of an \fBHBA\fR-specific +\fBtran_tgt_probe()\fR function, the default \fBscsi_probe\fR(9F) behavior is +supplied by the function \fBscsi_hba_probe\fR(9F). +.sp +.LP +The possible choices the \fBHBA \fRdriver may make are: +.RS +4 +.TP +.ie t \(bu +.el o +Initialize the \fBtran_tgt_probe\fR vector to point to +\fBscsi_hba_probe\fR(9F), which results in the same behavior. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Initialize the \fBtran_tgt_probe\fR vector to point to a private function in +the \fBHBA\fR, which may call \fBscsi_hba_probe\fR(9F) before or after any +necessary processing, as long as all the defined \fBscsi_probe\fR(9F) semantics +are preserved. +.RE +.sp +.LP +\fIwaitfunc\fR indicates what \fBtran_tgt_probe()\fR should do when resources +are not available: +.sp +.ne 2 +.mk +.na +\fB\fBNULL_FUNC\fR \fR +.ad +.RS 15n +.rt +Do not wait for resources. See \fBscsi_probe\fR(9F) for defined return values +if no resources are available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSLEEP_FUNC\fR \fR +.ad +.RS 15n +.rt +Wait indefinitely for resources. +.RE + +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBprobe\fR(9E), \fBtran_tgt_free\fR(9E), +\fBtran_tgt_init\fR(9E), \fBscsi_hba_probe\fR(9F), \fBscsi_probe\fR(9F), +\fBscsi_device\fR(9S), \fBscsi_hba_tran\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9e/write.9e b/usr/src/man/man9e/write.9e new file mode 100644 index 0000000000..2f918bae69 --- /dev/null +++ b/usr/src/man/man9e/write.9e @@ -0,0 +1,113 @@ +'\" 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 write 9E "28 Mar 1997" "SunOS 5.11" "Driver Entry Points" +.SH NAME +write \- write data to a device +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/open.h> +#include <sys/cred.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint prefix\fR\fBwrite\fR(\fBdev_t\fR \fIdev\fR, \fBstruct uio *\fR\fIuio_p\fR, \fBcred_t *\fR\fIcred_p\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). This entry point is optional. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR \fR +.ad +.RS 11n +.rt +Device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuio_p\fR \fR +.ad +.RS 11n +.rt +Pointer to the \fBuio\fR(9S) structure that describes where the data is to be +stored in user space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcred_p\fR \fR +.ad +.RS 11n +.rt +Pointer to the user credential structure for the \fBI/O \fRtransaction. +.RE + +.SH DESCRIPTION +.sp +.LP +Used for character or raw data \fBI/O, \fRthe driver \fBwrite()\fR routine is +called indirectly through \fBcb_ops\fR(9S) by the \fBwrite\fR(2) system call. +The \fBwrite()\fR routine supervises the data transfer from user space to a +device described by the \fBuio\fR(9S) structure. +.sp +.LP +The \fBwrite()\fR routine should check the validity of the minor number +component of \fIdev\fR and the user credentials pointed to by \fIcred_p\fR, if +pertinent. +.SH RETURN VALUES +.sp +.LP +The \fBwrite()\fR routine should return \fB0\fR for success, or the +appropriate error number. +.SH EXAMPLES +.sp +.LP +The following is an example of a \fBwrite()\fR routine using \fBphysio\fR(9F) +to perform writes to a seekable device: +.sp +.in +2 +.nf +static int +xxwrite(dev_t dev, struct uio *uiop, cred_t *credp) +{ + int instance; + xx_t xx; + + instance = getminor(dev); + xx = ddi_get_soft_state(xxstate, instance); + if (xx == NULL) + return (ENXIO); + return (physio(xxstrategy, NULL, dev, B_WRITE, + xxmin, uiop)); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBread\fR(2), \fBwrite\fR(2), \fBread\fR(9E), \fBphysio\fR(9F), +\fBcb_ops\fR(9S), \fBuio\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR |