diff options
| author | Richard Lowe <richlowe@richlowe.net> | 2011-03-14 14:05:30 -0400 |
|---|---|---|
| committer | Richard Lowe <richlowe@richlowe.net> | 2011-03-14 14:05:30 -0400 |
| commit | c10c16dec587a0662068f6e2991c29ed3a9db943 (patch) | |
| tree | f414286f4bba41d75683ed4fbbaa6bfa4bf7fabd /usr/src/man/man9f | |
| parent | 68caef18a23a498d9e3017b983562c0f4fd8ab23 (diff) | |
| download | illumos-joyent-c10c16dec587a0662068f6e2991c29ed3a9db943.tar.gz | |
243 system manual pages should live with the software
Reviewed by: garrett@nexenta.com
Reviewed by: gwr@nexenta.com
Reviewed by: trisk@opensolaris.org
Approved by: gwr@nexenta.com
--HG--
extra : rebase_source : 0c599d0bec0dc8865fbba67721a7a6cd6b1feefb
Diffstat (limited to 'usr/src/man/man9f')
505 files changed, 92150 insertions, 0 deletions
diff --git a/usr/src/man/man9f/ASSERT.9f b/usr/src/man/man9f/ASSERT.9f new file mode 100644 index 0000000000..56e4f16a54 --- /dev/null +++ b/usr/src/man/man9f/ASSERT.9f @@ -0,0 +1,49 @@ +'\" te +.\" Copyright (c) 2006, 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 ASSERT 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ASSERT, assert \- expression verification +.SH SYNOPSIS +.LP +.nf +#include <sys/debug.h> + + + +\fBvoid\fR \fBASSERT\fR(\fB\fR\fIEX\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIEX\fR\fR +.ad +.RS 6n +.rt +boolean expression. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBASSERT()\fR macro checks to see if the expression \fIEX\fR is true. If +it is not, then \fBASSERT()\fR causes an error message to be logged to the +console and the system to panic. \fBASSERT()\fR works only if the preprocessor +symbol \fBDEBUG\fR is defined. +.SH CONTEXT +.sp +.LP +The \fBASSERT()\fR macro can be used from user, interrupt, or kernel context. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/Intro.9f b/usr/src/man/man9f/Intro.9f new file mode 100644 index 0000000000..b79589e52b --- /dev/null +++ b/usr/src/man/man9f/Intro.9f @@ -0,0 +1,888 @@ +'\" 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 Intro 9F "11 Mar 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +Intro, intro \- introduction to DDI/DKI functions +.SH DESCRIPTION +.sp +.LP +Section 9F describes the kernel functions available for use by device drivers. +See \fBIntro\fR(9E) for an overview of device driver interfaces. +.sp +.LP +In this section, the information for each driver function is organized under +the following headings: +.RS +4 +.TP +.ie t \(bu +.el o +\fBNAME\fR summarizes the function's purpose. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBSYNOPSIS\fR shows the syntax of the function's entry point in the source +code. \fB#include\fR directives are shown for required headers. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBINTERFACE\fR \fBLEVEL\fR describes any architecture dependencies. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBARGUMENTS\fR describes any arguments required to invoke the function. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBDESCRIPTION\fR describes general information about the function. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBRETURN\fR \fBVALUES\fR describes the return values and messages that can +result from invoking the function. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBCONTEXT\fR indicates from which driver context (user, kernel, interrupt, or +high-level interrupt) the function can be called. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A driver function has \fIuser context\fR if it was directly invoked because of +a user thread. The \fBread\fR(9E) entry point of the driver, invoked by a +\fBread\fR(2) system call, has user context. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A driver function has \fIkernel context\fR if was invoked by some other part of +the kernel. In a block device driver, the \fBstrategy\fR(9E) entry point may be +called by the page daemon to write pages to the device. The page daemon has no +relation to the current user thread, so in this case \fBstrategy\fR(9E) has +kernel context. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fIInterrupt context\fR is kernel context, but also has an interrupt level +associated with it. Driver interrupt routines have interrupt context. +.sp +Note that a mutex acquired in user or kernel context that can also be acquired +in interrupt context means that the user or kernel context thread holding that +mutex is subject to all the restrictions imposed by interrupt context, for the +duration of the ownership of that mutex. Please see the \fBmutex\fR(9F) man +page for a more complete discussion of proper mutex handling for drivers. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fIHigh-level interrupt context\fR is a more restricted form of interrupt +context. If a driver interrupt priority returned from +\fBddi_intr_get_pri\fR(9F) is greater than the priority returned from +\fBddi_intr_get_hilevel_pri\fR(9F) this indicates the interrupt handler will +run in high-level interrupt context. These interrupt routines are only allowed +to call \fBddi_intr_trigger_softint\fR(9F), \fBmutex_enter\fR(9F), and +\fBmutex_exit\fR(9F). Furthermore, \fBmutex_enter\fR(9F) and +\fBmutex_exit\fR(9F) may only be called on mutexes initialized with the +interrupt priority returned by \fBddi_intr_get_pri\fR(9F). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBSEE ALSO\fR indicates functions that are related by usage and sources, and +which can be referred to for further information. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +\fBEXAMPLES\fR shows how the function can be used in driver code. +.RE +.sp +.LP +Every driver MUST include <\fBsys/ddi.h\fR> and <\fBsys/sunddi.h\fR>, in that +order, and as the last files the driver includes. +.SH STREAMS KERNEL FUNCTION SUMMARY +.sp +.LP +The following table summarizes the STREAMS functions described in this section. +.sp + +.sp +.TS +tab(); +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +RoutineType +_ +\fBadjmsg\fRDDI/DKI +\fBallocb\fRDDI/DKI +\fBallocb_tmpl\fRSolaris DDI +\fBbackq\fRDDI/DKI +\fBbcanput\fRDDI/DKI +\fBbcanputnext\fRDDI/DKI +\fBbufcall\fRDDI/DKI +\fBcanput\fRDDI/DKI +\fBcanputnext\fRDDI/DKI +\fBclrbuf\fRDDI/DKI +\fBcopyb\fRDDI/DKI +\fBcopymsg\fRDDI/DKI +\fBDB_BASE\fRSolaris DDI +\fBDB_LIM\fRSolaris DDI +\fBDB_REF\fRSolaris DDI +\fBDB_TYPE\fRSolaris DDI +\fBdatamsg\fRDDI/DKI +\fBdupb\fRDDI/DKI +\fBdupmsg\fRDDI/DKI +\fBenableok\fRDDI/DKI +\fBesballoc\fRDDI/DKI +\fBesbbcall\fRDDI/DKI +\fBflushband\fRDDI/DKI +\fBflushq\fRDDI/DKI +\fBfreeb\fRDDI/DKI +\fBfreemsg\fRDDI/DKI +\fBfreezestr\fRDDI/DKI +\fBgetq\fRDDI/DKI +\fBIOC_CONVER_FROM\fRSolaris DDI +\fBinsq\fRDDI/DKI +\fBlinkb\fRDDI/DKI +\fBMBLKHEAD\fRSolaris DDI +\fBMBLKIN\fRSolaris DDI +\fBMBLKL\fRSolaris DDI +\fBMBLKSIZE\fRSolaris DDI +\fBMBLKTAIL\fRSolaris DDI +\fBmcopyin\fRSolaris DDI +\fBmcopymsg\fRSolaris DDI +\fBmcopyout\fRSolaris DDI +\fBmerror\fRSolaris DDI +\fBmexchange\fRSolaris DDI +\fBmioc2ack\fRSolaris DDI +\fBmiocack\fRSolaris DDI +\fBmexchange\fRSolaris DDI +\fBmiocpullup\fRSolaris DDI +\fBmkiocb\fRSolaris DDI +\fBmsgdsize\fRDDI/DKI +\fBmsgpullup\fRDDI/DKI +\fBmsgsize\fRSolaris DDI +\fBmt-streams\fRSolaris DDI +\fBnoenable\fRDDI/DKI +\fBOTHERQ\fRDDI/DKI +\fBpullupmsg\fRDDI/DKI +\fBput\fRDDI/DKI +\fBputbq\fRDDI/DKI +\fBputctl\fRDDI/DKI +\fBputctl1\fRDDI/DKI +\fBputnext\fRDDI/DKI +\fBputnextctl\fRDDI/DKI +\fBputq\fRDDI/DKI +\fBqassociate\fRSolaris DDI +\fBqbufcall\fRSolaris DDI +\fBqenable\fRDDI/DKI +\fBqprocson\fRDDI/DKI +\fBqprocsoff\fRDDI/DKI +\fBqreply\fRDDI/DKI +\fBqsize\fRDDI/DKI +\fBqtimeout\fRSolaris DDI +\fBqunbufcall\fRSolaris DDI +\fBquntimeout\fRSolaris DDI +\fBqwait\fRSolaris DDI +\fBqwait_sig\fRSolaris DDI +\fBqwriter\fRSolaris DDI +\fBRD\fRDDI/DKI +\fBrmvb\fRDDI/DKI +\fBrmvq\fRDDI/DKI +\fBSAMESTR\fRDDI/DKI +\fBstrlog\fRDDI/DKI +\fBstrqget\fRDDI/DKI +\fBstrqset\fRDDI/DKI +\fBtestb\fRDDI/DKI +\fBunbufcall\fRDDI/DKI +\fBunfreezestr\fRDDI/DKI +\fBunlinkb\fRDDI/DKI +\fBWR\fRDDI/DKI +.TE + +.sp +.LP +The following table summarizes the functions not specific to STREAMS. +.sp + +.sp +.TS +tab(); +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +RoutineType +_ +\fBASSERT\fRDDI/DKI +\fBanocancel\fRSolaris DDI +\fBaphysio\fRSolaris DDI +\fBatomic_add\fRDDI/DKI +\fBatomic_and\fRDDI/DKI +\fBatomic_bits\fRDDI/DKI +\fBatomic_cas\fRDDI/DKI +\fBatomic_dec\fRDDI/DKI +\fBatomic_inc\fRDDI/DKI +\fBatomic_ops\fRDDI/DKI +\fBatomic_or\fRDDI/DKI +\fBatomic_swap\fRDDI/DKI +\fBbcmp\fRDDI/DKI +\fBbcopy\fRDDI/DKI +\fBbioclone\fRSolaris DDI +\fBbiodone\fRDDI/DKI +\fBbiofini\fRSolaris DDI +\fBbioinit\fRSolaris DDI +\fBbiomodified\fRSolaris DDI +\fBbiosize\fRSolaris DDI +\fBbioerror\fRSolaris DDI +\fBbioreset\fRSolaris DDI +\fBbiowait\fRDDI/DKI +\fBbp_copyin\fRDDI/DKI +\fBbp_copyout\fRDDI/DKI +\fBbp_mapin\fRDDI/DKI +\fBbp_mapout\fRDDI/DKI +\fBbtop\fRDDI/DKI +\fBbtopr\fRDDI/DKI +\fBbzero\fRDDI/DKI +\fBcmn_err\fRDDI/DKI +\fBcondvar\fRSolaris DDI +\fBcopyin\fRDDI/DKI +\fBcopyout\fRDDI/DKI +\fBcsx_AccessConfigurationRegister\fRSolaris DDI +\fBcsx_ConvertSize\fRSolaris DDI +\fBcsx_ConvertSpeed\fRSolaris DDI +\fBcsx_CS_DDI_Info\fRSolaris DDI +\fBcsx_DeregisterClient\fRSolaris DDI +\fBcsx_DupHandle\fRSolaris DDI +\fBcsx_Error2Text\fRSolaris DDI +\fBcsx_Event2Text\fRSolaris DDI +\fBcsx_FreeHandle\fRSolaris DDI +\fBcsx_Get8\fRSolaris DDI +\fBcsx_GetFirstClient\fRSolaris DDI +\fBcsx_GetFirstTuple\fRSolaris DDI +\fBcsx_GetHandleOffset\fRSolaris DDI +\fBcsx_GetMappedAddr\fRSolaris DDI +\fBcsx_GetStatus\fRSolaris DDI +\fBcsx_GetTupleData\fRSolaris DDI +\fBcsx_MakeDeviceNode\fRSolaris DDI +\fBcsx_MapLogSocket\fRSolaris DDI +\fBcsx_MapMemPage\fRSolaris DDI +\fBcsx_ModifyConfiguration\fRSolaris DDI +\fBcsx_ModifyWindow\fRSolaris DDI +\fBcsx_Parse_CISTPL_BATTERY\fRSolaris DDI +\fBcsx_Parse_CISTPL_BYTEORDER\fRSolaris DDI +\fBcsx_Parse_CISTPL_CFTABLE_ENTRY\fRSolaris DDI +\fBcsx_Parse_CISTPL_CONFIG\fRSolaris DDI +\fBcsx_Parse_CISTPL_DATE\fRSolaris DDI +\fBcsx_Parse_CISTPL_DEVICE\fRSolaris DDI +\fBcsx_Parse_CISTPL_DEVICEGEO\fRSolaris DDI +\fBcsx_Parse_CISTPL_DEVICEGEO_A\fRSolaris DDI +\fBcsx_Parse_CISTPL_FORMAT\fRSolaris DDI +\fBcsx_Parse_CISTPL_FUNCE\fRSolaris DDI +\fBcsx_Parse_CISTPL_FUNCID\fRSolaris DDI +\fBcsx_Parse_CISTPL_GEOMETRY\fRSolaris DDI +\fBcsx_Parse_CISTPL_JEDEC_C\fRSolaris DDI +\fBcsx_Parse_CISTPL_LINKTARGET\fRSolaris DDI +\fBcsx_Parse_CISTPL_LONGLINK_A\fRSolaris DDI +\fBcsx_Parse_CISTPL_LONGLINK_MFC\fRSolaris DDI +\fBcsx_Parse_CISTPL_MANFID\fRSolaris DDI +\fBcsx_Parse_CISTPL_ORG\fRSolaris DDI +\fBcsx_Parse_CISTPL_SPCL\fRSolaris DDI +\fBcsx_Parse_CISTPL_SWIL\fRSolaris DDI +\fBcsx_Parse_CISTPL_VERS_1\fRSolaris DDI +\fBcsx_Parse_CISTPL_VERS_2\fRSolaris DDI +\fBcsx_ParseTuple\fRSolaris DDI +\fBcsx_Put8\fRSolaris DDI +\fBcsx_RegisterClient\fRSolaris DDI +\fBcsx_ReleaseConfiguration\fRSolaris DDI +\fBcsx_RepGet8\fRSolaris DDI +\fBcsx_RepPut8\fRSolaris DDI +\fBcsx_RequestConfiguration\fRSolaris DDI +\fBcsx_RequestIO\fRSolaris DDI +\fBcsx_RequestIRQ\fRSolaris DDI +\fBcsx_RequestSocketMask\fRSolaris DDI +\fBcsx_RequestWindow\fRSolaris DDI +\fBcsx_ResetFunction\fRSolaris DDI +\fBcsx_SetEventMask\fRSolaris DDI +\fBcsx_SetHandleOffset\fRSolaris DDI +\fBcsx_ValidateCIS\fRSolaris DDI +\fBcv_broadcast\fRSolaris DDI +\fBcv_destroy\fRSolaris DDI +\fBcv_init\fRSolaris DDI +\fBcv_signal\fRSolaris DDI +\fBcv_timedwait\fRSolaris DDI +\fBcv_wait\fRSolaris DDI +\fBcv_wait_sig\fRSolaris DDI +\fBddi_add_event_handler\fRSolaris DDI +\fBddi_add_intr\fRSolaris DDI +\fBddi_add_softintr\fRSolaris DDI +\fBddi_binding_name\fRSolaris DDI +\fBddi_btop\fRSolaris DDI +\fBddi_btopr\fRSolaris DDI +\fBddi_can_receive_sig\fRSolaris DDI +\fBddi_check_acc_handle\fRSolaris DDI +\fBddi_copyin\fRSolaris DDI +\fBddi_copyout\fRSolaris DDI +\fBddi_create_minor_node\fRSolaris DDI +\fBddi_cred\fRSolaris DDI +\fBddi_dev_is_sid\fRSolaris DDI +\fBddi_dev_nintrs\fRSolaris DDI +\fBddi_dev_nregs\fRSolaris DDI +\fBddi_dev_regsize\fRSolaris DDI +\fBddi_device_copy\fRSolaris DDI +\fBddi_device_zero\fRSolaris DDI +\fBddi_devmap_segmap\fRSolaris DDI +\fBddi_dma_addr_bind_handle\fRSolaris DDI +\fBddi_dma_addr_setup\fRSolaris DDI +\fBddi_dma_alloc_handle\fRSolaris DDI +\fBddi_dma_buf_bind_handle\fRSolaris DDI +\fBddi_dma_buf_setup\fRSolaris DDI +\fBddi_dma_burstsizes\fRSolaris DDI +\fBddi_dma_coff\fRSolaris SPARC DDI +\fBddi_dma_curwin\fRSolaris SPARC DDI +\fBddi_dma_devalign\fRSolaris DDI +\fBddi_dma_free\fRSolaris DDI +\fBddi_dma_free_handle\fRSolaris DDI +\fBddi_dma_getwin\fRSolaris DDI +\fBddi_dma_get_attr\fRSolaris DDI +\fBddi_dma_htoc\fRSolaris SPARC DDI +\fBddi_dma_mem_alloc\fRSolaris DDI +\fBddi_dma_mem_free\fRSolaris DDI +\fBddi_dma_movwin\fRSolaris SPARC DDI +\fBddi_dma_nextcookie\fRSolaris DDI +\fBddi_dma_nextseg\fRSolaris DDI +\fBddi_dma_nextwin\fRSolaris DDI +\fBddi_dma_numwin\fRSolaris DDI +\fBddi_dma_segtocookie\fRSolaris DDI +\fBddi_dma_set_sbus64\fRSolaris DDI +\fBddi_dma_setup\fRSolaris DDI +\fBddi_dma_sync\fRSolaris DDI +\fBddi_dma_unbind_handle\fRSolaris DDI +\fBddi_dmae\fRSolaris x86 DDI +\fBddi_dmae_1stparty\fRSolaris x86 DDI +\fBddi_dmae_alloc\fRSolaris x86 DDI +\fBddi_dmae_disable\fRSolaris x86 DDI +\fBddi_dmae_enable\fRSolaris x86 DDI +\fBddi_dmae_getattr\fRSolaris x86 DDI +\fBddi_dmae_getcnt\fRSolaris x86 DDI +\fBddi_dmae_getlim\fRSolaris x86 DDI +\fBddi_dmae_prog\fRSolaris x86 DDI +\fBddi_dmae_release\fRSolaris x86 DDI +\fBddi_dmae_stop\fRSolaris x86 DDI +\fBddi_driver_major\fRSolaris DDI +\fBddi_driver_name\fRSolaris DDI +\fBddi_enter_critical\fRSolaris DDI +\fBddi_exit_critical\fRSolaris DDI +\fBddi_ffs\fRSolaris DDI +\fBddi_fls\fRSolaris DDI +\fBddi_fm_acc_err_clear\fRSolaris DDI +\fBddi_fm_acc_err_get\fRSolaris DDI +\fBddi_fm_ereport_post\fRSolaris DDI +\fBddi_fm_handler_register\fRSolaris DDI +\fBddi_fm_init\fRSolaris DDI +\fBddi_fm_service_impact\fRSolaris DDI +\fBddi_get16\fRSolaris DDI +\fBddi_get32\fRSolaris DDI +\fBddi_get64\fRSolaris DDI +\fBddi_get8\fRSolaris DDI +\fBddi_get_cred\fRSolaris DDI +\fBddi_get_devstate\fRSolaris DDI +\fBddi_get_driver_private\fRSolaris DDI +\fBddi_get_eventcookie\fRSolaris DDI +\fBddi_get_iblock_cookie\fRSolaris DDI +\fBddi_get_iminor\fRSolaris DDI +\fBddi_get_instance\fRSolaris DDI +\fBddi_get_kt_did\fRSolaris DDI +\fBddi_get_lbolt\fRSolaris DDI +\fBddi_get_name\fRSolaris DDI +\fBddi_get_parent\fRSolaris DDI +\fBddi_get_pid\fRSolaris DDI +\fBddi_get_soft_iblock_cookie\fRSolaris DDI +\fBddi_get_soft_state\fRSolaris DDI +\fBddi_getb\fRSolaris DDI +\fBddi_getl\fRSolaris DDI +\fBddi_getll\fRSolaris DDI +\fBddi_getlongprop\fRSolaris DDI +\fBddi_getlongprop_buf\fRSolaris DDI +\fBddi_getprop\fRSolaris DDI +\fBddi_getproplen\fRSolaris DDI +\fBddi_getw\fRSolaris DDI +\fBddi_intr_add_handler\fRSolaris DDI +\fBddi_intr_add_softint\fRSolaris DDI +\fBddi_intr_alloc\fRSolaris DDI +\fBddi_intr_block_disable\fRSolaris DDI +\fBddi_intr_block_enable\fRSolaris DDI +\fBddi_intr_clr_mask\fRSolaris DDI +\fBddi_intr_dup_handler\fRSolaris DDI +\fBddi_intr_disable\fRSolaris DDI +\fBddi_intr_enable\fRSolaris DDI +\fBddi_intr_free\fRSolaris DDI +\fBddi_intr_get_cap\fRSolaris DDI +\fBddi_intr_get_hilevel_pri\fRSolaris DDI +\fBddi_intr_get_navail\fRSolaris DDI +\fBddi_intr_get_nintrs\fRSolaris DDI +\fBddi_intr_get_pending\fRSolaris DDI +\fBddi_intr_get_pri\fRSolaris DDI +\fBddi_intr_get_softint_pri\fRSolaris DDI +\fBddi_intr_get_supported_types\fRSolaris DDI +\fBddi_intr_remove_handler\fRSolaris DDI +\fBddi_intr_remove_softint\fRSolaris DDI +\fBddi_intr_set_cap\fRSolaris DDI +\fBddi_intr_set_mask\fRSolaris DDI +\fBddi_intr_set_pri\fRSolaris DDI +\fBddi_intr_set_softint_pri\fRSolaris DDI +\fBddi_intr_trigger_softint\fRSolaris DDI +\fBddi_io_get16\fRSolaris DDI +\fBddi_io_get32\fRSolaris DDI +\fBddi_io_get8\fRSolaris DDI +\fBddi_io_getb\fRSolaris DDI +\fBddi_io_getl\fRSolaris DDI +\fBddi_io_getw\fRSolaris DDI +\fBddi_io_put16\fRSolaris DDI +\fBddi_io_put32\fRSolaris DDI +\fBddi_io_put8\fRSolaris DDI +\fBddi_io_putb\fRSolaris DDI +\fBddi_io_putl\fRSolaris DDI +\fBddi_io_putw\fRSolaris DDI +\fBddi_io_rep_get16\fRSolaris DDI +\fBddi_io_rep_get32\fRSolaris DDI +\fBddi_io_rep_get8\fRSolaris DDI +\fBddi_io_rep_getb\fRSolaris DDI +\fBddi_io_rep_getl\fRSolaris DDI +\fBddi_io_rep_getw\fRSolaris DDI +\fBddi_io_rep_put16\fRSolaris DDI +\fBddi_io_rep_put32\fRSolaris DDI +\fBddi_io_rep_put8\fRSolaris DDI +\fBddi_io_rep_putb\fRSolaris DDI +\fBddi_io_rep_putl\fRSolaris DDI +\fBddi_io_rep_putw\fRSolaris DDI +\fBddi_iomin\fRSolaris DDI +\fBddi_iopb_alloc\fRSolaris DDI +\fBddi_iopb_free\fRSolaris DDI +\fBddi_log_sysevent\fRSolaris DDI +\fBddi_map_regs\fRSolaris DDI +\fBddi_mapdev\fRSolaris DDI +\fBddi_mapdev_intercept\fRSolaris DDI +\fBddi_mapdev_nointercept\fRSolaris DDI +\fBddi_mapdev_set_device_acc_attr\fRSolaris DDI +\fBddi_mem_alloc\fRSolaris DDI +\fBddi_mem_free\fRSolaris DDI +\fBddi_mem_get16\fRSolaris DDI +\fBddi_mem_get32\fRSolaris DDI +\fBddi_mem_get64\fRSolaris DDI +\fBddi_mem_get8\fRSolaris DDI +\fBddi_mem_getb\fRSolaris DDI +\fBddi_mem_getl\fRSolaris DDI +\fBddi_mem_getll\fRSolaris DDI +\fBddi_mem_getw\fRSolaris DDI +\fBddi_mem_put16\fRSolaris DDI +\fBddi_mem_put32\fRSolaris DDI +\fBddi_mem_put64\fRSolaris DDI +\fBddi_mem_put8\fRSolaris DDI +\fBddi_mem_putb\fRSolaris DDI +\fBddi_mem_putl\fRSolaris DDI +\fBddi_mem_putll\fRSolaris DDI +\fBddi_mem_putw\fRSolaris DDI +\fBddi_mem_rep_get16\fRSolaris DDI +\fBddi_mem_rep_get32\fRSolaris DDI +\fBddi_mem_rep_get64\fRSolaris DDI +\fBddi_mem_rep_get8\fRSolaris DDI +\fBddi_mem_rep_getb\fRSolaris DDI +\fBddi_mem_rep_getl\fRSolaris DDI +\fBddi_mem_rep_getll\fRSolaris DDI +\fBddi_mem_rep_getw\fRSolaris DDI +\fBddi_mem_rep_put16\fRSolaris DDI +\fBddi_mem_rep_put32\fRSolaris DDI +\fBddi_mem_rep_put64\fRSolaris DDI +\fBddi_mem_rep_put8\fRSolaris DDI +\fBddi_mem_rep_putb\fRSolaris DDI +\fBddi_mem_rep_putl\fRSolaris DDI +\fBddi_mem_rep_putll\fRSolaris DDI +\fBddi_mem_rep_putw\fRSolaris DDI +\fBddi_mmap_get_model\fRSolaris DDI +\fBddi_model_convert_from\fRSolaris DDI +\fBddi_modopen\fRSolaris DDI +\fBddi_no_info\fRSolaris DDI +\fBddi_node_name\fRSolaris DDI +\fBddi_peek16\fRSolaris DDI +\fBddi_peek32\fRSolaris DDI +\fBddi_peek64\fRSolaris DDI +\fBddi_peek8\fRSolaris DDI +\fBddi_peekc\fRSolaris DDI +\fBddi_peekd\fRSolaris DDI +\fBddi_peekl\fRSolaris DDI +\fBddi_peeks\fRSolaris DDI +\fBddi_periodic_add\fRSolaris DDI +\fBddi_periodic_delete\fRSolaris DDI +\fBddi_poke16\fRSolaris DDI +\fBddi_poke32\fRSolaris DDI +\fBddi_poke64\fRSolaris DDI +\fBddi_poke8\fRSolaris DDI +\fBddi_pokec\fRSolaris DDI +\fBddi_poked\fRSolaris DDI +\fBddi_pokel\fRSolaris DDI +\fBddi_pokes\fRSolaris DDI +\fBddi_prop_create\fRSolaris DDI +\fBddi_prop_exists\fRSolaris DDI +\fBddi_prop_free\fRSolaris DDI +\fBddi_prop_get_int\fRSolaris DDI +\fBddi_prop_lookup\fRSolaris DDI +\fBddi_prop_lookup_byte_array\fRSolaris DDI +\fBddi_prop_lookup_int_array\fRSolaris DDI +\fBddi_prop_lookup_string\fRSolaris DDI +\fBddi_prop_lookup_string_array\fRSolaris DDI +\fBddi_prop_modify\fRSolaris DDI +\fBddi_prop_op\fRSolaris DDI +\fBddi_prop_remove\fRSolaris DDI +\fBddi_prop_remove_all\fRSolaris DDI +\fBddi_prop_undefine\fRSolaris DDI +\fBddi_prop_update\fRSolaris DDI +\fBddi_prop_update_byte_array\fRSolaris DDI +\fBddi_prop_update_int\fRSolaris DDI +\fBddi_prop_update_int_array\fRSolaris DDI +\fBddi_prop_update_string\fRSolaris DDI +\fBddi_prop_update_string_array\fRSolaris DDI +\fBddi_ptob\fRSolaris DDI +\fBddi_put16\fRSolaris DDI +\fBddi_put32\fRSolaris DDI +\fBddi_put64\fRSolaris DDI +\fBddi_put8\fRSolaris DDI +\fBddi_putb\fRSolaris DDI +\fBddi_putl\fRSolaris DDI +\fBddi_putll\fRSolaris DDI +\fBddi_putw\fRSolaris DDI +\fBddi_regs_map_free\fRSolaris DDI +\fBddi_regs_map_setup\fRSolaris DDI +\fBddi_remove_event_handler\fRSolaris DDI +\fBddi_remove_intr\fRSolaris DDI +\fBddi_remove_minor_node\fRSolaris DDI +\fBddi_remove_softintr\fRSolaris DDI +\fBddi_removing_power\fRSolaris DDI +\fBddi_rep_get16\fRSolaris DDI +\fBddi_rep_get32\fRSolaris DDI +\fBddi_rep_get64\fRSolaris DDI +\fBddi_rep_get8\fRSolaris DDI +\fBddi_rep_getb\fRSolaris DDI +\fBddi_rep_getl\fRSolaris DDI +\fBddi_rep_getll\fRSolaris DDI +\fBddi_rep_getw\fRSolaris DDI +\fBddi_rep_put16\fRSolaris DDI +\fBddi_rep_put32\fRSolaris DDI +\fBddi_rep_put64\fRSolaris DDI +\fBddi_rep_put8\fRSolaris DDI +\fBddi_rep_putb\fRSolaris DDI +\fBddi_rep_putl\fRSolaris DDI +\fBddi_rep_putll\fRSolaris DDI +\fBddi_rep_putw\fRSolaris DDI +\fBddi_report_dev\fRSolaris DDI +\fBddi_root_node\fRSolaris DDI +\fBddi_segmap\fRSolaris DDI +\fBddi_segmap_setup\fRSolaris DDI +\fBddi_set_driver_private\fRSolaris DDI +\fBddi_slaveonly\fRSolaris DDI +\fBddi_soft_state\fRSolaris DDI +\fBddi_soft_state_fini\fRSolaris DDI +\fBddi_soft_state_free\fRSolaris DDI +\fBddi_soft_state_init\fRSolaris DDI +\fBddi_soft_state_zalloc\fRSolaris DDI +\fBddi_strlol\fRSolaris DDI +\fBddi_strloul\fRSolaris DDI +\fBddi_trigger_softintr\fRSolaris DDI +\fBddi_umem_alloc\fRSolaris DDI +\fBddi_umem_free\fRSolaris DDI +\fBddi_umem_iosetup\fRSolaris DDI +\fBddi_umem_lock\fRSolaris DDI +\fBddi_unmap_regs\fRSolaris DDI +\fBdelay\fRDDI/DKI +\fBdevmap_default_access\fRSolaris DDI +\fBdevmap_devmem_setup\fRSolaris DDI +\fBdevmap_do_ctxmgt\fRSolaris DDI +\fBdevmap_load\fRSolaris DDI +\fBdevmap_set_ctx_timeout\fRSolaris DDI +\fBdevmap_setup\fRSolaris DDI +\fBdevmap_umem_setup\fRSolaris DDI +\fBdevmap_unload\fRSolaris DDI +\fBdisksort\fRSolaris DDI +\fBdlbindack\fRSolaris DDI +\fBdrv_getparm\fRDDI/DKI +\fBdrv_hztousec\fRDDI/DKI +\fBdrv_priv\fRDDI/DKI +\fBdrv_usectohz\fRDDI/DKI +\fBdrv_usecwait\fRDDI/DKI +\fBfree_pktiopb\fRSolaris DDI +\fBfreerbuf\fRDDI/DKI +\fBget_pktiopb\fRSolaris DDI +\fBgeterror\fRDDI/DKI +\fBgethrtime\fRDDI/DKI +\fBgetmajor\fRDDI/DKI +\fBgetminor\fRDDI/DKI +\fBgetrbuf\fRDDI/DKI +\fBgld\fRSolaris DDI +\fBhat_getkpfnum\fRDKI only +\fBid32_alloc\fRSolaris DDI +\fBinb\fRSolaris x86 DDI +\fBinl\fRSolaris x86 DDI +\fBinw\fRSolaris x86 DDI +\fBkiconv\fRSolaris DDI +\fBkiconv_close\fRSolaris DDI +\fBkiconv_open\fRSolaris DDI +\fBkiconvstr\fRSolaris DDI +\fBkmem_alloc\fRDDI/DKI +\fBkmem_cache_create\fRSolaris DDI +\fBkmem_free\fRDDI/DKI +\fBkmem_zalloc\fRDDI/DKI +\fBkstat_create\fRSolaris DDI +\fBkstat_delete\fRSolaris DDI +\fBkstat_install\fRSolaris DDI +\fBkstat_named_init\fRSolaris DDI +\fBkstat_queue\fRSolaris DDI +\fBkstat_runq_back_to_waitq\fRSolaris DDI +\fBkstat_runq_enter\fRSolaris DDI +\fBkstat_runq_exit\fRSolaris DDI +\fBkstat_waitq_enter\fRSolaris DDI +\fBkstat_waitq_exit\fRSolaris DDI +\fBkstat_waitq_to_runq\fRSolaris DDI +\fBldi_add_event_handler\fRSolaris DDI +\fBldi_aread\fRSolaris DDI +\fBldi_devmap\fRSolaris DDI +\fBldi_dump\fRSolaris DDI +\fBldi_ev_finalize\fRSolaris DDI +\fBldi_ev_get_cookie\fRSolaris DDI +\fBldi_ev_get_type\fRSolaris DDI +\fBldi_ev_notify\fRSolaris DDI +\fBldi_ev_register_callbacks\fRSolaris DDI +\fBldi_ev_remove_callbacks\fRSolaris DDI +\fBldi_get_dev\fRSolaris DDI +\fBldi_get_eventcookie\fRSolaris DDI +\fBldi_get_size\fRSolaris DDI +\fBldi_ident_from_dev\fRSolaris DDI +\fBldi_ioctl\fRSolaris DDI +\fBldi_open_by_dev\fRSolaris DDI +\fBldi_poll\fRSolaris DDI +\fBldi_prop_exists\fRSolaris DDI +\fBldi_prop_get_int\fRSolaris DDI +\fBldi_prop_get_lookup_int_array\fRSolaris DDI +\fBldi_putmsg\fRSolaris DDI +\fBldi_read\fRSolaris DDI +\fBldi_remove_event_handler\fRSolaris DDI +\fBldi_strategy\fRSolaris DDI +\fBmakecom_g0\fRSolaris DDI +\fBmakecom_g0_s\fRSolaris DDI +\fBmakecom_g1\fRSolaris DDI +\fBmakecom_g5\fRSolaris DDI +\fBmakedevice\fRDDI/DKI +\fBmax\fRDDI/DKI +\fBmax\fRDDI/DKI +\fBmembar_ops\fRSolaris DDI +\fBmemchr\fRSolaris DDI +\fBminphys\fRSolaris DDI +\fBmod_info\fRSolaris DDI +\fBmod_install\fRSolaris DDI +\fBmod_remove\fRSolaris DDI +\fBmutex_destroy\fRSolaris DDI +\fBmutex_enter\fRSolaris DDI +\fBmutex_exit\fRSolaris DDI +\fBmutex_init\fRSolaris DDI +\fBmutex_owned\fRSolaris DDI +\fBmutex_tryenter\fRSolaris DDI +\fBnochpoll\fRSolaris DDI +\fBnodev\fRDDI/DKI +\fBnulldev\fRDDI/DKI +\fBnumtos\fRSolaris DDI +\fBnvlist_add_boolean\fRSolaris DDI +\fBnvlist_alloc\fRSolaris DDI +\fBnvlist_lookup_boolean\fRSolaris DDI +\fBnvlist_lookup_nvpair\fRSolaris DDI +\fBnvlist_next_nvpair\fRSolaris DDI +\fBnvlist_remove\fRSolaris DDI +\fBnvlist_value_byte\fRSolaris DDI +\fBoutb\fRSolaris x86 DDI +\fBoutl\fRSolaris x86 DDI +\fBoutw\fRSolaris x86 DDI +\fBpci_config_get16\fRSolaris DDI +\fBpci_config_get32\fRSolaris DDI +\fBpci_config_get64\fRSolaris DDI +\fBpci_config_get8\fRSolaris DDI +\fBpci_config_getb\fRSolaris DDI +\fBpci_config_getl\fRSolaris DDI +\fBpci_config_getw\fRSolaris DDI +\fBpci_config_put16\fRSolaris DDI +\fBpci_config_put32\fRSolaris DDI +\fBpci_config_put64\fRSolaris DDI +\fBpci_config_put8\fRSolaris DDI +\fBpci_config_putb\fRSolaris DDI +\fBpci_config_putl\fRSolaris DDI +\fBpci_config_putw\fRSolaris DDI +\fBpci_config_setup\fRSolaris DDI +\fBpci_config_teardown\fRSolaris DDI +\fBpci_ereport_setup\fRSolaris DDI +\fBpci_report_pmcap\fRSolaris DDI +\fBpci_save_config_regs\fRSolaris DDI +\fBphysio\fRSolaris DDI +\fBpm_busy_component\fRSolaris DDI +\fBpm_power_has_changed\fRSolaris DDI +\fBpm_raise_power\fRSolaris DDI +\fBpm_trans_check\fRSolaris DDI +\fBpollwakeup\fRDDI/DKI +\fBpci_config_teardown\fRSolaris DDI +\fBpci_config_teardown\fRSolaris DDI +\fBpriv_getbyname\fRSolaris DDI +\fBpriv_policy\fRSolaris DDI +\fBproc_signal\fRSolaris DDI +\fBproc_unref\fRSolaris DDI +\fBptob\fRDDI/DKI +\fBrepinsb\fRSolaris x86 DDI +\fBrepinsd\fRSolaris x86 DDI +\fBrepinsw\fRSolaris x86 DDI +\fBrepoutsb\fRSolaris x86 DDI +\fBrepoutsd\fRSolaris x86 DDI +\fBrepoutsw\fRSolaris x86 DDI +\fBrmalloc\fRDDI/DKI +\fBrmalloc_wait\fRDDI/DKI +\fBrmallocmap\fRDDI/DKI +\fBrmallocmap_wait\fRDDI/DKI +\fBrmfree\fRDDI/DKI +\fBrmfreemap\fRDDI/DKI +\fBrw_destroy\fRSolaris DDI +\fBrw_downgrade\fRSolaris DDI +\fBrw_enter\fRSolaris DDI +\fBrw_exit\fRSolaris DDI +\fBrw_init\fRSolaris DDI +\fBrw_read_locked\fRSolaris DDI +\fBrw_tryenter\fRSolaris DDI +\fBrw_tryupgrade\fRSolaris DDI +\fBscsi_abort\fRSolaris DDI +\fBscsi_alloc_consistent_buf\fRSolaris DDI +\fBscsi_cname\fRSolaris DDI +\fBscsi_destroy_pkt\fRSolaris DDI +\fBscsi_dmafree\fRSolaris DDI +\fBscsi_dmaget\fRSolaris DDI +\fBscsi_dname\fRSolaris DDI +\fBscsi_errmsg\fRSolaris DDI +\fBscsi_ext_sense_fields\fRSolaris DDI +\fBscsi_find_sense_descr\fRSolaris DDI +\fBscsi_free_consistent_buf\fRSolaris DDI +\fBscsi_get_device_type_scsi_options\fRSolaris DDI +\fBscsi_get_device_type_string\fRSolaris DDI +\fBscsi_hba_attach\fRSolaris DDI +\fBscsi_hba_attach_setup\fRSolaris DDI +\fBscsi_hba_detach\fRSolaris DDI +\fBscsi_hba_fini\fRSolaris DDI +\fBscsi_hba_init\fRSolaris DDI +\fBscsi_hba_lookup_capstr\fRSolaris DDI +\fBscsi_hba_pkt_alloc\fRSolaris DDI +\fBscsi_hba_pkt_free\fRSolaris DDI +\fBscsi_hba_probe\fRSolaris DDI +\fBscsi_hba_tran_alloc\fRSolaris DDI +\fBscsi_hba_tran_free\fRSolaris DDI +\fBscsi_ifgetcap\fRSolaris DDI +\fBscsi_ifsetcap\fRSolaris DDI +\fBscsi_init_pkt\fRSolaris DDI +\fBscsi_log\fRSolaris DDI +\fBscsi_mname\fRSolaris DDI +\fBscsi_pktalloc\fRSolaris DDI +\fBscsi_pktfree\fRSolaris DDI +\fBscsi_poll\fRSolaris DDI +\fBscsi_probe\fRSolaris DDI +\fBscsi_resalloc\fRSolaris DDI +\fBscsi_reset\fRSolaris DDI +\fBscsi_reset_notify\fRSolaris DDI +\fBscsi_resfree\fRSolaris DDI +\fBscsi_rname\fRSolaris DDI +\fBscsi_sense_key\fRSolaris DDI +\fBscsi_setup_cdb\fRSolaris DDI +\fBscsi_slave\fRSolaris DDI +\fBscsi_sname\fRSolaris DDI +\fBscsi_sync_pkt\fRSolaris DDI +\fBscsi_transport\fRSolaris DDI +\fBscsi_unprobe\fRSolaris DDI +\fBscsi_unslave\fRSolaris DDI +\fBscsi_validate_sense\fRSolaris DDI +\fBscsi_vu_errmsg\fRSolaris DDI +\fBsema_destroy\fRSolaris DDI +\fBsema_init\fRSolaris DDI +\fBsema_p\fRSolaris DDI +\fBsema_p_sig\fRSolaris DDI +\fBsema_tryp\fRSolaris DDI +\fBsema_v\fRSolaris DDI +\fBsprintf\fRSolaris DDI +\fBstoi\fRSolaris DDI +\fBstrchr\fRSolaris DDI +\fBstrcmp\fRSolaris DDI +\fBstrcpy\fRSolaris DDI +\fBstrlen\fRSolaris DDI +\fBstrncmp\fRSolaris DDI +\fBstrncpy\fRSolaris DDI +\fBSTRUCT_DECL\fRSolaris DDI +\fBswab\fRDDI/DKI +\fBtaskq\fRSolaris DDI +\fBtimeout\fRDDI/DKI +\fBu8_strcmp\fRSolaris DDI +\fBu8_textprep_str\fRSolaris DDI +\fBu8_validate\fRSolaris DDI +\fBuconv_u16tou32\fRSolaris DDI +\fBuiomove\fRDDI/DKI +\fBuntimeout\fRDDI/DKI +\fBureadc\fRDDI/DKI +\fBusb_alloc_request\fRSolaris DDI +\fBusb_client_attach\fRSolaris DDI +\fBusb_clr_feature\fRSolaris DDI +\fBusb_create_pm_components\fRSolaris DDI +\fBusb_get_addr\fRSolaris DDI +\fBusb_get_alt_if\fRSolaris DDI +\fBusb_get_cfg\fRSolaris DDI +\fBusb_get_current_frame_number\fRSolaris DDI +\fBusb_get_dev_data\fRSolaris DDI +\fBusb_get_max_pkts_per_ioc_request\fRSolaris DDI +\fBusb_get_status\fRSolaris DDI +\fBusb_get_string_desc\fRSolaris DDI +\fBusb_handle_remote_wakeup\fRSolaris DDI +\fBusb_lookup_ep_data\fRSolaris DDI +\fBusb_parse_data\fRSolaris DDI +\fBusb_pipe_bulk_xfer\fRSolaris DDI +\fBusb_pipe_close\fRSolaris DDI +\fBusb_pipe_ctrl_xfer\fRSolaris DDI +\fBusb_pipe_drain_reqs\fRSolaris DDI +\fBusb_pipe_get_max_bulk_transfer_size\fRSolaris DDI +\fBusb_pipe_get_state\fRSolaris DDI +\fBusb_pipe_intr_xfer\fRSolaris DDI +\fBusb_pipe_isoc_xfer\fRSolaris DDI +\fBusb_pipe_open\fRSolaris DDI +\fBusb_pipe_reset\fRSolaris DDI +\fBusb_pipe_set_private\fRSolaris DDI +\fBusb_register_hotplug_cbs\fRSolaris DDI +\fBusb_reset_device\fRSolaris DDI +\fBuwritec\fRDDI/DKI +\fBva_arg\fRSolaris DDI +\fBva_end\fRSolaris DDI +\fBva_start\fRSolaris DDI +\fBvcmn_err\fRDDI/DKI +\fBvsprintf\fRSolaris DDI +.TE + +.SH SEE ALSO +.sp +.LP +\fBIntro\fR(9E), \fBmutex\fR(9F) diff --git a/usr/src/man/man9f/Makefile b/usr/src/man/man9f/Makefile new file mode 100644 index 0000000000..719a150e50 --- /dev/null +++ b/usr/src/man/man9f/Makefile @@ -0,0 +1,1993 @@ +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 9f + +MANFILES = ASSERT.9f \ + Intro.9f \ + OTHERQ.9f \ + RD.9f \ + SAMESTR.9f \ + STRUCT_DECL.9f \ + WR.9f \ + adjmsg.9f \ + allocb.9f \ + atomic_add.9f \ + atomic_and.9f \ + atomic_bits.9f \ + atomic_cas.9f \ + atomic_dec.9f \ + atomic_inc.9f \ + atomic_ops.9f \ + atomic_or.9f \ + atomic_swap.9f \ + backq.9f \ + bcanput.9f \ + bcmp.9f \ + bcopy.9f \ + bioclone.9f \ + biodone.9f \ + bioerror.9f \ + biofini.9f \ + bioinit.9f \ + biomodified.9f \ + bioreset.9f \ + biosize.9f \ + biowait.9f \ + bp_copyin.9f \ + bp_copyout.9f \ + bp_mapin.9f \ + bp_mapout.9f \ + btop.9f \ + btopr.9f \ + bufcall.9f \ + bzero.9f \ + canput.9f \ + clrbuf.9f \ + cmn_err.9f \ + condvar.9f \ + copyb.9f \ + copyin.9f \ + copymsg.9f \ + copyout.9f \ + csx_AccessConfigurationRegister.9f \ + csx_CS_DDI_Info.9f \ + csx_ConvertSize.9f \ + csx_ConvertSpeed.9f \ + csx_DeregisterClient.9f \ + csx_DupHandle.9f \ + csx_Error2Text.9f \ + csx_Event2Text.9f \ + csx_FreeHandle.9f \ + csx_Get8.9f \ + csx_GetFirstClient.9f \ + csx_GetFirstTuple.9f \ + csx_GetHandleOffset.9f \ + csx_GetMappedAddr.9f \ + csx_GetStatus.9f \ + csx_GetTupleData.9f \ + csx_MakeDeviceNode.9f \ + csx_MapLogSocket.9f \ + csx_MapMemPage.9f \ + csx_ModifyConfiguration.9f \ + csx_ModifyWindow.9f \ + csx_ParseTuple.9f \ + csx_Parse_CISTPL_BATTERY.9f \ + csx_Parse_CISTPL_BYTEORDER.9f \ + csx_Parse_CISTPL_CFTABLE_ENTRY.9f \ + csx_Parse_CISTPL_CONFIG.9f \ + csx_Parse_CISTPL_DATE.9f \ + csx_Parse_CISTPL_DEVICE.9f \ + csx_Parse_CISTPL_DEVICEGEO.9f \ + csx_Parse_CISTPL_DEVICEGEO_A.9f \ + csx_Parse_CISTPL_FORMAT.9f \ + csx_Parse_CISTPL_FUNCE.9f \ + csx_Parse_CISTPL_FUNCID.9f \ + csx_Parse_CISTPL_GEOMETRY.9f \ + csx_Parse_CISTPL_JEDEC_C.9f \ + csx_Parse_CISTPL_LINKTARGET.9f \ + csx_Parse_CISTPL_LONGLINK_A.9f \ + csx_Parse_CISTPL_LONGLINK_MFC.9f \ + csx_Parse_CISTPL_MANFID.9f \ + csx_Parse_CISTPL_ORG.9f \ + csx_Parse_CISTPL_SPCL.9f \ + csx_Parse_CISTPL_SWIL.9f \ + csx_Parse_CISTPL_VERS_1.9f \ + csx_Parse_CISTPL_VERS_2.9f \ + csx_Put8.9f \ + csx_RegisterClient.9f \ + csx_ReleaseConfiguration.9f \ + csx_RepGet8.9f \ + csx_RepPut8.9f \ + csx_RequestConfiguration.9f \ + csx_RequestIO.9f \ + csx_RequestIRQ.9f \ + csx_RequestSocketMask.9f \ + csx_RequestWindow.9f \ + csx_ResetFunction.9f \ + csx_SetEventMask.9f \ + csx_SetHandleOffset.9f \ + csx_ValidateCIS.9f \ + datamsg.9f \ + ddi_add_event_handler.9f \ + ddi_add_intr.9f \ + ddi_add_softintr.9f \ + ddi_binding_name.9f \ + ddi_btop.9f \ + ddi_can_receive_sig.9f \ + ddi_cb_register.9f \ + ddi_check_acc_handle.9f \ + ddi_copyin.9f \ + ddi_copyout.9f \ + ddi_create_minor_node.9f \ + ddi_cred.9f \ + ddi_dev_is_needed.9f \ + ddi_dev_is_sid.9f \ + ddi_dev_nintrs.9f \ + ddi_dev_nregs.9f \ + ddi_dev_regsize.9f \ + ddi_dev_report_fault.9f \ + ddi_device_copy.9f \ + ddi_device_zero.9f \ + ddi_devid_compare.9f \ + ddi_dma_addr_bind_handle.9f \ + ddi_dma_addr_setup.9f \ + ddi_dma_alloc_handle.9f \ + ddi_dma_buf_bind_handle.9f \ + ddi_dma_buf_setup.9f \ + ddi_dma_burstsizes.9f \ + ddi_dma_coff.9f \ + ddi_dma_curwin.9f \ + ddi_dma_devalign.9f \ + ddi_dma_free.9f \ + ddi_dma_free_handle.9f \ + ddi_dma_get_attr.9f \ + ddi_dma_getwin.9f \ + ddi_dma_htoc.9f \ + ddi_dma_mem_alloc.9f \ + ddi_dma_mem_free.9f \ + ddi_dma_movwin.9f \ + ddi_dma_nextcookie.9f \ + ddi_dma_nextseg.9f \ + ddi_dma_nextwin.9f \ + ddi_dma_numwin.9f \ + ddi_dma_segtocookie.9f \ + ddi_dma_set_sbus64.9f \ + ddi_dma_setup.9f \ + ddi_dma_sync.9f \ + ddi_dma_unbind_handle.9f \ + ddi_dmae.9f \ + ddi_driver_major.9f \ + ddi_driver_name.9f \ + ddi_enter_critical.9f \ + ddi_ffs.9f \ + ddi_fm_acc_err_clear.9f \ + ddi_fm_acc_err_get.9f \ + ddi_fm_ereport_post.9f \ + ddi_fm_handler_register.9f \ + ddi_fm_init.9f \ + ddi_fm_service_impact.9f \ + ddi_get8.9f \ + ddi_get_cred.9f \ + ddi_get_devstate.9f \ + ddi_get_driver_private.9f \ + ddi_get_eventcookie.9f \ + ddi_get_instance.9f \ + ddi_get_kt_did.9f \ + ddi_get_lbolt.9f \ + ddi_get_parent.9f \ + ddi_get_pid.9f \ + ddi_get_time.9f \ + ddi_getiminor.9f \ + ddi_in_panic.9f \ + ddi_intr_add_handler.9f \ + ddi_intr_add_softint.9f \ + ddi_intr_alloc.9f \ + ddi_intr_dup_handler.9f \ + ddi_intr_enable.9f \ + ddi_intr_get_cap.9f \ + ddi_intr_get_hilevel_pri.9f \ + ddi_intr_get_nintrs.9f \ + ddi_intr_get_pending.9f \ + ddi_intr_get_pri.9f \ + ddi_intr_get_supported_types.9f \ + ddi_intr_hilevel.9f \ + ddi_intr_set_mask.9f \ + ddi_intr_set_nreq.9f \ + ddi_io_get8.9f \ + ddi_io_put8.9f \ + ddi_io_rep_get8.9f \ + ddi_io_rep_put8.9f \ + ddi_iomin.9f \ + ddi_iopb_alloc.9f \ + ddi_log_sysevent.9f \ + ddi_map_regs.9f \ + ddi_mem_alloc.9f \ + ddi_mem_get8.9f \ + ddi_mem_put8.9f \ + ddi_mem_rep_get8.9f \ + ddi_mem_rep_put8.9f \ + ddi_mmap_get_model.9f \ + ddi_model_convert_from.9f \ + ddi_modopen.9f \ + ddi_no_info.9f \ + ddi_node_name.9f \ + ddi_peek.9f \ + ddi_periodic_add.9f \ + ddi_periodic_delete.9f \ + ddi_poke.9f \ + ddi_prop_create.9f \ + ddi_prop_exists.9f \ + ddi_prop_get_int.9f \ + ddi_prop_lookup.9f \ + ddi_prop_op.9f \ + ddi_prop_update.9f \ + ddi_put8.9f \ + ddi_regs_map_free.9f \ + ddi_regs_map_setup.9f \ + ddi_remove_event_handler.9f \ + ddi_remove_minor_node.9f \ + ddi_removing_power.9f \ + ddi_rep_get8.9f \ + ddi_rep_put8.9f \ + ddi_report_dev.9f \ + ddi_root_node.9f \ + ddi_segmap.9f \ + ddi_slaveonly.9f \ + ddi_soft_state.9f \ + ddi_strtol.9f \ + ddi_strtoll.9f \ + ddi_strtoul.9f \ + ddi_umem_alloc.9f \ + ddi_umem_iosetup.9f \ + ddi_umem_lock.9f \ + delay.9f \ + devmap_default_access.9f \ + devmap_devmem_setup.9f \ + devmap_do_ctxmgt.9f \ + devmap_set_ctx_timeout.9f \ + devmap_setup.9f \ + devmap_unload.9f \ + disksort.9f \ + dlbindack.9f \ + drv_getparm.9f \ + drv_hztousec.9f \ + drv_priv.9f \ + drv_usectohz.9f \ + drv_usecwait.9f \ + dupb.9f \ + dupmsg.9f \ + enableok.9f \ + esballoc.9f \ + esbbcall.9f \ + flushband.9f \ + flushq.9f \ + freeb.9f \ + freemsg.9f \ + freerbuf.9f \ + freezestr.9f \ + get_pktiopb.9f \ + geterror.9f \ + gethrtime.9f \ + getmajor.9f \ + getminor.9f \ + getq.9f \ + getrbuf.9f \ + gld.9f \ + hook_alloc.9f \ + hook_free.9f \ + id32_alloc.9f \ + inb.9f \ + insq.9f \ + kiconv.9f \ + kiconv_close.9f \ + kiconv_open.9f \ + kiconvstr.9f \ + kmem_alloc.9f \ + kmem_cache_create.9f \ + kstat_create.9f \ + kstat_delete.9f \ + kstat_install.9f \ + kstat_named_init.9f \ + kstat_queue.9f \ + ldi_add_event_handler.9f \ + ldi_aread.9f \ + ldi_devmap.9f \ + ldi_dump.9f \ + ldi_ev_finalize.9f \ + ldi_ev_get_cookie.9f \ + ldi_ev_get_type.9f \ + ldi_ev_notify.9f \ + ldi_ev_register_callbacks.9f \ + ldi_ev_remove_callbacks.9f \ + ldi_get_dev.9f \ + ldi_get_eventcookie.9f \ + ldi_get_size.9f \ + ldi_ident_from_dev.9f \ + ldi_ioctl.9f \ + ldi_open_by_dev.9f \ + ldi_poll.9f \ + ldi_prop_exists.9f \ + ldi_prop_get_int.9f \ + ldi_prop_lookup_int_array.9f \ + ldi_putmsg.9f \ + ldi_read.9f \ + ldi_remove_event_handler.9f \ + ldi_strategy.9f \ + linkb.9f \ + list_create.9f \ + makecom.9f \ + makedevice.9f \ + max.9f \ + mcopyin.9f \ + mcopymsg.9f \ + mcopyout.9f \ + membar_ops.9f \ + memchr.9f \ + merror.9f \ + mexchange.9f \ + min.9f \ + mioc2ack.9f \ + miocack.9f \ + miocnak.9f \ + miocpullup.9f \ + mkiocb.9f \ + mod_install.9f \ + msgdsize.9f \ + msgpullup.9f \ + msgsize.9f \ + mt-streams.9f \ + mutex.9f \ + net_event_notify_register.9f \ + net_getifname.9f \ + net_getlifaddr.9f \ + net_getmtu.9f \ + net_getnetid.9f \ + net_getpmtuenabled.9f \ + net_hook_register.9f \ + net_hook_unregister.9f \ + net_inject.9f \ + net_inject_alloc.9f \ + net_inject_free.9f \ + net_instance_alloc.9f \ + net_instance_free.9f \ + net_instance_notify_register.9f \ + net_instance_register.9f \ + net_instance_unregister.9f \ + net_ispartialchecksum.9f \ + net_isvalidchecksum.9f \ + net_kstat_create.9f \ + net_kstat_delete.9f \ + net_lifgetnext.9f \ + net_netidtozonid.9f \ + net_phygetnext.9f \ + net_phylookup.9f \ + net_protocol_lookup.9f \ + net_protocol_notify_register.9f \ + net_protocol_release.9f \ + net_protocol_walk.9f \ + net_routeto.9f \ + net_zoneidtonetid.9f \ + netinfo.9f \ + nochpoll.9f \ + nodev.9f \ + noenable.9f \ + nulldev.9f \ + nvlist_add_boolean.9f \ + nvlist_alloc.9f \ + nvlist_lookup_boolean.9f \ + nvlist_lookup_nvpair.9f \ + nvlist_next_nvpair.9f \ + nvlist_remove.9f \ + nvpair_value_byte.9f \ + outb.9f \ + pci_config_get8.9f \ + pci_config_setup.9f \ + pci_ereport_setup.9f \ + pci_report_pmcap.9f \ + pci_save_config_regs.9f \ + physio.9f \ + pm_busy_component.9f \ + pm_power_has_changed.9f \ + pm_raise_power.9f \ + pm_trans_check.9f \ + pollwakeup.9f \ + priv_getbyname.9f \ + priv_policy.9f \ + proc_signal.9f \ + ptob.9f \ + pullupmsg.9f \ + put.9f \ + putbq.9f \ + putctl.9f \ + putctl1.9f \ + putnext.9f \ + putnextctl.9f \ + putnextctl1.9f \ + putq.9f \ + qassociate.9f \ + qbufcall.9f \ + qenable.9f \ + qprocson.9f \ + qreply.9f \ + qsize.9f \ + qtimeout.9f \ + qunbufcall.9f \ + quntimeout.9f \ + qwait.9f \ + qwriter.9f \ + rmalloc.9f \ + rmalloc_wait.9f \ + rmallocmap.9f \ + rmfree.9f \ + rmvb.9f \ + rmvq.9f \ + rwlock.9f \ + scsi_abort.9f \ + scsi_alloc_consistent_buf.9f \ + scsi_cname.9f \ + scsi_destroy_pkt.9f \ + scsi_dmaget.9f \ + scsi_errmsg.9f \ + scsi_ext_sense_fields.9f \ + scsi_find_sense_descr.9f \ + scsi_free_consistent_buf.9f \ + scsi_get_device_type_scsi_options.9f \ + scsi_get_device_type_string.9f \ + scsi_hba_attach_setup.9f \ + scsi_hba_init.9f \ + scsi_hba_lookup_capstr.9f \ + scsi_hba_pkt_alloc.9f \ + scsi_hba_pkt_comp.9f \ + scsi_hba_probe.9f \ + scsi_hba_tran_alloc.9f \ + scsi_ifgetcap.9f \ + scsi_init_pkt.9f \ + scsi_log.9f \ + scsi_pktalloc.9f \ + scsi_poll.9f \ + scsi_probe.9f \ + scsi_reset.9f \ + scsi_reset_notify.9f \ + scsi_sense_key.9f \ + scsi_setup_cdb.9f \ + scsi_slave.9f \ + scsi_sync_pkt.9f \ + scsi_transport.9f \ + scsi_unprobe.9f \ + scsi_validate_sense.9f \ + scsi_vu_errmsg.9f \ + semaphore.9f \ + stoi.9f \ + string.9f \ + strlog.9f \ + strqget.9f \ + strqset.9f \ + swab.9f \ + taskq.9f \ + testb.9f \ + timeout.9f \ + u8_strcmp.9f \ + u8_textprep_str.9f \ + u8_validate.9f \ + uconv_u16tou32.9f \ + uiomove.9f \ + unbufcall.9f \ + unlinkb.9f \ + untimeout.9f \ + ureadc.9f \ + usb_alloc_request.9f \ + usb_client_attach.9f \ + usb_clr_feature.9f \ + usb_create_pm_components.9f \ + usb_get_addr.9f \ + usb_get_alt_if.9f \ + usb_get_cfg.9f \ + usb_get_current_frame_number.9f \ + usb_get_dev_data.9f \ + usb_get_max_pkts_per_isoc_request.9f \ + usb_get_status.9f \ + usb_get_string_descr.9f \ + usb_handle_remote_wakeup.9f \ + usb_lookup_ep_data.9f \ + usb_parse_data.9f \ + usb_pipe_bulk_xfer.9f \ + usb_pipe_close.9f \ + usb_pipe_ctrl_xfer.9f \ + usb_pipe_drain_reqs.9f \ + usb_pipe_get_max_bulk_transfer_size.9f \ + usb_pipe_get_state.9f \ + usb_pipe_intr_xfer.9f \ + usb_pipe_isoc_xfer.9f \ + usb_pipe_open.9f \ + usb_pipe_reset.9f \ + usb_pipe_set_private.9f \ + usb_register_hotplug_cbs.9f \ + usb_reset_device.9f \ + uwritec.9f \ + va_arg.9f \ + vsprintf.9f + +MANSOFILES = SIZEOF_PTR.9f \ + SIZEOF_STRUCT.9f \ + STRUCT_BUF.9f \ + STRUCT_FADDR.9f \ + STRUCT_FGET.9f \ + STRUCT_FGETP.9f \ + STRUCT_FSET.9f \ + STRUCT_FSETP.9f \ + STRUCT_HANDLE.9f \ + STRUCT_INIT.9f \ + STRUCT_SET_HANDLE.9f \ + STRUCT_SIZE.9f \ + assert.9f \ + atomic_add_16.9f \ + atomic_add_16_nv.9f \ + atomic_add_32.9f \ + atomic_add_32_nv.9f \ + atomic_add_64.9f \ + atomic_add_64_nv.9f \ + atomic_add_8.9f \ + atomic_add_8_nv.9f \ + atomic_add_char.9f \ + atomic_add_char_nv.9f \ + atomic_add_int.9f \ + atomic_add_int_nv.9f \ + atomic_add_long.9f \ + atomic_add_long_nv.9f \ + atomic_add_ptr.9f \ + atomic_add_ptr_nv.9f \ + atomic_add_short.9f \ + atomic_add_short_nv.9f \ + atomic_and_16.9f \ + atomic_and_16_nv.9f \ + atomic_and_32.9f \ + atomic_and_32_nv.9f \ + atomic_and_64.9f \ + atomic_and_64_nv.9f \ + atomic_and_8.9f \ + atomic_and_8_nv.9f \ + atomic_and_uchar.9f \ + atomic_and_uchar_nv.9f \ + atomic_and_uint.9f \ + atomic_and_uint_nv.9f \ + atomic_and_ulong.9f \ + atomic_and_ulong_nv.9f \ + atomic_and_ushort.9f \ + atomic_and_ushort_nv.9f \ + atomic_cas_16.9f \ + atomic_cas_32.9f \ + atomic_cas_64.9f \ + atomic_cas_8.9f \ + atomic_cas_ptr.9f \ + atomic_cas_uchar.9f \ + atomic_cas_uint.9f \ + atomic_cas_ulong.9f \ + atomic_cas_ushort.9f \ + atomic_clear_long_excl.9f \ + atomic_dec_16.9f \ + atomic_dec_16_nv.9f \ + atomic_dec_32.9f \ + atomic_dec_32_nv.9f \ + atomic_dec_64.9f \ + atomic_dec_64_nv.9f \ + atomic_dec_8.9f \ + atomic_dec_8_nv.9f \ + atomic_dec_ptr.9f \ + atomic_dec_ptr_nv.9f \ + atomic_dec_uchar.9f \ + atomic_dec_uchar_nv.9f \ + atomic_dec_uint.9f \ + atomic_dec_uint_nv.9f \ + atomic_dec_ulong.9f \ + atomic_dec_ulong_nv.9f \ + atomic_dec_ushort.9f \ + atomic_dec_ushort_nv.9f \ + atomic_inc_16.9f \ + atomic_inc_16_nv.9f \ + atomic_inc_32.9f \ + atomic_inc_32_nv.9f \ + atomic_inc_64.9f \ + atomic_inc_64_nv.9f \ + atomic_inc_8.9f \ + atomic_inc_8_nv.9f \ + atomic_inc_ptr.9f \ + atomic_inc_ptr_nv.9f \ + atomic_inc_uchar.9f \ + atomic_inc_uchar_nv.9f \ + atomic_inc_uint.9f \ + atomic_inc_uint_nv.9f \ + atomic_inc_ulong.9f \ + atomic_inc_ulong_nv.9f \ + atomic_inc_ushort.9f \ + atomic_inc_ushort_nv.9f \ + atomic_or_16.9f \ + atomic_or_16_nv.9f \ + atomic_or_32.9f \ + atomic_or_32_nv.9f \ + atomic_or_64.9f \ + atomic_or_64_nv.9f \ + atomic_or_8.9f \ + atomic_or_8_nv.9f \ + atomic_or_uchar.9f \ + atomic_or_uchar_nv.9f \ + atomic_or_uint.9f \ + atomic_or_uint_nv.9f \ + atomic_or_ulong.9f \ + atomic_or_ulong_nv.9f \ + atomic_or_ushort.9f \ + atomic_or_ushort_nv.9f \ + atomic_set_long_excl.9f \ + atomic_swap_16.9f \ + atomic_swap_32.9f \ + atomic_swap_64.9f \ + atomic_swap_8.9f \ + atomic_swap_ptr.9f \ + atomic_swap_uchar.9f \ + atomic_swap_uint.9f \ + atomic_swap_ulong.9f \ + atomic_swap_ushort.9f \ + crgetgid.9f \ + crgetgroups.9f \ + crgetngroups.9f \ + crgetrgid.9f \ + crgetruid.9f \ + crgetsgid.9f \ + crgetsuid.9f \ + crgetuid.9f \ + crgetzoneid.9f \ + csx_Get16.9f \ + csx_Get32.9f \ + csx_Get64.9f \ + csx_GetEventMask.9f \ + csx_GetNextClient.9f \ + csx_GetNextTuple.9f \ + csx_Parse_CISTPL_DEVICE_A.9f \ + csx_Parse_CISTPL_DEVICE_OA.9f \ + csx_Parse_CISTPL_DEVICE_OC.9f \ + csx_Parse_CISTPL_JEDEC_A.9f \ + csx_Parse_CISTPL_LONGLINK_C.9f \ + csx_Put16.9f \ + csx_Put32.9f \ + csx_Put64.9f \ + csx_ReleaseIO.9f \ + csx_ReleaseIRQ.9f \ + csx_ReleaseSocketMask.9f \ + csx_ReleaseWindow.9f \ + csx_RemoveDeviceNode.9f \ + csx_RepGet16.9f \ + csx_RepGet32.9f \ + csx_RepGet64.9f \ + csx_RepPut16.9f \ + csx_RepPut32.9f \ + csx_RepPut64.9f \ + cv_broadcast.9f \ + cv_destroy.9f \ + cv_init.9f \ + cv_reltimedwait.9f \ + cv_reltimedwait_sig.9f \ + cv_signal.9f \ + cv_timedwait.9f \ + cv_timedwait_sig.9f \ + cv_wait.9f \ + cv_wait_sig.9f \ + ddi_btopr.9f \ + ddi_cb_unregister.9f \ + ddi_check_dma_handle.9f \ + ddi_devid_free.9f \ + ddi_devid_get.9f \ + ddi_devid_init.9f \ + ddi_devid_register.9f \ + ddi_devid_sizeof.9f \ + ddi_devid_str_decode.9f \ + ddi_devid_str_encode.9f \ + ddi_devid_str_free.9f \ + ddi_devid_unregister.9f \ + ddi_devid_valid.9f \ + ddi_devmap_segmap.9f \ + ddi_dmae_1stparty.9f \ + ddi_dmae_alloc.9f \ + ddi_dmae_disable.9f \ + ddi_dmae_enable.9f \ + ddi_dmae_getattr.9f \ + ddi_dmae_getcnt.9f \ + ddi_dmae_getlim.9f \ + ddi_dmae_prog.9f \ + ddi_dmae_release.9f \ + ddi_dmae_stop.9f \ + ddi_exit_critical.9f \ + ddi_fls.9f \ + ddi_fm_capable.9f \ + ddi_fm_dma_err_clear.9f \ + ddi_fm_dma_err_get.9f \ + ddi_fm_fini.9f \ + ddi_fm_handler_unregister.9f \ + ddi_get16.9f \ + ddi_get32.9f \ + ddi_get64.9f \ + ddi_get_iblock_cookie.9f \ + ddi_get_lbolt64.9f \ + ddi_get_name.9f \ + ddi_get_soft_iblock_cookie.9f \ + ddi_get_soft_state.9f \ + ddi_getb.9f \ + ddi_getl.9f \ + ddi_getll.9f \ + ddi_getlongprop.9f \ + ddi_getlongprop_buf.9f \ + ddi_getprop.9f \ + ddi_getproplen.9f \ + ddi_getw.9f \ + ddi_intr_block_disable.9f \ + ddi_intr_block_enable.9f \ + ddi_intr_clr_mask.9f \ + ddi_intr_disable.9f \ + ddi_intr_free.9f \ + ddi_intr_get_navail.9f \ + ddi_intr_get_softint_pri.9f \ + ddi_intr_remove_handler.9f \ + ddi_intr_remove_softint.9f \ + ddi_intr_set_cap.9f \ + ddi_intr_set_pri.9f \ + ddi_intr_set_softint_pri.9f \ + ddi_intr_trigger_softint.9f \ + ddi_io_get16.9f \ + ddi_io_get32.9f \ + ddi_io_getb.9f \ + ddi_io_getl.9f \ + ddi_io_getw.9f \ + ddi_io_put16.9f \ + ddi_io_put32.9f \ + ddi_io_putb.9f \ + ddi_io_putl.9f \ + ddi_io_putw.9f \ + ddi_io_rep_get16.9f \ + ddi_io_rep_get32.9f \ + ddi_io_rep_getb.9f \ + ddi_io_rep_getl.9f \ + ddi_io_rep_getw.9f \ + ddi_io_rep_put16.9f \ + ddi_io_rep_put32.9f \ + ddi_io_rep_putb.9f \ + ddi_io_rep_putl.9f \ + ddi_io_rep_putw.9f \ + ddi_iopb_free.9f \ + ddi_mem_free.9f \ + ddi_mem_get16.9f \ + ddi_mem_get32.9f \ + ddi_mem_get64.9f \ + ddi_mem_getb.9f \ + ddi_mem_getl.9f \ + ddi_mem_getll.9f \ + ddi_mem_getw.9f \ + ddi_mem_put16.9f \ + ddi_mem_put32.9f \ + ddi_mem_put64.9f \ + ddi_mem_putb.9f \ + ddi_mem_putl.9f \ + ddi_mem_putll.9f \ + ddi_mem_putw.9f \ + ddi_mem_rep_get16.9f \ + ddi_mem_rep_get32.9f \ + ddi_mem_rep_get64.9f \ + ddi_mem_rep_getb.9f \ + ddi_mem_rep_getl.9f \ + ddi_mem_rep_getll.9f \ + ddi_mem_rep_getw.9f \ + ddi_mem_rep_put16.9f \ + ddi_mem_rep_put32.9f \ + ddi_mem_rep_put64.9f \ + ddi_mem_rep_putb.9f \ + ddi_mem_rep_putl.9f \ + ddi_mem_rep_putll.9f \ + ddi_mem_rep_putw.9f \ + ddi_modclose.9f \ + ddi_modsym.9f \ + ddi_peek16.9f \ + ddi_peek32.9f \ + ddi_peek64.9f \ + ddi_peek8.9f \ + ddi_peekc.9f \ + ddi_peekd.9f \ + ddi_peekl.9f \ + ddi_peeks.9f \ + ddi_poke16.9f \ + ddi_poke32.9f \ + ddi_poke64.9f \ + ddi_poke8.9f \ + ddi_pokec.9f \ + ddi_poked.9f \ + ddi_pokel.9f \ + ddi_pokes.9f \ + ddi_prop_free.9f \ + ddi_prop_get_int64.9f \ + ddi_prop_lookup_byte_array.9f \ + ddi_prop_lookup_int64_array.9f \ + ddi_prop_lookup_int_array.9f \ + ddi_prop_lookup_string.9f \ + ddi_prop_lookup_string_array.9f \ + ddi_prop_modify.9f \ + ddi_prop_remove.9f \ + ddi_prop_remove_all.9f \ + ddi_prop_undefine.9f \ + ddi_prop_update_byte_array.9f \ + ddi_prop_update_int.9f \ + ddi_prop_update_int64.9f \ + ddi_prop_update_int64_array.9f \ + ddi_prop_update_int_array.9f \ + ddi_prop_update_string.9f \ + ddi_prop_update_string_array.9f \ + ddi_ptob.9f \ + ddi_put16.9f \ + ddi_put32.9f \ + ddi_put64.9f \ + ddi_putb.9f \ + ddi_putl.9f \ + ddi_putll.9f \ + ddi_putw.9f \ + ddi_remove_intr.9f \ + ddi_remove_softintr.9f \ + ddi_rep_get16.9f \ + ddi_rep_get32.9f \ + ddi_rep_get64.9f \ + ddi_rep_getb.9f \ + ddi_rep_getl.9f \ + ddi_rep_getll.9f \ + ddi_rep_getw.9f \ + ddi_rep_put16.9f \ + ddi_rep_put32.9f \ + ddi_rep_put64.9f \ + ddi_rep_putb.9f \ + ddi_rep_putl.9f \ + ddi_rep_putll.9f \ + ddi_rep_putw.9f \ + ddi_segmap_setup.9f \ + ddi_set_driver_private.9f \ + ddi_soft_state_fini.9f \ + ddi_soft_state_free.9f \ + ddi_soft_state_init.9f \ + ddi_soft_state_zalloc.9f \ + ddi_strdup.9f \ + ddi_strtoull.9f \ + ddi_taskq_create.9f \ + ddi_taskq_destroy.9f \ + ddi_taskq_dispatch.9f \ + ddi_taskq_resume.9f \ + ddi_taskq_suspend.9f \ + ddi_taskq_wait.9f \ + ddi_trigger_softintr.9f \ + ddi_umem_free.9f \ + ddi_umem_unlock.9f \ + ddi_unmap_regs.9f \ + desballoc.9f \ + devmap_load.9f \ + devmap_umem_setup.9f \ + dlerrorack.9f \ + dlokack.9f \ + dlphysaddrack.9f \ + dluderrorind.9f \ + free_pktiopb.9f \ + gld_intr.9f \ + gld_mac_alloc.9f \ + gld_mac_free.9f \ + gld_recv.9f \ + gld_register.9f \ + gld_sched.9f \ + gld_unregister.9f \ + id32_free.9f \ + id32_lookup.9f \ + inl.9f \ + intro.9f \ + inw.9f \ + kmem_cache_alloc.9f \ + kmem_cache_destroy.9f \ + kmem_cache_free.9f \ + kmem_cache_set_move.9f \ + kmem_free.9f \ + kmem_zalloc.9f \ + kstat_named_setstr.9f \ + kstat_runq_back_to_waitq.9f \ + kstat_runq_enter.9f \ + kstat_runq_exit.9f \ + kstat_waitq_enter.9f \ + kstat_waitq_exit.9f \ + kstat_waitq_to_runq.9f \ + ldi_awrite.9f \ + ldi_close.9f \ + ldi_get_devid.9f \ + ldi_get_minor_name.9f \ + ldi_get_otyp.9f \ + ldi_getmsg.9f \ + ldi_ident_from_dip.9f \ + ldi_ident_from_stream.9f \ + ldi_ident_release.9f \ + ldi_open_by_devid.9f \ + ldi_open_by_name.9f \ + ldi_prop_get_int64.9f \ + ldi_prop_lookup_byte_array.9f \ + ldi_prop_lookup_int64_array.9f \ + ldi_prop_lookup_string.9f \ + ldi_prop_lookup_string_array.9f \ + ldi_write.9f \ + list_destroy.9f \ + list_head.9f \ + list_insert_after.9f \ + list_insert_before.9f \ + list_insert_head.9f \ + list_insert_tail.9f \ + list_is_empty.9f \ + list_link_active.9f \ + list_link_init.9f \ + list_link_replace.9f \ + list_move_tail.9f \ + list_next.9f \ + list_prev.9f \ + list_remove.9f \ + list_remove_head.9f \ + list_remove_tail.9f \ + list_tail.9f \ + makecom_g0.9f \ + makecom_g0_s.9f \ + makecom_g1.9f \ + makecom_g5.9f \ + membar_consumer.9f \ + membar_enter.9f \ + membar_exit.9f \ + membar_producer.9f \ + memcmp.9f \ + memcpy.9f \ + memmove.9f \ + memset.9f \ + minphys.9f \ + mod_info.9f \ + mod_modname.9f \ + mod_remove.9f \ + mutex_destroy.9f \ + mutex_enter.9f \ + mutex_exit.9f \ + mutex_init.9f \ + mutex_owned.9f \ + mutex_tryenter.9f \ + net_event_notify_unregister.9f \ + net_instance_notify_unregister.9f \ + net_instance_protocol_unregister.9f \ + numtos.9f \ + nv_alloc_fini.9f \ + nv_alloc_init.9f \ + nvlist_add_boolean_array.9f \ + nvlist_add_boolean_value.9f \ + nvlist_add_byte.9f \ + nvlist_add_byte_array.9f \ + nvlist_add_int16.9f \ + nvlist_add_int16_array.9f \ + nvlist_add_int32.9f \ + nvlist_add_int32_array.9f \ + nvlist_add_int64.9f \ + nvlist_add_int64_array.9f \ + nvlist_add_int8.9f \ + nvlist_add_int8_array.9f \ + nvlist_add_nvlist.9f \ + nvlist_add_nvlist_array.9f \ + nvlist_add_nvpair.9f \ + nvlist_add_string.9f \ + nvlist_add_string_array.9f \ + nvlist_add_uint16.9f \ + nvlist_add_uint16_array.9f \ + nvlist_add_uint32.9f \ + nvlist_add_uint32_array.9f \ + nvlist_add_uint64.9f \ + nvlist_add_uint64_array.9f \ + nvlist_add_uint8.9f \ + nvlist_add_uint8_array.9f \ + nvlist_dup.9f \ + nvlist_exists.9f \ + nvlist_free.9f \ + nvlist_lookup_boolean_array.9f \ + nvlist_lookup_boolean_value.9f \ + nvlist_lookup_byte.9f \ + nvlist_lookup_byte_array.9f \ + nvlist_lookup_int16.9f \ + nvlist_lookup_int16_array.9f \ + nvlist_lookup_int32.9f \ + nvlist_lookup_int32_array.9f \ + nvlist_lookup_int64.9f \ + nvlist_lookup_int64_array.9f \ + nvlist_lookup_int8.9f \ + nvlist_lookup_int8_array.9f \ + nvlist_lookup_nvlist.9f \ + nvlist_lookup_nvlist_array.9f \ + nvlist_lookup_pairs.9f \ + nvlist_lookup_string.9f \ + nvlist_lookup_string_array.9f \ + nvlist_lookup_uint16.9f \ + nvlist_lookup_uint16_array.9f \ + nvlist_lookup_uint32.9f \ + nvlist_lookup_uint32_array.9f \ + nvlist_lookup_uint64.9f \ + nvlist_lookup_uint64_array.9f \ + nvlist_lookup_uint8.9f \ + nvlist_lookup_uint8_array.9f \ + nvlist_merge.9f \ + nvlist_pack.9f \ + nvlist_remove_all.9f \ + nvlist_size.9f \ + nvlist_t.9f \ + nvlist_unpack.9f \ + nvlist_xalloc.9f \ + nvlist_xdup.9f \ + nvlist_xpack.9f \ + nvlist_xunpack.9f \ + nvpair_name.9f \ + nvpair_type.9f \ + nvpair_value_boolean_array.9f \ + nvpair_value_byte_array.9f \ + nvpair_value_int16.9f \ + nvpair_value_int16_array.9f \ + nvpair_value_int32.9f \ + nvpair_value_int32_array.9f \ + nvpair_value_int64.9f \ + nvpair_value_int64_array.9f \ + nvpair_value_int8.9f \ + nvpair_value_int8_array.9f \ + nvpair_value_nvlist.9f \ + nvpair_value_nvlist_array.9f \ + nvpair_value_string.9f \ + nvpair_value_string_array.9f \ + nvpair_value_uint16.9f \ + nvpair_value_uint16_array.9f \ + nvpair_value_uint32.9f \ + nvpair_value_uint32_array.9f \ + nvpair_value_uint64.9f \ + nvpair_value_uint64_array.9f \ + nvpair_value_uint8.9f \ + nvpair_value_uint8_array.9f \ + otherq.9f \ + outl.9f \ + outw.9f \ + pci_config_get16.9f \ + pci_config_get32.9f \ + pci_config_get64.9f \ + pci_config_getb.9f \ + pci_config_getl.9f \ + pci_config_getll.9f \ + pci_config_getw.9f \ + pci_config_put16.9f \ + pci_config_put32.9f \ + pci_config_put64.9f \ + pci_config_put8.9f \ + pci_config_putb.9f \ + pci_config_putl.9f \ + pci_config_putll.9f \ + pci_config_putw.9f \ + pci_config_teardown.9f \ + pci_ereport_post.9f \ + pci_ereport_teardown.9f \ + pci_restore_config_regs.9f \ + pm_idle_component.9f \ + pm_lower_power.9f \ + priv_policy_choice.9f \ + priv_policy_only.9f \ + proc_ref.9f \ + proc_unref.9f \ + qprocsoff.9f \ + qwait_sig.9f \ + rd.9f \ + repinsb.9f \ + repinsd.9f \ + repinsw.9f \ + repoutsb.9f \ + repoutsd.9f \ + repoutsw.9f \ + rmallocmap_wait.9f \ + rmfreemap.9f \ + rw_destroy.9f \ + rw_downgrade.9f \ + rw_enter.9f \ + rw_exit.9f \ + rw_init.9f \ + rw_read_locked.9f \ + rw_tryenter.9f \ + rw_tryupgrade.9f \ + samestr.9f \ + scsi_dmafree.9f \ + scsi_dname.9f \ + scsi_hba_attach.9f \ + scsi_hba_detach.9f \ + scsi_hba_fini.9f \ + scsi_hba_pkt_free.9f \ + scsi_hba_tran_free.9f \ + scsi_ifsetcap.9f \ + scsi_mname.9f \ + scsi_pktfree.9f \ + scsi_resalloc.9f \ + scsi_resfree.9f \ + scsi_rname.9f \ + scsi_sense_asc.9f \ + scsi_sense_ascq.9f \ + scsi_sense_cmdspecific_uint64.9f \ + scsi_sense_info_uint64.9f \ + scsi_sname.9f \ + scsi_unslave.9f \ + sema_destroy.9f \ + sema_init.9f \ + sema_p.9f \ + sema_p_sig.9f \ + sema_tryp.9f \ + sema_v.9f \ + strcasecmp.9f \ + strchr.9f \ + strcmp.9f \ + strcpy.9f \ + strdup.9f \ + strfree.9f \ + strlcat.9f \ + strlcpy.9f \ + strlen.9f \ + strncasecmp.9f \ + strncat.9f \ + strncmp.9f \ + strncpy.9f \ + strnlen.9f \ + strrchr.9f \ + strspn.9f \ + taskq_suspended.9f \ + uconv_u16tou8.9f \ + uconv_u32tou16.9f \ + uconv_u32tou8.9f \ + uconv_u8tou16.9f \ + uconv_u8tou32.9f \ + unfreezestr.9f \ + usb_alloc_bulk_req.9f \ + usb_alloc_ctrl_req.9f \ + usb_alloc_intr_req.9f \ + usb_alloc_isoc_req.9f \ + usb_client_detach.9f \ + usb_free_bulk_req.9f \ + usb_free_ctrl_req.9f \ + usb_free_descr_tree.9f \ + usb_free_dev_data.9f \ + usb_free_intr_req.9f \ + usb_free_isoc_req.9f \ + usb_get_if_number.9f \ + usb_owns_device.9f \ + usb_pipe_ctrl_xfer_wait.9f \ + usb_pipe_get_private.9f \ + usb_pipe_stop_intr_polling.9f \ + usb_pipe_stop_isoc_polling.9f \ + usb_print_descr_tree.9f \ + usb_set_alt_if.9f \ + usb_set_cfg.9f \ + usb_unregister_hotplug_cbs.9f \ + va_copy.9f \ + va_end.9f \ + va_start.9f \ + vcmn_err.9f \ + wr.9f \ + zcmn_err.9f + +MANFILES += $(MANSOFILES) + +assert.9f := SOSRC = man9f/ASSERT.9f + +intro.9f := SOSRC = man9f/Intro.9f + +otherq.9f := SOSRC = man9f/OTHERQ.9f + +rd.9f := SOSRC = man9f/RD.9f + +samestr.9f := SOSRC = man9f/SAMESTR.9f + +SIZEOF_PTR.9f := SOSRC = man9f/STRUCT_DECL.9f +SIZEOF_STRUCT.9f := SOSRC = man9f/STRUCT_DECL.9f +STRUCT_BUF.9f := SOSRC = man9f/STRUCT_DECL.9f +STRUCT_FADDR.9f := SOSRC = man9f/STRUCT_DECL.9f +STRUCT_FGET.9f := SOSRC = man9f/STRUCT_DECL.9f +STRUCT_FGETP.9f := SOSRC = man9f/STRUCT_DECL.9f +STRUCT_FSET.9f := SOSRC = man9f/STRUCT_DECL.9f +STRUCT_FSETP.9f := SOSRC = man9f/STRUCT_DECL.9f +STRUCT_HANDLE.9f := SOSRC = man9f/STRUCT_DECL.9f +STRUCT_INIT.9f := SOSRC = man9f/STRUCT_DECL.9f +STRUCT_SET_HANDLE.9f := SOSRC = man9f/STRUCT_DECL.9f +STRUCT_SIZE.9f := SOSRC = man9f/STRUCT_DECL.9f + +wr.9f := SOSRC = man9f/WR.9f + +atomic_add_16.9f := SOSRC = man9f/atomic_add.9f +atomic_add_16_nv.9f := SOSRC = man9f/atomic_add.9f +atomic_add_32.9f := SOSRC = man9f/atomic_add.9f +atomic_add_32_nv.9f := SOSRC = man9f/atomic_add.9f +atomic_add_64.9f := SOSRC = man9f/atomic_add.9f +atomic_add_64_nv.9f := SOSRC = man9f/atomic_add.9f +atomic_add_8.9f := SOSRC = man9f/atomic_add.9f +atomic_add_8_nv.9f := SOSRC = man9f/atomic_add.9f +atomic_add_char.9f := SOSRC = man9f/atomic_add.9f +atomic_add_char_nv.9f := SOSRC = man9f/atomic_add.9f +atomic_add_int.9f := SOSRC = man9f/atomic_add.9f +atomic_add_int_nv.9f := SOSRC = man9f/atomic_add.9f +atomic_add_long.9f := SOSRC = man9f/atomic_add.9f +atomic_add_long_nv.9f := SOSRC = man9f/atomic_add.9f +atomic_add_ptr.9f := SOSRC = man9f/atomic_add.9f +atomic_add_ptr_nv.9f := SOSRC = man9f/atomic_add.9f +atomic_add_short.9f := SOSRC = man9f/atomic_add.9f +atomic_add_short_nv.9f := SOSRC = man9f/atomic_add.9f +atomic_and_16.9f := SOSRC = man9f/atomic_and.9f +atomic_and_16_nv.9f := SOSRC = man9f/atomic_and.9f +atomic_and_32.9f := SOSRC = man9f/atomic_and.9f +atomic_and_32_nv.9f := SOSRC = man9f/atomic_and.9f +atomic_and_64.9f := SOSRC = man9f/atomic_and.9f +atomic_and_64_nv.9f := SOSRC = man9f/atomic_and.9f +atomic_and_8.9f := SOSRC = man9f/atomic_and.9f +atomic_and_8_nv.9f := SOSRC = man9f/atomic_and.9f +atomic_and_uchar.9f := SOSRC = man9f/atomic_and.9f +atomic_and_uchar_nv.9f := SOSRC = man9f/atomic_and.9f +atomic_and_uint.9f := SOSRC = man9f/atomic_and.9f +atomic_and_uint_nv.9f := SOSRC = man9f/atomic_and.9f +atomic_and_ulong.9f := SOSRC = man9f/atomic_and.9f +atomic_and_ulong_nv.9f := SOSRC = man9f/atomic_and.9f +atomic_and_ushort.9f := SOSRC = man9f/atomic_and.9f +atomic_and_ushort_nv.9f := SOSRC = man9f/atomic_and.9f + +atomic_clear_long_excl.9f := SOSRC = man9f/atomic_bits.9f +atomic_set_long_excl.9f := SOSRC = man9f/atomic_bits.9f + +atomic_cas_16.9f := SOSRC = man9f/atomic_cas.9f +atomic_cas_32.9f := SOSRC = man9f/atomic_cas.9f +atomic_cas_64.9f := SOSRC = man9f/atomic_cas.9f +atomic_cas_8.9f := SOSRC = man9f/atomic_cas.9f +atomic_cas_ptr.9f := SOSRC = man9f/atomic_cas.9f +atomic_cas_uchar.9f := SOSRC = man9f/atomic_cas.9f +atomic_cas_uint.9f := SOSRC = man9f/atomic_cas.9f +atomic_cas_ulong.9f := SOSRC = man9f/atomic_cas.9f +atomic_cas_ushort.9f := SOSRC = man9f/atomic_cas.9f + +atomic_dec_16.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_16_nv.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_32.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_32_nv.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_64.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_64_nv.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_8.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_8_nv.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_ptr.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_ptr_nv.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_uchar.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_uchar_nv.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_uint.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_uint_nv.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_ulong.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_ulong_nv.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_ushort.9f := SOSRC = man9f/atomic_dec.9f +atomic_dec_ushort_nv.9f := SOSRC = man9f/atomic_dec.9f + +atomic_inc_16.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_16_nv.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_32.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_32_nv.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_64.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_64_nv.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_8.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_8_nv.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_ptr.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_ptr_nv.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_uchar.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_uchar_nv.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_uint.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_uint_nv.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_ulong.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_ulong_nv.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_ushort.9f := SOSRC = man9f/atomic_inc.9f +atomic_inc_ushort_nv.9f := SOSRC = man9f/atomic_inc.9f + +atomic_or_16.9f := SOSRC = man9f/atomic_or.9f +atomic_or_16_nv.9f := SOSRC = man9f/atomic_or.9f +atomic_or_32.9f := SOSRC = man9f/atomic_or.9f +atomic_or_32_nv.9f := SOSRC = man9f/atomic_or.9f +atomic_or_64.9f := SOSRC = man9f/atomic_or.9f +atomic_or_64_nv.9f := SOSRC = man9f/atomic_or.9f +atomic_or_8.9f := SOSRC = man9f/atomic_or.9f +atomic_or_8_nv.9f := SOSRC = man9f/atomic_or.9f +atomic_or_uchar.9f := SOSRC = man9f/atomic_or.9f +atomic_or_uchar_nv.9f := SOSRC = man9f/atomic_or.9f +atomic_or_uint.9f := SOSRC = man9f/atomic_or.9f +atomic_or_uint_nv.9f := SOSRC = man9f/atomic_or.9f +atomic_or_ulong.9f := SOSRC = man9f/atomic_or.9f +atomic_or_ulong_nv.9f := SOSRC = man9f/atomic_or.9f +atomic_or_ushort.9f := SOSRC = man9f/atomic_or.9f +atomic_or_ushort_nv.9f := SOSRC = man9f/atomic_or.9f + +atomic_swap_16.9f := SOSRC = man9f/atomic_swap.9f +atomic_swap_32.9f := SOSRC = man9f/atomic_swap.9f +atomic_swap_64.9f := SOSRC = man9f/atomic_swap.9f +atomic_swap_8.9f := SOSRC = man9f/atomic_swap.9f +atomic_swap_ptr.9f := SOSRC = man9f/atomic_swap.9f +atomic_swap_uchar.9f := SOSRC = man9f/atomic_swap.9f +atomic_swap_uint.9f := SOSRC = man9f/atomic_swap.9f +atomic_swap_ulong.9f := SOSRC = man9f/atomic_swap.9f +atomic_swap_ushort.9f := SOSRC = man9f/atomic_swap.9f + +vcmn_err.9f := SOSRC = man9f/cmn_err.9f +zcmn_err.9f := SOSRC = man9f/cmn_err.9f + +cv_broadcast.9f := SOSRC = man9f/condvar.9f +cv_destroy.9f := SOSRC = man9f/condvar.9f +cv_init.9f := SOSRC = man9f/condvar.9f +cv_reltimedwait.9f := SOSRC = man9f/condvar.9f +cv_reltimedwait_sig.9f := SOSRC = man9f/condvar.9f +cv_signal.9f := SOSRC = man9f/condvar.9f +cv_timedwait.9f := SOSRC = man9f/condvar.9f +cv_timedwait_sig.9f := SOSRC = man9f/condvar.9f +cv_wait.9f := SOSRC = man9f/condvar.9f +cv_wait_sig.9f := SOSRC = man9f/condvar.9f + +csx_Get16.9f := SOSRC = man9f/csx_Get8.9f +csx_Get32.9f := SOSRC = man9f/csx_Get8.9f +csx_Get64.9f := SOSRC = man9f/csx_Get8.9f + +csx_GetNextClient.9f := SOSRC = man9f/csx_GetFirstClient.9f + +csx_GetNextTuple.9f := SOSRC = man9f/csx_GetFirstTuple.9f + +csx_RemoveDeviceNode.9f := SOSRC = man9f/csx_MakeDeviceNode.9f + +csx_Parse_CISTPL_DEVICE_A.9f := SOSRC = man9f/csx_Parse_CISTPL_DEVICE.9f +csx_Parse_CISTPL_DEVICE_OA.9f := SOSRC = man9f/csx_Parse_CISTPL_DEVICE.9f +csx_Parse_CISTPL_DEVICE_OC.9f := SOSRC = man9f/csx_Parse_CISTPL_DEVICE.9f + +csx_Parse_CISTPL_JEDEC_A.9f := SOSRC = man9f/csx_Parse_CISTPL_JEDEC_C.9f + +csx_Parse_CISTPL_LONGLINK_C.9f := SOSRC = man9f/csx_Parse_CISTPL_LONGLINK_A.9f + +csx_Put16.9f := SOSRC = man9f/csx_Put8.9f +csx_Put32.9f := SOSRC = man9f/csx_Put8.9f +csx_Put64.9f := SOSRC = man9f/csx_Put8.9f + +csx_RepGet16.9f := SOSRC = man9f/csx_RepGet8.9f +csx_RepGet32.9f := SOSRC = man9f/csx_RepGet8.9f +csx_RepGet64.9f := SOSRC = man9f/csx_RepGet8.9f + +csx_RepPut16.9f := SOSRC = man9f/csx_RepPut8.9f +csx_RepPut32.9f := SOSRC = man9f/csx_RepPut8.9f +csx_RepPut64.9f := SOSRC = man9f/csx_RepPut8.9f + +csx_ReleaseIO.9f := SOSRC = man9f/csx_RequestIO.9f + +csx_ReleaseIRQ.9f := SOSRC = man9f/csx_RequestIRQ.9f + +csx_ReleaseSocketMask.9f := SOSRC = man9f/csx_RequestSocketMask.9f + +csx_ReleaseWindow.9f := SOSRC = man9f/csx_RequestWindow.9f + +csx_GetEventMask.9f := SOSRC = man9f/csx_SetEventMask.9f + +ddi_get_iblock_cookie.9f := SOSRC = man9f/ddi_add_intr.9f +ddi_remove_intr.9f := SOSRC = man9f/ddi_add_intr.9f + +ddi_get_soft_iblock_cookie.9f := SOSRC = man9f/ddi_add_softintr.9f +ddi_remove_softintr.9f := SOSRC = man9f/ddi_add_softintr.9f +ddi_trigger_softintr.9f := SOSRC = man9f/ddi_add_softintr.9f + +ddi_get_name.9f := SOSRC = man9f/ddi_binding_name.9f + +ddi_btopr.9f := SOSRC = man9f/ddi_btop.9f +ddi_ptob.9f := SOSRC = man9f/ddi_btop.9f + +ddi_cb_unregister.9f := SOSRC = man9f/ddi_cb_register.9f + +ddi_check_dma_handle.9f := SOSRC = man9f/ddi_check_acc_handle.9f + +crgetgid.9f := SOSRC = man9f/ddi_cred.9f +crgetgroups.9f := SOSRC = man9f/ddi_cred.9f +crgetngroups.9f := SOSRC = man9f/ddi_cred.9f +crgetrgid.9f := SOSRC = man9f/ddi_cred.9f +crgetruid.9f := SOSRC = man9f/ddi_cred.9f +crgetsgid.9f := SOSRC = man9f/ddi_cred.9f +crgetsuid.9f := SOSRC = man9f/ddi_cred.9f +crgetuid.9f := SOSRC = man9f/ddi_cred.9f +crgetzoneid.9f := SOSRC = man9f/ddi_cred.9f + +ddi_devid_free.9f := SOSRC = man9f/ddi_devid_compare.9f +ddi_devid_get.9f := SOSRC = man9f/ddi_devid_compare.9f +ddi_devid_init.9f := SOSRC = man9f/ddi_devid_compare.9f +ddi_devid_register.9f := SOSRC = man9f/ddi_devid_compare.9f +ddi_devid_sizeof.9f := SOSRC = man9f/ddi_devid_compare.9f +ddi_devid_str_decode.9f := SOSRC = man9f/ddi_devid_compare.9f +ddi_devid_str_encode.9f := SOSRC = man9f/ddi_devid_compare.9f +ddi_devid_str_free.9f := SOSRC = man9f/ddi_devid_compare.9f +ddi_devid_unregister.9f := SOSRC = man9f/ddi_devid_compare.9f +ddi_devid_valid.9f := SOSRC = man9f/ddi_devid_compare.9f + +ddi_dmae_1stparty.9f := SOSRC = man9f/ddi_dmae.9f +ddi_dmae_alloc.9f := SOSRC = man9f/ddi_dmae.9f +ddi_dmae_disable.9f := SOSRC = man9f/ddi_dmae.9f +ddi_dmae_enable.9f := SOSRC = man9f/ddi_dmae.9f +ddi_dmae_getattr.9f := SOSRC = man9f/ddi_dmae.9f +ddi_dmae_getcnt.9f := SOSRC = man9f/ddi_dmae.9f +ddi_dmae_getlim.9f := SOSRC = man9f/ddi_dmae.9f +ddi_dmae_prog.9f := SOSRC = man9f/ddi_dmae.9f +ddi_dmae_release.9f := SOSRC = man9f/ddi_dmae.9f +ddi_dmae_stop.9f := SOSRC = man9f/ddi_dmae.9f + +ddi_exit_critical.9f := SOSRC = man9f/ddi_enter_critical.9f + +ddi_fls.9f := SOSRC = man9f/ddi_ffs.9f + +ddi_fm_dma_err_clear.9f := SOSRC = man9f/ddi_fm_acc_err_clear.9f + +ddi_fm_dma_err_get.9f := SOSRC = man9f/ddi_fm_acc_err_get.9f + +ddi_fm_handler_unregister.9f := SOSRC = man9f/ddi_fm_handler_register.9f + +ddi_fm_capable.9f := SOSRC = man9f/ddi_fm_init.9f +ddi_fm_fini.9f := SOSRC = man9f/ddi_fm_init.9f + +ddi_get16.9f := SOSRC = man9f/ddi_get8.9f +ddi_get32.9f := SOSRC = man9f/ddi_get8.9f +ddi_get64.9f := SOSRC = man9f/ddi_get8.9f +ddi_getb.9f := SOSRC = man9f/ddi_get8.9f +ddi_getl.9f := SOSRC = man9f/ddi_get8.9f +ddi_getll.9f := SOSRC = man9f/ddi_get8.9f +ddi_getw.9f := SOSRC = man9f/ddi_get8.9f + +ddi_set_driver_private.9f := SOSRC = man9f/ddi_get_driver_private.9f + +ddi_get_lbolt64.9f := SOSRC = man9f/ddi_get_lbolt.9f + +ddi_intr_remove_handler.9f := SOSRC = man9f/ddi_intr_add_handler.9f + +ddi_intr_get_softint_pri.9f := SOSRC = man9f/ddi_intr_add_softint.9f +ddi_intr_remove_softint.9f := SOSRC = man9f/ddi_intr_add_softint.9f +ddi_intr_set_softint_pri.9f := SOSRC = man9f/ddi_intr_add_softint.9f +ddi_intr_trigger_softint.9f := SOSRC = man9f/ddi_intr_add_softint.9f + +ddi_intr_free.9f := SOSRC = man9f/ddi_intr_alloc.9f + +ddi_intr_block_disable.9f := SOSRC = man9f/ddi_intr_enable.9f +ddi_intr_block_enable.9f := SOSRC = man9f/ddi_intr_enable.9f +ddi_intr_disable.9f := SOSRC = man9f/ddi_intr_enable.9f + +ddi_intr_set_cap.9f := SOSRC = man9f/ddi_intr_get_cap.9f + +ddi_intr_get_navail.9f := SOSRC = man9f/ddi_intr_get_nintrs.9f + +ddi_intr_set_pri.9f := SOSRC = man9f/ddi_intr_get_pri.9f + +ddi_intr_clr_mask.9f := SOSRC = man9f/ddi_intr_set_mask.9f + +ddi_io_get16.9f := SOSRC = man9f/ddi_io_get8.9f +ddi_io_get32.9f := SOSRC = man9f/ddi_io_get8.9f +ddi_io_getb.9f := SOSRC = man9f/ddi_io_get8.9f +ddi_io_getl.9f := SOSRC = man9f/ddi_io_get8.9f +ddi_io_getw.9f := SOSRC = man9f/ddi_io_get8.9f + +ddi_io_put16.9f := SOSRC = man9f/ddi_io_put8.9f +ddi_io_put32.9f := SOSRC = man9f/ddi_io_put8.9f +ddi_io_putb.9f := SOSRC = man9f/ddi_io_put8.9f +ddi_io_putl.9f := SOSRC = man9f/ddi_io_put8.9f +ddi_io_putw.9f := SOSRC = man9f/ddi_io_put8.9f + +ddi_io_rep_get16.9f := SOSRC = man9f/ddi_io_rep_get8.9f +ddi_io_rep_get32.9f := SOSRC = man9f/ddi_io_rep_get8.9f +ddi_io_rep_getb.9f := SOSRC = man9f/ddi_io_rep_get8.9f +ddi_io_rep_getl.9f := SOSRC = man9f/ddi_io_rep_get8.9f +ddi_io_rep_getw.9f := SOSRC = man9f/ddi_io_rep_get8.9f + +ddi_io_rep_put16.9f := SOSRC = man9f/ddi_io_rep_put8.9f +ddi_io_rep_put32.9f := SOSRC = man9f/ddi_io_rep_put8.9f +ddi_io_rep_putb.9f := SOSRC = man9f/ddi_io_rep_put8.9f +ddi_io_rep_putl.9f := SOSRC = man9f/ddi_io_rep_put8.9f +ddi_io_rep_putw.9f := SOSRC = man9f/ddi_io_rep_put8.9f + +ddi_iopb_free.9f := SOSRC = man9f/ddi_iopb_alloc.9f + +ddi_unmap_regs.9f := SOSRC = man9f/ddi_map_regs.9f + +ddi_mem_free.9f := SOSRC = man9f/ddi_mem_alloc.9f + +ddi_mem_get16.9f := SOSRC = man9f/ddi_mem_get8.9f +ddi_mem_get32.9f := SOSRC = man9f/ddi_mem_get8.9f +ddi_mem_get64.9f := SOSRC = man9f/ddi_mem_get8.9f +ddi_mem_getb.9f := SOSRC = man9f/ddi_mem_get8.9f +ddi_mem_getl.9f := SOSRC = man9f/ddi_mem_get8.9f +ddi_mem_getll.9f := SOSRC = man9f/ddi_mem_get8.9f +ddi_mem_getw.9f := SOSRC = man9f/ddi_mem_get8.9f + +ddi_mem_put16.9f := SOSRC = man9f/ddi_mem_put8.9f +ddi_mem_put32.9f := SOSRC = man9f/ddi_mem_put8.9f +ddi_mem_put64.9f := SOSRC = man9f/ddi_mem_put8.9f +ddi_mem_putb.9f := SOSRC = man9f/ddi_mem_put8.9f +ddi_mem_putl.9f := SOSRC = man9f/ddi_mem_put8.9f +ddi_mem_putll.9f := SOSRC = man9f/ddi_mem_put8.9f +ddi_mem_putw.9f := SOSRC = man9f/ddi_mem_put8.9f + +ddi_mem_rep_get16.9f := SOSRC = man9f/ddi_mem_rep_get8.9f +ddi_mem_rep_get32.9f := SOSRC = man9f/ddi_mem_rep_get8.9f +ddi_mem_rep_get64.9f := SOSRC = man9f/ddi_mem_rep_get8.9f +ddi_mem_rep_getb.9f := SOSRC = man9f/ddi_mem_rep_get8.9f +ddi_mem_rep_getl.9f := SOSRC = man9f/ddi_mem_rep_get8.9f +ddi_mem_rep_getll.9f := SOSRC = man9f/ddi_mem_rep_get8.9f +ddi_mem_rep_getw.9f := SOSRC = man9f/ddi_mem_rep_get8.9f + +ddi_mem_rep_put16.9f := SOSRC = man9f/ddi_mem_rep_put8.9f +ddi_mem_rep_put32.9f := SOSRC = man9f/ddi_mem_rep_put8.9f +ddi_mem_rep_put64.9f := SOSRC = man9f/ddi_mem_rep_put8.9f +ddi_mem_rep_putb.9f := SOSRC = man9f/ddi_mem_rep_put8.9f +ddi_mem_rep_putl.9f := SOSRC = man9f/ddi_mem_rep_put8.9f +ddi_mem_rep_putll.9f := SOSRC = man9f/ddi_mem_rep_put8.9f +ddi_mem_rep_putw.9f := SOSRC = man9f/ddi_mem_rep_put8.9f + +ddi_modclose.9f := SOSRC = man9f/ddi_modopen.9f +ddi_modsym.9f := SOSRC = man9f/ddi_modopen.9f + +ddi_peek16.9f := SOSRC = man9f/ddi_peek.9f +ddi_peek32.9f := SOSRC = man9f/ddi_peek.9f +ddi_peek64.9f := SOSRC = man9f/ddi_peek.9f +ddi_peek8.9f := SOSRC = man9f/ddi_peek.9f +ddi_peekc.9f := SOSRC = man9f/ddi_peek.9f +ddi_peekd.9f := SOSRC = man9f/ddi_peek.9f +ddi_peekl.9f := SOSRC = man9f/ddi_peek.9f +ddi_peeks.9f := SOSRC = man9f/ddi_peek.9f + +ddi_poke16.9f := SOSRC = man9f/ddi_poke.9f +ddi_poke32.9f := SOSRC = man9f/ddi_poke.9f +ddi_poke64.9f := SOSRC = man9f/ddi_poke.9f +ddi_poke8.9f := SOSRC = man9f/ddi_poke.9f +ddi_pokec.9f := SOSRC = man9f/ddi_poke.9f +ddi_poked.9f := SOSRC = man9f/ddi_poke.9f +ddi_pokel.9f := SOSRC = man9f/ddi_poke.9f +ddi_pokes.9f := SOSRC = man9f/ddi_poke.9f + +ddi_prop_modify.9f := SOSRC = man9f/ddi_prop_create.9f +ddi_prop_remove.9f := SOSRC = man9f/ddi_prop_create.9f +ddi_prop_remove_all.9f := SOSRC = man9f/ddi_prop_create.9f +ddi_prop_undefine.9f := SOSRC = man9f/ddi_prop_create.9f + +ddi_prop_get_int64.9f := SOSRC = man9f/ddi_prop_get_int.9f + +ddi_prop_free.9f := SOSRC = man9f/ddi_prop_lookup.9f +ddi_prop_lookup_byte_array.9f := SOSRC = man9f/ddi_prop_lookup.9f +ddi_prop_lookup_int64_array.9f := SOSRC = man9f/ddi_prop_lookup.9f +ddi_prop_lookup_int_array.9f := SOSRC = man9f/ddi_prop_lookup.9f +ddi_prop_lookup_string.9f := SOSRC = man9f/ddi_prop_lookup.9f +ddi_prop_lookup_string_array.9f := SOSRC = man9f/ddi_prop_lookup.9f + +ddi_getlongprop.9f := SOSRC = man9f/ddi_prop_op.9f +ddi_getlongprop_buf.9f := SOSRC = man9f/ddi_prop_op.9f +ddi_getprop.9f := SOSRC = man9f/ddi_prop_op.9f +ddi_getproplen.9f := SOSRC = man9f/ddi_prop_op.9f + +ddi_prop_update_byte_array.9f := SOSRC = man9f/ddi_prop_update.9f +ddi_prop_update_int.9f := SOSRC = man9f/ddi_prop_update.9f +ddi_prop_update_int64.9f := SOSRC = man9f/ddi_prop_update.9f +ddi_prop_update_int64_array.9f := SOSRC = man9f/ddi_prop_update.9f +ddi_prop_update_int_array.9f := SOSRC = man9f/ddi_prop_update.9f +ddi_prop_update_string.9f := SOSRC = man9f/ddi_prop_update.9f +ddi_prop_update_string_array.9f := SOSRC = man9f/ddi_prop_update.9f + +ddi_put16.9f := SOSRC = man9f/ddi_put8.9f +ddi_put32.9f := SOSRC = man9f/ddi_put8.9f +ddi_put64.9f := SOSRC = man9f/ddi_put8.9f +ddi_putb.9f := SOSRC = man9f/ddi_put8.9f +ddi_putl.9f := SOSRC = man9f/ddi_put8.9f +ddi_putll.9f := SOSRC = man9f/ddi_put8.9f +ddi_putw.9f := SOSRC = man9f/ddi_put8.9f + +ddi_rep_get16.9f := SOSRC = man9f/ddi_rep_get8.9f +ddi_rep_get32.9f := SOSRC = man9f/ddi_rep_get8.9f +ddi_rep_get64.9f := SOSRC = man9f/ddi_rep_get8.9f +ddi_rep_getb.9f := SOSRC = man9f/ddi_rep_get8.9f +ddi_rep_getl.9f := SOSRC = man9f/ddi_rep_get8.9f +ddi_rep_getll.9f := SOSRC = man9f/ddi_rep_get8.9f +ddi_rep_getw.9f := SOSRC = man9f/ddi_rep_get8.9f + +ddi_rep_put16.9f := SOSRC = man9f/ddi_rep_put8.9f +ddi_rep_put32.9f := SOSRC = man9f/ddi_rep_put8.9f +ddi_rep_put64.9f := SOSRC = man9f/ddi_rep_put8.9f +ddi_rep_putb.9f := SOSRC = man9f/ddi_rep_put8.9f +ddi_rep_putl.9f := SOSRC = man9f/ddi_rep_put8.9f +ddi_rep_putll.9f := SOSRC = man9f/ddi_rep_put8.9f +ddi_rep_putw.9f := SOSRC = man9f/ddi_rep_put8.9f + +ddi_segmap_setup.9f := SOSRC = man9f/ddi_segmap.9f + +ddi_get_soft_state.9f := SOSRC = man9f/ddi_soft_state.9f +ddi_soft_state_fini.9f := SOSRC = man9f/ddi_soft_state.9f +ddi_soft_state_free.9f := SOSRC = man9f/ddi_soft_state.9f +ddi_soft_state_init.9f := SOSRC = man9f/ddi_soft_state.9f +ddi_soft_state_zalloc.9f := SOSRC = man9f/ddi_soft_state.9f + +ddi_strtoull.9f := SOSRC = man9f/ddi_strtoll.9f + +ddi_umem_free.9f := SOSRC = man9f/ddi_umem_alloc.9f + +ddi_umem_unlock.9f := SOSRC = man9f/ddi_umem_lock.9f + +devmap_umem_setup.9f := SOSRC = man9f/devmap_devmem_setup.9f + +ddi_devmap_segmap.9f := SOSRC = man9f/devmap_setup.9f + +devmap_load.9f := SOSRC = man9f/devmap_unload.9f + +dlerrorack.9f := SOSRC = man9f/dlbindack.9f +dlokack.9f := SOSRC = man9f/dlbindack.9f +dlphysaddrack.9f := SOSRC = man9f/dlbindack.9f +dluderrorind.9f := SOSRC = man9f/dlbindack.9f + +desballoc.9f := SOSRC = man9f/esballoc.9f + +unfreezestr.9f := SOSRC = man9f/freezestr.9f + +free_pktiopb.9f := SOSRC = man9f/get_pktiopb.9f + +gld_intr.9f := SOSRC = man9f/gld.9f +gld_mac_alloc.9f := SOSRC = man9f/gld.9f +gld_mac_free.9f := SOSRC = man9f/gld.9f +gld_recv.9f := SOSRC = man9f/gld.9f +gld_register.9f := SOSRC = man9f/gld.9f +gld_sched.9f := SOSRC = man9f/gld.9f +gld_unregister.9f := SOSRC = man9f/gld.9f + +id32_free.9f := SOSRC = man9f/id32_alloc.9f +id32_lookup.9f := SOSRC = man9f/id32_alloc.9f + +inl.9f := SOSRC = man9f/inb.9f +inw.9f := SOSRC = man9f/inb.9f +repinsb.9f := SOSRC = man9f/inb.9f +repinsd.9f := SOSRC = man9f/inb.9f +repinsw.9f := SOSRC = man9f/inb.9f + +kmem_free.9f := SOSRC = man9f/kmem_alloc.9f +kmem_zalloc.9f := SOSRC = man9f/kmem_alloc.9f + +kmem_cache_alloc.9f := SOSRC = man9f/kmem_cache_create.9f +kmem_cache_destroy.9f := SOSRC = man9f/kmem_cache_create.9f +kmem_cache_free.9f := SOSRC = man9f/kmem_cache_create.9f +kmem_cache_set_move.9f := SOSRC = man9f/kmem_cache_create.9f + +kstat_named_setstr.9f := SOSRC = man9f/kstat_named_init.9f + +kstat_runq_back_to_waitq.9f := SOSRC = man9f/kstat_queue.9f +kstat_runq_enter.9f := SOSRC = man9f/kstat_queue.9f +kstat_runq_exit.9f := SOSRC = man9f/kstat_queue.9f +kstat_waitq_enter.9f := SOSRC = man9f/kstat_queue.9f +kstat_waitq_exit.9f := SOSRC = man9f/kstat_queue.9f +kstat_waitq_to_runq.9f := SOSRC = man9f/kstat_queue.9f + +ldi_awrite.9f := SOSRC = man9f/ldi_aread.9f + +ldi_get_devid.9f := SOSRC = man9f/ldi_get_dev.9f +ldi_get_minor_name.9f := SOSRC = man9f/ldi_get_dev.9f +ldi_get_otyp.9f := SOSRC = man9f/ldi_get_dev.9f + +ldi_ident_from_dip.9f := SOSRC = man9f/ldi_ident_from_dev.9f +ldi_ident_from_stream.9f := SOSRC = man9f/ldi_ident_from_dev.9f +ldi_ident_release.9f := SOSRC = man9f/ldi_ident_from_dev.9f + +ldi_close.9f := SOSRC = man9f/ldi_open_by_dev.9f +ldi_open_by_devid.9f := SOSRC = man9f/ldi_open_by_dev.9f +ldi_open_by_name.9f := SOSRC = man9f/ldi_open_by_dev.9f + +ldi_prop_get_int64.9f := SOSRC = man9f/ldi_prop_get_int.9f + +ldi_prop_lookup_byte_array.9f := SOSRC = man9f/ldi_prop_lookup_int_array.9f +ldi_prop_lookup_int64_array.9f := SOSRC = man9f/ldi_prop_lookup_int_array.9f +ldi_prop_lookup_string.9f := SOSRC = man9f/ldi_prop_lookup_int_array.9f +ldi_prop_lookup_string_array.9f := SOSRC = man9f/ldi_prop_lookup_int_array.9f + +ldi_getmsg.9f := SOSRC = man9f/ldi_putmsg.9f + +ldi_write.9f := SOSRC = man9f/ldi_read.9f + +list_destroy.9f := SOSRC = man9f/list_create.9f +list_head.9f := SOSRC = man9f/list_create.9f +list_insert_after.9f := SOSRC = man9f/list_create.9f +list_insert_before.9f := SOSRC = man9f/list_create.9f +list_insert_head.9f := SOSRC = man9f/list_create.9f +list_insert_tail.9f := SOSRC = man9f/list_create.9f +list_is_empty.9f := SOSRC = man9f/list_create.9f +list_link_active.9f := SOSRC = man9f/list_create.9f +list_link_init.9f := SOSRC = man9f/list_create.9f +list_link_replace.9f := SOSRC = man9f/list_create.9f +list_move_tail.9f := SOSRC = man9f/list_create.9f +list_next.9f := SOSRC = man9f/list_create.9f +list_prev.9f := SOSRC = man9f/list_create.9f +list_remove.9f := SOSRC = man9f/list_create.9f +list_remove_head.9f := SOSRC = man9f/list_create.9f +list_remove_tail.9f := SOSRC = man9f/list_create.9f +list_tail.9f := SOSRC = man9f/list_create.9f + +makecom_g0.9f := SOSRC = man9f/makecom.9f +makecom_g0_s.9f := SOSRC = man9f/makecom.9f +makecom_g1.9f := SOSRC = man9f/makecom.9f +makecom_g5.9f := SOSRC = man9f/makecom.9f + +membar_consumer.9f := SOSRC = man9f/membar_ops.9f +membar_enter.9f := SOSRC = man9f/membar_ops.9f +membar_exit.9f := SOSRC = man9f/membar_ops.9f +membar_producer.9f := SOSRC = man9f/membar_ops.9f + +memcmp.9f := SOSRC = man9f/memchr.9f +memcpy.9f := SOSRC = man9f/memchr.9f +memmove.9f := SOSRC = man9f/memchr.9f +memset.9f := SOSRC = man9f/memchr.9f + +mod_info.9f := SOSRC = man9f/mod_install.9f +mod_modname.9f := SOSRC = man9f/mod_install.9f +mod_remove.9f := SOSRC = man9f/mod_install.9f + +mutex_destroy.9f := SOSRC = man9f/mutex.9f +mutex_enter.9f := SOSRC = man9f/mutex.9f +mutex_exit.9f := SOSRC = man9f/mutex.9f +mutex_init.9f := SOSRC = man9f/mutex.9f +mutex_owned.9f := SOSRC = man9f/mutex.9f +mutex_tryenter.9f := SOSRC = man9f/mutex.9f + +net_event_notify_unregister.9f := SOSRC = man9f/net_event_notify_register.9f + +net_instance_notify_unregister.9f := SOSRC = man9f/net_instance_notify_register.9f + +net_instance_protocol_unregister.9f := SOSRC = man9f/net_protocol_notify_register.9f + +nvlist_add_boolean_array.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_boolean_value.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_byte.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_byte_array.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_int16.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_int16_array.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_int32.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_int32_array.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_int64.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_int64_array.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_int8.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_int8_array.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_nvlist.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_nvlist_array.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_nvpair.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_string.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_string_array.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_uint16.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_uint16_array.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_uint32.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_uint32_array.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_uint64.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_uint64_array.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_uint8.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_add_uint8_array.9f := SOSRC = man9f/nvlist_add_boolean.9f +nvlist_t.9f := SOSRC = man9f/nvlist_add_boolean.9f + +nv_alloc_fini.9f := SOSRC = man9f/nvlist_alloc.9f +nv_alloc_init.9f := SOSRC = man9f/nvlist_alloc.9f +nvlist_dup.9f := SOSRC = man9f/nvlist_alloc.9f +nvlist_free.9f := SOSRC = man9f/nvlist_alloc.9f +nvlist_merge.9f := SOSRC = man9f/nvlist_alloc.9f +nvlist_pack.9f := SOSRC = man9f/nvlist_alloc.9f +nvlist_size.9f := SOSRC = man9f/nvlist_alloc.9f +nvlist_unpack.9f := SOSRC = man9f/nvlist_alloc.9f +nvlist_xalloc.9f := SOSRC = man9f/nvlist_alloc.9f +nvlist_xdup.9f := SOSRC = man9f/nvlist_alloc.9f +nvlist_xpack.9f := SOSRC = man9f/nvlist_alloc.9f +nvlist_xunpack.9f := SOSRC = man9f/nvlist_alloc.9f + +nvlist_lookup_boolean_array.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_boolean_value.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_byte.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_byte_array.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_int16.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_int16_array.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_int32.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_int32_array.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_int64.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_int64_array.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_int8.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_int8_array.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_nvlist.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_nvlist_array.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_pairs.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_string.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_string_array.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_uint16.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_uint16_array.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_uint32.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_uint32_array.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_uint64.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_uint64_array.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_uint8.9f := SOSRC = man9f/nvlist_lookup_boolean.9f +nvlist_lookup_uint8_array.9f := SOSRC = man9f/nvlist_lookup_boolean.9f + +nvlist_exists.9f := SOSRC = man9f/nvlist_lookup_nvpair.9f + +nvpair_name.9f := SOSRC = man9f/nvlist_next_nvpair.9f +nvpair_type.9f := SOSRC = man9f/nvlist_next_nvpair.9f + +nvlist_remove_all.9f := SOSRC = man9f/nvlist_remove.9f + +nvpair_value_boolean_array.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_byte_array.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_int16.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_int16_array.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_int32.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_int32_array.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_int64.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_int64_array.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_int8.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_int8_array.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_nvlist.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_nvlist_array.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_string.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_string_array.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_uint16.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_uint16_array.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_uint32.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_uint32_array.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_uint64.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_uint64_array.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_uint8.9f := SOSRC = man9f/nvpair_value_byte.9f +nvpair_value_uint8_array.9f := SOSRC = man9f/nvpair_value_byte.9f + +outl.9f := SOSRC = man9f/outb.9f +outw.9f := SOSRC = man9f/outb.9f +repoutsb.9f := SOSRC = man9f/outb.9f +repoutsd.9f := SOSRC = man9f/outb.9f +repoutsw.9f := SOSRC = man9f/outb.9f + +pci_config_get16.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_get32.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_get64.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_getb.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_getl.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_getll.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_getw.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_put16.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_put32.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_put64.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_put8.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_putb.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_putl.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_putll.9f := SOSRC = man9f/pci_config_get8.9f +pci_config_putw.9f := SOSRC = man9f/pci_config_get8.9f + +pci_config_teardown.9f := SOSRC = man9f/pci_config_setup.9f + +pci_ereport_post.9f := SOSRC = man9f/pci_ereport_setup.9f +pci_ereport_teardown.9f := SOSRC = man9f/pci_ereport_setup.9f + +pci_restore_config_regs.9f := SOSRC = man9f/pci_save_config_regs.9f + +minphys.9f := SOSRC = man9f/physio.9f + +pm_idle_component.9f := SOSRC = man9f/pm_busy_component.9f + +pm_lower_power.9f := SOSRC = man9f/pm_raise_power.9f + +priv_policy_choice.9f := SOSRC = man9f/priv_policy.9f +priv_policy_only.9f := SOSRC = man9f/priv_policy.9f + +proc_ref.9f := SOSRC = man9f/proc_signal.9f +proc_unref.9f := SOSRC = man9f/proc_signal.9f + +qprocsoff.9f := SOSRC = man9f/qprocson.9f + +qwait_sig.9f := SOSRC = man9f/qwait.9f + +rmallocmap_wait.9f := SOSRC = man9f/rmallocmap.9f +rmfreemap.9f := SOSRC = man9f/rmallocmap.9f + +rw_destroy.9f := SOSRC = man9f/rwlock.9f +rw_downgrade.9f := SOSRC = man9f/rwlock.9f +rw_enter.9f := SOSRC = man9f/rwlock.9f +rw_exit.9f := SOSRC = man9f/rwlock.9f +rw_init.9f := SOSRC = man9f/rwlock.9f +rw_read_locked.9f := SOSRC = man9f/rwlock.9f +rw_tryenter.9f := SOSRC = man9f/rwlock.9f +rw_tryupgrade.9f := SOSRC = man9f/rwlock.9f + +scsi_dname.9f := SOSRC = man9f/scsi_cname.9f +scsi_mname.9f := SOSRC = man9f/scsi_cname.9f +scsi_rname.9f := SOSRC = man9f/scsi_cname.9f +scsi_sname.9f := SOSRC = man9f/scsi_cname.9f + +scsi_dmafree.9f := SOSRC = man9f/scsi_dmaget.9f + +scsi_sense_cmdspecific_uint64.9f := SOSRC = man9f/scsi_ext_sense_fields.9f +scsi_sense_info_uint64.9f := SOSRC = man9f/scsi_ext_sense_fields.9f + +scsi_hba_attach.9f := SOSRC = man9f/scsi_hba_attach_setup.9f +scsi_hba_detach.9f := SOSRC = man9f/scsi_hba_attach_setup.9f + +scsi_hba_fini.9f := SOSRC = man9f/scsi_hba_init.9f + +scsi_hba_pkt_free.9f := SOSRC = man9f/scsi_hba_pkt_alloc.9f + +scsi_hba_tran_free.9f := SOSRC = man9f/scsi_hba_tran_alloc.9f + +scsi_ifsetcap.9f := SOSRC = man9f/scsi_ifgetcap.9f + +scsi_pktfree.9f := SOSRC = man9f/scsi_pktalloc.9f +scsi_resalloc.9f := SOSRC = man9f/scsi_pktalloc.9f +scsi_resfree.9f := SOSRC = man9f/scsi_pktalloc.9f + +scsi_sense_asc.9f := SOSRC = man9f/scsi_sense_key.9f +scsi_sense_ascq.9f := SOSRC = man9f/scsi_sense_key.9f + +scsi_unslave.9f := SOSRC = man9f/scsi_unprobe.9f + +sema_destroy.9f := SOSRC = man9f/semaphore.9f +sema_init.9f := SOSRC = man9f/semaphore.9f +sema_p.9f := SOSRC = man9f/semaphore.9f +sema_p_sig.9f := SOSRC = man9f/semaphore.9f +sema_tryp.9f := SOSRC = man9f/semaphore.9f +sema_v.9f := SOSRC = man9f/semaphore.9f + +numtos.9f := SOSRC = man9f/stoi.9f + +ddi_strdup.9f := SOSRC = man9f/string.9f +strcasecmp.9f := SOSRC = man9f/string.9f +strchr.9f := SOSRC = man9f/string.9f +strcmp.9f := SOSRC = man9f/string.9f +strcpy.9f := SOSRC = man9f/string.9f +strdup.9f := SOSRC = man9f/string.9f +strfree.9f := SOSRC = man9f/string.9f +strlcat.9f := SOSRC = man9f/string.9f +strlcpy.9f := SOSRC = man9f/string.9f +strlen.9f := SOSRC = man9f/string.9f +strncasecmp.9f := SOSRC = man9f/string.9f +strncat.9f := SOSRC = man9f/string.9f +strncmp.9f := SOSRC = man9f/string.9f +strncpy.9f := SOSRC = man9f/string.9f +strnlen.9f := SOSRC = man9f/string.9f +strrchr.9f := SOSRC = man9f/string.9f +strspn.9f := SOSRC = man9f/string.9f + +ddi_taskq_create.9f := SOSRC = man9f/taskq.9f +ddi_taskq_destroy.9f := SOSRC = man9f/taskq.9f +ddi_taskq_dispatch.9f := SOSRC = man9f/taskq.9f +ddi_taskq_resume.9f := SOSRC = man9f/taskq.9f +ddi_taskq_suspend.9f := SOSRC = man9f/taskq.9f +ddi_taskq_wait.9f := SOSRC = man9f/taskq.9f +taskq_suspended.9f := SOSRC = man9f/taskq.9f + +uconv_u16tou8.9f := SOSRC = man9f/uconv_u16tou32.9f +uconv_u32tou16.9f := SOSRC = man9f/uconv_u16tou32.9f +uconv_u32tou8.9f := SOSRC = man9f/uconv_u16tou32.9f +uconv_u8tou16.9f := SOSRC = man9f/uconv_u16tou32.9f +uconv_u8tou32.9f := SOSRC = man9f/uconv_u16tou32.9f + +usb_alloc_bulk_req.9f := SOSRC = man9f/usb_alloc_request.9f +usb_alloc_ctrl_req.9f := SOSRC = man9f/usb_alloc_request.9f +usb_alloc_intr_req.9f := SOSRC = man9f/usb_alloc_request.9f +usb_alloc_isoc_req.9f := SOSRC = man9f/usb_alloc_request.9f +usb_free_bulk_req.9f := SOSRC = man9f/usb_alloc_request.9f +usb_free_ctrl_req.9f := SOSRC = man9f/usb_alloc_request.9f +usb_free_intr_req.9f := SOSRC = man9f/usb_alloc_request.9f +usb_free_isoc_req.9f := SOSRC = man9f/usb_alloc_request.9f +usb_client_detach.9f := SOSRC = man9f/usb_client_attach.9f + +usb_get_if_number.9f := SOSRC = man9f/usb_get_alt_if.9f +usb_owns_device.9f := SOSRC = man9f/usb_get_alt_if.9f +usb_set_alt_if.9f := SOSRC = man9f/usb_get_alt_if.9f + +usb_set_cfg.9f := SOSRC = man9f/usb_get_cfg.9f + +usb_free_descr_tree.9f := SOSRC = man9f/usb_get_dev_data.9f +usb_free_dev_data.9f := SOSRC = man9f/usb_get_dev_data.9f +usb_print_descr_tree.9f := SOSRC = man9f/usb_get_dev_data.9f + +usb_pipe_ctrl_xfer_wait.9f := SOSRC = man9f/usb_pipe_ctrl_xfer.9f +usb_pipe_stop_intr_polling.9f := SOSRC = man9f/usb_pipe_intr_xfer.9f +usb_pipe_stop_isoc_polling.9f := SOSRC = man9f/usb_pipe_isoc_xfer.9f + +usb_pipe_get_private.9f := SOSRC = man9f/usb_pipe_set_private.9f + +usb_unregister_hotplug_cbs.9f := SOSRC = man9f/usb_register_hotplug_cbs.9f + +va_copy.9f := SOSRC = man9f/va_arg.9f +va_end.9f := SOSRC = man9f/va_arg.9f +va_start.9f := SOSRC = man9f/va_arg.9f + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) + + diff --git a/usr/src/man/man9f/OTHERQ.9f b/usr/src/man/man9f/OTHERQ.9f new file mode 100644 index 0000000000..4f672a58d7 --- /dev/null +++ b/usr/src/man/man9f/OTHERQ.9f @@ -0,0 +1,91 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH OTHERQ 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +OTHERQ, otherq \- get pointer to queue's partner queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBqueue_t *\fR\fBOTHERQ\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 5n +.rt +Pointer to the queue. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBOTHERQ()\fR function returns a pointer to the other of the two +\fBqueue\fR structures that make up a STREAMS module or driver. If \fIq\fR +points to the read queue the write queue will be returned, and vice versa. +.SH RETURN VALUES +.sp +.LP +The \fBOTHERQ()\fR function returns a pointer to a queue's partner. +.SH CONTEXT +.sp +.LP +The \fBOTHERQ()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRSetting Queues +.sp +.LP +This routine sets the minimum packet size, the maximum packet size, the high +water mark, and the low water mark for the read and write queues of a given +module or driver. It is passed either one of the queues. This could be used if +a module or driver wished to update its queue parameters dynamically. + +.sp +.in +2 +.nf + 1 void + 2 set_q_params(q, min, max, hi, lo) + 3 queue_t *q; + 4 short min; + 5 short max; + 6 ushort_t hi; + 7 ushort_t lo; + 8 { + 9 q->q_minpsz = min; +10 q->q_maxpsz = max; +11 q->q_hiwat = hi; +12 q->q_lowat = lo; +13 OTHERQ(q)->q_minpsz = min; +14 OTHERQ(q)->q_maxpsz = max; +15 OTHERQ(q)->q_hiwat = hi; +16 OTHERQ(q)->q_lowat = lo; +17 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/RD.9f b/usr/src/man/man9f/RD.9f new file mode 100644 index 0000000000..f058521722 --- /dev/null +++ b/usr/src/man/man9f/RD.9f @@ -0,0 +1,71 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH RD 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +RD, rd \- get pointer to the read queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBqueue_t *\fR\fBRD\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (\fBDDI/DKI)\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 5n +.rt +Pointer to the \fBwrite\fR queue whose \fBread\fR queue is to be returned. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBRD()\fR function accepts a \fBwrite\fR queue pointer as an argument and +returns a pointer to the \fBread\fR queue of the same module. +.sp +.LP +\fBCAUTION:\fR Make sure the argument to this function is a pointer to a +\fBwrite\fR queue. \fBRD()\fR will not check for queue type, and a system panic +could result if it is not the right type. +.SH RETURN VALUES +.sp +.LP +The pointer to the \fBread\fR queue. +.SH CONTEXT +.sp +.LP +The \fBRD()\fR function can be called from user, interrupt, or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRFunction page reference +.sp +.LP +See the \fBqreply\fR(9F) function page for an example of \fBRD()\fR. + +.SH SEE ALSO +.sp +.LP +\fBqreply\fR(9F), \fBWR\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/SAMESTR.9f b/usr/src/man/man9f/SAMESTR.9f new file mode 100644 index 0000000000..9f9689d6db --- /dev/null +++ b/usr/src/man/man9f/SAMESTR.9f @@ -0,0 +1,64 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH SAMESTR 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +SAMESTR, samestr \- test if next queue is in the same stream +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBSAMESTR\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 5n +.rt +Pointer to the queue. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBSAMESTR()\fR function is used to see if the next queue in a stream (if +it exists) is the same type as the current queue (that is, both are read queues +or both are write queues). This function accounts for the twisted queue +connections that occur in a STREAMS pipe and should be used in preference to +direct examination of the \fBq_next\fR field of \fBqueue\fR(9S) to see if the +stream continues beyond \fIq\fR. +.SH RETURN VALUES +.sp +.LP +The \fBSAMESTR()\fR function returns \fB1\fR if the next queue is the same type +as the current queue. It returns \fB0\fR if the next queue does not exist or if +it is not the same type. +.SH CONTEXT +.sp +.LP +The \fBSAMESTR()\fR function can be called from user, interrupt, context. +.SH SEE ALSO +.sp +.LP +\fBOTHERQ\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/STRUCT_DECL.9f b/usr/src/man/man9f/STRUCT_DECL.9f new file mode 100644 index 0000000000..74212391af --- /dev/null +++ b/usr/src/man/man9f/STRUCT_DECL.9f @@ -0,0 +1,493 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH STRUCT_DECL 9F "20 May 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +STRUCT_DECL, SIZEOF_PTR, SIZEOF_STRUCT, STRUCT_BUF, STRUCT_FADDR, STRUCT_FGET, +STRUCT_FGETP, STRUCT_FSET, STRUCT_FSETP, STRUCT_HANDLE, STRUCT_INIT, +STRUCT_SIZE, STRUCT_SET_HANDLE \- 32-bit application data access macros +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fB\fR\fBSTRUCT_DECL\fR(\fB\fR\fIstructname\fR, \fB\fR \fIhandle\fR); +.fi + +.LP +.nf +\fB\fR\fBSTRUCT_HANDLE\fR(\fB\fR\fIstructname\fR, \fB\fR\fIhandle\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBSTRUCT_INIT\fR(\fB\fR\fIhandle\fR, \fBmodel_t\fR \fIumodel\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBSTRUCT_SET_HANDLE\fR(\fB\fR\fIhandle\fR, \fBmodel_t\fR \fIumodel\fR, \fBvoid\fR \fI*addr\fR); +.fi + +.LP +.nf +\fB\fR\fBSTRUCT_FGET\fR(\fB\fR\fIhandle\fR, \fB\fR\fIfield\fR); +.fi + +.LP +.nf +\fB\fR\fBSTRUCT_FGETP\fR(\fB\fR\fIhandle\fR, \fB\fR\fIfield\fR); +.fi + +.LP +.nf +\fB\fR\fBSTRUCT_FSET\fR(\fB\fR\fIhandle\fR, \fB\fR\fIfield\fR, \fB\fR\fIval\fR); +.fi + +.LP +.nf +\fB\fR\fBSTRUCT_FSETP\fR(\fB\fR\fIhandle\fR, \fB\fR\fIfield\fR, \fB\fR\fIval\fR); +.fi + +.LP +.nf +\fB<typeof field> *\fR\fBSTRUCT_FADDR\fR(\fB\fR\fIhandle\fR, \fB\fR\fIfield\fR); +.fi + +.LP +.nf +\fBstruct structname *\fR\fBSTRUCT_BUF\fR(\fB\fR\fIhandle\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBSIZEOF_STRUCT\fR(\fB\fR\fIstructname\fR, \fB\fR\fIumodel\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBSIZEOF_PTR\fR(\fB\fR\fIumodel\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBSTRUCT_SIZE\fR(\fB\fR\fIhandle\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +The macros take the following parameters: +.sp +.ne 2 +.mk +.na +\fB\fIstructname\fR\fR +.ad +.RS 14n +.rt +The structure name that appears \fBafter\fR the \fBC\fR keyword struct of the +native form. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIumodel\fR\fR +.ad +.RS 14n +.rt + A bit field that contains either the \fBILP32\fR model bit +(\fBDATAMODEL_ILP32\fR), or the \fBLP64\fR model bit (\fBDATAMODEL_LP64\fR). In +an \fBioctl\fR(9E), these bits are present in the flag parameter. In a +\fBdevmap\fR(9E), the bits are present in the model parameter \fBmmap\fR(9E). +The \fBddi_mmap_get_model\fR(9F) can be called to get the data model of the +current thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 14n +.rt +The variable name used to refer to a particular instance of a structure which +is handled by these macros. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfield\fR\fR +.ad +.RS 14n +.rt +The field name within the structure that can contain substructures. If the +structures contain substructures, unions, or arrays, the \fIfield\fR can be +whatever complex expression would naturally follow the first . or ->. +.RE + +.SH DESCRIPTION +.sp +.LP +The above macros allow a device driver to access data consumed from a 32-bit +application regardless whether the driver was compiled to the ILP32 or LP64 +data model. These macros effectively hide the difference between the data model +of the user application and the driver. +.sp +.LP +The macros can be broken up into two main categories described in the following +sections. +.SS "Declaration and Initialization Macros" +.sp +.LP +The macros \fBSTRUCT_DECL()\fR and \fBSTRUCT_HANDLE()\fR declare structure +handles on the stack, whereas the macros \fBSTRUCT_INIT()\fR and +\fBSTRUCT_SET_HANDLE()\fR initialize the structure handles to point to an +instance of the native form structure. +.sp +.LP +The macros \fBSTRUCT_HANDLE()\fR and \fBSTRUCT_SET_HANDLE()\fR are used to +declare and initialize a structure handle to an existing data structure, for +example, ioctls within a STREAMS module. +.sp +.LP +The macros \fBSTRUCT_DECL()\fR and \fBSTRUCT_INIT()\fR, on the other hand, are +used in modules which declare and initialize a structure handle to a data +structure allocated by \fBSTRUCT_DECL()\fR, that is, any standard character or +block device driver \fBioctl\fR(9E) routine that needs to copy in data from a +user-mode program. +.sp +.ne 2 +.mk +.na +\fBSTRUCT_DECL(structname, handle)\fR +.ad +.sp .6 +.RS 4n +Declares a structure handle for a struct and allocates an instance of its +native form on the stack. It is assumed that the native form is larger than or +equal to the ILP32 form. \fIhandle\fR is a variable name and is declared as a +variable by this macro. +.RE + +.sp +.ne 2 +.mk +.na +\fBvoid STRUCT_INIT(handle, model_t umodel)\fR +.ad +.sp .6 +.RS 4n +Initializes \fIhandle\fR to point to the instance allocated by +\fBSTRUCT_DECL()\fR. It also sets data model for \fIhandle\fR to \fIumodel\fR +and it must be called before any access is made through the macros that operate +on these structures. When used in an \fBioctl\fR(9E) routine, \fIumodel\fR is +the flag parameter. In a \fBdevmap\fR(9E) routine, \fIumodel\fR is the model +parameter. In a \fBmmap\fR(9E) routine, \fIumodel\fR is the return value of +\fBddi_mmap_get_model\fR(9F). This macro is intended only for handles created +with \fBSTRUCT_DECL()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBSTRUCT_HANDLE(structname, handle)\fR +.ad +.sp .6 +.RS 4n +Declares a structure handle \fIhandle\fR but, unlike \fBSTRUCT_DECL()\fR, it +does not allocate an instance of "struct". +.RE + +.sp +.ne 2 +.mk +.na +\fBvoid STRUCT_SET_HANDLE(handle, model_t umodel, void *addr)\fR +.ad +.sp .6 +.RS 4n +Initializes handle to point to the native form instance at \fIaddr\fR. It also +sets the data model for \fIhandle\fR to \fIumodel\fR. This is intended for +handles created with \fBSTRUCT_HANDLE()\fR. Fields cannot be referenced via the +\fIhandle\fR until this macro has been invoked. Typically, \fIaddr\fR is the +address of the native form structure containing the user-mode programs data. +When used in an \fBioctl\fR(9E), \fIumodel\fR is the flag parameter. In a +\fBdevmap\fR(9E) routine, \fIumodel\fR is the model parameter. In an +\fBmmap\fR(9E) routine, \fIumodel\fR is the return value of +\fBddi_mmap_get_model\fR(9F). +.RE + +.SS "Operation Macros" +.sp +.ne 2 +.mk +.na +\fBsize_t STRUCT_SIZE(handle)\fR +.ad +.sp .6 +.RS 4n +Returns size of the structure referred to by \fIhandle\fR, depending on the +data model associated with \fIhandle\fR. If the data model stored by +\fBSTRUCT_INIT()\fR or \fBSTRUCT_SET_HANDLE()\fR is \fBDATAMODEL_ILP32\fR, the +size of the \fBILP32\fR form is returned. Otherwise, the size of the native +form is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fBSTRUCT_FGET(handle, field)\fR +.ad +.sp .6 +.RS 4n +Returns the contents of \fIfield\fR in the structure described by \fIhandle\fR +according to the data model associated with \fIhandle\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBSTRUCT_FGETP(handle, field)\fR +.ad +.sp .6 +.RS 4n +This is the same as \fBSTRUCT_FGET()\fR except that the \fIfield\fR in question +is a pointer of some kind. This macro casts caddr32_t to a (void *) when it is +accessed. Failure to use this macro for a pointer leads to compiler warnings or +failures. +.RE + +.sp +.ne 2 +.mk +.na +\fBSTRUCT_FSET(handle, field, val)\fR +.ad +.sp .6 +.RS 4n +Assigns \fIval\fR to the (non-pointer) in the structure described by +\fIhandle\fR. It should not be used within another expression, but only as a +statement. +.RE + +.sp +.ne 2 +.mk +.na +\fBSTRUCT_FSETP(handle, field, val)\fR +.ad +.sp .6 +.RS 4n +This is the equivalent of STRUCT_FGETP() for STRUCT_FGET(), with the same +exceptions. Like STRUCT_FSET, STRUCT_FSETP should not be used within another +expression, but only as a statement. +.RE + +.sp +.ne 2 +.mk +.na +\fBstruct structname *STRUCT_BUF(handle)\fR +.ad +.sp .6 +.RS 4n +Returns a pointer to the native mode instance of the structure described by +\fIhandle\fR. +.RE + +.SS "Macros Not Using Handles" +.sp +.ne 2 +.mk +.na +\fBsize_t SIZEOF_STRUCT(structname, umodel)\fR +.ad +.sp .6 +.RS 4n +Returns size of \fIstructname\fR based on \fIumodel\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBsize_t SIZEOF_PTR(umodel)\fR +.ad +.sp .6 +.RS 4n +Returns the size of a pointer based on \fIumodel\fR. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRCopying a Structure +.sp +.LP +The following example uses an \fBioctl\fR(9E) on a regular character device +that copies a data structure that looks like this into the kernel: + +.sp +.in +2 +.nf +struct opdata { + size_t size; + uint_t flag; +}; +.fi +.in -2 + +.LP +\fBExample 2 \fRDefining a Structure +.sp +.LP +This data structure definition describes what the \fBioctl\fR(9E) would look +like in a 32-bit application using fixed width types. + +.sp +.in +2 +.nf +#if defined(_MULTI_DATAMODEL) +struct opdata32 { + size32_t size; + uint32_t flag; +}; +#endif +.fi +.in -2 + +.LP +\fBExample 3 \fRUsing \fBSTRUCT_DECL()\fR and \fBSTRUCT_INIT()\fR +.sp +.LP +Note: This example uses the \fBSTRUCT_DECL()\fR and \fBSTRUCT_INIT()\fR macros +to declare and initialize the structure handle. + +.sp +.in +2 +.nf +int +xxioctl(dev_t dev, int cmd, intptr_t arg, int mode, + cred_t *cr, int *rval_p); +{ + STRUCT_DECL(opdata, op); + + if (cmd != OPONE) + return (ENOTTY); + + STRUCT_INIT(op, mode); + + if (copyin((void *)data, + STRUCT_BUF(op), STRUCT_SIZE(op))) + return (EFAULT); + + if (STRUCT_FGET(op, flag) != FACTIVE || + STRUCT_FGET(op, size) > sizeof (device_state)) + return (EINVAL); + xxdowork(device_state, STRUCT_FGET(op, size)); + return (0); +} +.fi +.in -2 + +.sp +.LP +This piece of code is an excerpt from a STREAMS module that handles +\fBioctl\fR(9E) data (M_IOCDATA) messages and uses the data structure defined +above. This code has been written to run in the ILP32 environment only. + +.LP +\fBExample 4 \fRUsing \fBSTRUCT_HANDLE()\fR and \fBSTRUCT_SET_HANDLE()\fR +.sp +.LP +The next example illustrates the use of the \fBSTRUCT_HANDLE()\fR and +\fBSTRUCT_SET_HANDLE()\fR macros which declare and initialize the structure +handle to point to an already existing instance of the structure. + +.sp +.LP +The above code example can be converted to run in the LP64 environment using +the \fBSTRUCT_HANDLE()\fR and \fBSTRUCT_SET_HANDLE()\fR as follows: + +.sp +.in +2 +.nf +struct strbuf { +int maxlen; /* no. of bytes in buffer */ +int len; /* no. of bytes returned */ +caddr_t buf; /* pointer to data */ +}; +.fi +.in -2 + +.sp +.in +2 +.nf +static void +wput_iocdata(queue_t *q, mblk_t *msgp) +{ + struct copyresp *cp = (struct copyresp *)msgp->b_rptr; + STRUCT_HANDLE(strbuf, sb); + + if (msgp->b_cont->b_cont != NULL) { + msgp->b_cont = msgpullup(msgp->b_cont, -1); + if (msgp->b_cont == NULL) { + miocnak(q, msgp, 0, ENOSR); + return; + } + } + STRUCT_SET_HANDLE(sb, cp->cp_flag, (void *)msgp->b_cont->b_rptr); + if (STRUCT_FGET(sb, maxlen) < (int)sizeof (ipa_t)) { + miocnak(q, msgp, 0, ENOSR); + return; + } + ... + miocack(q, msgp, 0, 0); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBdevmap\fR(9E), \fBioctl\fR(9E), \fBmmap\fR(9E),\fBddi_mmap_get_model\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/WR.9f b/usr/src/man/man9f/WR.9f new file mode 100644 index 0000000000..b5f5672689 --- /dev/null +++ b/usr/src/man/man9f/WR.9f @@ -0,0 +1,88 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH WR 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +WR, wr \- get pointer to the write queue for this module or driver +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBqueue_t *\fR\fBWR\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 5n +.rt +Pointer to the \fIread\fR queue whose \fIwrite\fR queue is to be returned. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBWR()\fR function accepts a \fIread\fR queue pointer as an argument and +returns a pointer to the \fIwrite\fR queue of the same module. +.sp +.LP +CAUTION: Make sure the argument to this function is a pointer to a \fIread\fR +queue. \fBWR()\fR will not check for queue type, and a system panic could +result if the pointer is not to a \fIread\fR queue. +.SH RETURN VALUES +.sp +.LP +The pointer to the \fIwrite\fR queue. +.SH CONTEXT +.sp +.LP +The \fBWR()\fR function can be called from user, interrupt, or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBWR()\fR +.sp +.LP +In a STREAMS \fBclose\fR(9E) routine, the driver or module is passed a pointer +to the \fIread\fR queue. These usually are set to the address of the +module-specific data structure for the minor device. + +.sp +.in +2 +.nf + +1 xxxclose(q, flag) +2 queue_t *q; +3 int flag; +4 { +5 q->q_ptr = NULL; +6 WR(q)->q_ptr = NULL; + . . . +7 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(9E), \fBOTHERQ\fR(9F), \fBRD\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/adjmsg.9f b/usr/src/man/man9f/adjmsg.9f new file mode 100644 index 0000000000..5f609cf6bd --- /dev/null +++ b/usr/src/man/man9f/adjmsg.9f @@ -0,0 +1,105 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH adjmsg 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +adjmsg \- trim bytes from a message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBadjmsg\fR(\fBmblk_t *\fR\fImp\fR, \fBssize_t\fR \fIlen\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 7n +.rt +Pointer to the message to be trimmed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 7n +.rt +The number of bytes to be removed. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBadjmsg()\fR function removes bytes from a message. |\fIlen\fR| (the +absolute value of \fIlen\fR) specifies the number of bytes to be removed. The +\fBadjmsg()\fR function only trims bytes across message blocks of the same +type. +.sp +.LP +The \fBadjmsg()\fR function finds the maximal leading sequence of message +blocks of the same type as that of \fImp\fR and starts removing bytes either +from the head of that sequence or from the tail of that sequence. If \fIlen\fR +is greater than \fB0\fR, \fBadjmsg()\fR removes bytes from the start of the +first message block in that sequence. If \fIlen\fR is less than \fB0\fR, it +removes bytes from the end of the last message block in that sequence. +.sp +.LP +The \fBadjmsg()\fR function fails if |\fIlen\fR| is greater than the number of +bytes in the maximal leading sequence it finds. +.sp +.LP +The \fBadjmsg()\fR function may remove any except the first zero-length message +block created during adjusting. It may also remove any zero-length message +blocks that occur within the scope of |\fIlen\fR|. +.SH RETURN VALUES +.sp +.LP +The \fBadjmsg()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 5n +.rt +Successful completion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +An error occurred. +.RE + +.SH CONTEXT +.sp +.LP +The \fBadjmsg()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/allocb.9f b/usr/src/man/man9f/allocb.9f new file mode 100644 index 0000000000..30c0dade13 --- /dev/null +++ b/usr/src/man/man9f/allocb.9f @@ -0,0 +1,228 @@ +'\" te +.\" Copyright (C) 2006, Sun Microsystems, Inc. +.\" All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH allocb 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +allocb \- allocate a message block +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBmblk_t *\fR\fBallocb\fR(\fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH DESCRIPTION +.sp +.LP +The \fBallocb()\fR function tries to allocate a \fBSTREAMS\fR message block. +Buffer allocation fails only when the system is out of memory. If no buffer is +available, the \fBbufcall\fR(9F) function can help a module recover from an +allocation failure. +.sp +.LP +A \fBSTREAMS\fR message block is composed of three structures. The first +structure is a message block (\fBmblk_t\fR). See \fBmsgb\fR(9S). The +\fBmblk_t\fR structure points to a data block structure (\fBdblk_t\fR). See +\fBdatab\fR(9S). Together these two structures describe the message type (if +applicable) and the size and location of the third structure, the data buffer. +The data buffer contains the data for this message block. The allocated data +buffer is at least double-word aligned, so it can hold any C data structure. +.sp +.LP +The fields in the \fBmblk_t\fR structure are initialized as follows: +.sp +.ne 2 +.mk +.na +\fB\fBb_cont\fR\fR +.ad +.RS 11n +.rt +set to \fINULL\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBb_rptr\fR\fR +.ad +.RS 11n +.rt +points to the beginning of the data buffer +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBb_wptr\fR\fR +.ad +.RS 11n +.rt +points to the beginning of the data buffer +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBb_datap\fR\fR +.ad +.RS 11n +.rt +points to the \fBdblk_t\fR structure +.RE + +.sp +.LP +The fields in the \fBdblk_t\fR structure are initialized as follows: +.sp +.ne 2 +.mk +.na +\fB\fBdb_base\fR\fR +.ad +.RS 11n +.rt +points to the first byte of the data buffer +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdb_lim\fR\fR +.ad +.RS 11n +.rt +points to the last byte + 1 of the buffer +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdb_type\fR\fR +.ad +.RS 11n +.rt +set to \fBM_DATA\fR +.RE + +.sp +.LP +The following figure identifies the data structure members that are affected +when a message block is allocated. +.sp +Printed copy or docs.sun.com shows a figure that identifies the data structure +members that are affected when a message block is allocated +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 8n +.rt +The number of bytes in the message block. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpri\fR\fR +.ad +.RS 8n +.rt +Priority of the request (no longer used). +.RE + +.SH RETURN VALUES +.sp +.LP +Upon success, \fBallocb()\fR returns a pointer to the allocated message block +of type \fBM_DATA\fR. On failure, \fBallocb()\fR returns a \fINULL\fR pointer. +.SH CONTEXT +.sp +.LP +The \fBallocb()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBallocb()\fR Code Sample +.sp +.LP +Given a pointer to a queue (\fIq\fR) and an error number (\fIerr\fR), the +\fBsend_error()\fR routine sends an \fBM_ERROR\fR type message to the stream +head. + +.sp +.LP +If a message cannot be allocated, \fINULL\fR is returned, indicating an +allocation failure (line 8). Otherwise, the message type is set to +\fBM_ERROR\fR (line 10). Line 11 increments the write pointer +(\fBbp->b_wptr\fR) by the size (one byte) of the data in the message. + +.sp +.LP +A message must be sent up the read side of the stream to arrive at the stream +head. To determine whether \fIq\fR points to a read queue or to a write queue, +the \fBq->q_flag\fR member is tested to see if \fBQREADR\fR is set (line 13). +If it is not set, \fIq\fR points to a write queue, and in line 14 the +\fBRD\fR(9F) function is used to find the corresponding read queue. In line 15, +the \fBputnext\fR(9F) function is used to send the message upstream, returning +\fB1\fR if successful. + +.sp +.in +2 +.nf +1 send_error(q,err) +2 queue_t *q; +3 unsigned char err; +4 { +5 mblk_t *bp; +6 +7 if ((bp = allocb(1, BPRI_HI)) == NULL) /* allocate msg. block */ +8 return(0); +9 +10 bp->b_datap->db_type = M_ERROR; /* set msg type to M_ERROR */ +11 *bp->b_wptr++ = err; /* increment write pointer */ +12 +13 if (!(q->q_flag & QREADR)) /* if not read queue */ +14 q = RD(q); /* get read queue */ +15 putnext(q,bp); /* send message upstream */ +16 return(1); +17 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBRD\fR(9F), \fBbufcall\fR(9F), \fBesballoc\fR(9F), \fBesbbcall\fR(9F), +\fBputnext\fR(9F), \fBtestb\fR(9F), \fBdatab\fR(9S), \fBmsgb\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH NOTES +.sp +.LP +The \fIpri\fR argument is no longer used, but is retained for compatibility +with existing drivers. diff --git a/usr/src/man/man9f/atomic_add.9f b/usr/src/man/man9f/atomic_add.9f new file mode 100644 index 0000000000..236781a98f --- /dev/null +++ b/usr/src/man/man9f/atomic_add.9f @@ -0,0 +1,154 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_add 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +atomic_add, atomic_add_8, atomic_add_char, atomic_add_16, atomic_add_short, +atomic_add_32, atomic_add_int, atomic_add_long, atomic_add_64, atomic_add_ptr, +atomic_add_8_nv, atomic_add_char_nv, atomic_add_16_nv, atomic_add_short_nv, +atomic_add_32_nv, atomic_add_int_nv, atomic_add_long_nv, atomic_add_64_nv, +atomic_add_ptr_nv \- atomic add operations +.SH SYNOPSIS +.LP +.nf +#include <sys/atomic.h> + +\fBvoid\fR \fBatomic_add_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBint8_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_char\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBsigned char\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBint16_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_short\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBshort\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBint32_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_int\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBint\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_long\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBlong\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBint64_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_add_ptr\fR(\fBvolatile void *\fR\fItarget\fR, \fBssize_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBuint8_t\fR \fBatomic_add_8_nv\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBint8_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_add_char_nv\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBsigned char\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_add_16_nv\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBint16_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_add_short_nv\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBshort\fR\fIdelta\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_add_32_nv\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBint32_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_add_int_nv\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBint\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_add_long_nv\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBlong\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_add_64_nv\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBint64_t\fR \fIdelta\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBatomic_add_ptr_nv\fR(\fBvolatile void *\fR\fItarget\fR, \fBssize_t\fR \fIdelta\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable the addition of \fIdelta\fR to the value stored in +\fItarget\fR to occur in an atomic manner. +.SH RETURN VALUES +.sp +.LP +The *\fB_nv()\fR variants of these functions return the new value of +\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.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 +\fBatomic_and\fR(9F), \fBatomic_bits\fR(9F), \fBatomic_cas\fR(9F), +\fBatomic_dec\fR(9F), \fBatomic_inc\fR(9F), \fBatomic_or\fR(9F), +\fBatomic_swap\fR(9F), \fBmembar_ops\fR(9F), \fBattributes\fR(5), +\fBatomic_ops\fR(3C) +.SH NOTES +.sp +.LP +The *\fB_nv()\fR variants are substantially more expensive on some platforms +than the versions that do not return values. Do not use them unless you need to +know the new value \fBatomically\fR (for example, when decrementing a reference +count and checking whether it went to zero). diff --git a/usr/src/man/man9f/atomic_and.9f b/usr/src/man/man9f/atomic_and.9f new file mode 100644 index 0000000000..5c8021317a --- /dev/null +++ b/usr/src/man/man9f/atomic_and.9f @@ -0,0 +1,143 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_and 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +atomic_and, atomic_and_8, atomic_and_uchar, atomic_and_16, atomic_and_ushort, +atomic_and_32, atomic_and_uint, atomic_and_ulong, atomic_and_64, +atomic_and_8_nv, atomic_and_uchar_nv, atomic_and_16_nv, atomic_and_ushort_nv, +atomic_and_32_nv, atomic_and_uint_nv, atomic_and_ulong_nv, atomic_and_64_nv \- +atomic AND operations +.SH SYNOPSIS +.LP +.nf +#include <sys/atomic.h> + +\fBvoid\fR \fBatomic_and_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBuint8_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_uchar\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBuchar_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBuint16_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_ushort\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBushort_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBuint32_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_uint\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBuint_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_ulong\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBulong_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_and_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBuint64_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint8_t\fR \fBatomic_and_8_nv\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBuint8_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_and_uchar_nv\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBuchar_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_and_16_nv\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBuint16_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_and_ushort_nv\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBushort_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_and_32_nv\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBuint32_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_and_uint_nv\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBuint_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_and_ulong_nv\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBulong_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_and_64_nv\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBuint64_t\fR \fIbits\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable the bitwise AND of \fIbits\fR to the value stored in +\fItarget\fR to occur in an atomic manner. +.SH RETURN VALUES +.sp +.LP +The *\fB_nv()\fR variants of these functions return the new value of +\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.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 +\fBatomic_add\fR(9F), \fBatomic_bits\fR(9F), \fBatomic_cas\fR(9F), +\fBatomic_dec\fR(9F), \fBatomic_inc\fR(9F), \fBatomic_or\fR(9F), +\fBatomic_swap\fR(9F), \fBmembar_ops\fR(9F), \fBattributes\fR(5), +\fBatomic_ops\fR(3C) +.SH NOTES +.sp +.LP +The *\fB_nv()\fR variants are substantially more expensive on some platforms +than the versions that do not return values. Do not use them unless you need to +know the new value \fBatomically\fR. diff --git a/usr/src/man/man9f/atomic_bits.9f b/usr/src/man/man9f/atomic_bits.9f new file mode 100644 index 0000000000..b76e06e271 --- /dev/null +++ b/usr/src/man/man9f/atomic_bits.9f @@ -0,0 +1,69 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_bits 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +atomic_bits, atomic_set_long_excl, atomic_clear_long_excl \- atomic set and +clear bit operations +.SH SYNOPSIS +.LP +.nf +#include <sys/atomic.h> + +\fBint\fR \fBatomic_set_long_excl\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBuint_t\fR \fIbit\fR); +.fi + +.LP +.nf +\fBint\fR \fBatomic_clear_long_excl\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBuint_t\fR \fIbit\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBatomic_set_long_excl()\fR and \fBatomic_clear_long_excl()\fR functions +perform an exclusive atomic bit set or clear operation on \fItarget\fR. The +value of \fIbit\fR specifies the number of the bit to be modified within +target. Bits are numbered from zero to one less than the maximum number of bits +in a \fBlong\fR. If the value of bit falls outside of this range, the result of +the operation is undefined. +.SH RETURN VALUES +.sp +.LP +The \fBatomic_set_long_excl()\fR and \fBatomic_clear_long_excl()\fR functions +return 0 if \fIbit\fR was successfully set or cleared. They return -1 if +\fIbit\fR was already set or cleared. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.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 +\fBatomic_add\fR(9F), \fBatomic_and\fR(9F), \fBatomic_cas\fR(9F), +\fBatomic_dec\fR(9F), \fBatomic_inc\fR(9F), \fBatomic_or\fR(9F), +\fBatomic_swap\fR(9F), \fBmembar_ops\fR(9F), \fBattributes\fR(5), +\fBatomic_ops\fR(3C) diff --git a/usr/src/man/man9f/atomic_cas.9f b/usr/src/man/man9f/atomic_cas.9f new file mode 100644 index 0000000000..69cacf0464 --- /dev/null +++ b/usr/src/man/man9f/atomic_cas.9f @@ -0,0 +1,109 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_cas 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +atomic_cas, atomic_cas_8, atomic_cas_uchar, atomic_cas_16, atomic_cas_ushort, +atomic_cas_32, atomic_cas_uint, atomic_cas_ulong, atomic_cas_64, atomic_cas_ptr +\- atomic compare and swap operations +.SH SYNOPSIS +.LP +.nf +#include <sys/atomic.h> + +\fBuint8_t\fR \fBatomic_cas_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBuint8_t\fR \fIcmp\fR, \fBuint8_t\fR + \fInewval\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_cas_uchar\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBuchar_t\fR \fIcmp\fR, \fBuchar_t\fR + \fInewval\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_cas_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBuint16_t\fR \fIcmp\fR, \fBuint16_t\fR + \fInewval\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_cas_ushort\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBushort_t\fR \fIcmp\fR, + \fBushort_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_cas_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBuint32_t\fR \fIcmp\fR, \fBuint32_t\fR + \fInewval\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_cas_uint\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBuint_t\fR \fIcmp\fR, \fBuint_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_cas_ulong\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBulong_t\fR \fIcmp\fR, \fBulong_t\fR + \fInewval\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_cas_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBuint64_t\fR \fIcmp\fR, \fBuint64_t\fR + \fInewval\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBatomic_cas_ptr\fR(\fBvolatile void *\fR\fItarget\fR, \fBvoid *\fR\fIcmp\fR, \fBvoid *\fR\fInewval\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable a compare and swap operation to occur atomically. The +value stored in \fItarget\fR is compared with \fIcmp\fR. If these values are +equal, the value stored in \fItarget\fR is replaced with \fInewval\fR. The old +value stored in \fItarget\fR is returned by the function whether or not the +replacement occurred. +.SH RETURN VALUES +.sp +.LP +These functions return the old of *\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.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 +\fBatomic_add\fR(9F), \fBatomic_and\fR(9F), \fBatomic_bits\fR(9F), +\fBatomic_dec\fR(9F), \fBatomic_inc\fR(9F), \fBatomic_or\fR(9F), +\fBatomic_swap\fR(9F), \fBmembar_ops\fR(9F), \fBattributes\fR(5), +\fBatomic_ops\fR(3C) diff --git a/usr/src/man/man9f/atomic_dec.9f b/usr/src/man/man9f/atomic_dec.9f new file mode 100644 index 0000000000..3a4f3dd101 --- /dev/null +++ b/usr/src/man/man9f/atomic_dec.9f @@ -0,0 +1,156 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_dec 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +atomic_dec, atomic_dec_8, atomic_dec_uchar, atomic_dec_16, atomic_dec_ushort, +atomic_dec_32, atomic_dec_uint, atomic_dec_ulong, atomic_dec_64, +atomic_dec_ptr, atomic_dec_8_nv, atomic_dec_uchar_nv, atomic_dec_16_nv, +atomic_dec_ushort_nv, atomic_dec_32_nv, atomic_dec_uint_nv, +atomic_dec_ulong_nv, atomic_dec_64_nv, atomic_dec_ptr_nv \- atomic decrement +operations +.SH SYNOPSIS +.LP +.nf +#include <sys/atomic.h> + +\fBvoid\fR \fBatomic_dec_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_uchar\fR(\fBvolatile uchar_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_ushort\fR(\fBvolatile ushort_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_uint\fR(\fBvolatile uint_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_ulong\fR(\fBvolatile ulong_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_dec_ptr\fR(\fBvolatile void *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint8_t\fR \fBatomic_dec_8_nv\fR(\fBvolatile uint8_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_dec_uchar_nv\fR(\fBvolatile uchar_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_dec_16_nv\fR(\fBvolatile uint16_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_dec_ushort_nv\fR(\fBvolatile ushort_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_dec_32_nv\fR(\fBvolatile uint32_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_dec_uint_nv\fR(\fBvolatile uint_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_dec_ulong_nv\fR(\fBvolatile ulong_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_dec_64_nv\fR(\fBvolatile uint64_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBatomic_dec_ptr_nv\fR(\fBvolatile void *\fR\fItarget\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable the decrementing (by one) of the value stored in +\fItarget\fR to occur in an atomic manner. +.SH RETURN VALUES +.sp +.LP +The *\fB_nv()\fR variants of these functions return the new value of +\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.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 +\fBatomic_add\fR(9F), \fBatomic_and\fR(9F), \fBatomic_bits\fR(9F), +\fBatomic_cas\fR(9F), \fBatomic_inc\fR(9F), \fBatomic_or\fR(9F), +\fBatomic_swap\fR(9F), \fBmembar_ops\fR(9F), \fBattributes\fR(5), +\fBatomic_ops\fR(3C) +.SH NOTES +.sp +.LP +The *\fB_nv()\fR variants are substantially more expensive on some platforms +than the versions that do not return values. Do not use them unless you need to +know the new value atomically (for example, when decrementing a reference count +and checking whether it went to zero). diff --git a/usr/src/man/man9f/atomic_inc.9f b/usr/src/man/man9f/atomic_inc.9f new file mode 100644 index 0000000000..dc6e931707 --- /dev/null +++ b/usr/src/man/man9f/atomic_inc.9f @@ -0,0 +1,155 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_inc 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +atomic_inc, atomic_inc_8, atomic_inc_uchar, atomic_inc_16, atomic_inc_ushort, +atomic_inc_32, atomic_inc_uint, atomic_inc_ulong, atomic_inc_64, +atomic_inc_ptr, atomic_inc_8_nv, atomic_inc_uchar_nv, atomic_inc_16_nv, +atomic_inc_ushort_nv, atomic_inc_32_nv, atomic_inc_uint_nv, +atomic_inc_ulong_nv, atomic_inc_64_nv, atomic_inc_ptr_nv \- atomic inrement +operations +.SH SYNOPSIS +.LP +.nf +#include <sys/atomic.h> + +\fBvoid\fR \fBatomic_inc_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_uchar\fR(\fBvolatile uchar_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_ushort\fR(\fBvolatile ushort_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_uint\fR(\fBvolatile uint_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_ulong\fR(\fBvolatile ulong_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_inc_ptr\fR(\fBvolatile void *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint8_t\fR \fBatomic_inc_8_nv\fR(\fBvolatile uint8_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_inc_uchar_nv\fR(\fBvolatile uchar_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_inc_16_nv\fR(\fBvolatile uint16_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_inc_ushort_nv\fR(\fBvolatile ushort_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_inc_32_nv\fR(\fBvolatile uint32_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_inc_uint_nv\fR(\fBvolatile uint_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_inc_ulong_nv\fR(\fBvolatile ulong_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_inc_64_nv\fR(\fBvolatile uint64_t *\fR\fItarget\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBatomic_inc_ptr_nv\fR(\fBvolatile void *\fR\fItarget\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable the inrementing (by one) of the value stored in +\fItarget\fR to occur in an atomic manner. +.SH RETURN VALUES +.sp +.LP +The *\fB_nv()\fR variants of these functions return the new value of +\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.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 +\fBatomic_add\fR(9F), \fBatomic_and\fR(9F), \fBatomic_bits\fR(9F), +\fBatomic_cas\fR(9F), \fBatomic_dec\fR(9F), \fBatomic_or\fR(9F), +\fBatomic_swap\fR(9F), \fBmembar_ops\fR(9F), \fBattributes\fR(5), +\fBatomic_ops\fR(3C) +.SH NOTES +.sp +.LP +The *\fB_nv()\fR variants are substantially more expensive on some platforms +than the versions that do not return values. Do not use them unless you need to +know the new value \fBatomically\fR. diff --git a/usr/src/man/man9f/atomic_ops.9f b/usr/src/man/man9f/atomic_ops.9f new file mode 100644 index 0000000000..f48e61e0b0 --- /dev/null +++ b/usr/src/man/man9f/atomic_ops.9f @@ -0,0 +1,151 @@ +'\" 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 atomic_ops 9F "28 Mar 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +atomic_ops \- atomic operations +.SH SYNOPSIS +.LP +.nf +#include <\fBsys/atomic.h\fR> +.fi + +.SH DESCRIPTION +.sp +.LP +This collection of functions provides atomic memory operations. There are 8 +different classes of atomic operations: +.sp +.ne 2 +.mk +.na +\fB\fBatomic_add\fR(9F)\fR +.ad +.RS 19n +.rt +These functions provide an atomic addition of a signed value to a variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_and\fR(9F)\fR +.ad +.RS 19n +.rt +These functions provide an atomic logical 'and' of a value to a variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_bits\fR(9F)\fR +.ad +.RS 19n +.rt +These functions provide atomic bit setting and clearing within a variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_cas\fR(9F)\fR +.ad +.RS 19n +.rt +These functions provide an atomic comparison of a value with a variable. If the +comparison is equal, then swap in a new value for the variable, returning the +old value of the variable in either case. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_dec\fR(9F)\fR +.ad +.RS 19n +.rt +These functions provide an atomic decrement on a variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_inc\fR(9F)\fR +.ad +.RS 19n +.rt +These functions provide an atomic increment on a variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_or\fR(9F)\fR +.ad +.RS 19n +.rt +These functions provide an atomic logical 'or' of a value to a variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBatomic_swap\fR(9F)\fR +.ad +.RS 19n +.rt +These functions provide an atomic swap of a value with a variable, returning +the old value of the variable. +.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 +\fBatomic_add\fR(9F), \fBatomic_and\fR(9F), \fBatomic_bits\fR(9F), +\fBatomic_cas\fR(9F), \fBatomic_dec\fR(9F), \fBatomic_inc\fR(9F), +\fBatomic_or\fR(9F), \fBatomic_swap\fR(9F), \fBmembar_ops\fR(9F), +\fBattributes\fR(5) +.SH NOTES +.sp +.LP +Atomic instructions ensure global visibility of atomically-modified variables +on completion. In a relaxed store order system, this does not guarantee that +the visibility of other variables will be synchronized with the completion of +the atomic instruction. If such synchronization is required, memory barrier +instructions must be used. See \fBmembar_ops\fR(9F). +.sp +.LP +Atomic instructions can be expensive. since they require synchronization to +occur at a hardware level. This means they should be used with care to ensure +that forcing hardware level synchronization occurs a minimum number of times. +For example, if you have several variables that need to be incremented as a +group, and each needs to be done atomically, then do so with a mutex lock +protecting all of them being incremented rather than using the +\fBatomic_inc\fR(9F) operation on each of them. diff --git a/usr/src/man/man9f/atomic_or.9f b/usr/src/man/man9f/atomic_or.9f new file mode 100644 index 0000000000..dd4c6455bc --- /dev/null +++ b/usr/src/man/man9f/atomic_or.9f @@ -0,0 +1,142 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_or 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +atomic_or, atomic_or_8, atomic_or_uchar, atomic_or_16, atomic_or_ushort, +atomic_or_32, atomic_or_uint, atomic_or_ulong, atomic_or_64, atomic_or_8_nv, +atomic_or_uchar_nv, atomic_or_16_nv, atomic_or_ushort_nv, atomic_or_32_nv, +atomic_or_uint_nv, atomic_or_ulong_nv, atomic_or_64_nv \- atomic OR operations +.SH SYNOPSIS +.LP +.nf +#include <sys/atomic.h> + +\fBvoid\fR \fBatomic_or_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBuint8_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_uchar\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBuchar_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBuint16_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_ushort\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBushort_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBuint32_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_uint\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBuint_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_ulong\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBulong_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBatomic_or_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBuint64_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint8_t\fR \fBatomic_or_8_nv\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBuint8_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_or_uchar_nv\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBuchar_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_or_16_nv\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBuint16_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_or_ushort_nv\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBushort_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_or_32_nv\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBuint32_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_or_uint_nv\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBuint_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_or_ulong_nv\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBulong_t\fR \fIbits\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_or_64_nv\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBuint64_t\fR \fIbits\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable the bitwise OR of \fIbits\fR to the value stored in +\fItarget\fR to occur in an atomic manner. +.SH RETURN VALUES +.sp +.LP +The *\fB_nv()\fR variants of these functions return the new value of +\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.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 +\fBatomic_add\fR(9F), \fBatomic_and\fR(9F), \fBatomic_bits\fR(9F), +\fBatomic_cas\fR(9F), \fBatomic_dec\fR(9F), \fBatomic_inc\fR(9F), +\fBatomic_swap\fR(9F), \fBmembar_ops\fR(9F), \fBattributes\fR(5), +\fBatomic_ops\fR(3C) +.SH NOTES +.sp +.LP +The *\fB_nv()\fR variants are substantially more expensive on some platforms +than the versions that do not return values. Do not use them unless you need to +know the new value \fBatomically\fR. diff --git a/usr/src/man/man9f/atomic_swap.9f b/usr/src/man/man9f/atomic_swap.9f new file mode 100644 index 0000000000..e4e811b63c --- /dev/null +++ b/usr/src/man/man9f/atomic_swap.9f @@ -0,0 +1,101 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH atomic_swap 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +atomic_swap, atomic_swap_8, atomic_swap_uchar, atomic_swap_16, +atomic_swap_ushort, atomic_swap_32, atomic_swap_uint, atomic_swap_ulong, +atomic_swap_64, atomic_swap_ptr \- atomic swap operations +.SH SYNOPSIS +.LP +.nf +#include <sys/atomic.h> + +\fBuint8_t\fR \fBatomic_swap_8\fR(\fBvolatile uint8_t *\fR\fItarget\fR, \fBuint8_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuchar_t\fR \fBatomic_swap_uchar\fR(\fBvolatile uchar_t *\fR\fItarget\fR, \fBuchar_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBatomic_swap_16\fR(\fBvolatile uint16_t *\fR\fItarget\fR, \fBuint16_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBushort_t\fR \fBatomic_swap_ushort\fR(\fBvolatile ushort_t *\fR\fItarget\fR, \fBushort_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBatomic_swap_32\fR(\fBvolatile uint32_t *\fR\fItarget\fR, \fBuint32_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBatomic_swap_uint\fR(\fBvolatile uint_t *\fR\fItarget\fR, \fBuint_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBulong_t\fR \fBatomic_swap_ulong\fR(\fBvolatile ulong_t *\fR\fItarget\fR, \fBulong_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBatomic_swap_64\fR(\fBvolatile uint64_t *\fR\fItarget\fR, \fBuint64_t\fR \fInewval\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBatomic_swap_ptr\fR(\fBvolatile void *\fR\fItarget\fR, \fBvoid *\fR\fInewval\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions enable a swap operation to occur atomically. The value stored +in \fItarget\fR is replaced with \fInewval\fR. The old value is returned by the +function. +.SH RETURN VALUES +.sp +.LP +These functions return the old of *\fItarget\fR. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.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 +\fBatomic_add\fR(9F), \fBatomic_and\fR(9F), \fBatomic_bits\fR(9F), +\fBatomic_dec\fR(9F), \fBatomic_inc\fR(9F), \fBatomic_or\fR(9F), +\fBatomic_cas\fR(9F), \fBmembar_ops\fR(9F), \fBattributes\fR(5), +\fBatomic_ops\fR(3C) diff --git a/usr/src/man/man9f/backq.9f b/usr/src/man/man9f/backq.9f new file mode 100644 index 0000000000..77282c2a6e --- /dev/null +++ b/usr/src/man/man9f/backq.9f @@ -0,0 +1,65 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH backq 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +backq \- get pointer to the queue behind the current queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBqueue_t *\fR\fBbackq\fR(\fBqueue_t *\fR\fIcq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcq\fR\fR +.ad +.RS 6n +.rt +The pointer to the current queue. \fBqueue_t\fR is an alias for the +\fBqueue\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbackq()\fR function returns a pointer to the queue preceding \fIcq\fR +(the current queue). If \fIcq\fR is a read queue, \fBbackq()\fR returns a +pointer to the queue downstream from \fIcq\fR, unless it is the stream end. If +\fIcq\fR is a write queue, \fBbackq()\fR returns a pointer to the next queue +upstream from \fIcq\fR, unless it is the stream head. +.SH RETURN VALUES +.sp +.LP +If successful, \fBbackq()\fR returns a pointer to the queue preceding the +current queue. Otherwise, it returns \fINULL.\fR +.SH CONTEXT +.sp +.LP +The \fBbackq()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBqueue\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/bcanput.9f b/usr/src/man/man9f/bcanput.9f new file mode 100644 index 0000000000..42cca877ab --- /dev/null +++ b/usr/src/man/man9f/bcanput.9f @@ -0,0 +1,109 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH bcanput 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +bcanput \- test for flow control in specified priority band +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBbcanput\fR(\fBqueue_t *\fR\fIq\fR, \fBunsigned char\fR \fIpri\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 7n +.rt +Pointer to the message queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpri\fR\fR +.ad +.RS 7n +.rt +Message priority. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbcanput()\fR function searches through the stream (starting at \fIq\fR) +until it finds a queue containing a service routine where the message can be +enqueued, or until it reaches the end of the stream. If found, the queue +containing the service routine is tested to see if there is room for a message +of priority \fIpri\fR in the queue. +.sp +.LP +If \fIpri\fR is \fB0\fR, \fBbcanput()\fR is equivalent to a call with +\fBcanput\fR(9F). +.sp +.LP +\fBcanputnext(\fR\fIq\fR\fB)\fR and +\fBbcanputnext(\fR\fIq\fR\fB,\fR\fIpri\fR\fB)\fR should always be used in +preference to \fBcanput(\fR\fIq\fR\fB\(->q_next)\fR and +\fBbcanput(\fR\fIq\fR\fB\(->q_next,\fR\fIpri\fR\fB)\fR respectively. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 5n +.rt +If a message of priority \fIpri\fR can be placed on the queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +If the priority band is full. +.RE + +.SH CONTEXT +.sp +.LP +The \fBbcanput()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBbcanputnext\fR(9F), \fBcanput\fR(9F), \fBcanputnext\fR(9F), \fBputbq\fR(9F), +\fBputnext\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH WARNINGS +.sp +.LP +Drivers are responsible for both testing a queue with \fBbcanput()\fR and +refraining from placing a message on the queue if \fBbcanput()\fR fails. diff --git a/usr/src/man/man9f/bcmp.9f b/usr/src/man/man9f/bcmp.9f new file mode 100644 index 0000000000..505e75b366 --- /dev/null +++ b/usr/src/man/man9f/bcmp.9f @@ -0,0 +1,84 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH bcmp 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +bcmp \- compare two byte arrays +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> + + + +\fBint\fR \fBbcmp\fR(\fBconst void *\fR\fIs1\fR, \fBconst void *\fR\fIs2\fR, \fBsize_t\fR \fIlen\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIs1\fR\fR +.ad +.RS 7n +.rt +Pointer to the first character string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIs2\fR\fR +.ad +.RS 7n +.rt +Pointer to the second character string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 7n +.rt +Number of bytes to be compared. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbcmp()\fR function compares two byte arrays of length \fIlen\fR. +.SH RETURN VALUES +.sp +.LP +The \fBbcmp()\fR function returns \fB0\fR if the arrays are identical, or +\fB1\fR if they are not. +.SH CONTEXT +.sp +.LP +The \fBbcmp()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBstrcmp\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Unlike \fBstrcmp\fR(9F), \fBbcmp()\fR does not terminate when it encounters a +null byte. diff --git a/usr/src/man/man9f/bcopy.9f b/usr/src/man/man9f/bcopy.9f new file mode 100644 index 0000000000..2ac26b9b18 --- /dev/null +++ b/usr/src/man/man9f/bcopy.9f @@ -0,0 +1,127 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH bcopy 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +bcopy \- copy data between address locations in the kernel +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/sunddi.h> + + + + +\fBvoid\fR \fBbcopy\fR(\fBconst void *\fR\fIfrom\fR, \fBvoid *\fR\fIto\fR, \fBsize_t\fR \fIbcount\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIfrom\fR\fR +.ad +.RS 10n +.rt +Source address from which the copy is made. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIto\fR\fR +.ad +.RS 10n +.rt +Destination address to which copy is made. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbcount\fR\fR +.ad +.RS 10n +.rt +The number of bytes moved. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbcopy()\fR function copies \fIbcount\fR bytes from one kernel address to +another. If the input and output addresses overlap, the command executes, but +the results may not be as expected. +.sp +.LP +Note that \fBbcopy()\fR should never be used to move data in or out of a user +buffer, because it has no provision for handling page faults. The user address +space can be swapped out at any time, and \fBbcopy()\fR always assumes that +there will be no paging faults. If \fBbcopy()\fR attempts to access the user +buffer when it is swapped out, the system will panic. It is safe to use +\fBbcopy()\fR to move data within kernel space, since kernel space is never +swapped out. +.SH CONTEXT +.sp +.LP +The \fBbcopy()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRCopying data between address locations in the kernel: +.sp +.LP +An \fBI/O\fR request is made for data stored in a \fBRAM\fR disk. If the \fBI/O +\fRoperation is a read request, the data is copied from the \fBRAM\fR disk to a +buffer (line 8). If it is a write request, the data is copied from a buffer to +the \fBRAM\fR disk (line 15). \fBbcopy()\fR is used since both the \fBRAM\fR +disk and the buffer are part of the kernel address space. + +.sp +.in +2 +.nf + 1 #define RAMDNBLK 1000 /* blocks in the RAM disk */ + 2 #define RAMDBSIZ 512 /* bytes per block */ + 3 char ramdblks[RAMDNBLK][RAMDBSIZ]; /* blocks forming RAM + /* disk + ... + 4 + 5 if (bp->b_flags & B_READ) /* if read request, copy data */ + 6 /* from RAM disk data block */ + 7 /* to system buffer */ + 8 bcopy(&ramdblks[bp->b_blkno][0], bp->b_un.b_addr, + 9 bp->b_bcount); +10 +11 else /* else write request, */ +12 /* copy data from a */ +13 /* system buffer to RAM disk */ +14 /* data block */ +15 bcopy(bp->b_un.b_addr, &ramdblks[bp->b_blkno][0], +16 bp->b_bcount); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBcopyin\fR(9F), \fBcopyout\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +The \fIfrom\fR and \fIto\fR addresses must be within the kernel space. No range +checking is done. If an address outside of the kernel space is selected, the +driver may corrupt the system in an unpredictable way. diff --git a/usr/src/man/man9f/bioclone.9f b/usr/src/man/man9f/bioclone.9f new file mode 100644 index 0000000000..97af083291 --- /dev/null +++ b/usr/src/man/man9f/bioclone.9f @@ -0,0 +1,227 @@ +'\" 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 bioclone 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +bioclone \- clone another buffer +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBstruct buf *\fR\fBbioclone\fR(\fBstruct buf\fR \fI*bp\fR, \fBoff_t\fR \fIoff\fR, \fBsize_t\fR \fIlen\fR, \fBdev_t\fR \fIdev\fR, + \fBdaddr_t\fR \fIblkno\fR, \fBint (\fR\fI*iodone\fR) (struct buf \fI*\fR), \fBstruct buf\fR \fI*bp_mem\fR, + \fBint\fR \fIsleepflag\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 13n +.rt +Pointer to the \fBbuf\fR(9S) structure describing the original \fBI/O\fR +request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoff\fR\fR +.ad +.RS 13n +.rt +Offset within original \fBI/O\fR request where new \fBI/O\fR request should +start. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 13n +.rt +Length of the \fBI/O \fRrequest. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 13n +.rt +Device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIblkno\fR\fR +.ad +.RS 13n +.rt +Block number on device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIiodone\fR\fR +.ad +.RS 13n +.rt +Specific \fBbiodone\fR(9F) routine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbp_mem\fR\fR +.ad +.RS 13n +.rt +Pointer to a buffer structure to be filled in or \fBNULL. \fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsleepflag\fR\fR +.ad +.RS 13n +.rt +Determines whether caller can sleep for memory. Possible flags are +\fBKM_SLEEP\fR to allow sleeping until memory is available, or \fBKM_NOSLEEP\fR +to return \fINULL\fR immediately if memory is not available. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbioclone()\fR function returns an initialized buffer to perform +\fBI/O\fR to a portion of another buffer. The new buffer will be set up to +perform \fBI/O\fR to the range within the original \fBI/O\fR request specified +by the parameters \fIoff\fR and \fIlen\fR. An offset \fB0\fR starts the new +\fBI/O\fR request at the same address as the original request. \fIoff\fR + +\fIlen\fR must not exceed \fIb_bcount,\fR the length of the original request. +The device number \fIdev\fR specifies the device to which the buffer is to +perform \fBI/O\fR. \fIblkno\fR is the block number on device. It will be +assigned to the \fIb_blkno\fR field of the cloned buffer structure. +\fIiodone\fR lets the driver identify a specific \fBbiodone\fR(9F) routine to +be called by the driver when the \fBI/O\fR is complete. \fIbp_mem\fR determines +from where the space for the buffer should be allocated. If \fIbp_mem\fR is +\fBNULL\fR, \fBbioclone()\fR will allocate a new buffer using +\fBgetrbuf\fR(9F). If \fIsleepflag\fR is set to \fBKM_SLEEP\fR, the driver may +sleep until space is freed up. If \fIsleepflag\fR is set to \fBKM_NOSLEEP\fR, +the driver will not sleep. In either case, a pointer to the allocated space is +returned or \fINULL\fR to indicate that no space was available. After the +transfer is completed, the buffer has to be freed using \fBfreerbuf\fR(9F). If +\fIbp_mem\fR is not \fINULL\fR, it will be used as the space for the buffer +structure. The driver has to ensure that \fIbp_mem\fR is initialized properly +either using \fBgetrbuf\fR(9F) or \fBbioinit\fR(9F). +.sp +.LP +If the original buffer is mapped into the kernel virtual address space using +\fBbp_mapin\fR(9F) before calling \fBbioclone()\fR, a clone buffer will share +the kernel mapping of the original buffer. An additional \fBbp_mapin()\fR to +get a kernel mapping for the clone buffer is not necessary. +.sp +.LP +The driver has to ensure that the original buffer is not freed while any of the +clone buffers is still performing \fBI/O\fR. The \fBbiodone()\fR function has +to be called on all clone buffers \fBbefore\fR it is called on the original +buffer. +.SH RETURN VALUES +.sp +.LP +The \fBbioclone()\fR function returns a pointer to the initialized buffer +header, or \fBNULL\fR if no space is available. +.SH CONTEXT +.sp +.LP +The \fBbioclone()\fR function can be called from user, interrup, or interrupt +context. Drivers must not allow \fBbioclone()\fR to sleep if called from an +interrupt routine. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBbioclone()\fR for Disk Striping +.sp +.LP +A device driver can use \fBbioclone()\fR for disk striping. For each disk in +the stripe, a clone buffer is created which performs \fBI/O\fR to a portion of +the original buffer. + +.sp +.in +2 +.nf +static int +stripe_strategy(struct buf *bp) +{ + ... + bp_orig = bp; + bp_1 = bioclone(bp_orig, 0, size_1, dev_1, blkno_1, + stripe_done, NULL, KM_SLEEP); + fragment++; + ... + bp_n = bioclone(bp_orig, offset_n, size_n, dev_n, + blkno_n, stripe_done, NULL, KM_SLEEP); + fragment++; + /* submit bp_1 ... bp_n to device */ + xxstrategy(bp_x); + return (0); +} + +static uint_t +xxintr(caddr_t arg) +{ + ... + /* + * get bp of completed subrequest. biodone(9F) will + * call stripe_done() + */ + biodone(bp); + return (0); +} + +static int +stripe_done(struct buf *bp) +{ + ... + freerbuf(bp); + fragment--; + if (fragment == 0) { + /* get bp_orig */ + biodone(bp_orig); + } + return (0); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBbiodone\fR(9F), \fBbp_mapin\fR(9F), \fBfreerbuf\fR(9F), \fBgetrbuf\fR(9F), +\fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/biodone.9f b/usr/src/man/man9f/biodone.9f new file mode 100644 index 0000000000..4725f53e5d --- /dev/null +++ b/usr/src/man/man9f/biodone.9f @@ -0,0 +1,129 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH biodone 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +biodone \- release buffer after buffer I/O transfer and notify blocked threads +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/buf.h> + + + +\fBvoid\fR \fBbiodone\fR(\fBstruct buf *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBbuf\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbiodone()\fR function notifies blocked processes waiting for the\fB +I/O\fR to complete, sets the \fBB_DONE\fR flag in the \fBb_flags\fR field of +the \fBbuf\fR(9S) structure, and releases the buffer if the \fBI/O\fR is +asynchronous. \fBbiodone()\fR is called by either the driver interrupt or +\fBstrategy\fR(9E) routines when a buffer \fBI/O\fR request is complete. +.sp +.LP +The \fBbiodone()\fR function provides the capability to call a completion +routine if \fIbp\fR describes a kernel buffer. The address of the routine is +specified in the \fBb_iodone\fR field of the \fBbuf\fR(9S) structure. If such a +routine is specified, \fBbiodone()\fR calls it and returns without performing +any other actions. Otherwise, it performs the steps above. +.SH CONTEXT +.sp +.LP +The \fBbiodone()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +Generally, the first validation test performed by any block device +\fBstrategy\fR(9E) routine is a check for an end-of-file (\fBEOF\fR) condition. +The \fBstrategy\fR(9E) routine is responsible for determining an \fBEOF\fR +condition when the device is accessed directly. If a \fBread\fR(2) request is +made for one block beyond the limits of the device (line 10), it will report an +\fBEOF\fR condition. Otherwise, if the request is outside the limits of the +device, the routine will report an error condition. In either case, report the +\fBI/O\fR operation as complete (line 27). +.sp +.in +2 +.nf + 1 #define RAMDNBLK 1000 /* Number of blocks in RAM disk */ + 2 #define RAMDBSIZ 512 /* Number of bytes per block */ + 3 char ramdblks[RAMDNBLK][RAMDBSIZ]; /* Array containing RAM disk */ + 4 + 5 static int + 6 ramdstrategy(struct buf *bp) + 7 { + 8 daddr_t blkno = bp->b_blkno; /* get block number */ + 9 +10 if ((blkno < 0) || (blkno >= RAMDNBLK)) { +11 /* +12 * If requested block is outside RAM disk +13 * limits, test for EOF which could result +14 * from a direct (physio) request. +15 */ +16 if ((blkno == RAMDNBLK) && (bp->b_flags & B_READ)) { +17 /* +18 * If read is for block beyond RAM disk +19 * limits, mark EOF condition. +20 */ +21 bp->b_resid = bp->b_bcount; /* compute return value */ +22 +23 } else { /* I/O attempt is beyond */ +24 bp->b_error = ENXIO; /* limits of RAM disk */ +25 bp->b_flags |= B_ERROR; /* return error */ +26 } +27 biodone(bp); /* mark I/O complete (B_DONE) */ +28 /* +29 * Wake any processes awaiting this I/O +30 * or release buffer for asynchronous +31 * (B_ASYNC) request. +32 */ +33 return (0); +34 } + .\|.\|.\| +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBread\fR(2), \fBstrategy\fR(9E), \fBbiowait\fR(9F), \fBddi_add_intr\fR(9F), +\fBdelay\fR(9F), \fBtimeout\fR(9F), \fBuntimeout\fR(9F), \fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +After calling \fBbiodone()\fR, \fIbp\fR is no longer available to be referred +to by the driver. If the driver makes any reference to \fIbp\fR after calling +\fBbiodone()\fR, a panic may result. +.SH NOTES +.sp +.LP +Drivers that use the \fBb_iodone\fR field of the \fBbuf\fR(9S) structure to +specify a substitute completion routine should save the value of \fBb_iodone\fR +before changing it, and then restore the old value before calling +\fBbiodone()\fR to release the buffer. diff --git a/usr/src/man/man9f/bioerror.9f b/usr/src/man/man9f/bioerror.9f new file mode 100644 index 0000000000..50f326c73f --- /dev/null +++ b/usr/src/man/man9f/bioerror.9f @@ -0,0 +1,65 @@ +'\" te +.\" Copyright (c) 1994, 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 bioerror 9F "26 May 1994" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +bioerror \- indicate error in buffer header +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/buf.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBbioerror\fR(\fBstruct buf *\fR\fIbp\fR, \fBint\fR \fIerror\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR \fR +.ad +.RS 10n +.rt +Pointer to the \fBbuf\fR(9S) structure describing the transfer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerror\fR \fR +.ad +.RS 10n +.rt +Error number to be set, or zero to clear an error indication. +.RE + +.SH DESCRIPTION +.sp +.LP +If \fIerror\fR is non-zero, \fBbioerror()\fR indicates an error has occured in +the \fBbuf\fR(9S) structure. A subsequent call to \fBgeterror\fR(9F) will +return \fIerror\fR. +.sp +.LP +If \fIerror\fR is \fB0\fR, the error indication is cleared and a subsequent +call to \fBgeterror\fR(9F) will return \fB0\fR. +.SH CONTEXT +.sp +.LP +\fBbioerror()\fR can be called from any context. +.SH SEE ALSO +.sp +.LP +\fBstrategy\fR(9E), \fBgeterror\fR(9F), \fBgetrbuf\fR(9F), \fBbuf\fR(9S) diff --git a/usr/src/man/man9f/biofini.9f b/usr/src/man/man9f/biofini.9f new file mode 100644 index 0000000000..b652099bd7 --- /dev/null +++ b/usr/src/man/man9f/biofini.9f @@ -0,0 +1,68 @@ +'\" 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 biofini 9F "20 Nov 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +biofini \- uninitialize a buffer structure +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBvoid\fR \fBbiofini\fR(\fBstruct buf *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +Pointer to the buffer header structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbiofini()\fR function uninitializes a \fBbuf\fR(9S) structure. If a +buffer structure has been allocated and initialized using \fBkmem_alloc\fR(9F) +and \fBbioinit\fR(9F) it needs to be uninitialized using \fBbiofini()\fR before +calling \fBkmem_free\fR(9F). It is not necessary to call \fBbiofini()\fR before +freeing a buffer structure using \fBfreerbuf\fR(9F) because \fBfreerbuf()\fR +will call \fBbiofini()\fR directly. +.SH CONTEXT +.sp +.LP +The \fBbiofini()\fR function can be called from any context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBbiofini()\fR +.sp +.in +2 +.nf +struct buf *bp = kmem_alloc(biosize(), KM_SLEEP); +bioinit(bp); +/* use buffer */ +biofini(bp); +kmem_free(bp, biosize()); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBbioinit\fR(9F), \fBbioreset\fR(9F), \fBbiosize\fR(9F), \fBfreerbuf\fR(9F), +\fBkmem_alloc\fR(9F), \fBkmem_free\fR(9F), \fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/bioinit.9f b/usr/src/man/man9f/bioinit.9f new file mode 100644 index 0000000000..a908500be6 --- /dev/null +++ b/usr/src/man/man9f/bioinit.9f @@ -0,0 +1,66 @@ +'\" 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 bioinit 9F "20 Nov 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +bioinit \- initialize a buffer structure +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBvoid\fR \fBbioinit\fR(\fBstruct buf *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +Pointer to the buffer header structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbioinit()\fR function initializes a \fBbuf\fR(9S) structure. A buffer +structure contains state information which has to be initialized if the memory +for the buffer was allocated using \fBkmem_alloc\fR(9F). This is not necessary +for a buffer allocated using \fBgetrbuf\fR(9F) because \fBgetrbuf()\fR will +call \fBbioinit()\fR directly. +.SH CONTEXT +.sp +.LP +The \fBbioinit()\fR function can be called from any context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBbioinit()\fR +.sp +.in +2 +.nf + +struct buf *bp = kmem_alloc(biosize(), KM_SLEEP); +bioinit(bp); +/* use buffer */ +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBbiofini\fR(9F), \fBbioreset\fR(9F), \fBbiosize\fR(9F), \fBgetrbuf\fR(9F), +\fBkmem_alloc\fR(9F), \fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/biomodified.9f b/usr/src/man/man9f/biomodified.9f new file mode 100644 index 0000000000..361a2084cf --- /dev/null +++ b/usr/src/man/man9f/biomodified.9f @@ -0,0 +1,103 @@ +'\" 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 biomodified 9F "20 Nov 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +biomodified \- check if a buffer is modified +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBbiomodified\fR(\fBstruct buf *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +Pointer to the buffer header structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbiomodified()\fR function returns status to indicate if the buffer is +modified. The \fBbiomodified()\fR function is only supported for paged- \fBI/O +\fRrequest, that is the \fBB_PAGEIO\fRflag must be set in the \fIb_flags\fR +field of the \fBbuf\fR(9S) structure. The \fBbiomodified()\fR function will +check the memory pages associated with this buffer whether the Virtual Memory +system's modification bit is set. If at least one of these pages is modified, +the buffer is indicated as modified. A filesystem will mark the pages +\fBunmodified\fR when it writes the pages to the backing store. The +\fBbiomodified()\fR function can be used to detect any modifications to the +memory pages while \fBI/O \fRis in progress. +.sp +.LP +A device driver can use \fBbiomodified()\fR for disk mirroring. An application +is allowed to mmap a file which can reside on a disk which is mirrored by +multiple submirrors. If the file system writes the file to the backing store, +it is written to all submirrors in parallel. It must be ensured that the +copies on all submirrors are identical. The \fBbiomodified()\fR function can be +used in the device driver to detect any modifications to the buffer by the +user program during the time the buffer is written to multiple submirrors. +.SH RETURN VALUES +.sp +.LP +The \fBbiomodified()\fR function returns the following values: +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 6n +.rt +Buffer is modified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 6n +.rt +Buffer is not modified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB-1\fR\fR +.ad +.RS 6n +.rt +Buffer is not used for paged \fBI/O\fR request. +.RE + +.SH CONTEXT +.sp +.LP +\fBbiomodified()\fR can be called from any context. +.SH SEE ALSO +.sp +.LP +\fBbp_mapin\fR(9F), \fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/bioreset.9f b/usr/src/man/man9f/bioreset.9f new file mode 100644 index 0000000000..401b8d4c30 --- /dev/null +++ b/usr/src/man/man9f/bioreset.9f @@ -0,0 +1,56 @@ +'\" 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 bioreset 9F "15 Nov 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +bioreset \- reuse a private buffer header after I/O is complete +.SH SYNOPSIS +.LP +.nf +#include <sys/buf.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBbioreset\fR(\fBstruct buf *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.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 +\fBbioreset()\fR is used by drivers that allocate private buffers with +\fBgetrbuf\fR(9F) or \fBkmem_alloc\fR(9F) and want to reuse them in multiple +transfers before freeing them with \fBfreerbuf\fR(9F) or \fBkmem_free\fR(9F). +\fBbioreset()\fR resets the buffer header to the state it had when initially +allocated by \fBgetrbuf()\fR or initialized by \fBbioinit\fR(9F). +.SH CONTEXT +.sp +.LP +\fBbioreset()\fR can be called from any context. +.SH SEE ALSO +.sp +.LP +\fBstrategy\fR(9E), \fBbioinit\fR(9F), \fBbiofini\fR(9F), \fBfreerbuf\fR(9F), +\fBgetrbuf\fR(9F), \fBkmem_alloc\fR(9F), \fBkmem_free\fR(9F), \fBbuf\fR(9S) +.SH NOTES +.sp +.LP +\fIbp\fR must not describe a transfer in progress. diff --git a/usr/src/man/man9f/biosize.9f b/usr/src/man/man9f/biosize.9f new file mode 100644 index 0000000000..b1b9c5295a --- /dev/null +++ b/usr/src/man/man9f/biosize.9f @@ -0,0 +1,40 @@ +'\" 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 biosize 9F "20 Nov 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +biosize \- returns size of a buffer structure +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBsize_t\fR \fBbiosize\fR(void) +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBbiosize()\fR function returns the size in bytes of the \fBbuf\fR(9S) +structure. The \fBbiosize()\fR function is used by drivers in combination with +\fBkmem_alloc\fR(9F) and \fBbioinit\fR(9F) to allocate buffer structures +embedded in other data structures. +.SH CONTEXT +.sp +.LP +The \fBbiosize()\fR function can be called from any context. +.SH SEE ALSO +.sp +.LP +\fBbiofini\fR(9F), \fBbioinit\fR(9F), \fBgetrbuf\fR(9F), \fBkmem_alloc\fR(9F), +\fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/biowait.9f b/usr/src/man/man9f/biowait.9f new file mode 100644 index 0000000000..3ef6243a42 --- /dev/null +++ b/usr/src/man/man9f/biowait.9f @@ -0,0 +1,82 @@ +'\" 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 biowait 9F "11 Apr 1991" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +biowait \- suspend processes pending completion of block I/O +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/buf.h> + + + +\fBint\fR \fBbiowait\fR(\fBstruct buf *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR \fR +.ad +.RS 7n +.rt +Pointer to the \fBbuf\fR structure describing the transfer. +.RE + +.SH DESCRIPTION +.sp +.LP +Drivers allocating their own \fBbuf\fR structures with \fBgetrbuf\fR(9F) can +use the \fBbiowait()\fR function to suspend the current thread and wait for +completion of the transfer. +.sp +.LP +Drivers must call \fBbiodone\fR(9F) when the transfer is complete to notify +the thread blocked by \fBbiowait()\fR. \fBbiodone()\fR is usually called in the +interrupt routine. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB0\fR \fR +.ad +.RS 12n +.rt +Upon success +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnon-zero\fR\fR +.ad +.RS 12n +.rt +Upon \fBI/O\fR failure. \fBbiowait()\fR calls \fBgeterror\fR(9F) to retrieve +the error number which it returns. +.RE + +.SH CONTEXT +.sp +.LP +\fBbiowait()\fR can be called from user context only. +.SH SEE ALSO +.sp +.LP +\fBbiodone\fR(9F), \fBgeterror\fR(9F), \fBgetrbuf\fR(9F), \fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/bp_copyin.9f b/usr/src/man/man9f/bp_copyin.9f new file mode 100644 index 0000000000..7e970b525a --- /dev/null +++ b/usr/src/man/man9f/bp_copyin.9f @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH bp_copyin 9F "16 Oct 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +bp_copyin \- copy from a buf(9S) into a driver buffer +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/buf.h> + + + + +\fBint\fR \fBbp_copyin\fR(\fBstruct buf *\fR\fIbp\fR, \fBvoid *\fR\fIdriverbuf\fR, \fBoffset_t\fR \fIoffset\fR, + \fBsize_t\fR \fIsize\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 13n +.rt +Pointer to the buffer header structure to copy from. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdriverbuf\fR\fR +.ad +.RS 13n +.rt +Driver buffer to copy to. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR\fR +.ad +.RS 13n +.rt +Offset into \fIbp\fR where to start copying. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 13n +.rt +Size of copy. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbp_copyin()\fR function copies \fIsize\fR bytes into the memory +associated with \fIbp\fR to the destination driver buffer \fIdriverbuf\fR. The +\fIoffset\fR only applies to \fIbp\fR. +.SH RETURN VALUES +.sp +.LP +Under normal conditions, 0 is returned to indicate a successful copy. +Otherwise, -1 is returned if \fIbp\fR references invalid pages. +.SH CONTEXT +.sp +.LP +The \fBbp_copyin()\fR function can be called from user or kernel context only. +.SH SEE ALSO +.sp +.LP +\fBbp_copyout\fR(9F), \fBbp_mapin\fR(9F), \fBbp_mapout\fR(9F), +\fBddi_copyout\fR(9F), \fBbuf\fR(9S) diff --git a/usr/src/man/man9f/bp_copyout.9f b/usr/src/man/man9f/bp_copyout.9f new file mode 100644 index 0000000000..f7464e5126 --- /dev/null +++ b/usr/src/man/man9f/bp_copyout.9f @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH bp_copyout 9F "16 Oct 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +bp_copyout \- copy from a driver buffer into a buf(9S) +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/buf.h> + + + + +\fBint\fR \fBbp_copyout\fR(\fBvoid *\fR\fIdriverbuf\fR, \fBstruct buf *\fR\fIbp\fR, \fBoffset_t\fR \fIoffset\fR, + \fBsize_t\fR \fIsize\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 13n +.rt +Pointer to the buffer header structure to copy to. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdriverbuf\fR\fR +.ad +.RS 13n +.rt +Driver buffer to copy from. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR\fR +.ad +.RS 13n +.rt +Offset into \fIbp\fR where to start copying. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 13n +.rt +Size of copy. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbp_copyout()\fR function copies \fIsize\fR bytes starting from the +driver buffer \fIdriverbuf\fR to \fIoffset\fR bytes into the memory associated +with \fIbp\fR. The \fIoffset\fR only applies to \fIbp\fR. +.SH RETURN VALUES +.sp +.LP +Under normal conditions, 0 is returned to indicate a successful copy. +Otherwise, -1 is returned if \fIbp\fR references invalid pages. +.SH CONTEXT +.sp +.LP +The \fBbp_copyout()\fR function can be called from user or kernel context only. +.SH SEE ALSO +.sp +.LP +\fBbp_copyin\fR(9F), \fBbp_mapin\fR(9F), \fBbp_mapout\fR(9F), +\fBddi_copyout\fR(9F), \fBbuf\fR(9S) diff --git a/usr/src/man/man9f/bp_mapin.9f b/usr/src/man/man9f/bp_mapin.9f new file mode 100644 index 0000000000..78f0de23d8 --- /dev/null +++ b/usr/src/man/man9f/bp_mapin.9f @@ -0,0 +1,60 @@ +'\" 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 bp_mapin 9F "13 Sep 1992" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +bp_mapin \- allocate virtual address space +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/buf.h> + + + +\fBvoid\fR \fBbp_mapin\fR(\fBstruct buf *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR \fR +.ad +.RS 7n +.rt +Pointer to the buffer header structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBbp_mapin()\fR is used to map virtual address space to a page list maintained +by the buffer header during a paged- \fBI/O \fRrequest. \fBbp_mapin()\fR +allocates system virtual address space, maps that space to the page list, and +returns the starting address of the space in the \fBbp->b_un.b_addr\fR field of +the \fBbuf\fR(9S) structure. Virtual address space is then deallocated using +the \fBbp_mapout\fR(9F) function. +.sp +.LP +If a null page list is encountered, \fBbp_mapin()\fR returns without allocating +space and no mapping is performed. +.SH CONTEXT +.sp +.LP +\fBbp_mapin()\fR can be called from user and kernel contexts. +.SH SEE ALSO +.sp +.LP +\fBbp_mapout\fR(9F), \fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/bp_mapout.9f b/usr/src/man/man9f/bp_mapout.9f new file mode 100644 index 0000000000..cc038777f9 --- /dev/null +++ b/usr/src/man/man9f/bp_mapout.9f @@ -0,0 +1,57 @@ +'\" 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 bp_mapout 9F "15 Nov 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +bp_mapout \- deallocate virtual address space +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/buf.h> + + + +\fBvoid\fR \fBbp_mapout\fR(\fBstruct buf *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR \fR +.ad +.RS 7n +.rt +Pointer to the buffer header structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBbp_mapout()\fR deallocates system virtual address space allocated by a +previous call to \fBbp_mapin\fR(9F)\fB\&.\fR\fBbp_mapout()\fR should only be +called on buffers which have been allocated and are owned by the device driver. +It must not be called on buffers passed to the driver through the +\fBstrategy\fR(9E) entry point (for example a filesystem). Because +\fBbp_mapin\fR(9F) does not keep a reference count, \fBbp_mapout()\fR will wipe +out any kernel mapping that a layer above the device driver might rely on. +.SH CONTEXT +.sp +.LP +\fBbp_mapout()\fR can be called from user context only. +.SH SEE ALSO +.sp +.LP +\fBstrategy\fR(9E), \fBbp_mapin\fR(9F), \fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/btop.9f b/usr/src/man/man9f/btop.9f new file mode 100644 index 0000000000..bce83c6ef5 --- /dev/null +++ b/usr/src/man/man9f/btop.9f @@ -0,0 +1,60 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH btop 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +btop \- convert size in bytes to size in pages (round down) +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> + + + +\fBunsigned long\fR \fBbtop\fR(\fBunsigned long\fR \fInumbytes\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInumbytes\fR\fR +.ad +.RS 12n +.rt +Number of bytes. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbtop()\fR function returns the number of memory pages that are contained +in the specified number of bytes, with downward rounding in the case that the +byte count is not a page multiple. For example, if the page size is \fB2048\fR, +then \fBbtop(4096)\fR returns \fB2\fR, and \fBbtop(4097)\fR returns \fB2\fR as +well. \fBbtop(0)\fR returns \fB0\fR. +.SH RETURN VALUES +.sp +.LP +The return value is always the number of pages. There are no invalid input +values, and therefore no error return values. +.SH CONTEXT +.sp +.LP +The \fBbtop()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBbtopr\fR(9F), \fBddi_btop\fR(9F), \fBptob\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/btopr.9f b/usr/src/man/man9f/btopr.9f new file mode 100644 index 0000000000..c1e5e3cff8 --- /dev/null +++ b/usr/src/man/man9f/btopr.9f @@ -0,0 +1,59 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH btopr 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +btopr \- convert size in bytes to size in pages (round up) +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> + + + +\fBunsigned long\fR \fBbtopr\fR(\fBunsigned long\fR \fInumbytes\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInumbytes\fR\fR +.ad +.RS 12n +.rt +Number of bytes. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbtopr()\fR function returns the number of memory pages contained in the +specified number of bytes memory, rounded up to the next whole page. For +example, if the page size is 2048, then \fBbtopr(4096)\fR returns \fB2\fR, and +\fBbtopr(4097)\fR returns \fB3\fR. +.SH RETURN VALUES +.sp +.LP +The return value is always the number of pages. There are no invalid input +values, and therefore no error return values. +.SH CONTEXT +.sp +.LP +The \fBbtopr()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBbtop\fR(9F), \fBddi_btopr\fR(9F), \fBptob\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/bufcall.9f b/usr/src/man/man9f/bufcall.9f new file mode 100644 index 0000000000..b4fdb57918 --- /dev/null +++ b/usr/src/man/man9f/bufcall.9f @@ -0,0 +1,198 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH bufcall 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +bufcall \- call a function when a buffer becomes available +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/stream.h> + + + +\fBbufcall_id_t\fR \fBbufcall\fR(\fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR, \fBvoid \fR\fI*func\fRvoid \fI*arg\fR, + \fBvoid\fR \fI*arg\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 8n +.rt +Number of bytes required for the buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpri\fR\fR +.ad +.RS 8n +.rt +Priority of the \fBallocb\fR(9F) allocation request (not used). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfunc\fR\fR +.ad +.RS 8n +.rt +Function or driver routine to be called when a buffer becomes available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 8n +.rt +Argument to the function to be called when a buffer becomes available. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbufcall()\fR function serves as a \fBtimeout\fR(9F) call of +indeterminate length. When a buffer allocation request fails, \fBbufcall()\fR +can be used to schedule the routine \fIfunc\fR, to be called with the argument +\fIarg\fR when a buffer becomes available. \fIfunc\fR may call \fBallocb()\fR +or it may do something else. +.SH RETURN VALUES +.sp +.LP +If successful, \fBbufcall()\fR returns a \fBbufcall\fR \fBID\fR that can be +used in a call to \fBunbufcall()\fR to cancel the request. If the +\fBbufcall()\fR scheduling fails, \fIfunc\fR is never called and \fB0\fR is +returned. +.SH CONTEXT +.sp +.LP +The \fBbufcall()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRCalling a function when a buffer becomes available: +.sp +.LP +The purpose of this \fBsrv\fR(9E) service routine is to add a header to all +\fBM_DATA\fR messages. Service routines must process all messages on their +queues before returning, or arrange to be rescheduled + +.sp +.LP +While there are messages to be processed (line 13), check to see if it is a +high priority message or a normal priority message that can be sent on (line +14). Normal priority message that cannot be sent are put back on the message +queue (line 34). If the message was a high priority one, or if it was normal +priority and \fBcanputnext\fR(9F) succeeded, then send all but \fBM_DATA\fR +messages to the next module with \fBputnext\fR(9F) (line 16). + +.sp +.LP +For \fBM_DATA\fR messages, try to allocate a buffer large enough to hold the +header (line 18). If no such buffer is available, the service routine must be +rescheduled for a time when a buffer is available. The original message is put +back on the queue (line 20) and \fBbufcall\fR (line 21) is used to attempt the +rescheduling. It will succeed if the rescheduling succeeds, indicating that +qenable will be called subsequently with the argument \fIq\fR once a buffer of +the specified size (\fBsizeof (struct hdr)\fR) becomes available. If it does, +\fBqenable\fR(9F) will put \fIq\fR on the list of queues to have their service +routines called. If \fBbufcall()\fR fails, \fBtimeout\fR(9F) (line 22) is used +to try again in about a half second. + +.sp +.LP +If the buffer allocation was successful, initialize the header (lines 25-28), +make the message type \fBM_PROTO\fR (line 29), link the \fBM_DATA\fR message to +it (line 30), and pass it on (line 31). + +.sp +.LP +Note that this example ignores the bookkeeping needed to handle \fBbufcall()\fR +and \fBtimeout\fR(9F) cancellation for ones that are still outstanding at close +time. + +.sp +.in +2 +.nf + \fB1 struct hdr { + 2 unsigned int h_size; + 3 int h_version; + 4 }; + 5 + 6 void xxxsrv(q) + 7 queue_t *q; + 8 { + 9 mblk_t *bp; +10 mblk_t *mp; +11 struct hdr *hp; +12 +13 while ((mp = getq(q)) != NULL) { /* get next message */ +14 if (mp->b_datap->db_type >= QPCTL || /* if high priority */ + canputnext(q)) { /* normal & can be passed */ +15 if (mp->b_datap->db_type != M_DATA) +16 putnext(q, mp); /* send all but M_DATA */ +17 else { +18 bp = allocb(sizeof(struct hdr), BPRI_LO); +19 if (bp == NULL) { /* if unsuccessful */ +20 putbq(q, mp); /* put it back */ +21 if (!bufcall(sizeof(struct hdr), BPRI_LO, + qenable, q)) /* try to reschedule */ +22 timeout(qenable, q, drv_usectohz(500000)); +23 return (0); +24 } +25 hp = (struct hdr *)bp->b_wptr; +26 hp->h_size = msgdsize(mp); /* initialize header */ +27 hp->h_version = 1; +28 bp->b_wptr += sizeof(struct hdr); +29 bp->b_datap->db_type = M_PROTO;/* make M_PROTO */ +30 bp->b_cont = mp; /* link it */ +31 putnext(q, bp); /* pass it on */ +32 } +33 } else { /* normal priority, canputnext failed */ +34 putbq(q, mp); /* put back on the message queue */ +35 return (0); +36 } +37 } + return (0); +38 }\fR +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBsrv\fR(9E), \fBallocb\fR(9F), \fBcanputnext\fR(9F), \fBesballoc\fR(9F), +\fBesbbcall\fR(9F), \fBputnext\fR(9F), \fBqenable\fR(9F), \fBtestb\fR(9F), +\fBtimeout\fR(9F), \fBunbufcall\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH WARNINGS +.sp +.LP +Even when \fIfunc\fR is called by \fBbufcall()\fR, \fBallocb\fR(9F) can fail if +another module or driver had allocated the memory before \fIfunc\fR was able to +call \fBallocb\fR(9F). diff --git a/usr/src/man/man9f/bzero.9f b/usr/src/man/man9f/bzero.9f new file mode 100644 index 0000000000..713f1c4331 --- /dev/null +++ b/usr/src/man/man9f/bzero.9f @@ -0,0 +1,70 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH bzero 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +bzero \- clear memory for a given number of bytes +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBbzero\fR(\fBvoid *\fR\fIaddr\fR, \fBsize_t\fR \fIbytes\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR\fR +.ad +.RS 9n +.rt +Starting virtual address of memory to be cleared. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbytes\fR\fR +.ad +.RS 9n +.rt +The number of bytes to clear starting at \fIaddr\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBbzero()\fR function clears a contiguous portion of memory by filling it +with zeros. +.SH CONTEXT +.sp +.LP +The \fBbzero()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBbcopy\fR(9F), \fBclrbuf\fR(9F), \fBkmem_zalloc\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +The address range specified must be within the kernel space. No range checking +is done. If an address outside of the kernel space is selected, the driver may +corrupt the system in an unpredictable way. diff --git a/usr/src/man/man9f/canput.9f b/usr/src/man/man9f/canput.9f new file mode 100644 index 0000000000..e81f323971 --- /dev/null +++ b/usr/src/man/man9f/canput.9f @@ -0,0 +1,91 @@ +'\" 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 canput 9F "11 Apr 1991" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +canput \- test for room in a message queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBcanput\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR \fR +.ad +.RS 6n +.rt +Pointer to the message queue. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBcanput()\fR searches through the stream (starting at \fIq\fR) until it finds +a queue containing a service routine where the message can be enqueued, or +until it reaches the end of the stream. If found, the queue containing the +service routine is tested to see if there is room for a message in the queue. +.sp +.LP +\fBcanputnext(\fR\fIq\fR\fB)\fR and \fBbcanputnext(\fR\fIq\fR\fB,\fR\fI +pri\fR\fB)\fR should always be used in preference to +\fBcanput(\fR\fIq\fR\fB\(->q_next)\fR and +\fBbcanput(\fR\fIq\fR\fB\(->q_next,\fR\fI pri\fR\fB)\fR respectively. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB1\fR \fR +.ad +.RS 6n +.rt +If the message queue is not full. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR \fR +.ad +.RS 6n +.rt +If the queue is full. +.RE + +.SH CONTEXT +.sp +.LP +\fBcanput()\fR can be called from user or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBbcanput\fR(9F), \fBbcanputnext\fR(9F), \fBcanputnext\fR(9F), +\fBputbq\fR(9F), \fBputnext\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP + \fISTREAMS Programming Guide\fR +.SH WARNINGS +.sp +.LP +Drivers are responsible for both testing a queue with \fBcanput()\fR and +refraining from placing a message on the queue if \fBcanput()\fR fails. diff --git a/usr/src/man/man9f/clrbuf.9f b/usr/src/man/man9f/clrbuf.9f new file mode 100644 index 0000000000..184419e9b6 --- /dev/null +++ b/usr/src/man/man9f/clrbuf.9f @@ -0,0 +1,56 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH clrbuf 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +clrbuf \- erase the contents of a buffer +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/buf.h> + + + +\fBvoid\fR \fBclrbuf\fR(\fBstruct buf *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +Pointer to the \fBbuf\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBclrbuf()\fR function zeros a buffer and sets the \fBb_resid\fR member of +the \fBbuf\fR(9S) structure to \fB0\fR. Zeros are placed in the buffer starting +at \fIbp\fR\fB\(->b_un.b_addr\fR for a length of \fIbp\fR\fB\(->b_bcount\fR +bytes. \fBb_un.b_addr\fR and \fBb_bcount\fR are members of the \fBbuf\fR(9S) +data structure. +.SH CONTEXT +.sp +.LP +The \fBclrbuf()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBgetrbuf\fR(9F), \fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/cmn_err.9f b/usr/src/man/man9f/cmn_err.9f new file mode 100644 index 0000000000..6b19ae958d --- /dev/null +++ b/usr/src/man/man9f/cmn_err.9f @@ -0,0 +1,523 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cmn_err 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +cmn_err, vcmn_err, zcmn_err \- display an error message or panic the system +.SH SYNOPSIS +.LP +.nf +#include <sys/cmn_err.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBcmn_err\fR(\fBint\fR \fIlevel\fR, \fBchar *\fR\fIformat\fR... +.fi + +.LP +.nf +#include <sys/varargs.h> + + + +\fBvoid\fR \fBvcmn_err\fR(\fBint\fR \fIlevel\fR, \fBchar *\fR\fIformat\fR, \fBva_list\fR \fIap\fR); +.fi + +.LP +.nf +#include <sys/types.h> + + + +\fBvoid\fR \fBzcmn_err\fR(\fBzoneid_t\fR \fIzoneid\fR, \fBint\fR \fIlevel\fR, \fBchar *\fR\fIformat\fR...); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.SS "cmn_err(\|)" +.sp +.ne 2 +.mk +.na +\fB\fIlevel\fR\fR +.ad +.RS 10n +.rt +A constant indicating the severity of the error condition. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIformat\fR\fR +.ad +.RS 10n +.rt +Message to be displayed. +.RE + +.SS "vcmn_err(\|)" +.sp +.LP +The \fBvcmn_err()\fR function takes \fIlevel\fR and \fIformat\fR as described +for \fBcmn_err()\fR, but its third argument is different: +.sp +.ne 2 +.mk +.na +\fB\fIap\fR\fR +.ad +.RS 6n +.rt +Variable argument list passed to the function. +.RE + +.SS "zcmn_err(\|)" +.sp +.LP +The \fBzcmn_err()\fR function works exactly like \fBcmn_err()\fR, but includes +an additional argument: +.sp +.ne 2 +.mk +.na +\fB\fIzoneid\fR\fR +.ad +.RS 10n +.rt +Zone to which log messages should be directed. See \fBzones\fR(5). +.RE + +.SH DESCRIPTION +.SS "cmn_err(\|)" +.sp +.LP +The \fBcmn_err()\fR function displays a specified message on the console. +\fBcmn_err()\fR can also panic the system. When the system panics, it attempts +to save recent changes to data, display a "panic message" on the console, +attempt to write a core file, and halt system processing. See the +\fBCE_PANIC\fR \fIlevel\fR below. +.sp +.LP +\fIlevel\fR is a constant indicating the severity of the error condition. The +four severity levels are: +.sp +.ne 2 +.mk +.na +\fB\fBCE_CONT\fR\fR +.ad +.RS 12n +.rt +Used to continue another message or to display an informative message not +associated with an error. Note that multiple \fBCE_CONT\fR messages without a +newline may or may not appear on the system console or in the system log as a +single line message. A single line message may be produced by constructing the +message with \fBsprintf\fR(9F) or \fBvsprintf\fR(9F) before calling +\fBcmn_err()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCE_NOTE\fR\fR +.ad +.RS 12n +.rt +Used to display a message preceded with \fBNOTICE\fR. This message is used to +report system events that do not necessarily require user action, but may +interest the system administrator. For example, a message saying that a sector +on a disk needs to be accessed repeatedly before it can be accessed correctly +might be noteworthy. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCE_WARN\fR\fR +.ad +.RS 12n +.rt +Used to display a message preceded with \fBWARNING\fR. This message is used to +report system events that require immediate attention, such as those where if +an action is not taken, the system may panic. For example, when a peripheral +device does not initialize correctly, this level should be used. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCE_PANIC\fR\fR +.ad +.RS 12n +.rt +Used to display a message preceded with \fB"panic"\fR, and to panic the system. +Drivers should specify this level only under the most severe conditions or when +debugging a driver. A valid use of this level is when the system cannot +continue to function. If the error is recoverable, or not essential to +continued system operation, do not panic the system. +.RE + +.sp +.LP +\fIformat\fR is the message to be displayed. It is a character string which may +contain plain characters and conversion specifications. By default, the message +is sent both to the system console and to the system log. +.sp +.LP +Each conversion specification in \fIformat\fR is introduced by the \fB%\fR +character, after which the following appear in sequence: +.sp +.LP +An optional decimal digit specifying a minimum field width for numeric +conversion. The converted value will be right-justified and padded with leading +zeroes if it has fewer characters than the minimum. +.sp +.LP +An optional \fBl\fR (\fBll\fR) specifying that a following \fBd\fR, \fBD\fR, +\fBo\fR, \fBO\fR, \fBx\fR, \fBX\fR, or \fBu\fR conversion character applies to +a \fBlong\fR (\fBlong long\fR) integer argument. An \fBl\fR (\fBll\fR) before +any other conversion character is ignored. +.sp +.LP +A character indicating the type of conversion to be applied: +.sp +.ne 2 +.mk +.na +\fB\fBd\fR,\fBD\fR,\fBo\fR,\fBO\fR,\fBx\fR,\fBX\fR,\fBu\fR\fR +.ad +.RS 17n +.rt +The integer argument is converted to signed decimal (\fBd\fR, \fBD\fR), +unsigned octal (\fBo\fR, \fBO\fR), unsigned hexadecimal (\fBx\fR, \fBX\fR), or +unsigned decimal (\fBu\fR), respectively, and displayed. The letters +\fBabcdef\fR are used for \fBx\fR and \fBX\fR conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBc\fR\fR +.ad +.RS 17n +.rt +The character value of the argument is displayed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBb\fR\fR +.ad +.RS 17n +.rt +The \fB%b\fR conversion specification allows bit values to be displayed +meaningfully. Each \fB%b\fR takes an integer value and a format string from the +argument list. The first character of the format string should be the output +base encoded as a control character. This base is used to display the integer +argument. The remaining groups of characters in the format string consist of a +bit number (between 1 and 32, also encoded as a control character) and the next +characters (up to the next control character or '\e0') give the name of the bit +field. The string corresponding to the bit fields set in the integer argument +is displayed after the numerical value. See EXAMPLE section. +.RE + +.sp +.ne 2 +.mk +.na +\fBp\fR +.ad +.RS 17n +.rt +The argument is taken to be a pointer; the value of the pointer is displayed in +unsigned hexadecimal. The display format is equivalent to \fB%lx\fR. To avoid +lint warnings, cast pointers to type \fBvoid *\fR when using the \fB%p\fR +format specifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs\fR\fR +.ad +.RS 17n +.rt +The argument is taken to be a string (character pointer), and characters from +the string are displayed until a null character is encountered. If the +character pointer is \fINULL\fR, the string \fB<null string>\fR is used in its +place. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%\fR\fR +.ad +.RS 17n +.rt +Copy a \fB%\fR; no argument is converted. +.RE + +.sp +.LP +The first character in \fIformat\fR affects where the message will be written: +.sp +.ne 2 +.mk +.na +\fB\fB!\fR\fR +.ad +.RS 5n +.rt +The message goes only to the system log. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB^\fR\fR +.ad +.RS 5n +.rt +The message goes only to the console. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB?\fR\fR +.ad +.RS 5n +.rt +If \fIlevel\fR is also \fBCE_CONT,\fR the message is always sent to the system +log, but is only written to the console when the system has been booted in +verbose mode. See \fBkernel\fR(1M). If neither condition is met, the '?\|' +character has no effect and is simply ignored. +.RE + +.sp +.LP +Refer to \fBsyslogd\fR(1M) to determine where the system log is written. +.sp +.LP +The \fBcmn_err()\fR function sends log messages to the log of the global zone. +\fBcmn_err()\fR appends a \fB\en\fR to each \fIformat\fR, except when +\fIlevel\fR is \fBCE_CONT\fR. +.SS "vcmn_err(\|)" +.sp +.LP +The \fBvcmn_err()\fR function is identical to \fBcmn_err()\fR except that its +last argument, \fIap\fR, is a pointer to a variable list of arguments. \fIap\fR +contains the list of arguments used by the conversion specifications in +\fIformat\fR. \fIap\fR must be initialized by calling \fBva_start\fR(9F). +\fBva_end\fR(9F) is used to clean up and must be called after each traversal of +the list. Multiple traversals of the argument list, each bracketed by +\fBva_start\fR(9F) and \fBva_end\fR(9F), are possible. +.SS "zcmn_err(\|)" +.sp +.LP +With the exception of its first argument (\fBzoneid\fR), \fBzcmn_err()\fR is +identical to \fBcmn_err()\fR. \fBzoneid\fR is the numeric ID of the zone to +which the message should be directed. Note that \fBzoneid\fR only has an effect +if the message is sent to the system log. Using \fBzoneid\fR will cause +messages to be sent to the log associated with the specified local zone rather +than the log in the global zone. This is accomplished by the message being +received and processed by the \fBsyslogd\fR(1M) process running in the +specified zone instead of the one running in the global zone. You can retrieve +a process zone ID from its credential structure using \fBcrgetzoneid\fR(9F). +.SH RETURN VALUES +.sp +.LP +None. However, if an unknown \fIlevel\fR is passed to \fBcmn_err()\fR, the +following panic error message is displayed: +.sp +.in +2 +.nf +panic: unknown level in cmn_err (level=\fIlevel\fR, msg=format) +.fi +.in -2 +.sp + +.SH CONTEXT +.sp +.LP +The \fBcmn_err()\fR function can be called from user, kernel, interrupt, or +high-level interrupt context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBcmn_err()\fR +.sp +.LP +This first example shows how \fBcmn_err()\fR can record tracing and debugging +information only in the system log (lines 17); display problems with a device +only on the system console (line 23); or display problems with the device on +both the system console and in the system log (line 28). + +.sp +.in +2 +.nf +1 struct reg { +2 uchar_t data; +3 uchar_t csr; +4 }; +5 +6 struct xxstate { +7 .\|.\|. +8 dev_info_t *dip; +9 struct reg *regp; +10 .\|.\|. +11 }; +12 +13 dev_t dev; +14 struct xxstate *xsp; +15 .\|.\|. +16 #ifdef DEBUG /* in debugging mode, log function call */ +17 cmn_err(CE_CONT, "!%s%d: xxopen function called.", +18 ddi_binding_name(xsp->dip), getminor(dev)); +19 #endif /* end DEBUG */ +20 .\|.\|. +21 /* display device power failure on system console */ +22 if ((xsp->regp->csr & POWER) == OFF) +23 cmn_err(CE_NOTE, "^OFF.", +24 ddi_binding_name(xsp->dip), getminor(dev)); +25 .\|.\|. +26 /* display warning if device has bad VTOC */ +27 if (xsp->regp->csr & BADVTOC) +28 cmn_err(CE_WARN, "%s%d: xxopen: Bad VTOC.", +29 ddi_binding_name(xsp->dip), getminor(dev)); +.fi +.in -2 + +.LP +\fBExample 2 \fRUsing the %b conversion specification +.sp +.LP +This example shows how to use the \fB%b\fR conversion specification. Because of +the leading '?\|' character in the format string, this message will always be +logged, but it will only be displayed when the kernel is booted in verbose +mode. + +.sp +.in +2 +.nf +cmn_err(CE_CONT, "?reg=0x%b\en", regval, "\e020\e3Intr\e2Err\e1Enable"); +.fi +.in -2 +.sp + +.LP +\fBExample 3 \fRUsing \fIregval\fR +.sp +.LP +When \fIregval\fR is set to (decimal) \fB13\fR, the following message would be +displayed: + +.sp +.in +2 +.nf +reg=0xd<Intr,,Enable> +.fi +.in -2 +.sp + +.LP +\fBExample 4 \fRError Routine +.sp +.LP +This example shows an error reporting routine which accepts a variable number +of arguments and displays a single line error message both in the system log +and on the system console. Note the use of \fBvsprintf()\fR to construct the +error message before calling \fBcmn_err()\fR. + +.sp +.in +2 +.nf +#include <sys/varargs.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> +#define MAX_MSG 256; + +void +xxerror(dev_info_t *dip, int level, const char *fmt, .\|.\|.\|) +{ + va_list ap; + int instance; + char buf[MAX_MSG], *name; + +instance = ddi_get_instance(dip); +name = ddi_binding_name(dip); + +/* format buf using fmt and arguments contained in ap */ + +va_start(ap, fmt); +vsprintf(buf, fmt, ap); +va_end(ap); + +/* pass formatted string to cmn_err(9F) */ + +cmn_err(level, "%s%d: %s", name, instance, buf); + +} +.fi +.in -2 + +.LP +\fBExample 5 \fRLog to Current Zone +.sp +.LP +This example shows how messages can be sent to the log of the zone in which a +thread is currently running, when applicable. Note that most hardware-related +messages should instead be sent to the global zone using \fBcmn_err()\fR. + +.sp +.in +2 +.nf +zcmn_err(crgetzoneid(ddi_get_cred()), CE_NOTE, "out of processes0); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBdmesg\fR(1M), \fBkernel\fR(1M), \fBprintf\fR(3C), \fBzones\fR(5), +\fBddi_binding_name\fR(9F), \fBddi_cred\fR(9F), \fBsprintf\fR(9F), +\fBva_arg\fR(9F), \fBva_end\fR(9F), \fBva_start\fR(9F), \fBvsprintf\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +The \fBcmn_err()\fR function with the \fBCE_CONT\fR argument can be used by +driver developers as a driver code debugging tool. However, using +\fBcmn_err()\fR in this capacity can change system timing characteristics. +.SH NOTES +.sp +.LP +Messages of arbitrary length can be generated using \fBcmn_err()\fR, but if the +call to \fBcmn_err()\fR is made from high-level interrupt context and +insufficient memory is available to create a buffer of the specified size, the +message will be truncated to \fBLOG_MSGSIZE\fR bytes (see <\fBsys/log.h\fR>). +For this reason, callers of \fBcmn_err()\fR that require complete and accurate +message generation should post down from high-level interrupt context before +calling \fBcmn_err()\fR. diff --git a/usr/src/man/man9f/condvar.9f b/usr/src/man/man9f/condvar.9f new file mode 100644 index 0000000000..11ca0ed3a3 --- /dev/null +++ b/usr/src/man/man9f/condvar.9f @@ -0,0 +1,317 @@ +'\" 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 condvar 9F "15 Dec 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +condvar, cv_init, cv_destroy, cv_wait, cv_signal, cv_broadcast, cv_wait_sig, +cv_timedwait, cv_timedwait_sig \- condition variable routines +.SH SYNOPSIS +.LP +.nf +#include <sys/ksynch.h> + + + +\fBvoid\fR \fBcv_init\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBchar *\fR\fIname\fR, \fBkcv_type_t\fR \fItype\fR, \fBvoid *\fR\fIarg\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcv_destroy\fR(\fBkcondvar_t *\fR\fIcvp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcv_wait\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcv_signal\fR(\fBkcondvar_t *\fR\fIcvp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcv_broadcast\fR(\fBkcondvar_t *\fR\fIcvp\fR); +.fi + +.LP +.nf +\fBint\fR \fBcv_wait_sig\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR); +.fi + +.LP +.nf +\fBclock_t\fR \fBcv_timedwait\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fItimeout\fR); +.fi + +.LP +.nf +\fBclock_t\fR \fBcv_timedwait_sig\fR(\fBkcondvar_t *\fR\fIcvp\fR, \fBkmutex_t *\fR\fImp\fR, \fBclock_t\fR \fItimeout\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcvp\fR\fR +.ad +.RS 11n +.rt +A pointer to an abstract data type \fBkcondvar_t\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 11n +.rt +A pointer to a mutual exclusion lock (\fBkmutex_t\fR), initialized by +\fBmutex_init\fR(9F) and held by the caller. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 11n +.rt +Descriptive string. This is obsolete and should be \fINULL\fR. (Non-\fINULL\fR +strings are legal, but they're a waste of kernel memory.) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 11n +.rt +The constant \fBCV_DRIVER\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 11n +.rt +A type-specific argument, drivers should pass arg as \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItimeout\fR\fR +.ad +.RS 11n +.rt +A time, in absolute ticks since boot, when \fBcv_timedwait()\fR or +\fBcv_timedwait_sig()\fR should return. +.RE + +.SH DESCRIPTION +.sp +.LP +Condition variables are a standard form of thread synchronization. They are +designed to be used with mutual exclusion locks (mutexes). The associated mutex +is used to ensure that a condition can be checked atomically and that the +thread can block on the associated condition variable without missing either a +change to the condition or a signal that the condition has changed. Condition +variables must be initialized by calling \fBcv_init()\fR, and must be +deallocated by calling \fBcv_destroy()\fR. +.sp +.LP +The usual use of condition variables is to check a condition (for example, +device state, data structure reference count, etc.) while holding a mutex which +keeps other threads from changing the condition. If the condition is such that +the thread should block, \fBcv_wait()\fR is called with a related condition +variable and the mutex. At some later point in time, another thread would +acquire the mutex, set the condition such that the previous thread can be +unblocked, unblock the previous thread with \fBcv_signal()\fR or +\fBcv_broadcast()\fR, and then release the mutex. +.sp +.LP +\fBcv_wait()\fR suspends the calling thread and exits the mutex atomically so +that another thread which holds the mutex cannot signal on the condition +variable until the blocking thread is blocked. Before returning, the mutex is +reacquired. +.sp +.LP +\fBcv_signal()\fR signals the condition and wakes one blocked thread. All +blocked threads can be unblocked by calling \fBcv_broadcast()\fR. +\fBcv_signal()\fR and \fBcv_broadcast()\fR can be called by a thread even if it +does not hold the mutex passed into \fBcv_wait()\fR, though holding the mutex +is necessary to ensure predictable scheduling. +.sp +.LP +The function \fBcv_wait_sig()\fR is similar to \fBcv_wait()\fR but returns +\fB0\fR if a signal (for example, by \fBkill\fR(2)) is sent to the thread. In +any case, the mutex is reacquired before returning. +.sp +.LP +The function \fBcv_timedwait()\fR is similar to \fBcv_wait()\fR, except that it +returns \fB\(mi1\fR without the condition being signaled after the timeout time +has been reached. +.sp +.LP +The function \fBcv_timedwait_sig()\fR is similar to \fBcv_timedwait()\fR and +\fBcv_wait_sig()\fR, except that it returns \fB\(mi1\fR without the condition +being signaled after the timeout time has been reached, or \fB0\fR if a signal +(for example, by \fBkill\fR(2)) is sent to the thread. +.sp +.LP +For both \fBcv_timedwait()\fR and \fBcv_timedwait_sig()\fR, time is in absolute +clock ticks since the last system reboot. The current time may be found by +calling \fBddi_get_lbolt\fR(9F). +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 9n +.rt +For \fBcv_wait_sig()\fR and \fBcv_timedwait_sig()\fR indicates that the +condition was not necessarily signaled and the function returned because a +signal (as in \fBkill\fR(2)) was pending. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\(mi1\fR\fR +.ad +.RS 9n +.rt +For \fBcv_timedwait()\fR and \fBcv_timedwait_sig()\fR indicates that the +condition was not necessarily signaled and the function returned because the +timeout time was reached. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB>0\fR\fR +.ad +.RS 9n +.rt +For \fBcv_wait_sig()\fR, \fBcv_timedwait()\fR or \fBcv_timedwait_sig()\fR +indicates that the condition was met and the function returned due to a call to +\fBcv_signal()\fR or \fBcv_broadcast()\fR, or due to a premature wakeup (see +NOTES). +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel or interrupt context. In most +cases, however, \fBcv_wait()\fR, \fBcv_timedwait()\fR, \fBcv_wait_sig()\fR, and +\fBcv_timedwait_sig()\fR should not be called from interrupt context, and +cannot be called from a high-level interrupt context. +.sp +.LP +If \fBcv_wait()\fR, \fBcv_timedwait()\fR, \fBcv_wait_sig()\fR, or +\fBcv_timedwait_sig()\fR are used from interrupt context, lower-priority +interrupts will not be serviced during the wait. This means that if the thread +that will eventually perform the wakeup becomes blocked on anything that +requires the lower-priority interrupt, the system will hang. +.sp +.LP +For example, the thread that will perform the wakeup may need to first allocate +memory. This memory allocation may require waiting for paging \fBI/O\fR to +complete, which may require a lower-priority disk or network interrupt to be +serviced. In general, situations like this are hard to predict, so it is +advisable to avoid waiting on condition variables or semaphores in an interrupt +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRWaiting for a Flag Value in a Driver's Unit +.sp +.LP +Here the condition being waited for is a flag value in a driver's unit +structure. The condition variable is also in the unit structure, and the flag +word is protected by a mutex in the unit structure. + +.sp +.in +2 +.nf + mutex_enter(&un->un_lock); + while (un->un_flag & UNIT_BUSY) + cv_wait(&un->un_cv, &un->un_lock); + un->un_flag |= UNIT_BUSY; + mutex_exit(&un->un_lock); +.fi +.in -2 + +.LP +\fBExample 2 \fRUnblocking Threads Blocked by the Code in Example 1 +.sp +.LP +At some later point in time, another thread would execute the following to +unblock any threads blocked by the above code. + +.sp +.in +2 +.nf + +mutex_enter(&un->un_lock); +un->un_flag &= ~UNIT_BUSY; +cv_broadcast(&un->un_cv); +mutex_exit(&un->un_lock); +.fi +.in -2 + +.SH NOTES +.sp +.LP +It is possible for \fBcv_wait()\fR, \fBcv_wait_sig()\fR, \fBcv_timedwait()\fR, +and \fBcv_timedwait_sig()\fR to return prematurely, that is, not due to a call +to \fBcv_signal()\fR or \fBcv_broadcast()\fR. This occurs most commonly in the +case of \fBcv_wait_sig()\fR and \fBcv_timedwait_sig()\fR when the thread is +stopped and restarted by job control signals or by a debugger, but can happen +in other cases as well, even for \fBcv_wait()\fR. Code that calls these +functions must always recheck the reason for blocking and call again if the +reason for blocking is still true. +.sp +.LP +If your driver needs to wait on behalf of processes that have real-time +constraints, use \fBcv_timedwait()\fR rather than \fBdelay\fR(9F). The +\fBdelay()\fR function calls \fBtimeout\fR(9F), which can be subject to +priority inversions. +.sp +.LP +Not all threads can receive signals from user level processes. In cases where +such reception is impossible (such as during execution of \fBclose\fR(9E) due +to \fBexit\fR(2)), \fBcv_wait_sig()\fR behaves as \fBcv_wait()\fR, and +\fBcv_timedwait_sig()\fR behaves as \fBcv_timedwait()\fR. To avoid unkillable +processes, users of these functions may need to protect against waiting +indefinitely for events that might not occur. The \fBddi_can_receive_sig\fR(9F) +function is provided to detect when signal reception is possible. +.SH SEE ALSO +.sp +.LP +\fBkill\fR(2), \fBddi_can_receive_sig\fR(9F), \fBddi_get_lbolt\fR(9F), +\fBmutex\fR(9F), \fBmutex_init\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/copyb.9f b/usr/src/man/man9f/copyb.9f new file mode 100644 index 0000000000..881ab0d3f9 --- /dev/null +++ b/usr/src/man/man9f/copyb.9f @@ -0,0 +1,127 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2006, 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 copyb 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +copyb \- copy a message block +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBmblk_t *\fR\fBcopyb\fR(\fBmblk_t *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +Pointer to the message block from which data is copied. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBcopyb()\fR function allocates a new message block, and copies into it +the data from the block that \fIbp\fR denotes. The new block will be at least +as large as the block being copied. \fBcopyb()\fR uses the \fBb_rptr\fR and +\fBb_wptr\fR members of \fIbp\fR to determine how many bytes to copy. +.SH RETURN VALUES +.sp +.LP +If successful, \fBcopyb()\fR returns a pointer to the newly allocated message +block containing the copied data. Otherwise, it returns a \fINULL\fR pointer. +.SH CONTEXT +.sp +.LP +The \fBcopyb()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing copyb +.sp +.LP +For each message in the list, test to see if the downstream queue is full with +the \fBcanputnext\fR(9F) function (line 21). If it is not full, use \fBcopyb\fR +to copy a header message block, and \fBdupmsg\fR(9F) to duplicate the data to +be retransmitted. If either operation fails, reschedule a timeout at the next +valid interval. + +.sp +.LP +Update the new header block with the correct destination address (line 34), +link the message to it (line 35), and send it downstream (line 36). At the end +of the list, reschedule this routine. + +.sp +.in +2 +.nf + 1 struct retrans { + 2 mblk_t *r_mp; + 3 int r_address; + 4 queue_t *r_outq; + 5 struct retrans *r_next; + 6 }; + 7 + 8 struct protoheader { + \&.\|.\|. + 9 int h_address; + \&.\|.\|. +10 }; +11 +12 mblk_t *header; +13 +14 void +15 retransmit(struct retrans *ret) +16 { +17 mblk_t *bp, *mp; +18 struct protoheader *php; +19 +20 while (ret) { +21 if (!canputnext(ret->r_outq)) { /* no room */ +22 ret = ret->r_next; +23 continue; +24 } +25 bp = copyb(header); /* copy header msg. block */ +26 if (bp == NULL) +27 break; +28 mp = dupmsg(ret->r_mp); /* duplicate data */ +29 if (mp == NULL) { /* if unsuccessful */ +30 freeb(bp); /* free the block */ +31 break; +32 } +33 php = (struct protoheader *)bp->b_rptr; +34 php->h_address = ret->r_address; /* new header */ +35 bp->bp_cont = mp; /* link the message */ +36 putnext(ret->r_outq, bp); /* send downstream */ +37 ret = ret->r_next; +38 } +39 /* reschedule */ +40 (void) timeout(retransmit, (caddr_t)ret, RETRANS_TIME); +41 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBallocb\fR(9F), \fBcanputnext\fR(9F), \fBdupmsg\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/copyin.9f b/usr/src/man/man9f/copyin.9f new file mode 100644 index 0000000000..8f02f1056a --- /dev/null +++ b/usr/src/man/man9f/copyin.9f @@ -0,0 +1,187 @@ +'\" te +.\" Copyright 1989 AT&T 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 copyin 9F "27 Sep 2002" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +copyin \- copy data from a user program to a driver buffer +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> + + + +\fBint\fR \fBcopyin\fR(\fBconst void *\fR\fIuserbuf\fR, \fBvoid *\fR\fIdriverbuf\fR, \fBsize_t\fR \fIcn\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. \fBddi_copyin\fR(9F) should be used instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIuserbuf\fR \fR +.ad +.RS 14n +.rt +User program source address from which data is transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdriverbuf\fR \fR +.ad +.RS 14n +.rt +Driver destination address to which data is transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcn\fR \fR +.ad +.RS 14n +.rt +Number of bytes transferred. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBcopyin()\fR copies data from a user program source address to a driver +buffer. The driver developer must ensure that adequate space is allocated for +the destination address. +.sp +.LP +Addresses that are word-aligned are moved most efficiently. However, the +driver developer is not obligated to ensure alignment. This function +automatically finds the most efficient move according to address alignment. +.SH RETURN VALUES +.sp +.LP +Under normal conditions, a \fB0\fR is returned indicating a successful copy. +Otherwise, a \(mi\fB1\fR is returned if one of the following occurs: +.RS +4 +.TP +.ie t \(bu +.el o +Paging fault; the driver tried to access a page of memory for which it did not +have read or write access. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Invalid user address, such as a user area or stack area. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Invalid address that would have resulted in data being copied into the user +block. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Hardware fault; a hardware error prevented access to the specified user memory. +For example, an uncorrectable parity or \fBECC\fR error occurred. +.RE +.sp +.LP +If a \(mi\fB1\fR is returned to the caller, driver entry point routines should +return \fBEFAULT\fR. +.SH CONTEXT +.sp +.LP +\fBcopyin()\fR can be called from user context only. +.SH EXAMPLES +.LP +\fBExample 1 \fRAn \fBioctl()\fR Routine +.sp +.LP +A driver \fBioctl\fR(9E) routine (line 10) can be used to get or set device +attributes or registers. In the \fBXX_GETREGS\fR condition (line 17), the +driver copies the current device register values to a user data area (line 18). +If the specified argument contains an invalid address, an error code is +returned. + +.sp +.in +2 +.nf + + 1 struct device { /* layout of physical device registers */ + 2 int control; /* physical device control word */ + 3 int status; /* physical device status word */ + 4 short recv_char; /* receive character from device */ + 5 short xmit_char; /* transmit character to device */ + 6 }; + 7 + 8 extern struct device xx_addr[]; /* phys. device regs. location */ + 9 . . . +10 xx_ioctl(dev_t dev, int cmd, int arg, int mode, +11 cred_t *cred_p, int *rval_p) +12 ... +13 { +14 register struct device *rp = &xx_addr[getminor(dev) >> 4]; +15 switch (cmd) { +16 +17 case XX_GETREGS: /* copy device regs. to user program */ +18 if (copyin(arg, rp, sizeof(struct device))) +19 return(EFAULT); +20 break; +21 ... +22 } +23 ... +24 } +.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 +\fBattributes\fR(5), \fBioctl\fR(9E), \fBbcopy\fR(9F), \fBcopyout\fR(9F), +\fBddi_copyin\fR(9F), \fBddi_copyout\fR(9F), \fBuiomove\fR(9F). +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Driver writers who intend to support layered ioctls in their \fBioctl\fR(9E) +routines should use \fBddi_copyin\fR(9F) instead. +.sp +.LP +Driver defined locks should not be held across calls to this function. +.sp +.LP +\fBcopyin()\fR should not be used from a streams driver. See \fBM_COPYIN\fR and +\fBM_COPYOUT\fR in \fISTREAMS Programming Guide\fR. diff --git a/usr/src/man/man9f/copymsg.9f b/usr/src/man/man9f/copymsg.9f new file mode 100644 index 0000000000..2a2bd5f053 --- /dev/null +++ b/usr/src/man/man9f/copymsg.9f @@ -0,0 +1,105 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH copymsg 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +copymsg \- copy a message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBmblk_t *\fR\fBcopymsg\fR(\fBmblk_t *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 6n +.rt +Pointer to the message to be copied. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBcopymsg()\fR function forms a new message by allocating new message +blocks, and copying the contents of the message referred to by \fImp\fR (using +the \fBcopyb\fR(9F) function). It returns a pointer to the new message. +.SH RETURN VALUES +.sp +.LP +If the copy is successful, \fBcopymsg()\fR returns a pointer to the new +message. Otherwise, it returns a \fINULL\fR pointer. +.SH CONTEXT +.sp +.LP +The \fBcopymsg()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fR: Using copymsg +.sp +.LP +The routine \fBlctouc()\fR converts all the lowercase \fBASCII \fRcharacters in +the message to uppercase. If the reference count is greater than one (line 8), +then the message is shared, and must be copied before changing the contents of +the data buffer. If the call to the \fBcopymsg()\fR function fails (line 9), +return \fINULL\fR (line 10), otherwise, free the original message (line 11). If +the reference count was equal to \fB1\fR, the message can be modified. For each +character (line 16) in each message block (line 15), if it is a lowercase +letter, convert it to an uppercase letter (line 18). A pointer to the converted +message is returned (line 21). + +.sp +.in +2 +.nf + + 1 mblk_t *lctouc(mp) + 2 mblk_t *mp; + 3 { + 4 mblk_t *cmp; + 5 mblk_t *tmp; + 6 unsigned char *cp; + 7 + 8 if (mp->b_datap->db_ref > 1) { + 9 if ((cmp = copymsg(mp)) == NULL) +10 return (NULL); +11 freemsg(mp); +12 } else { +13 cmp = mp; +14 } +15 for (tmp = cmp; tmp; tmp = tmp->b_cont) { +16 for (cp = tmp->b_rptr; cp < tmp->b_wptr; cp++) { +17 if ((*cp <= 'z') && (*cp >= 'a')) +18 *cp -= 0x20; +19 } +20 } +21 return(cmp); +22 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBallocb\fR(9F), \fBcopyb\fR(9F), \fBmsgb\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/copyout.9f b/usr/src/man/man9f/copyout.9f new file mode 100644 index 0000000000..b1767e4b30 --- /dev/null +++ b/usr/src/man/man9f/copyout.9f @@ -0,0 +1,185 @@ +'\" 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 copyout 9F "27 Sep 2002" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +copyout \- copy data from a driver to a user program +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> + + + +\fBint\fR \fBcopyout\fR(\fBconst void *\fR\fIdriverbuf\fR, \fBvoid *\fR\fIuserbuf\fR, \fBsize_t\fR \fIcn\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. \fBddi_copyout\fR(9F) should be used instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdriverbuf\fR \fR +.ad +.RS 14n +.rt +Source address in the driver from which the data is transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuserbuf\fR \fR +.ad +.RS 14n +.rt +Destination address in the user program to which the data is transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcn\fR \fR +.ad +.RS 14n +.rt +Number of bytes moved. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBcopyout()\fR copies data from driver buffers to user data space. +.sp +.LP +Addresses that are word-aligned are moved most efficiently. However, the +driver developer is not obligated to ensure alignment. This function +automatically finds the most efficient move algorithm according to address +alignment. +.SH RETURN VALUES +.sp +.LP +Under normal conditions, a \fB0\fR is returned to indicate a successful copy. +Otherwise, a \(mi\fB1\fR is returned if one of the following occurs: +.RS +4 +.TP +.ie t \(bu +.el o +Paging fault; the driver tried to access a page of memory for which it did not +have read or write access. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Invalid user address, such as a user area or stack area. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Invalid address that would have resulted in data being copied into the user +block. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Hardware fault; a hardware error prevented access to the specified user memory. +For example, an uncorrectable parity or \fBECC\fR error occurred. +.RE +.sp +.LP +If a \(mi\fB1\fR is returned to the caller, driver entry point routines should +return \fBEFAULT\fR. +.SH CONTEXT +.sp +.LP +\fBcopyout()\fR can be called from user context only. +.SH EXAMPLES +.LP +\fBExample 1 \fRAn \fBioctl()\fR Routine +.sp +.LP +A driver \fBioctl\fR(9E) routine (line 10) can be used to get or set device +attributes or registers. In the \fBXX_GETREGS\fR condition (line 17), the +driver copies the current device register values to a user data area (line 18). +If the specified argument contains an invalid address, an error code is +returned. + +.sp +.in +2 +.nf + 1 struct device { /* layout of physical device registers */ + 2 int control; /* physical device control word */ + 3 int status; /* physical device status word */ + 4 short recv_char; /* receive character from device */ + 5 short xmit_char; /* transmit character to device */ + 6 }; + 7 + 8 extern struct device xx_addr[]; /* phys. device regs. location */ + 9 . . . +10 xx_ioctl(dev_t dev, int cmd, int arg, int mode, +11 cred_t *cred_p, int *rval_p) +12 ... +13 { +14 register struct device *rp = &xx_addr[getminor(dev) >> 4]; +15 switch (cmd) { +16 +17 case XX_GETREGS: /* copy device regs. to user program */ +18 if (copyout(rp, arg, sizeof(struct device))) +19 return(EFAULT); +20 break; +21 ... +22 } +23 ... +24 } +.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 +\fBattributes\fR(5), \fBioctl\fR(9E), \fBbcopy\fR(9F), \fBcopyin\fR(9F), +\fBddi_copyin\fR(9F), \fBddi_copyout\fR(9F), \fBuiomove\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Driver writers who intend to support layered ioctls in their \fBioctl\fR(9E) +routines should use \fBddi_copyout\fR(9F) instead. +.sp +.LP +Driver defined locks should not be held across calls to this function. +.sp +.LP +\fBcopyout()\fR should not be used from a streams driver. See \fBM_COPYIN\fR +and \fBM_COPYOUT\fR in \fISTREAMS Programming Guide\fR. diff --git a/usr/src/man/man9f/csx_AccessConfigurationRegister.9f b/usr/src/man/man9f/csx_AccessConfigurationRegister.9f new file mode 100644 index 0000000000..0ff1d94257 --- /dev/null +++ b/usr/src/man/man9f/csx_AccessConfigurationRegister.9f @@ -0,0 +1,222 @@ +'\" 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_AccessConfigurationRegister 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_AccessConfigurationRegister \- read or write a PC Card Configuration +Register +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_AccessConfigurationRegister\fR(\fBclient_handle_t\fR \fIch\fR, + \fBaccess_config_reg_t *\fR\fIacr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIacr\fR\fR +.ad +.RS 7n +.rt +Pointer to an \fBaccess_config_reg_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function allows a client to read or write a \fBPC\fRCard Configuration +Register. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBaccess_config_reg_t\fR are: +.sp +.in +2 +.nf +uint32_t Socket; /* socket number*/ +uint32_t Action; /* register access operation*/ +uint32_t Offset; /* config register offset*/ +uint32_t Value; /* value read or written*/ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR\fR +.ad +.RS 10n +.rt +Not used in Solaris, but for portability with other Card Services +implementations, it should be set to the logical socket number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAction\fR\fR +.ad +.RS 10n +.rt +May be set to \fBCONFIG_REG_READ\fR or \fBCONFIG_REG_WRITE\fR. All other values +in the \fBAction\fR field are reserved for future use. If the \fBAction\fR +field is set to \fBCONFIG_REG_WRITE,\fR the \fBValue\fR field is written to the +specified configuration register. Card Services does not read the configuration +register after a write operation. For that reason, the \fBValue\fR field is +only updated by a \fBCONFIG_REG_READ\fR request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBOffset\fR\fR +.ad +.RS 10n +.rt +Specifies the byte offset for the desired configuration register from the \fBPC +\fRCard configuration register base specified in +\fBcsx_RequestConfiguration\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBValue\fR\fR +.ad +.RS 10n +.rt +Contains the value read from the \fBPC \fRCard Configuration Register for a +read operation. For a write operation, the \fBValue\fR field contains the value +to write to the configuration register. As noted above, on return from a write +request, the \fBValue\fR field is the value written to the \fBPC \fRCard and +not any changed value that may have resulted from the write request (that is, +no read after write is performed). +.RE + +.sp +.LP +A client must be very careful when writing to the \fBCOR \fR(Configuration +Option Register) at offset \fB0\fR. This has the potential to change the type +of interrupt request generated by the \fBPC \fRCard or place the card in the +reset state. Either request may have undefined results. The client should read +the register to determine the appropriate setting for the interrupt mode (Bit +6) before writing to the register. +.sp +.LP +If a client wants to reset a \fBPC\fRCard, the \fBcsx_ResetFunction\fR(9F) +function should be used. Unlike \fBcsx_AccessConfigurationRegister()\fR, the +\fBcsx_ResetFunction\fR(9F) function generates a series of event notifications +to all clients using the \fBPC \fRCard, so they can re-establish the +appropriate card state after the reset operation is complete. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_ARGS\fR\fR +.ad +.RS 27n +.rt +Specified arguments are invalid. Client specifies an \fBOffset\fR that is out +of range or neither \fBCONFIG_REG_READ\fR or \fBCONFIG_REG_WRITE\fR is set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_MODE\fR\fR +.ad +.RS 27n +.rt +Client has not called \fBcsx_RequestConfiguration\fR(9F) before calling this +function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRcard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_ParseTuple\fR(9F), \fBcsx_RegisterClient\fR(9F), +\fBcsx_RequestConfiguration\fR(9F), \fBcsx_ResetFunction\fR(9F) +.sp +.LP +\fIPCCard 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_CS_DDI_Info.9f b/usr/src/man/man9f/csx_CS_DDI_Info.9f new file mode 100644 index 0000000000..5ff618eeec --- /dev/null +++ b/usr/src/man/man9f/csx_CS_DDI_Info.9f @@ -0,0 +1,192 @@ +'\" 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_CS_DDI_Info 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_CS_DDI_Info \- obtain DDI information +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_CS_DDI_Info\fR(\fBcs_ddi_info_t *\fR\fIcdi\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcdi\fR \fR +.ad +.RS 8n +.rt +Pointer to a \fBcs_ddi_info_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function is a Solaris-specific extension that is used by clients that need +to provide the \fIxx_getinfo\fR driver entry point (see \fBgetinfo\fR(9E)). It +provides a method for clients to obtain \fBDDI \fRinformation based on their +socket number and client driver name. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcs_ddi_info_t\fR are: +.sp +.in +2 +.nf +uint32_t Socket; /* socket number */ +char* driver_name; /* unique driver name */ +dev_info_t *dip; /* dip */ +int32_t instance; /* instance */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR \fR +.ad +.RS 16n +.rt +This field must be set to the physical socket number that the client is +interested in getting information about. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdriver_name\fR \fR +.ad +.RS 16n +.rt +This field must be set to a string containing the name of the client driver to +get information about. +.RE + +.sp +.LP +If \fBcsx_CS_DDI_Info()\fR is used in a client's \fIxx_getinfo\fR function, +then the client will typically extract the \fBSocket\fR value from the +\fB*\fR\fIarg\fR argument and it \fImust\fR set the \fBdriver_name\fR field to +the same string used with \fBcsx_RegisterClient\fR(9F). +.sp +.LP +If the \fBdriver_name\fR is found on the \fBSocket\fR, the +\fBcsx_CS_DDI_Info()\fR function returns both the \fBdev_info\fR pointer and +the \fBinstance\fR fields for the requested driver instance. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SOCKET\fR \fR +.ad +.RS 28n +.rt +Client not found on \fBSocket\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fR: Using csx_CS_DDI_Info +.sp +.LP +The following example shows how a client might call the \fBcsx_CS_DDI_Info()\fR +in the client's \fIxx_getinfo\fR function to return the dip or the instance +number: + +.sp +.in +2 +.nf +static int +pcepp_getinfo(dev_info_t *dip, ddi_info_cmd_t cmd, void *arg, + void **result) +{ + int error = DDI_SUCCESS; + pcepp_state_t *pps; + cs_ddi_info_t cs_ddi_info; + + switch (cmd) { + + case DDI_INFO_DEVT2DEVINFO: + cs_ddi_info.Socket = getminor((dev_t)arg) & 0x3f; + cs_ddi_info.driver_name = pcepp_name; + if (csx_CS_DDI_Info(&cs_ddi_info) != CS_SUCCESS) + return (DDI_FAILURE); + if (!(pps = ddi_get_soft_state(pcepp_soft_state_p, + cs_ddi_info.instance))) { + *result = NULL; + } else { + *result = pps->dip; + } + break; + + case DDI_INFO_DEVT2INSTANCE: + cs_ddi_info.Socket = getminor((dev_t)arg) & 0x3f; + cs_ddi_info.driver_name = pcepp_name; + if (csx_CS_DDI_Info(&cs_ddi_info) != CS_SUCCESS) + return (DDI_FAILURE); + *result = (void *)cs_ddi_info.instance; + break; + + default: + error = DDI_FAILURE; + break; + + } + + return (error); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBgetinfo\fR(9E), \fBcsx_RegisterClient\fR(9F), \fBddi_get_instance\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_ConvertSize.9f b/usr/src/man/man9f/csx_ConvertSize.9f new file mode 100644 index 0000000000..15fbca72b7 --- /dev/null +++ b/usr/src/man/man9f/csx_ConvertSize.9f @@ -0,0 +1,159 @@ +'\" 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_ConvertSize 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_ConvertSize \- convert device sizes +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_ConvertSize\fR(\fBconvert_size_t *\fR\fIcs\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcs\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBconvert_size_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBcsx_ConvertSize()\fR is a Solaris-specific extension that provides a method +for clients to convert from one type of device size representation to another, +that is, from \fIdevsize\fR format to \fIbytes\fR and vice versa. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBconvert_size_t\fR are: +.sp +.in +2 +.nf +uint32_t Attributes; +uint32_t bytes; +uint32_t devsize; +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR \fR +.ad +.RS 15n +.rt +This is a bit-mapped field that identifies the type of size conversion to be +performed. The field is defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBCONVERT_BYTES_TO_DEVSIZE\fR\fR +.ad +.RS 28n +.rt +Converts \fIbytes\fR to \fIdevsize\fR format. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCONVERT_DEVSIZE_TO_BYTES\fR\fR +.ad +.RS 28n +.rt +Converts \fIdevsize\fR format to \fIbytes\fR. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBbytes\fR \fR +.ad +.RS 15n +.rt +If \fBCONVERT_BYTES_TO_DEVSIZE\fR is set, the value in the \fBbytes\fR field is +converted to a \fIdevsize\fR format and returned in the \fBdevsize\fR field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevsize\fR \fR +.ad +.RS 15n +.rt +If \fBCONVERT_DEVSIZE_TO_BYTES\fR is set, the value in the \fBdevsize\fR field +is converted to a \fIbytes\fR value and returned in the \fBbytes\fR field. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SIZE\fR \fR +.ad +.RS 28n +.rt +Invalid \fIbytes\fR or \fIdevsize\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_ModifyWindow\fR(9F), \fBcsx_RequestWindow\fR(9F) +.sp +.LP +\fIPCCard 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_ConvertSpeed.9f b/usr/src/man/man9f/csx_ConvertSpeed.9f new file mode 100644 index 0000000000..ef3acb351b --- /dev/null +++ b/usr/src/man/man9f/csx_ConvertSpeed.9f @@ -0,0 +1,170 @@ +'\" 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_ConvertSpeed 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_ConvertSpeed \- convert device speeds +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_ConvertSpeed\fR(\fBconvert_speed_t *\fR\fIcs\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcs\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBconvert_speed_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function is a Solaris-specific extension that provides a method for +clients to convert from one type of device speed representation to another, +that is, from \fIdevspeed\fR format to \fInS\fR and vice versa. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBconvert_speed_t\fR are: +.sp +.in +2 +.nf +uint32_t Attributes; +uint32_t nS; +uint32_t devspeed; +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR \fR +.ad +.RS 15n +.rt +This is a bit-mapped field that identifies the type of speed conversion to be +performed. The field is defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBCONVERT_NS_TO_DEVSPEED\fR\fR +.ad +.RS 26n +.rt +Converts \fInS\fR to \fIdevspeed\fR format +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCONVERT_DEVSPEED_TO_NS\fR\fR +.ad +.RS 26n +.rt +Converts \fIdevspeed\fR format to \fInS\fR +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnS\fR \fR +.ad +.RS 15n +.rt +If \fBCONVERT_NS_TO_DEVSPEED\fR is set, the value in the \fBnS\fR field is +converted to a \fIdevspeed\fR format and returned in the \fBdevspeed\fR field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevspeed\fR \fR +.ad +.RS 15n +.rt +If \fBCONVERT_DEVSPEED_TO_NS\fR is set, the value in the \fBdevspeed\fR field +is converted to an \fInS\fR value and returned in the \fBnS\fR field. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SPEED\fR \fR +.ad +.RS 28n +.rt +Invalid \fInS\fR or \fIdevspeed\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_ATTRIBUTE\fR \fR +.ad +.RS 28n +.rt +Bad \fBAttributes\fR value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_ModifyWindow\fR(9F), \fBcsx_RequestWindow\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_DeregisterClient.9f b/usr/src/man/man9f/csx_DeregisterClient.9f new file mode 100644 index 0000000000..a996248a00 --- /dev/null +++ b/usr/src/man/man9f/csx_DeregisterClient.9f @@ -0,0 +1,105 @@ +'\" 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_DeregisterClient 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_DeregisterClient \- remove client from Card Services list +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_DeregisterClient\fR(\fBclient_handle_t\fR \fIch\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +This function removes a client from the list of registered clients maintained +by Card Services. The Client Handle returned by \fBcsx_RegisterClient\fR(9F) is +passed in the \fBclient_handle_t\fR argument. +.sp +.LP +The client must have returned all requested resources before this function is +called. If any resources have not been released, \fBCS_IN_USE\fR is returned. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_IN_USE\fR \fR +.ad +.RS 28n +.rt +Resources not released by this client. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_RegisterClient\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR +.SH WARNINGS +.sp +.LP +Clients should be prepared to receive callbacks until Card Services returns +from this request successfully. diff --git a/usr/src/man/man9f/csx_DupHandle.9f b/usr/src/man/man9f/csx_DupHandle.9f new file mode 100644 index 0000000000..17d5b8de94 --- /dev/null +++ b/usr/src/man/man9f/csx_DupHandle.9f @@ -0,0 +1,220 @@ +'\" 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_DupHandle 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_DupHandle \- duplicate access handle +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_DupHandle\fR(\fBacc_handle_t\fR \fIhandle1\fR, \fBacc_handle_t *\fR\fIhandle2\fR, + \fBuint32_t\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle1\fR \fR +.ad +.RS 12n +.rt +The access handle returned from \fBcsx_RequestIO\fR(9F) or +\fBcsx_RequestWindow\fR(9F) that is to be duplicated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandle2\fR \fR +.ad +.RS 12n +.rt +A pointer to the newly-created duplicated data access handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR \fR +.ad +.RS 12n +.rt +The access attributes that will be applied to the new handle. +.RE + +.SH DESCRIPTION +.sp +.LP +This function duplicates the handle, \fIhandle1\fR, into a new handle, +\fIhandle2\fR, that has the access attributes specified in the \fIflags\fR +argument. Both the original handle and the new handle are active and can be +used with the common access functions. +.sp +.LP +Both handles must be explicitly freed when they are no longer necessary. +.sp +.LP +The \fIflags\fR argument is bit-mapped. The following bits are defined: +.sp +.in +2 +.nf +WIN_ACC_NEVER_SWAP Host endian byte ordering +WIN_ACC_BIG_ENDIAN Big endian byte ordering +WIN_ACC_LITTLE_ENDIAN Little endian byte ordering +WIN_ACC_STRICT_ORDER Program ordering references +WIN_ACC_UNORDERED_OK May re-order references +WIN_ACC_MERGING_OK Merge stores to consecutive locations +WIN_ACC_LOADCACHING_OK May cache load operations +WIN_ACC_STORECACHING_OK May cache store operations +.fi +.in -2 + +.sp +.LP +\fBWIN_ACC_BIG_ENDIAN\fR and \fBWIN_ACC_LITTLE_ENDIAN\fR describe the endian +characteristics of the device as big endian or little endian, respectively. +Even though most of the devices will have the same endian characteristics as +their busses, there are examples of devices with an \fBI/O \fRprocessor that +has opposite endian characteristics of the busses. When +\fBWIN_ACC_BIG_ENDIAN\fR or \fBWIN_ACC_LITTLE_ENDIAN\fR is set, byte swapping +will automatically be performed by the system if the host machine and the +device data formats have opposite endian characteristics. The implementation +may take advantage of hardware platform byte swapping capabilities. When +\fBWIN_ACC_NEVER_SWAP\fR is specified, byte swapping will not be invoked in the +data access functions. The ability to specify the order in which the \fBCPU +\fRwill reference data is provided by the following \fIflags\fR bits. Only one +of the following bits may be specified: +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_STRICT_ORDER\fR \fR +.ad +.RS 28n +.rt +The data references must be issued by a \fBCPU \fRin program order. Strict +ordering is the default behavior. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_UNORDERED_OK\fR \fR +.ad +.RS 28n +.rt +The \fBCPU \fRmay re-order the data references. This includes all kinds of +re-ordering (that is, a load followed by a store may be replaced by a store +followed by a load). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_MERGING_OK\fR \fR +.ad +.RS 28n +.rt +The \fBCPU \fRmay merge individual stores to consecutive locations. For +example, the \fBCPU \fRmay turn two consecutive byte stores into one halfword +store. It may also batch individual loads. For example, the \fBCPU \fRmay turn +two consecutive byte loads into one halfword load. Setting this bit also +implies re-ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_LOADCACHING_OK\fR \fR +.ad +.RS 28n +.rt +The \fBCPU \fRmay cache the data it fetches and reuse it until another store +occurs. The default behavior is to fetch new data on every load. Setting this +bit also implies merging and re-ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_STORECACHING_OK\fR \fR +.ad +.RS 28n +.rt +The \fBCPU \fRmay keep the data in the cache and push it to the device (perhaps +with other data) at a later time. The default behavior is to push the data +right away. Setting this bit also implies load caching, merging, and +re-ordering. +.RE + +.sp +.LP +These values are advisory, not mandatory. For example, data can be ordered +without being merged or cached, even though a driver requests unordered, merged +and cached together. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_FAILURE\fR \fR +.ad +.RS 28n +.rt +Error in \fIflags\fR argument or handle could not be duplicated for some +reason. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_Get8\fR(9F), \fBcsx_GetMappedAddr\fR(9F), \fBcsx_Put8\fR(9F), +\fBcsx_RepGet8\fR(9F), \fBcsx_RepPut8\fR(9F), \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestWindow\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_Error2Text.9f b/usr/src/man/man9f/csx_Error2Text.9f new file mode 100644 index 0000000000..1a6c474b44 --- /dev/null +++ b/usr/src/man/man9f/csx_Error2Text.9f @@ -0,0 +1,113 @@ +'\" 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_Error2Text 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Error2Text \- convert error return codes to text strings +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Error2Text\fR(\fBerror2text_t *\fR\fIer\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIer\fR \fR +.ad +.RS 7n +.rt +Pointer to an \fBerror2text_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function is a Solaris-specific extension that provides a method for +clients to convert Card Services error return codes to text strings. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBerror2text_t\fR are: +.sp +.in +2 +.nf +uint32_t item; /*the error code*/ +char test[CS_ERROR_MAX_BUFSIZE}; /*the error code*/ +.fi +.in -2 + +.sp +.LP +A pointer to the text for the Card Services error return code in the \fBitem\fR +field is returned in the \fBtext\fR field if the error return code is found. +The client is not responsible for allocating a buffer to hold the text. If the +Card Services error return code specified in the item field is not found, the +\fBtext\fR field will be set to a string of the form: +.sp +.LP +"{\fIunknown Card Services return code\fR}" +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fR: Using the csxError2Text function +.sp +.in +2 +.nf +if ((ret = csx_RegisterClient(&client_handle, & + client_reg)) != CS_SUCCESS) +{ + error2text_t error2text; + error2text.item = ret; + csx_Error2Text(&error2text); + cmn_err(CE_CONT, "RegisterClient failed %s (0x%x)", + error2text.text, ret); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBcsx_Event2Text\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_Event2Text.9f b/usr/src/man/man9f/csx_Event2Text.9f new file mode 100644 index 0000000000..0c6b04b562 --- /dev/null +++ b/usr/src/man/man9f/csx_Event2Text.9f @@ -0,0 +1,129 @@ +'\" 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_Event2Text 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Event2Text \- convert events to text strings +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Event2Text\fR(\fBevent2text_t *\fR\fIev\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIev\fR\fR +.ad +.RS 6n +.rt +Pointer to an \fBevent2text_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function is a Solaris-specific extension that provides a method for +clients to convert Card Services events to text strings. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBevent2text_t\fR are: +.sp +.in +2 +.nf +event_t event; /*the event code*/ +char text[CS_EVENT_MAX_BUFSIZE] /*the event code*/ + +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBevent\fR\fR +.ad +.RS 9n +.rt +The text for the event code in the \fBevent\fR field is returned in the +\fBtext\fR field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtext\fR\fR +.ad +.RS 9n +.rt +The text string describing the name of the event. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fR: Using \fBcsx_Event2Text()\fR +.sp +.in +2 +.nf +xx_event(event_t event, int priority, event_callback_args_t *eca) +{ + event2text_t event2text; + + event2text.event = event; + csx_Event2Text(&event2text); + cmn_err(CE_CONT, "event %s (0x%x)", event2text.text, (int)event); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBcsx_event_handler\fR(9E), \fBcsx_Error2Text\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_FreeHandle.9f b/usr/src/man/man9f/csx_FreeHandle.9f new file mode 100644 index 0000000000..8eec13b0ad --- /dev/null +++ b/usr/src/man/man9f/csx_FreeHandle.9f @@ -0,0 +1,77 @@ +'\" 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_FreeHandle 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_FreeHandle \- free access handle +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_FreeHandle\fR(\fBacc_handle_t *\fR\fIhandle\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 11n +.rt +The access handle returned from \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestWindow\fR(9F), or \fBcsx_DupHandle\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +This function frees the handle, \fIhandle\fR. If the handle was created by the +\fBcsx_DupHandle\fR(9F) function, this function will free the storage +associated with this handle, but will not modify any resources that the +original handle refers to. If the handle was created by a common access setup +function, this function will release the resources associated with this handle. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_DupHandle\fR(9F), \fBcsx_RequestIO\fR(9F), \fBcsx_RequestWindow\fR(9F) +.sp +.LP +\fIPC Card95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_Get8.9f b/usr/src/man/man9f/csx_Get8.9f new file mode 100644 index 0000000000..e1164b91d1 --- /dev/null +++ b/usr/src/man/man9f/csx_Get8.9f @@ -0,0 +1,95 @@ +'\" 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_Get8 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Get8, csx_Get16, csx_Get32, csx_Get64 \- read data from device address +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBuint8_t\fR \fBcsx_Get8\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint32_t\fR \fIoffset\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBcsx_Get16\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint32_t\fR \fIoffset\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBcsx_Get32\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint32_t\fR \fIoffset\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBcsx_Get64\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint64_t\fR \fIoffset\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 11n +.rt +The access handle returned from \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestWindow\fR(9F), or \fBcsx_DupHandle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR \fR +.ad +.RS 11n +.rt +The offset in bytes from the base of the mapped resource. +.RE + +.SH DESCRIPTION +.sp +.LP +These functions generate a read of various sizes from the mapped memory or +device register. +.sp +.LP +The \fBcsx_Get8()\fR, \fBcsx_Get16()\fR, \fBcsx_Get32()\fR, and +\fBcsx_Get64()\fR functions read 8 bits, 16 bits, 32 bits, and 64 bits of data, +respectively, from the device address represented by the handle, \fIhandle\fR, +at an offset in bytes represented by the offset, \fIoffset\fR. +.sp +.LP +Data that consists of more than one byte will automatically be translated to +maintain a consistent view between the host and the device based on the encoded +information in the data access handle. The translation may involve byte +swapping if the host and the device have incompatible endian characteristics. +.SH RETURN VALUES +.sp +.LP +These functions return the value read from the mapped address. +.SH CONTEXT +.sp +.LP +These functions may be called from user, kernel, or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBcsx_DupHandle\fR(9F), \fBcsx_GetMappedAddr\fR(9F), \fBcsx_Put8\fR(9F), +\fBcsx_RepGet8\fR(9F), \fBcsx_RepPut8\fR(9F), \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestWindow\fR(9F) +.sp +.LP +\fIPC Card 95 Standard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_GetFirstClient.9f b/usr/src/man/man9f/csx_GetFirstClient.9f new file mode 100644 index 0000000000..59c14623d8 --- /dev/null +++ b/usr/src/man/man9f/csx_GetFirstClient.9f @@ -0,0 +1,208 @@ +'\" 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 csx_GetFirstClient 9F "16 May 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_GetFirstClient, csx_GetNextClient \- return first or next client +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_GetFirstClient\fR(\fBget_firstnext_client_t *\fR\fIfnc\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBcsx_GetNextClient\fR(\fBget_firstnext_client_t *\fR\fIfnc\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIfnc\fR \fR +.ad +.RS 8n +.rt +Pointer to a \fBget_firstnext_client_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The functions \fBcsx_GetFirstClient()\fR and \fBcsx_GetNextClient()\fR return +information about the first or subsequent \fBPC \fRcards, respectively, that +are installed in the system. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBget_firstnext_client_t\fR are: +.sp +.in +2 +.nf +uint32_t Socket; /* socket number */ +uint32_t Attributes; /* attributes */ +client_handle_t client_handle; /* client handle */ +uint32_t num_clients; /* number of clients */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR \fR +.ad +.RS 18n +.rt +If the \fBCS_GET_FIRSTNEXT_CLIENT_SOCKET_ONLY\fR attribute is set, return +information only on the \fBPC \fRcard installed in this socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR \fR +.ad +.RS 18n +.rt +This field indicates the type of client. The field is bit-mapped; the following +bits are defined: +.sp +.ne 2 +.mk +.na +\fBCS_GET_FIRSTNEXT_CLIENT_ALL_CLIENTS\fR +.ad +.sp .6 +.RS 4n +Return information on all clients. +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_GET_FIRSTNEXT_CLIENT_SOCKET_ONLY\fR +.ad +.sp .6 +.RS 4n +Return client information for the specified socket only. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBclient_handle\fR \fR +.ad +.RS 18n +.rt +The client handle of the \fBPC \fRcard driver is returned in this field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnum_clients\fR \fR +.ad +.RS 18n +.rt +The number of clients is returned in this field. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SOCKET\fR \fR +.ad +.RS 28n +.rt +Socket number is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR \fR +.ad +.RS 28n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_MORE_ITEMS\fR \fR +.ad +.RS 28n +.rt +\fBPC \fRCard driver does not handle the \fBCS_EVENT_CLIENT_INFO\fR event. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_event_handler\fR(9E) +.sp +.LP +\fIPC Card 95 Standard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_GetFirstTuple.9f b/usr/src/man/man9f/csx_GetFirstTuple.9f new file mode 100644 index 0000000000..e09eb60cd5 --- /dev/null +++ b/usr/src/man/man9f/csx_GetFirstTuple.9f @@ -0,0 +1,248 @@ +'\" 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_GetFirstTuple 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_GetFirstTuple, csx_GetNextTuple \- return Card Information Structure tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_GetFirstTuple\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBcsx_GetNextTuple\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBtuple_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The functions \fBcsx_GetFirstTuple()\fR and \fBcsx_GetNextTuple()\fR return the +first and next tuple, respectively, of the specified type in the Card +Information Structure (CIS) for the specified socket. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBtuple_t\fR are: +.sp +.in +2 +.nf +uint32_t Socket; /* socket number */ +uint32_t Attributes; /* Attributes */ +cisdata_t DesiredTuple; /* tuple to search for or flags */ +cisdata_t TupleCode; /* tuple type code */ +cisdata_t TupleLink; /* tuple data body size */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR\fR +.ad +.RS 23n +.rt +Not used in Solaris, but for portability with other Card Services +implementations, it should be set to the logical socket number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR\fR +.ad +.RS 23n +.rt +This field is bit-mapped. The following bits are defined: +.sp +.ne 2 +.mk +.na +\fBTUPLE_RETURN_LINK\fR +.ad +.sp .6 +.RS 4n +Return link tuples if set. The following are link tuples and will only be +returned by this function if the \fBTUPLE_RETURN_LINK\fR bit in the +\fBAttributes\fR field is set: +.sp +.in +2 +.nf + CISTPL_NULL CISTPL_LONGLINK_MFC + CISTPL_LONGLINK_A CISTPL_LINKTARGET + CISTPL_LONGLINK_C CISTPL_NO_LINK + CISTPL_LONGLINK_CB CISTPL_END +.fi +.in -2 + +.RE + +.sp +.ne 2 +.mk +.na +\fBTUPLE_RETURN_IGNORED_TUPLES\fR +.ad +.sp .6 +.RS 4n +Return ignored tuples if set. Ignored tuples will be returned by this function +if the \fBTUPLE_RETURN_IGNORED_TUPLES\fR bit in the \fBAttributes\fR field is +set, see \fBtuple\fR(9S) for more information. The \fBCIS \fRis parsed from the +location setup by the previous \fBcsx_GetFirstTuple()\fR or +\fBcsx_GetNextTuple()\fR request. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDesiredTuple\fR\fR +.ad +.RS 23n +.rt +This field is the tuple value desired. If it is \fBRETURN_FIRST_TUPLE,\fR the +very first tuple of the \fBCIS \fRis returned (if it exists). If this field is +set to \fBRETURN_NEXT_TUPLE,\fR the very next tuple of the \fBCIS \fRis +returned (if it exists). If the \fBDesiredTuple\fR field is any other value on +entry, the \fBCIS \fRis searched in an attempt to locate a tuple which matches. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTupleCode,TupleLink\fR\fR +.ad +.RS 23n +.rt +These fields are the values returned from the tuple found. If there are no +tuples on the card, \fBCS_NO_MORE_ITEMS\fR is returned. +.RE + +.sp +.LP +Since the \fBcsx_GetFirstTuple()\fR, \fBcsx_GetNextTuple()\fR, and +\fBcsx_GetTupleData\fR(9F) functions all share the same \fBtuple_t\fR +structure, some fields in the \fBtuple_t\fR structure are unused or reserved +when calling this function and these fields must not be initialized by the +client. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRcard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_MORE_ITEMS\fR\fR +.ad +.RS 27n +.rt +Desired tuple not found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetTupleData\fR(9F), \fBcsx_ParseTuple\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card \fR\fI95Standard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_GetHandleOffset.9f b/usr/src/man/man9f/csx_GetHandleOffset.9f new file mode 100644 index 0000000000..31c24e3a12 --- /dev/null +++ b/usr/src/man/man9f/csx_GetHandleOffset.9f @@ -0,0 +1,73 @@ +'\" 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 csx_GetHandleOffset 9F "16 May 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_GetHandleOffset \- return current access handle offset +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + +\fBint32_t\fR \fBcsx_GetHandleOffset\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint32_t *\fR\fIoffset\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 11n +.rt +Access handle returned by \fBcsx_RequestIRQ\fR(9F) or \fBcsx_RequestIO\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR \fR +.ad +.RS 11n +.rt +Pointer to a \fBuint32_t\fR in which the current access handle offset is +returned. +.RE + +.SH DESCRIPTION +.sp +.LP +This function returns the current offset for the access handle, \fIhandle\fR, +in \fIoffset\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 15n +.rt +Successful operation. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_RequestIO\fR(9F), \fBcsx_RequestIRQ\fR(9F), +\fBcsx_SetHandleOffset\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_GetMappedAddr.9f b/usr/src/man/man9f/csx_GetMappedAddr.9f new file mode 100644 index 0000000000..06f24725c0 --- /dev/null +++ b/usr/src/man/man9f/csx_GetMappedAddr.9f @@ -0,0 +1,101 @@ +'\" 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_GetMappedAddr 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_GetMappedAddr \- return mapped virtual address +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_GetMappedAddr\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBvoid **\fR\fIaddr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 11n +.rt +The access handle returned from \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestWindow\fR(9F), or \fBcsx_DupHandle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR \fR +.ad +.RS 11n +.rt +The virtual or \fBI/O \fRport number represented by the handle. +.RE + +.SH DESCRIPTION +.sp +.LP +This function returns the mapped virtual address or the mapped \fBI/O \fRport +number represented by the handle, \fIhandle\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +The resulting address or \fBI/O \fRport number can be directly accessed by the +caller. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_FAILURE\fR \fR +.ad +.RS 28n +.rt +The resulting address or \fBI/O \fRport number can not be directly accessed by +the caller; the caller must make all accesses to the mapped area via the common +access functions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user, kernel, or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBcsx_DupHandle\fR(9F), \fBcsx_Get8\fR(9F), \fBcsx_Put8\fR(9F), +\fBcsx_RepGet8\fR(9F), \fBcsx_RepPut8\fR(9F), \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestWindow\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_GetStatus.9f b/usr/src/man/man9f/csx_GetStatus.9f new file mode 100644 index 0000000000..c701e04801 --- /dev/null +++ b/usr/src/man/man9f/csx_GetStatus.9f @@ -0,0 +1,545 @@ +'\" 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_GetStatus 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_GetStatus \- return the current status of a PC Card and its socket +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_GetStatus\fR(\fBclient_handle_t\fR \fIch\fR, \fBget_status_t *\fR\fIgs\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIgs\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBget_status_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function returns the current status of a \fBPC \fRCard and its socket. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBget_status_t\fR are: +.sp +.in +2 +.nf +uint32_t Socket; /* socket number*/ +uint32_t CardState; /* "live" card status for this client*/ +uint32_t SocketState; /* latched socket values */ +uint32_t raw_CardState; /* raw live card status */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR \fR +.ad +.RS 18n +.rt +Not used in Solaris, but for portability with other Card Services +implementations, it should be set to the logical socket number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCardState\fR \fR +.ad +.RS 18n +.rt +The \fBCardState\fR field is the bit-mapped output data returned from Card +Services. The bits identify what Card Services thinks the current state of the +installed \fBPC \fRCard is. The bits are: +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_WRITE_PROTECTED\fR +.ad +.sp .6 +.RS 4n +Card is write protected +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_CARD_LOCKED\fR +.ad +.sp .6 +.RS 4n +Card is locked +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_EJECTION_REQUEST\fR +.ad +.sp .6 +.RS 4n +Ejection request in progress +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_INSERTION_REQUEST\fR +.ad +.sp .6 +.RS 4n +Insertion request in progress +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_BATTERY_DEAD\fR +.ad +.sp .6 +.RS 4n +Card battery is dead +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_BATTERY_DEAD\fR +.ad +.sp .6 +.RS 4n +Card battery is dead (\fBBVD1\fR) +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_BATTERY_LOW\fR +.ad +.sp .6 +.RS 4n +Card battery is low (\fBBVD2\fR) +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_CARD_READY\fR +.ad +.sp .6 +.RS 4n +Card is READY +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_CARD_INSERTED\fR +.ad +.sp .6 +.RS 4n +Card is inserted +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_REQ_ATTN\fR +.ad +.sp .6 +.RS 4n +Extended status attention request +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_RES_EVT1\fR +.ad +.sp .6 +.RS 4n +Extended status reserved event status +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_RES_EVT2\fR +.ad +.sp .6 +.RS 4n +Extended status reserved event status +.RE + +.sp +.ne 2 +.mk +.na +\fB CS_STATUS_RES_EVT3\fR +.ad +.sp .6 +.RS 4n +Extended status reserved event status +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_VCC_50\fR +.ad +.sp .6 +.RS 4n +5.0 Volts Vcc Indicated +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_VCC_33\fR +.ad +.sp .6 +.RS 4n +3.3 Volts Vcc Indicated +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_VCC_XX\fR +.ad +.sp .6 +.RS 4n +X.X Volts Vcc Indicated +.RE + +The state of the \fBCS_STATUS_CARD_INSERTED\fR bit indicates whether the \fBPC +\fRCard associated with this driver instance, not just any card, is inserted in +the socket. If an \fBI/O \fRcard is installed in the specified socket, card +state is returned from the \fBPRR\fR (Pin Replacement Register) and the +\fBESR\fR (Extended Status Register) (if present). If certain state bits are +not present in the \fBPRR\fR or \fBESR\fR, a simulated state bit value is +returned as defined below: +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_WRITE_PROTECTED\fR +.ad +.RS 29n +.rt +Not write protected +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_BATTERY_DEAD\fR +.ad +.RS 29n +.rt +Power good +.RE + +.sp +.ne 2 +.mk +.na +\fBPCS_STATUS_BATTERY_LOW\fR +.ad +.RS 29n +.rt +Power good +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_CARD_READY\fR +.ad +.RS 29n +.rt +Ready +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_REQ_ATTN\fR +.ad +.RS 29n +.rt +Not set +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_RES_EVT1\fR +.ad +.RS 29n +.rt +Not set +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_RES_EVT2\fR +.ad +.RS 29n +.rt +Not set +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_STATUS_RES_EVT3\fR +.ad +.RS 29n +.rt +Not set +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSocketState\fR \fR +.ad +.RS 18n +.rt +The \fBSocketState\fR field is a bit-map of the current card and socket state. +The bits are: +.sp +.ne 2 +.mk +.na +\fBCS_SOCK_STATUS_WRITE_PROTECT_CHANGE\fR +.ad +.sp .6 +.RS 4n +Write Protect +.RE + +.sp +.ne 2 +.mk +.na +\fBECS_SOCK_STATUS_CARD_LOCK_CHANGE\fR +.ad +.sp .6 +.RS 4n +Card Lock Change +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_SOCK_STATUS_EJECTION_PENDING\fR +.ad +.sp .6 +.RS 4n +Ejection Request +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_SOCK_STATUS_INSERTION_PENDING\fR +.ad +.sp .6 +.RS 4n +Insertion Request +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_SOCK_STATUS_BATTERY_DEAD_CHANGE\fR +.ad +.sp .6 +.RS 4n +Battery Dead +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_SOCK_STATUS_BATTERY_LOW_CHANGE\fR +.ad +.sp .6 +.RS 4n +Battery Low +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_SOCK_STATUS_CARD_READY_CHANGE\fR +.ad +.sp .6 +.RS 4n +Ready Change +.RE + +.sp +.ne 2 +.mk +.na +\fBCS_SOCK_STATUS_CARD_INSERTION_CHANGE\fR +.ad +.sp .6 +.RS 4n +Card is inserted +.sp + The state reported in the SocketState field may be different from the state +reported in the CardState field. Clients should normally depend only on the +state reported in the CardState field. +.sp +The state reported in the \fBSocketState\fR field may be different from the +state reported in the \fBCardState\fR field. Clients should normally depend +only on the state reported in the \fBCardState\fR field. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBraw_CardState\fR \fR +.ad +.RS 18n +.rt +The \fBraw_CardState\fR field is a Solaris-specific extension that allows the +client to determine if any card is inserted in the socket. The bit definitions +in the \fBraw_CardState\fR field are identical to those in the \fBCardState\fR +field with the exception that the \fBCS_STATUS_CARD_INSERTED\fR bit in the +\fBraw_CardState\fR field is set whenever any card is inserted into the socket. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SOCKET\fR \fR +.ad +.RS 28n +.rt +Error getting socket state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.sp +.LP +\fBCS_NO_CARD\fR will not be returned if there is no \fBPC \fRCard present in +the socket. +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_RegisterClient\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_GetTupleData.9f b/usr/src/man/man9f/csx_GetTupleData.9f new file mode 100644 index 0000000000..f2ab402235 --- /dev/null +++ b/usr/src/man/man9f/csx_GetTupleData.9f @@ -0,0 +1,272 @@ +'\" 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_GetTupleData 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_GetTupleData \- return the data portion of a tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_GetTupleData\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBtuple_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function returns the data portion of a tuple, as returned by the +\fBcsx_GetFirstTuple\fR(9F) and \fBcsx_GetNextTuple\fR(9F) functions. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBtuple_t\fR are: +.sp +.LP +The fields are defined as follows: +.sp +.in +2 +.nf +uint32_t Socket; /* socket number */ +uint32_t Attributes; /* tuple attributes*/ +cisdata_t DesiredTuple; /* tuple to search for*/ +cisdata_t TupleOffset; /* tuple data offset*/ +cisdata_t TupleDataMax; /* max tuple data size*/ +cisdata_t TupleDataLen; /* actual tuple data length*/ +cisdata_t TupleData[CIS_MAX_TUPLE_DATA_LEN];/* tuple body data buffer*/ +cisdata_t TupleCode; /* tuple type code*/ +cisdata_t TupleLink; /* tuple link */ +.fi +.in -2 + +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR\fR +.ad +.RS 16n +.rt +Not used in Solaris, but for portability with other Card Services +implementations, it should be set to the logical socket number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR\fR +.ad +.RS 16n +.rt +Initialized by \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F); the +client must not modify the value in this field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDesiredTuple\fR\fR +.ad +.RS 16n +.rt +Initialized by \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F); the +client must not modify the value in this field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTupleOffset\fR\fR +.ad +.RS 16n +.rt +This field allows partial tuple information to be retrieved, starting anywhere +within the tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTupleDataMax\fR\fR +.ad +.RS 16n +.rt +This field is the size of the tuple data buffer that Card Services uses to +return raw tuple data from \fBcsx_GetTupleData\fR. It can be larger than the +number of bytes in the tuple data body. Card Services ignores any value placed +here by the client. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTupleDataLen\fR\fR +.ad +.RS 16n +.rt +This field is the actual size of the tuple data body. It represents the number +of tuple data body bytes returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTupleData\fR\fR +.ad +.RS 16n +.rt +This field is an array of bytes containing the raw tuple data body contents. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTupleCode\fR\fR +.ad +.RS 16n +.rt +Initialized by \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F); the +client must not modify the value in this field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTupleLink\fR\fR +.ad +.RS 16n +.rt +Initialized by \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F); the +client must not modify the value in this field. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_ARGS\fR\fR +.ad +.RS 27n +.rt +Data from prior \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F) is +corrupt. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_MORE_ITEMS\fR\fR +.ad +.RS 27n +.rt +Card Services was not able to read the tuple from the \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_ParseTuple\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_MakeDeviceNode.9f b/usr/src/man/man9f/csx_MakeDeviceNode.9f new file mode 100644 index 0000000000..bd52f24683 --- /dev/null +++ b/usr/src/man/man9f/csx_MakeDeviceNode.9f @@ -0,0 +1,270 @@ +'\" 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_MakeDeviceNode 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_MakeDeviceNode, csx_RemoveDeviceNode \- create and remove minor nodes on +behalf of the client +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_MakeDeviceNode\fR(\fBclient_handle_t\fR \fIch\fR, \fBmake_device_node_t *\fR\fIdn\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBcsx_RemoveDeviceNode\fR(\fBclient_handle_t\fR \fIch\fR, \fBremove_device_node_t *\fR\fIdn\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdn\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBmake_device_node_t\fR or \fBremove_device_node_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBcsx_MakeDeviceNode()\fR and \fBcsx_RemoveDeviceNode()\fR are +Solaris-specific extensions to allow the client to request that device nodes in +the filesystem are created or removed, respectively, on its behalf. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBmake_device_node_t\fR are: +.sp +.in +2 +.nf +uint32_t Action; /* device operation */ +uint32_t NumDevNodes; /* number of nodes to create */ +devnode_desc_t *devnode_desc; /* description of device nodes */ +.fi +.in -2 + +.sp +.LP +The structure members of \fBremove_device_node_t\fR are: +.sp +.in +2 +.nf +uint32_t Action; /* device operation */ +uint32_t NumDevNodes; /* number of nodes to remove */ +devnode_desc_t *devnode_desc; /* description of device nodes */ +.fi +.in -2 + +.sp +.LP +The structure members of \fBdevnode_desc_t\fR are: +.sp +.in +2 +.nf +char *name; /* device node path and name */ +int32_t spec_type; /* device special type (block or char) */ +int32_t minor_num; /* device node minor number */ +char *node_type; /* device node type */ +.fi +.in -2 + +.sp +.LP +The \fBAction\fR field is used to specify the operation that +\fBcsx_MakeDeviceNode()\fR and \fBcsx_RemoveDeviceNode()\fR should perform. +.sp +.LP +The following \fBAction\fR values are defined for \fBcsx_MakeDeviceNode()\fR: +.sp +.ne 2 +.mk +.na +\fBCREATE_DEVICE_NODE\fR +.ad +.RS 22n +.rt +Create \fBNumDevNodes\fR minor nodes +.RE + +.sp +.LP +The following \fBAction\fR values are defined for \fBcsx_RemoveDeviceNode()\fR: +.sp +.ne 2 +.mk +.na +\fBREMOVE_DEVICE_NODE\fR +.ad +.RS 27n +.rt +Remove \fBNumDevNodes\fR minor nodes +.RE + +.sp +.ne 2 +.mk +.na +\fBREMOVE_ALL_DEVICE_NODES\fR +.ad +.RS 27n +.rt +Remove all minor nodes for this client +.RE + +.sp +.LP +For \fBcsx_MakeDeviceNode()\fR, if the \fBAction\fR field is: +.sp +.ne 2 +.mk +.na +\fB\fBCREATE_DEVICE_NODE\fR \fR +.ad +.RS 23n +.rt +The \fBNumDevNodes\fR field must be set to the number of minor devices to +create, and the client must allocate the quantity of \fBdevnode_desc_t\fR +structures specified by \fBNumDevNodes\fR and fill out the fields in the +\fBdevnode_desc_t\fR structure with the appropriate minor node information. The +meanings of the fields in the \fBdevnode_desc_t\fR structure are identical to +the parameters of the same name to the \fBddi_create_minor_node\fR(9F) \fBDDI +\fRfunction. +.RE + +.sp +.LP +For \fBcsx_RemoveDeviceNode()\fR, if the \fBAction\fR field is: +.sp +.ne 2 +.mk +.na +\fB\fBREMOVE_DEVICE_NODE\fR \fR +.ad +.RS 28n +.rt +The \fBNumDevNodes\fR field must be set to the number of minor devices to +remove, and the client must allocate the quantity of \fBdevnode_desc_t\fR +structures specified by \fBNumDevNodes\fR and fill out the fields in the +\fBdevnode_desc_t\fR structure with the appropriate minor node information. The +meanings of the fields in the \fBdevnode_desc_t\fR structure are identical to +the parameters of the same name to the \fBddi_remove_minor_node\fR(9F) \fBDDI +\fRfunction. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBREMOVE_ALL_DEVICE_NODES\fR \fR +.ad +.RS 28n +.rt +The \fBNumDevNodes\fR field must be set to \fB0\fR and the \fBdevnode_desc_t\fR +structure pointer must be set to \fINULL\fR. All device nodes for this client +will be removed from the filesystem. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_ATTRIBUTE\fR \fR +.ad +.RS 28n +.rt +The value of one or more arguments is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_ARGS\fR \fR +.ad +.RS 28n +.rt +Action is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_OUT_OF_RESOURCE\fR \fR +.ad +.RS 28n +.rt +Unable to create or remove device node. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_RegisterClient\fR(9F), \fBddi_create_minor_node\fR(9F), +\fBddi_remove_minor_node\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_MapLogSocket.9f b/usr/src/man/man9f/csx_MapLogSocket.9f new file mode 100644 index 0000000000..0f65eedca7 --- /dev/null +++ b/usr/src/man/man9f/csx_MapLogSocket.9f @@ -0,0 +1,149 @@ +'\" 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_MapLogSocket 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_MapLogSocket \- return the physical socket number associated with the +client handle +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_MapLogSocket\fR(\fBclient_handle_t\fR \fIch\fR, \fBmap_log_socket_t *\fR\fIls\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIls\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBmap_log_socket_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function returns the physical socket number associated with the client +handle. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBmap_log_socket_t\fR are: +.sp +.in +2 +.nf +uint32_t LogSocket; /* logical socket number */ +uint32_t PhyAdapter; /* physical adapter number */ +uint32_t PhySocket; /* physical socket number */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBLogSocket\fR \fR +.ad +.RS 15n +.rt +Not used by this implementation of Card Services and can be set to any +arbitrary value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPhyAdapter\fR \fR +.ad +.RS 15n +.rt +Returns the physical adapter number, which is always \fB0\fR in the Solaris +implementation of Card Services. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPhySocket\fR \fR +.ad +.RS 15n +.rt +Returns the physical socket number associated with the client handle. The +physical socket number is typically used as part of an error or message string +or if the client creates minor nodes based on the physical socket number. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_RegisterClient\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_MapMemPage.9f b/usr/src/man/man9f/csx_MapMemPage.9f new file mode 100644 index 0000000000..06ad098dda --- /dev/null +++ b/usr/src/man/man9f/csx_MapMemPage.9f @@ -0,0 +1,168 @@ +'\" 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_MapMemPage 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_MapMemPage \- map the memory area on a PC Card +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_MapMemPage\fR(\fBwindow_handle_t\fR \fIwh\fR, \fBmap_mem_page_t *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIwh\fR \fR +.ad +.RS 7n +.rt +Window handle returned from \fBcsx_RequestWindow\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBmap_mem_page_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function maps the memory area on a \fBPC \fRCard into a page of a window +allocated with the \fBcsx_RequestWindow\fR(9F) function. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBmap_mem_page_t\fR are: +.sp +.in +2 +.nf +uint32_t CardOffset; /* card offset */ +uint32_t Page; /* page number */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBCardOffset\fR \fR +.ad +.RS 15n +.rt +The absolute offset in bytes from the beginning of the \fBPC \fRCard to map +into system memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPage\fR \fR +.ad +.RS 15n +.rt +Used internally by Card Services; clients must set this field to \fB0\fR before +calling this function. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_OFFSET\fR \fR +.ad +.RS 28n +.rt +Offset is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_PAGE\fR \fR +.ad +.RS 28n +.rt +Page is not zero. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR \fR +.ad +.RS 28n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_ModifyWindow\fR(9F), \fBcsx_ReleaseWindow\fR(9F), +\fBcsx_RequestWindow\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_ModifyConfiguration.9f b/usr/src/man/man9f/csx_ModifyConfiguration.9f new file mode 100644 index 0000000000..fedbbfb6f0 --- /dev/null +++ b/usr/src/man/man9f/csx_ModifyConfiguration.9f @@ -0,0 +1,286 @@ +'\" 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 csx_ModifyConfiguration 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_ModifyConfiguration \- modify socket and PC Card Configuration Register +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_ModifyConfiguration\fR(\fBclient_handle_t\fR \fIch\fR, \fBmodify_config_t *\fR\fImc\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImc\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBmodify_config_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function allows a socket and \fBPC \fRCard configuration to be modified. +This function can only modify a configuration requested via +\fBcsx_RequestConfiguration\fR(9F). +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBmodify_config_t\fR are: +.sp +.in +2 +.nf +uint32_t Socket; /* socket number */ +uint32_t Attributes; /* attributes to modify */ +uint32_t Vpp1; /* Vpp1 value */ +uint32_t Vpp2; /* Vpp2 value */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR \fR +.ad +.RS 15n +.rt +Not used in Solaris, but for portability with other Card Services +implementations, it should be set to the logical socket number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR \fR +.ad +.RS 15n +.rt +This field is bit-mapped. The following bits are defined: +.sp +.ne 2 +.mk +.na +\fBCONF_ENABLE_IRQ_STEERING\fR +.ad +.RS 28n +.rt +Enable IRQ steering. Set to connect the \fBPC \fRCard \fBIREQ \fRline to a +previously selected system interrupt. +.RE + +.sp +.ne 2 +.mk +.na +\fBCONF_IRQ_CHANGE_VALID\fR +.ad +.RS 28n +.rt +IRQ change valid. Set to request the \fBIRQ \fRsteering enable to be changed. +.RE + +.sp +.ne 2 +.mk +.na +\fBCONF_VPP1_CHANGE_VALID\fR +.ad +.RS 28n +.rt +Vpp1 change valid. These bits are set to request a change to the corresponding +voltage level for the \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fBCONF_VPP2_CHANGE_VALID\fR +.ad +.RS 28n +.rt +Vpp2 change valid. These bits are set to request a change to the corresponding +voltage level for the \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fBCONF_VSOVERRIDE\fR +.ad +.RS 28n +.rt +Override VS pins. For Low Voltage keyed cards, must be set if a client desires +to apply a voltage inappropriate for this card to any pin. After card insertion +and prior to the first \fBcsx_RequestConfiguration\fR(9F) call for this client, +the voltage levels applied to the card will be those specified by the Card +Interface Specification. (See \fBWARNINGS\fR.) +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBVpp1\fR, \fBVpp2\fR\fR +.ad +.RS 15n +.rt +Represent voltages expressed in tenths of a volt. Values from \fB0\fR to +\fB25.5\fR volts may be set. To be valid, the exact voltage must be available +from the system. To be compliant with the \fIPC Card 95 Standard, +PCMCIA/JEIDA\fR, systems must always support \fB5.0\fR volts for both \fBVcc\fR +and \fBVpp\fR. (See \fBWARNINGS\fR.) +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid or \fBcsx_RequestConfiguration\fR(9F) not done. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SOCKET\fR \fR +.ad +.RS 28n +.rt +Error getting/setting socket hardware parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_VPP\fR \fR +.ad +.RS 28n +.rt +Requested \fBVpp\fR is not available on socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR \fR +.ad +.RS 28n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_RegisterClient\fR(9F), \fBcsx_ReleaseConfiguration\fR(9F), +\fBcsx_ReleaseIO\fR(9F), \fBcsx_ReleaseIRQ\fR(9F), +\fBcsx_RequestConfiguration\fR(9F), \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestIRQ\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR +.SH WARNINGS +.RS +4 +.TP +1. +\fBCONF_VSOVERRIDE\fR is provided for clients that have a need to override +the information provided in the CIS. The client must exercise caution when +setting this as it overrides any voltage level protection provided by Card +Services. +.RE +.RS +4 +.TP +2. +Using \fBcsx_ModifyConfiguration()\fR to set \fBVpp\fR to \fB0\fR volts may +result in the loss of a \fBPC \fRCard's state. Any client setting \fBVpp\fR to +\fB0\fR volts is responsible for insuring that the \fBPC \fRCard's state is +restored when power is re-applied to the card. +.RE +.SH NOTES +.sp +.LP +Mapped \fBIO \fRaddresses can only be changed by first releasing the current +configuration and \fBIO \fRresources with \fBcsx_ReleaseConfiguration\fR(9F) +and \fBcsx_ReleaseIO\fR(9F), requesting new \fBIO \fRresources and a new +configuration with \fBcsx_RequestIO\fR(9F), followed by +\fBcsx_RequestConfiguration\fR(9F). +.sp +.LP +\fBIRQ \fRpriority can only be changed by first releasing the current +configuration and \fBIRQ \fRresources with \fBcsx_ReleaseConfiguration\fR(9F) +and \fBcsx_ReleaseIRQ\fR(9F), requesting new \fBIRQ \fRresources and a new +configuration with \fBcsx_RequestIRQ\fR(9F), followed by +\fBcsx_RequestConfiguration\fR(9F). +.sp +.LP +\fBVcc\fR can not be changed using \fBcsx_ModifyConfiguration()\fR. \fBVcc\fR +may be changed by first invoking \fBcsx_ReleaseConfiguration\fR(9F), followed +by \fBcsx_RequestConfiguration\fR(9F) with a new \fBVcc\fR value. diff --git a/usr/src/man/man9f/csx_ModifyWindow.9f b/usr/src/man/man9f/csx_ModifyWindow.9f new file mode 100644 index 0000000000..d1881b4eac --- /dev/null +++ b/usr/src/man/man9f/csx_ModifyWindow.9f @@ -0,0 +1,305 @@ +'\" 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 csx_ModifyWindow 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_ModifyWindow \- modify window attributes +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_ModifyWindow\fR(\fBwindow_handle_t\fR \fIwh\fR, \fBmodify_win_t *\fR\fImw\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIwh\fR \fR +.ad +.RS 7n +.rt +Window handle returned from \fBcsx_RequestWindow\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImw\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBmodify_win_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function modifies the attributes of a window allocated by the +\fBcsx_RequestWindow\fR(9F) function. +.sp +.LP +Only some of the window attributes or the access speed field may be modified by +this request. The \fBcsx_MapMemPage\fR(9F) function is also used to set the +offset into \fBPC \fRCard memory to be mapped into system memory for paged +windows. The \fBcsx_RequestWindow\fR(9F) and \fBcsx_ReleaseWindow\fR(9F) +functions must be used to change the window base or size. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBmodify_win_t\fR are: +.sp +.in +2 +.nf +uint32_t Attributes; /* window flags */ +uint32_t AccessSpeed; /* window access speed */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR \fR +.ad +.RS 15n +.rt +This field is bit-mapped and defined as follows: +.sp +.ne 2 +.mk +.na +\fBWIN_MEMORY_TYPE_CM\fR +.ad +.RS 26n +.rt +Window points to Common Memory area. Set this to map the window to Common +Memory. +.RE + +.sp +.ne 2 +.mk +.na +\fBWIN_MEMORY_TYPE_AM\fR +.ad +.RS 26n +.rt +Window points to Attribute Memory area. Set this to map the window to Attribute +Memory. +.RE + +.sp +.ne 2 +.mk +.na +\fBWIN_ENABLE\fR +.ad +.RS 26n +.rt +Enable Window. The client must set this to enable the window. +.RE + +.sp +.ne 2 +.mk +.na +\fBWIN_ACCESS_SPEED_VALID\fR +.ad +.RS 26n +.rt +\fBAccessSpeed\fR valid. The client must set this when the \fBAccessSpeed\fR +field has a value that the client wants set for the window. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAccessSpeed\fR\fR +.ad +.RS 15n +.rt +The bit definitions for this field use the format of the extended speed byte of +the Device \fBID \fRtuple. If the mantissa is \fB0\fR (noted as reserved in the +\fIPC Card 95 Standard\fR), the lower bits are a binary code representing a +speed from the list below. Numbers in the first column are codes; items in the +second column are speeds. +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 9n +.rt +Reserved: do not use +.RE + +.sp +.ne 2 +.mk +.na +\fB1\fR +.ad +.RS 9n +.rt +\fB250 nsec\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB2\fR +.ad +.RS 9n +.rt +\fB200 nsec\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB3\fR +.ad +.RS 9n +.rt +\fB150 nsec\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB4\fR +.ad +.RS 9n +.rt +\fB100 nsec\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB5 - 7\fR +.ad +.RS 9n +.rt +Reserved: do not use +.RE + +It is recommended that clients use the \fBcsx_ConvertSpeed\fR(9F) function to +generate the appropriate \fBAccessSpeed\fR values rather than manually +perturbing the \fBAccessSpeed\fR field. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Window handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR \fR +.ad +.RS 28n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_OFFSET\fR \fR +.ad +.RS 28n +.rt +Error getting/setting window hardware parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_WINDOW\fR \fR +.ad +.RS 28n +.rt +Error getting/setting window hardware parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SPEED\fR \fR +.ad +.RS 28n +.rt +\fBAccessSpeed\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_ConvertSpeed\fR(9F), \fBcsx_MapMemPage\fR(9F), +\fBcsx_ReleaseWindow\fR(9F), \fBcsx_RequestWindow\fR(9F) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_ParseTuple.9f b/usr/src/man/man9f/csx_ParseTuple.9f new file mode 100644 index 0000000000..ccab40cce1 --- /dev/null +++ b/usr/src/man/man9f/csx_ParseTuple.9f @@ -0,0 +1,207 @@ +'\" 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_ParseTuple 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_ParseTuple \- generic tuple parser +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_ParseTuple\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, \fBcisparse_t *\fR\fIcp\fR, + \fBcisdata_t\fR \fIcd\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcp\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBcisparse_t\fR structure that unifies all tuple parsing +structures. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcd\fR \fR +.ad +.RS 7n +.rt +Extended tuple data for some tuples. +.RE + +.SH DESCRIPTION +.sp +.LP +This function is the generic tuple parser entry point. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcisparse_t\fR are: +.sp +.in +2 +.nf + typedef union cisparse_t { + cistpl_config_t cistpl_config; + cistpl_device_t cistpl_device; + cistpl_vers_1_t cistpl_vers_1; + cistpl_vers_2_t cistpl_vers_2; + cistpl_jedec_t cistpl_jedec; + cistpl_format_t cistpl_format; + cistpl_geometry_t cistpl_geometry; + cistpl_byteorder_t cistpl_byteorder; + cistpl_date_t cistpl_date; + cistpl_battery_t cistpl_battery; + cistpl_org_t cistpl_org; + cistpl_manfid_t cistpl_manfid; + cistpl_funcid_t cistpl_funcid; + cistpl_funce_t cistpl_funce; + cistpl_cftable_entry_t cistpl_cftable_entry; + cistpl_linktarget_t cistpl_linktarget; + cistpl_longlink_ac_t cistpl_longlink_ac; + cistpl_longlink_mfc_t cistpl_longlink_mfc; + cistpl_spcl_t cistpl_spcl; + cistpl_swil_t cistpl_swil; + cistpl_bar_t cistpl_bar; + cistpl_devicegeo_t cistpl_devicegeo; + cistpl_longlink_cb_t cistpl_longlink_cb; + cistpl_get_tuple_name_t cistpl_get_tuple_name; + } cisparse_t; +.fi +.in -2 + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR \fR +.ad +.RS 28n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR \fR +.ad +.RS 28n +.rt +No \fBPC\fR Card in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_CIS\fR \fR +.ad +.RS 28n +.rt +Generic parser error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR \fR +.ad +.RS 28n +.rt +No Card Information Structure (\fBCIS\fR) on \fBPC\fR Card. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA\fR hardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_Parse_CISTPL_BATTERY\fR(9F), \fBcsx_Parse_CISTPL_BYTEORDER\fR(9F), +\fBcsx_Parse_CISTPL_CFTABLE_ENTRY\fR(9F), \fBcsx_Parse_CISTPL_CONFIG\fR(9F), +\fBcsx_Parse_CISTPL_DATE\fR(9F), \fBcsx_Parse_CISTPL_DEVICE\fR(9F), +\fBcsx_Parse_CISTPL_FUNCE\fR(9F), \fBcsx_Parse_CISTPL_FUNCID\fR(9F), +\fBcsx_Parse_CISTPL_JEDEC_C\fR(9F), \fBcsx_Parse_CISTPL_MANFID\fR(9F), +\fBcsx_Parse_CISTPL_SPCL\fR(9F), \fBcsx_Parse_CISTPL_VERS_1\fR(9F), +\fBcsx_Parse_CISTPL_VERS_2\fR(9F), \fBcsx_RegisterClient\fR(9F), +\fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_BATTERY.9f b/usr/src/man/man9f/csx_Parse_CISTPL_BATTERY.9f new file mode 100644 index 0000000000..9cf78c8187 --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_BATTERY.9f @@ -0,0 +1,186 @@ +'\" 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_Parse_CISTPL_BATTERY 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_BATTERY \- parse the Battery Replacement Date tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_BATTERY\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_battery_t *\fR\fIcb\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcb\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBcistpl_battery_t\fR structure which contains the parsed +\fBCISTPL_BATTERY\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Battery Replacement Date tuple, \fBCISTPL_BATTERY,\fR +into a form usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_BATTERY\fR tuple is an optional tuple which shall be present only +in \fBPC \fRCards with battery-backed storage. It indicates the date on which +the battery was replaced, and the date on which the battery is expected to need +replacement. Only one \fBCISTPL_BATTERY\fR tuple is allowed per \fBPC \fRCard. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_battery_t\fR are: +.sp +.in +2 +.nf +uint32_t rday; /* date battery last replaced */ +uint32_t xday; /* date battery due for replacement */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBrday\fR\fR +.ad +.RS 8n +.rt +This field indicates the date on which the battery was last replaced. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBxday\fR\fR +.ad +.RS 8n +.rt +This field indicates the date on which the battery should be replaced. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_BYTEORDER.9f b/usr/src/man/man9f/csx_Parse_CISTPL_BYTEORDER.9f new file mode 100644 index 0000000000..ac5e82dd2b --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_BYTEORDER.9f @@ -0,0 +1,241 @@ +'\" 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 csx_Parse_CISTPL_BYTEORDER 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_BYTEORDER \- parse the Byte Order tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_BYTEORDER\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_byteorder_t *\fR\fIcbo\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 8n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR \fR +.ad +.RS 8n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcbo\fR \fR +.ad +.RS 8n +.rt +Pointer to a \fBcistpl_byteorder_t\fR structure which contains the parsed +\fBCISTPL_BYTEORDER\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Byte Order tuple, \fBCISTPL_BYTEORDER\fR, into a form +usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_BYTEORDER\fR tuple shall only appear in a partition tuple set for +a memory-like partition. It specifies two parameters: the order for multi-byte +data, and the order in which bytes map into words for 16-bit cards. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_byteorder_t\fR are: +.sp +.in +2 +.nf +uint32_t order; /* byte order code */ +uint32_t map; /* byte mapping code */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBorder\fR \fR +.ad +.RS 10n +.rt +This field specifies the byte order for multi-byte numeric data. +.sp +.ne 2 +.mk +.na +\fBTPLBYTEORD_LOW\fR +.ad +.RS 18n +.rt +Little endian order +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLBYTEORD_VS\fR +.ad +.RS 18n +.rt +Vendor specific +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBmap\fR \fR +.ad +.RS 10n +.rt +This field specifies the byte mapping for 16-bit or wider cards. +.sp +.ne 2 +.mk +.na +\fBTPLBYTEMAP_LOW\fR +.ad +.RS 19n +.rt +Byte zero is least significant byte +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLBYTEMAP_HIGH\fR +.ad +.RS 19n +.rt +Byte zero is most significant byte +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLBYTEMAP_VS\fR +.ad +.RS 19n +.rt +Vendor specific mapping +.RE + +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR \fR +.ad +.RS 28n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR \fR +.ad +.RS 28n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR \fR +.ad +.RS 28n +.rt +No Card Information Structure (CIS) \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_CFTABLE_ENTRY.9f b/usr/src/man/man9f/csx_Parse_CISTPL_CFTABLE_ENTRY.9f new file mode 100644 index 0000000000..29585a591e --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_CFTABLE_ENTRY.9f @@ -0,0 +1,961 @@ +'\" 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_Parse_CISTPL_CFTABLE_ENTRY 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_CFTABLE_ENTRY \- parse 16-bit Card Configuration Table Entry +tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_CFTABLE_ENTRY\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_cftable_entry_t *\fR\fIcft\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcft\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBcistpl_cftable_entry_t\fR structure which contains the parsed +\fBCISTPL_CFTABLE_ENTRY\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the 16 bit Card Configuration Table Entry tuple, +\fBCISTPL_CFTABLE_ENTRY,\fR into a form usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_CFTABLE_ENTRY\fR tuple is used to describe each possible +configuration of a \fBPC \fRCard and to distinguish among the permitted +configurations. The \fBCISTPL_CONFIG\fR tuple must precede all +\fBCISTPL_CFTABLE_ENTRY\fR tuples. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_cftable_entry_t\fR are: +.sp +.in +2 +.nf +uint32_t flags; /* valid descriptions */ +uint32_t ifc; /* interface description */ + /* information */ +uint32_t pin; /* values for PRR */ +uint32_t index; /* configuration index number */ +cistpl_cftable_entry_pd_t pd; /* power requirements */ + /* description */ +cistpl_cftable_entry_speed_t speed; /* device speed description */ +cistpl_cftable_entry_io_t io; /* device I/O map */ +cistpl_cftable_entry_irq_t irq; /* device IRQ utilization */ +cistpl_cftable_entry_mem_t mem; /* device memory space */ +cistpl_cftable_entry_misc_t misc; /* miscellaneous + /* device features */ +.fi +.in -2 + +.sp +.LP +The \fBflags\fR field is defined and bit-mapped as follows: +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_DEFAULT\fR +.ad +.sp .6 +.RS 4n +This is a default configuration +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_IF\fR +.ad +.sp .6 +.RS 4n +If configuration byte exists +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_PWR\fR +.ad +.sp .6 +.RS 4n +Power information exists +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_TD\fR +.ad +.sp .6 +.RS 4n +Timing information exists +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_IO\fR +.ad +.sp .6 +.RS 4n +I/O information exists +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_IRQ\fR +.ad +.sp .6 +.RS 4n +IRQ information exists +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_MEM\fR +.ad +.sp .6 +.RS 4n +MEM space information exists +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_MISC\fR +.ad +.sp .6 +.RS 4n +MISC information exists +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_STCE_EV\fR +.ad +.sp .6 +.RS 4n +STCE_EV exists +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_STCE_PD\fR +.ad +.sp .6 +.RS 4n +STCE_PD exists +.RE + +.sp +.LP +If the \fBCISTPL_CFTABLE_TPCE_IF\fR flag is set, the \fBifc\fR field is +bit-mapped and defined as follows: +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_IF_MEMORY\fR +.ad +.sp .6 +.RS 4n +Memory interface +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_IF_IO_MEM\fR +.ad +.sp .6 +.RS 4n +IO and memory +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_IF_CUSTOM_0\fR +.ad +.sp .6 +.RS 4n +Custom interface 0 +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_IF_CUSTOM_1\fR +.ad +.sp .6 +.RS 4n +Custom interface 1 +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_IF_CUSTOM_2\fR +.ad +.sp .6 +.RS 4n +Custom interface 2 +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_IF_CUSTOM_3\fR +.ad +.sp .6 +.RS 4n +Custom interface 3 +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_IF_MASK\fR +.ad +.sp .6 +.RS 4n +Interface type mask +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_IF_BVD\fR +.ad +.sp .6 +.RS 4n +BVD active in PRR +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_IF_WP\fR +.ad +.sp .6 +.RS 4n +WP active in PRR +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_IF_RDY\fR +.ad +.sp .6 +.RS 4n +RDY active in PRR +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_IF_MWAIT\fR +.ad +.sp .6 +.RS 4n +WAIT - mem cycles +.RE + +.sp +.LP +\fBpin\fR is a value for the Pin Replacement Register. +.sp +.LP +\fBindex\fR is a configuration index number. +.sp +.LP +The structure members of \fBcistpl_cftable_entry_pd_t\fR are: +.sp +.in +2 +.nf +uint32_t flags; /* which descriptions are valid */ +cistpl_cftable_entry_pwr_t pd_vcc; /* VCC power description */ +cistpl_cftable_entry_pwr_t pd_vpp1; /* Vpp1 power description */ +cistpl_cftable_entry_pwr_t pd_vpp2; /* Vpp2 power description */ +.fi +.in -2 + +.sp +.LP +This \fBflags\fR field is bit-mapped and defined as follows: +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_PWR_VCC\fR +.ad +.sp .6 +.RS 4n +Vcc description valid +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_PWR_VPP1\fR +.ad +.sp .6 +.RS 4n +Vpp1 description valid +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_PWR_VPP2\fR +.ad +.sp .6 +.RS 4n +Vpp2 description valid +.RE + +.sp +.LP +The structure members of \fBcistpl_cftable_entry_pwr_t\fR are: +.sp +.in +2 +.nf +uint32_t nomV; /* nominal supply voltage */ +uint32_t nomV_flags; +uint32_t minV; /* minimum supply voltage */ +uint32_t minV_flags; +uint32_t maxV; /* maximum supply voltage */ +uint32_t maxV_flags; +uint32_t staticI; /* continuous supply current */ +uint32_t staticI_flags; +uint32_t avgI; /* max current required averaged over 1 sec. */ +uint32_t avgI_flags; +uint32_t peakI; /* max current required averaged over 10mS */ +uint32_t peakI_flags; +uint32_t pdownI; /* power down supply current required */ +uint32_t pdownI_flags; +.fi +.in -2 + +.sp +.LP +\fBnomV\fR, \fBminV\fR, \fBmaxV\fR, \fBstaticI\fR, \fBavgI\fR, +\fBpeakI_flag\fR, and \fBpdownI\fR are defined and bit-mapped as follows: +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_PD_NOMV\fR +.ad +.RS 29n +.rt +Nominal supply voltage +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_PD_MINV\fR +.ad +.RS 29n +.rt +Minimum supply voltage +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_PD_MAXV\fR +.ad +.RS 29n +.rt +Maximum supply voltage +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_PD_STATICI\fR +.ad +.RS 29n +.rt +Continuous supply current +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_PD_AVGI\fR +.ad +.RS 29n +.rt +Maximum current required averaged over 1 second +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_PD_PEAKI\fR +.ad +.RS 29n +.rt +Maximum current required averaged over 10mS +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_PD_PDOWNI\fR +.ad +.RS 29n +.rt +Power down supply current required +.RE + +.sp +.LP +\fBnomV_flags\fR, \fBminV_flags\fR, \fBmaxV_flags\fR, \fBstaticI_flags\fR, +\fBavgI_flags\fR, \fBpeakI_flags\fR, and \fBpdownI_flags\fR are defined and +bit-mapped as follows: +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_PD_EXISTS\fR +.ad +.RS 30n +.rt +This parameter exists +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_PD_MUL10\fR +.ad +.RS 30n +.rt +Multiply return value by 10 +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_PD_NC_SLEEP\fR +.ad +.RS 30n +.rt +No connection on sleep/power down +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_PD_ZERO\fR +.ad +.RS 30n +.rt +Zero value required +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_PD_NC\fR +.ad +.RS 30n +.rt +No connection ever +.RE + +.sp +.LP +The structure members of \fBcistpl_cftable_entry_speed_t\fR are: +.sp +.in +2 +.nf +uint32_t flags; /* which timing information is present */ +uint32_t wait; /* max WAIT time in device speed format */ +uint32_t nS_wait; /* max WAIT time in nS */ +uint32_t rdybsy; /* max RDY/BSY time in device speed format */ +uint32_t nS_rdybsy; /* max RDY/BSY time in nS */ +uint32_t rsvd; /* max RSVD time in device speed format */ +uint32_t nS_rsvd; /* max RSVD time in nS */ +.fi +.in -2 + +.sp +.LP +The \fBflags\fR field is bit-mapped and defined as follows: +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_TD_WAIT\fR +.ad +.sp .6 +.RS 4n +WAIT timing exists +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_TD_RDY\fR +.ad +.sp .6 +.RS 4n +RDY/BSY timing exists +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_TD_RSVD\fR +.ad +.sp .6 +.RS 4n +RSVD timing exists +.RE + +.sp +.LP +The structure members of \fBcistpl_cftable_entry_io_t\fR are: +.sp +.in +2 +.nf +uint32_t flags; /* direct copy of TPCE_IO byte in tuple */ +uint32_t addr_lines; /* number of decoded I/O address lines */ +uint32_t ranges; /* number of I/O ranges */ +cistpl_cftable_entry_io_range_t + range[CISTPL_CFTABLE_ENTRY_MAX_IO_RANGES]; +.fi +.in -2 + +.sp +.LP +The \fBflags\fR field is defined and bit-mapped as follows: +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_IO_BUS\fR +.ad +.sp .6 +.RS 4n +Bus width mask +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_IO_BUS8\fR +.ad +.sp .6 +.RS 4n +8-bit flag +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_IO_BUS16\fR +.ad +.sp .6 +.RS 4n +16-bit flag +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_IO_RANGE\fR +.ad +.sp .6 +.RS 4n +IO address ranges exist +.RE + +.sp +.LP +The structure members of \fBcistpl_cftable_entry_io_range_t\fR are: +.sp +.in +2 +.nf +uint32_t addr; /* I/O start address */ +uint32_t length; /* I/O register length */ +.fi +.in -2 + +.sp +.LP +The structure members of \fBcistpl_cftable_entry_irq_t\fR are: +.sp +.in +2 +.nf +uint32_t flags; /* direct copy of TPCE_IR byte in tuple */ +uint32_t irqs; /* bit mask for each allowed IRQ */ +.fi +.in -2 + +.sp +.LP +The structure members of \fBcistpl_cftable_entry_mem_t\fR are: +.sp +.in +2 +.nf +uint32_t flags; /* memory descriptor type and host addr info */ +uint32_t windows; /* number of memory space descriptors */ +cistpl_cftable_entry_mem_window_t + window[CISTPL_CFTABLE_ENTRY_MAX_MEM_WINDOWS]; +.fi +.in -2 + +.sp +.LP +The \fBflags\fR field is defined and bit-mapped as follows: +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_MEM3\fR +.ad +.sp .6 +.RS 4n +Space descriptors +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_MEM2\fR +.ad +.sp .6 +.RS 4n +\fBhost_addr\fR=\fBcard_addr\fR +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_MEM1\fR +.ad +.sp .6 +.RS 4n +Card address=0 any host address +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_FS_MEM_HOST\fR +.ad +.sp .6 +.RS 4n +If host address is present in MEM3 +.RE + +.sp +.LP +The structure members of \fBcistpl_cftable_entry_mem_window_t\fR are: +.sp +.in +2 +.nf +uint32_t length; /* length of this window */ +uint32_t card_addr; /* card address */ +uint32_t host_addr; /* host address */ +.fi +.in -2 + +.sp +.LP +The structure members of \fBcistpl_cftable_entry_misc_t\fR are: +.sp +.in +2 +.nf +uint32_t flags; /* miscellaneous features flags */ +.fi +.in -2 + +.sp +.LP +The \fBflags\fR field is defined and bit-mapped as follows: +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_MI_MTC_MASK\fR +.ad +.sp .6 +.RS 4n +Max twin cards mask +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_MI_AUDIO\fR +.ad +.sp .6 +.RS 4n +Audio on BVD2 +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_MI_READONLY\fR +.ad +.sp .6 +.RS 4n +R/O storage +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_MI_PWRDOWN\fR +.ad +.sp .6 +.RS 4n +Powerdown capable +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_MI_DRQ_MASK\fR +.ad +.sp .6 +.RS 4n +DMAREQ mask +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_MI_DRQ_SPK\fR +.ad +.sp .6 +.RS 4n +DMAREQ on SPKR +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_MI_DRQ_IOIS\fR +.ad +.sp .6 +.RS 4n +DMAREQ on IOIS16 +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_MI_DRQ_INP\fR +.ad +.sp .6 +.RS 4n +DMAREQ on INPACK +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_MI_DMA_8\fR +.ad +.sp .6 +.RS 4n +DMA width 8 bits +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_CFTABLE_TPCE_MI_DMA_16\fR +.ad +.sp .6 +.RS 4n +DMA width 16 bits +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_Parse_CISTPL_CONFIG\fR(9F), \fBcsx_RegisterClient\fR(9F), +\fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_CONFIG.9f b/usr/src/man/man9f/csx_Parse_CISTPL_CONFIG.9f new file mode 100644 index 0000000000..777b25b686 --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_CONFIG.9f @@ -0,0 +1,356 @@ +'\" 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_Parse_CISTPL_CONFIG 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_CONFIG \- parse Configuration tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_CONFIG\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_config_t *\fR\fIcc\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcc\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBcistpl_config_t\fR structure which contains the parsed +\fBCISTPL_CONFIG\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Configuration tuple, \fBCISTPL_CONFIG,\fR into a form +usable by \fBPC \fRCard drivers. The \fBCISTPL_CONFIG\fR tuple is used to +describe the general characteristics of 16-bit \fBPC \fRCards containing \fBI/O +\fRdevices or using custom interfaces. It may also describe \fBPC \fRCards, +including Memory Only cards, which exceed nominal power supply specifications, +or which need descriptions of their power requirements or other information. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_config_t\fR are: +.sp +.in +2 +.nf +uint32_t present; /* register present flags */ +uint32_t nr; /* number of config registers found */ +uint32_t hr; /* highest config register index found */ +uint32_t regs[CISTPL_CONFIG_MAX_CONFIG_REGS]; /* reg offsets */ +uint32_t base; /* base offset of config registers */ +uint32_t last; /* last config index */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBpresent\fR\fR +.ad +.RS 11n +.rt +This field indicates which configuration registers are present on the \fBPC +\fRCard. +.sp +.ne 2 +.mk +.na +\fBCONFIG_OPTION_REG_PRESENT\fR +.ad +.RS 30n +.rt +Configuration Option Register present +.RE + +.sp +.ne 2 +.mk +.na +\fBCONFIG_STATUS_REG_PRESENT\fR +.ad +.RS 30n +.rt +Configuration Status Register present +.RE + +.sp +.ne 2 +.mk +.na +\fBCONFIG_PINREPL_REG_PRESENT\fR +.ad +.RS 30n +.rt +Pin Replacement Register present +.RE + +.sp +.ne 2 +.mk +.na +\fBCONFIG_COPY_REG_PRESENT\fR +.ad +.RS 30n +.rt +Copy Register present +.RE + +.sp +.ne 2 +.mk +.na +\fBCONFIG_EXSTAT_REG_PRESENT\fR +.ad +.RS 30n +.rt +Extended Status Register present +.RE + +.sp +.ne 2 +.mk +.na +\fBCONFIG_IOBASE0_REG_PRESENT\fR +.ad +.RS 30n +.rt +IO Base 0 Register present +.RE + +.sp +.ne 2 +.mk +.na +\fBCONFIG_IOBASE1_REG_PRESENT\fR +.ad +.RS 30n +.rt +IO Base 1 Register present +.RE + +.sp +.ne 2 +.mk +.na +\fBCONFIG_IOBASE2_REG_PRESENT\fR +.ad +.RS 30n +.rt +IO Base2 Register present +.RE + +.sp +.ne 2 +.mk +.na +\fBCONFIG_IOBASE3_REG_PRESENT\fR +.ad +.RS 30n +.rt +IO Base3 Register present +.RE + +.sp +.ne 2 +.mk +.na +\fBCONFIG_IOLIMIT_REG_PRESENT\fR +.ad +.RS 30n +.rt +IO Limit Register present +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnr\fR\fR +.ad +.RS 11n +.rt +This field specifies the number of configuration registers that are present on +the \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBhr\fR\fR +.ad +.RS 11n +.rt +This field specifies the highest configuration register number that is present +on the \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBregs\fR\fR +.ad +.RS 11n +.rt +This array contains the offset from the start of Attribute Memory space for +each configuration register that is present on the \fBPC \fRCard. If a +configuration register is not present on the \fBPC \fRCard, the value in the +corresponding entry in the \fBregs\fR array is undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBbase\fR\fR +.ad +.RS 11n +.rt +This field contains the offset from the start of Attribute Memory space to the +base of the \fBPC \fRCard configuration register space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBlast\fR\fR +.ad +.RS 11n +.rt +This field contains the value of the last valid configuration index for this +\fBPC \fRCard. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_Parse_CISTPL_CFTABLE_ENTRY\fR(9F), \fBcsx_RegisterClient\fR(9F), +\fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR +.SH NOTES +.sp +.LP +\fBPC \fRCard drivers should not attempt to use configurations beyond the +"last" member in the \fBcistpl_config_t\fR structure. diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_DATE.9f b/usr/src/man/man9f/csx_Parse_CISTPL_DATE.9f new file mode 100644 index 0000000000..98d45b8f40 --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_DATE.9f @@ -0,0 +1,185 @@ +'\" 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_Parse_CISTPL_DATE 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_DATE \- parse the Card Initialization Date tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_DATE\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_date_t *\fR\fIcd\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcd\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBcistpl_date_t\fR structure which contains the parsed +\fBCISTPL_DATE\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Card Initialization Date tuple, \fBCISTPL_DATE,\fR +into a form usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_DATE\fR tuple is an optional tuple. It indicates the date and +time at which the card was formatted. Only one \fBCISTPL_DATE\fR tuple is +allowed per \fBPC \fRCard. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_date_t\fR are: +.sp +.in +2 +.nf +uint32_t time; +uint32_t day +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBtime\fR\fR +.ad +.RS 8n +.rt +This field indicates the time at which the \fBPC \fRCard was initialized. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBday\fR\fR +.ad +.RS 8n +.rt +This field indicates the date the \fBPC \fRCard was initialized. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_DEVICE.9f b/usr/src/man/man9f/csx_Parse_CISTPL_DEVICE.9f new file mode 100644 index 0000000000..7b2b9abc1d --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_DEVICE.9f @@ -0,0 +1,475 @@ +'\" 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 csx_Parse_CISTPL_DEVICE 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_DEVICE, csx_Parse_CISTPL_DEVICE_A, csx_Parse_CISTPL_DEVICE_OC, +csx_Parse_CISTPL_DEVICE_OA \- parse Device Information tuples +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_DEVICE\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_device_t *\fR\fIcd\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBcsx_Parse_CISTPL_DEVICE_A\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_device_t *\fR\fIcd\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBcsx_Parse_CISTPL_DEVICE_OC\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_device_t *\fR\fIcd\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBcsx_Parse_CISTPL_DEVICE_OA\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_device_t *\fR\fIcd\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcd\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBcistpl_device_t\fR structure which contains the parsed +\fBCISTPL_DEVICE,\fR \fBCISTPL_DEVICE_A,\fR \fBCISTPL_DEVICE_OC,\fR or +\fBCISTPL_DEVICE_OA\fR tuple information upon return from these functions, +respectively. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBcsx_Parse_CISTPL_DEVICE()\fR and \fBcsx_Parse_CISTPL_DEVICE_A()\fR parse the +5 volt Device Information tuples, \fBCISTPL_DEVICE\fR and +\fBCISTPL_DEVICE_A,\fR respectively, into a form usable by \fBPC \fRCard +drivers. +.sp +.LP +\fBcsx_Parse_CISTPL_DEVICE_OC()\fR and \fBcsx_Parse_CISTPL_DEVICE_OA()\fR parse +the Other Condition Device Information tuples, \fBCISTPL_DEVICE_OC\fR and +\fBCISTPL_DEVICE_OA,\fR respectively, into a form usable by \fBPC \fRCard +drivers. +.sp +.LP +The \fBCISTPL_DEVICE\fR and \fBCISTPL_DEVICE_A\fR tuples are used to describe +the card's device information, such as device speed, device size, device type, +and address space layout information for Common Memory or Attribute Memory +space, respectively. +.sp +.LP +The \fBCISTPL_DEVICE_OC\fR and \fBCISTPL_DEVICE_OA\fR tuples are used to +describe the information about the card's device under a set of operating +conditions for Common Memory or Attribute Memory space, respectively. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_device_t\fR are: +.sp +.in +2 +.nf +uint32_t num_devices; /* number of devices found */ +cistpl_device_node_t devnode[CISTPL_DEVICE_MAX_DEVICES]; +.fi +.in -2 + +.sp +.LP +The structure members of \fBcistpl_device_node_t\fR are: +.sp +.in +2 +.nf +uint32_t flags; /* flags specific to this device */ +uint32_t speed; /* device speed in device + /* speed code format */ +uint32_t nS_speed; /* device speed in nS */ +uint32_t type; /* device type */ +uint32_t size; /* device size */ +uint32_t size_in_bytes; /* device size in bytes */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBflags\fR\fR +.ad +.RS 9n +.rt +This field indicates whether or not the device is writable, and describes a +\fBVcc\fR voltage at which the \fBPC \fRCard can be operated. +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_WPS\fR +.ad +.RS 21n +.rt +Write Protect Switch bit is set +.RE + +Bits which are applicable only for \fBCISTPL_DEVICE_OC\fR and +\fBCISTPL_DEVICE_OA\fR are: +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_OC_MWAIT\fR +.ad +.RS 29n +.rt +Use MWAIT +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_OC_Vcc_MASK\fR +.ad +.RS 29n +.rt +Mask for \fBVcc\fR value +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_OC_Vcc5\fR +.ad +.RS 29n +.rt +5.0 volt operation +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_OC_Vcc33\fR +.ad +.RS 29n +.rt +3.3 volt operation +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_OC_VccXX\fR +.ad +.RS 29n +.rt +X.X volt operation +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_OC_VccYY\fR +.ad +.RS 29n +.rt +Y.Y volt operation +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBspeed\fR\fR +.ad +.RS 17n +.rt +The device speed value described in the device speed code unit. If this field +is set to \fBCISTPL_DEVICE_SPEED_SIZE_IGNORE,\fR then the speed information +will be ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnS_speed\fR\fR +.ad +.RS 17n +.rt +The device speed value described in nanosecond units. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsize\fR\fR +.ad +.RS 17n +.rt +The device size value described in the device size code unit. If this field is +set to \fBCISTPL_DEVICE_SPEED_SIZE_IGNORE,\fR then the size information will be +ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsize_in_bytes\fR\fR +.ad +.RS 17n +.rt +The device size value described in byte units. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtype\fR\fR +.ad +.RS 17n +.rt +This is the device type code field which is defined as follows: +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_DTYPE_NULL\fR +.ad +.sp .6 +.RS 4n +No device +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_DTYPE_ROM\fR +.ad +.sp .6 +.RS 4n +Masked ROM +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_DTYPE_OTPROM\fR +.ad +.sp .6 +.RS 4n +One Time Programmable ROM +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_DTYPE_EPROM\fR +.ad +.sp .6 +.RS 4n +UV EPROM +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_DTYPE_EEPROM\fR +.ad +.sp .6 +.RS 4n +EEPROM +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_DTYPE_FLASH\fR +.ad +.sp .6 +.RS 4n +FLASH +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_DTYPE_SRAM\fR +.ad +.sp .6 +.RS 4n +Static RAM +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_DTYPE_DRAM\fR +.ad +.sp .6 +.RS 4n +Dynamic RAM +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_DTYPE_FUNCSPEC\fR +.ad +.sp .6 +.RS 4n +Function-specific memory address range +.RE + +.sp +.ne 2 +.mk +.na +\fBCISTPL_DEVICE_DTYPE_EXTEND\fR +.ad +.sp .6 +.RS 4n +Extended type follows +.RE + +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_Parse_CISTPL_JEDEC_C\fR(9F), \fBcsx_RegisterClient\fR(9F), +\fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_DEVICEGEO.9f b/usr/src/man/man9f/csx_Parse_CISTPL_DEVICEGEO.9f new file mode 100644 index 0000000000..bd6e5f07cb --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_DEVICEGEO.9f @@ -0,0 +1,234 @@ +'\" 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 csx_Parse_CISTPL_DEVICEGEO 9F "16 May 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_DEVICEGEO \- parse the Device Geo tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_DEVICEGEO\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItp\fR, + \fBcistpl_devicegeo_t *\fR\fIpt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItp\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpt\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBcistpl_devicegeo_t\fR structure which contains the parsed +Device Geo tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Device Geo tuple, \fBCISTPL_DEVICEGEO,\fR into a form +usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_DEVICEGEO\fR tuple describes the device geometry of common memory +partitions. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_devicegeo_t\fR are: +.sp +.in +2 +.nf +uint32_t info[CISTPL_DEVICEGEO_MAX_PARTITIONS].bus; +uint32_t info[CISTPL_DEVICEGEO_MAX_PARTITIONS].ebs; +uint32_t info[CISTPL_DEVICEGEO_MAX_PARTITIONS].rbs; +uint32_t info[CISTPL_DEVICEGEO_MAX_PARTITIONS].wbs; +uint32_t info[CISTPL_DEVICEGEO_MAX_PARTITIONS].part; +uint32_t info[CISTPL_DEVICEGEO_MAX_PARTITIONS].hwil; +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBinfo[CISTPL_DEVICEGEO_MAX_PARTITIONS].bus\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the card interface width in bytes for the given partition. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBinfo[CISTPL_DEVICEGEO_MAX_PARTITIONS].ebs\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the minimum erase block size for the given partition. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBinfo[CISTPL_DEVICEGEO_MAX_PARTITIONS].rbs\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the minimum read block size for the given partition. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBinfo[CISTPL_DEVICEGEO_MAX_PARTITIONS].wbs\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the minimum write block size for the given partition. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBinfo[CISTPL_DEVICEGEO_MAX_PARTITIONS].part\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the segment partition subdivisions for the given +partition. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBinfo[CISTPL_DEVICEGEO_MAX_PARTITIONS].hwil\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the hardware interleave +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR \fR +.ad +.RS 28n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR \fR +.ad +.RS 28n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR \fR +.ad +.RS 28n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetNextTuple\fR(9F), +\fBcsx_GetTupleData\fR(9F), \fBcsx_Parse_CISTPL_DEVICEGEO_A\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_DEVICEGEO_A.9f b/usr/src/man/man9f/csx_Parse_CISTPL_DEVICEGEO_A.9f new file mode 100644 index 0000000000..c565bfd4b7 --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_DEVICEGEO_A.9f @@ -0,0 +1,234 @@ +'\" 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 csx_Parse_CISTPL_DEVICEGEO_A 9F "16 May 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_DEVICEGEO_A \- parse the Device Geo A tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_DEVICEGEO_A\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItp\fR, + \fBcistpl_devicegeo_t *\fR\fIpt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItp\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpt\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBcistpl_devicegeo_t\fR structure which contains the parsed +Device Geo A tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Device Geo A tuple, \fBCISTPL_DEVICEGEO_A,\fR into a +form usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_DEVICEGEO_A\fR tuple describes the device geometry of attribute +memory partitions. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_devicegeo_t\fR are: +.sp +.in +2 +.nf +uint32_t info[CISTPL_DEVICEGEO_MAX_PARTITIONS].bus; +uint32_t info[CISTPL_DEVICEGEO_MAX_PARTITIONS].ebs; +uint32_t info[CISTPL_DEVICEGEO_MAX_PARTITIONS].rbs; +uint32_t info[CISTPL_DEVICEGEO_MAX_PARTITIONS].wbs; +uint32_t info[CISTPL_DEVICEGEO_MAX_PARTITIONS].part; +uint32_t info[CISTPL_DEVICEGEO_MAX_PARTITIONS].hwil; +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBinfo[CISTPL_DEVICEGEO_MAX_PARTITIONS].bus\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the card interface width in bytes for the given partition. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBinfo[CISTPL_DEVICEGEO_MAX_PARTITIONS].ebs\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the minimum erase block size for the given partition. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBinfo[CISTPL_DEVICEGEO_MAX_PARTITIONS].rbs\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the minimum read block size for the given partition. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBinfo[CISTPL_DEVICEGEO_MAX_PARTITIONS].wbs\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the minimum write block size for the given partition. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBinfo[CISTPL_DEVICEGEO_MAX_PARTITIONS].part\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the segment partition subdivisions for the given +partition. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBinfo[CISTPL_DEVICEGEO_MAX_PARTITIONS].hwil\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the hardware interleave for the given partition. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR \fR +.ad +.RS 28n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR \fR +.ad +.RS 28n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR \fR +.ad +.RS 28n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetNextTuple\fR(9F), +\fBcsx_GetTupleData\fR(9F), \fBcsx_Parse_CISTPL_DEVICEGEO\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_FORMAT.9f b/usr/src/man/man9f/csx_Parse_CISTPL_FORMAT.9f new file mode 100644 index 0000000000..eaacf1f8ee --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_FORMAT.9f @@ -0,0 +1,361 @@ +'\" 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 csx_Parse_CISTPL_FORMAT 9F "24 Jan 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_FORMAT \- parse the Data Recording Format tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_FORMAT\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_format_t *\fR\fIpt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpt\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBcistpl_format_t\fR structure which contains the parsed +\fBCISTPL_FORMAT\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Data Recording Format tuple, \fBCISTPL_FORMAT,\fR into +a form usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_FORMAT\fR tuple indicates the data recording format for a device +partition. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_format_t\fR are: +.sp +.in +2 +.nf +uint32_t type; +uint32_t edc_length; +uint32_t edc_type; +uint32_t offset; +uint32_t nbytes; +uint32_t dev.disk.bksize; +uint32_t dev.disk.nblocks; +uint32_t dev.disk.edcloc; +uint32_t dev.mem.flags; +uint32_t dev.mem.reserved; +caddr_t dev.mem.address; +uint32_t dev.mem.edcloc; +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBtype\fR\fR +.ad +.RS 20n +.rt +This field indicates the type of device: +.sp +.ne 2 +.mk +.na +\fBTPLFMTTYPE_DISK\fR +.ad +.RS 19n +.rt +disk-like device +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFMTTYPE_MEM\fR +.ad +.RS 19n +.rt +memory-like device +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFMTTYPE_VS\fR +.ad +.RS 19n +.rt +vendor-specific device +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBedc_length\fR\fR +.ad +.RS 20n +.rt +This field indicates the error detection code length. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBedc_type\fR\fR +.ad +.RS 20n +.rt +This field indicates the error detection code type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBoffset\fR\fR +.ad +.RS 20n +.rt +This field indicates the offset of the first byte of data in this partition. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnbytes\fR\fR +.ad +.RS 20n +.rt +This field indicates the number of bytes of data in this partition +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdev.disk.bksize\fR\fR +.ad +.RS 20n +.rt +This field indicates the block size, for disk devices. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdev.disk.nblocks\fR\fR +.ad +.RS 20n +.rt +This field indicates the number of blocks, for disk devices. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdev.disk.edcloc\fR\fR +.ad +.RS 20n +.rt +This field indicates the location of the error detection code, for disk +devices. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdev.mem.flags\fR\fR +.ad +.RS 20n +.rt +This field provides flags, for memory devices. Valid flags are: +.sp +.ne 2 +.mk +.na +\fBTPLFMTFLAGS_ADDR\fR +.ad +.RS 20n +.rt +address is valid +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFMTFLAGS_AUTO\fR +.ad +.RS 20n +.rt +automatically map memory region +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdev.mem.reserved\fR\fR +.ad +.RS 20n +.rt +This field is reserved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdev.mem.address\fR\fR +.ad +.RS 20n +.rt +This field indicates the physical address, for memory devices. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdev.mem.edcloc\fR\fR +.ad +.RS 20n +.rt +This field indicates the location of the error detection code, for memory +devices. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_FUNCE.9f b/usr/src/man/man9f/csx_Parse_CISTPL_FUNCE.9f new file mode 100644 index 0000000000..5da4463e5c --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_FUNCE.9f @@ -0,0 +1,1389 @@ +'\" 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 csx_Parse_CISTPL_FUNCE 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_FUNCE \- parse Function Extension tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_FUNCE\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_funce_t *\fR\fIcf\fR, + \fBuint32_t\fR \fIfid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcf\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBcistpl_funce_t\fR structure which contains the parsed +\fBCISTPL_FUNCE\fR tuple information upon return from this function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfid\fR\fR +.ad +.RS 7n +.rt +The function \fBID \fRcode to which this \fBCISTPL_FUNCE\fR tuple refers. See +\fBcsx_Parse_CISTPL_FUNCID\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Function Extension tuple, \fBCISTPL_FUNCE,\fR into a +form usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_FUNCE\fR tuple is used to describe information about a specific +\fBPC\fRCard function. The information provided is determined by the Function +Identification tuple, \fBCISTPL_FUNCID,\fR that is being extended. Each +function has a defined set of extension tuples. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_funce_t\fR are: +.sp +.in +2 +.nf +uint32_t function; /* type of extended data */ +uint32_t subfunction; +union { + struct serial { + uint32_t ua; /* UART in use */ + uint32_t uc; /* UART capabilities */ + } serial; + struct modem { + uint32_t fc; /* supported flow control methods */ + uint32_t cb; /* size of DCE command buffer */ + uint32_t eb; /* size of DCE to DCE buffer */ + uint32_t tb; /* size of DTE to DCE buffer */ + } modem; + struct data_modem { + uint32_t ud; /* highest data rate */ + uint32_t ms; /* modulation standards */ + uint32_t em; /* err correct proto and + /* non-CCITT modulation */ + uint32_t dc; /* data compression protocols */ + uint32_t cm; /* command protocols */ + uint32_t ex; /* escape mechanisms */ + uint32_t dy; /* standardized data encryption */ + uint32_t ef; /* miscellaneous end user features */ + uint32_t ncd; /* number of country codes */ + uchar_t cd[16]; /* CCITT country code */ + } data_modem; + struct fax { + uint32_t uf; /* highest data rate in DTE/UART */ + uint32_t fm; /* CCITT modulation standards */ + uint32_t fy; /* standardized data encryption */ + uint32_t fs; /* feature selection */ + uint32_t ncf; /* number of country codes */ + uchar_t cf[16]; /* CCITT country codes */ + } fax; + struct voice { + uint32_t uv; /* highest data rate */ + uint32_t nsr; + uint32_t sr[16]; /* voice sampling rates (*100) */ + uint32_t nss; + uint32_t ss[16]; /* voice sample sizes (*10) */ + uint32_t nsc; + uint32_t sc[16]; /* voice compression methods */ + } voice; + struct lan { + uint32_t tech; /* network technology */ + uint32_t speed; /* media bit or baud rate */ + uint32_t media; /* network media supported */ + uint32_t con; /* open/closed connector standard */ + uint32_t id_sz; /* length of lan station id */ + uchar_t id[16]; /* station ID */ + } lan; +} data; +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fBfunction\fR +.ad +.RS 15n +.rt +This field identifies the type of extended information provided about a +function by the \fBCISTPL_FUNCE\fR tuple. This field is defined as follows: +.sp +.ne 2 +.mk +.na +\fBTPLFE_SUB_SERIAL\fR +.ad +.RS 26n +.rt +Serial port interface +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_SUB_MODEM_COMMON\fR +.ad +.RS 26n +.rt +Common modem interface +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_SUB_MODEM_DATA\fR +.ad +.RS 26n +.rt +Data modem services +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_SUB_MODEM_FAX\fR +.ad +.RS 26n +.rt +Fax modem services +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_SUB_VOICE\fR +.ad +.RS 26n +.rt +Voice services +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_CAP_MODEM_DATA\fR +.ad +.RS 26n +.rt +Capabilities of the data modem interface +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_CAP_MODEM_FAX\fR +.ad +.RS 26n +.rt +Capabilities of the fax modem interface +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_CAP_MODEM_VOICE\fR +.ad +.RS 26n +.rt +Capabilities of the voice modem interface +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_CAP_SERIAL_DATA\fR +.ad +.RS 26n +.rt +Serial port interface for data modem services +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_CAP_SERIAL_FAX\fR +.ad +.RS 26n +.rt +Serial port interface for fax modem services +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_CAP_SERIAL_VOICE\fR +.ad +.RS 26n +.rt +Serial port interface for voice modem services +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsubfunction\fR\fR +.ad +.RS 15n +.rt +This is for identifying a sub-category of services provided by a function in +the \fBCISTPL_FUNCE\fR tuple. The numeric value of the code is in the range of +\fB1\fR to \fB15\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBua\fR\fR +.ad +.RS 15n +.rt +This is the serial port \fBUART \fRidentification and is defined as follows: +.sp +.ne 2 +.mk +.na +\fBTPLFE_UA_8250\fR +.ad +.RS 18n +.rt +Intel 8250 +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_UA_16450\fR +.ad +.RS 18n +.rt +NS 16450 +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_UA_16550\fR +.ad +.RS 18n +.rt +NS 16550 +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBuc\fR\fR +.ad +.RS 15n +.rt +This identifies the serial port \fBUART \fRcapabilities and is defined as +follows: +.sp +.ne 2 +.mk +.na +\fBTPLFE_UC_PARITY_SPACE\fR +.ad +.RS 25n +.rt +Space parity supported +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_UC_PARITY_MARK\fR +.ad +.RS 25n +.rt +Mark parity supported +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_UC_PARITY_ODD\fR +.ad +.RS 25n +.rt +Odd parity supported +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_UC_PARITY_EVEN\fR +.ad +.RS 25n +.rt +Even parity supported +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_UC_CS5\fR +.ad +.RS 25n +.rt +5 bit characters supported +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_UC_CS6\fR +.ad +.RS 25n +.rt +6 bit characters supported +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_UC_CS7\fR +.ad +.RS 25n +.rt +7 bit characters supported +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_UC_CS8\fR +.ad +.RS 25n +.rt +8 bit characters supported +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_UC_STOP_1\fR +.ad +.RS 25n +.rt +1 stop bit supported +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_UC_STOP_15\fR +.ad +.RS 25n +.rt +1.5 stop bits supported +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_UC_STOP_2\fR +.ad +.RS 25n +.rt +2 stop bits supported +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBfc\fR\fR +.ad +.RS 15n +.rt +This identifies the modem flow control methods and is defined as follows: +.sp +.ne 2 +.mk +.na +\fBTPLFE_FC_TX_XONOFF\fR +.ad +.RS 22n +.rt +Transmit XON/XOFF +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FC_RX_XONOFF\fR +.ad +.RS 22n +.rt +Receiver XON/XOFF +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FC_TX_HW\fR +.ad +.RS 22n +.rt +Transmit hardware flow control (CTS) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FC_RX_HW\fR +.ad +.RS 22n +.rt +Receiver hardware flow control (RTS) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FC_TRANS\fR +.ad +.RS 22n +.rt +Transparent flow control +.RE + +.sp +.ne 2 +.mk +.na +\fBms\fR +.ad +.RS 6n +.rt +This identifies the modem modulation standards and is defined as follows: +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_MS_BELL103\fR +.ad +.RS 20n +.rt +300bps +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_MS_V21\fR +.ad +.RS 20n +.rt +300bps (V.21) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_MS_V23\fR +.ad +.RS 20n +.rt +600/1200bps (V.23) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_MS_V22AB\fR +.ad +.RS 20n +.rt +1200bps (V.22A V.22B) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_MS_BELL212\fR +.ad +.RS 20n +.rt +2400bps (US Bell 212 +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_MS_V22BIS\fR +.ad +.RS 20n +.rt +2400bps (V.22bis) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_MS_V26\fR +.ad +.RS 20n +.rt +2400bps leased line (V.26) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_MS_V26BIS\fR +.ad +.RS 20n +.rt +2400bps (V.26bis) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_MS_V27BIS\fR +.ad +.RS 20n +.rt +4800/2400bps leased line (V.27bis) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_MS_V29\fR +.ad +.RS 20n +.rt +9600/7200/4800 leased line (V.29) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_MS_V32\fR +.ad +.RS 20n +.rt +Up to 9600bps (V.32) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_MS_V32BIS\fR +.ad +.RS 20n +.rt +Up to 14400bps (V.32bis) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_MS_VFAST\fR +.ad +.RS 20n +.rt +Up to 28800 V.FAST +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBem\fR\fR +.ad +.RS 15n +.rt +This identifies modem error correction/detection protocols and is defined as +follows: +.sp +.ne 2 +.mk +.na +\fBTPLFE_EM_MNP\fR +.ad +.RS 16n +.rt +MNP levels 2-4 +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_EM_V42\fR +.ad +.RS 16n +.rt +CCITT LAPM (V.42) +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdc\fR\fR +.ad +.RS 15n +.rt +This identifies modem data compression protocols and is defined as follows: +.sp +.ne 2 +.mk +.na +\fBTPLFE_DC_V42BI\fR +.ad +.RS 18n +.rt +CCITT compression V.42 +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_DC_MNP5\fR +.ad +.RS 18n +.rt +MNP compression (uses MNP 2, 3 or 4) +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcm\fR\fR +.ad +.RS 15n +.rt +This identifies modem command protocols and is defined as follows: +.sp +.ne 2 +.mk +.na +\fBTPLFE_CM_AT1\fR +.ad +.RS 19n +.rt +ANSI/EIA/TIA 602 "Action" commands +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_CM_AT2\fR +.ad +.RS 19n +.rt +ANSI/EIA/TIA 602 "ACE/DCE IF Params" +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_CM_AT3\fR +.ad +.RS 19n +.rt +ANSI/EIA/TIA 602 "Ace Parameters" +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_CM_MNP_AT\fR +.ad +.RS 19n +.rt +MNP specification AT commands +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_CM_V25BIS\fR +.ad +.RS 19n +.rt +V.25bis calling commands +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_CM_V25A\fR +.ad +.RS 19n +.rt +V.25bis test procedures +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_CM_DMCL\fR +.ad +.RS 19n +.rt +DMCL command mode +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBex\fR\fR +.ad +.RS 15n +.rt +This identifies the modem escape mechanism and is defined as follows: +.sp +.ne 2 +.mk +.na +\fBTPLFE_EX_BREAK\fR +.ad +.RS 18n +.rt +BREAK support standardized +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_EX_PLUS\fR +.ad +.RS 18n +.rt ++++ returns to command mode +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_EX_UD\fR +.ad +.RS 18n +.rt +User defined escape character +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdy\fR\fR +.ad +.RS 15n +.rt +This identifies modem standardized data encryption and is a reserved field for +future use and must be set to \fB0\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBef\fR\fR +.ad +.RS 15n +.rt +This identifies modem miscellaneous features and is defined as follows: +.sp +.ne 2 +.mk +.na +\fBTPLFE_EF_CALLERID\fR +.ad +.RS 21n +.rt +Caller ID is supported +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBfm\fR\fR +.ad +.RS 15n +.rt +This identifies fax modulation standards and is defined as follows: +.sp +.ne 2 +.mk +.na +\fBTPLFE_FM_V21C2\fR +.ad +.RS 19n +.rt +300bps (V.21-C2) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FM_V27TER\fR +.ad +.RS 19n +.rt +4800/2400bps (V.27ter) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FM_V29\fR +.ad +.RS 19n +.rt +9600/7200/4800 leased line (V.29) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FM_V17\fR +.ad +.RS 19n +.rt +14.4K/12K/9600/7200bps (V.17) +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FM_V33\fR +.ad +.RS 19n +.rt +4.4K/12K/9600/7200 leased line (V.33) +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBfs\fR\fR +.ad +.RS 15n +.rt +This identifies the fax feature selection and is defined as follows: +.sp +.ne 2 +.mk +.na +\fBTPLFE_FS_T3\fR +.ad +.RS 21n +.rt +Group 2 (T.3) service class +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FS_T4\fR +.ad +.RS 21n +.rt +Group 3 (T.4) service class +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FS_T6\fR +.ad +.RS 21n +.rt +Group 4 (T.6) service class +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FS_ECM\fR +.ad +.RS 21n +.rt +Error Correction Mode +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FS_VOICEREQ\fR +.ad +.RS 21n +.rt +Voice requests allowed +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FS_POLLING\fR +.ad +.RS 21n +.rt +Polling support +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FS_FTP\fR +.ad +.RS 21n +.rt +File transfer support +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_FS_PASSWORD\fR +.ad +.RS 21n +.rt +Password support +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtech\fR\fR +.ad +.RS 15n +.rt +This identifies the \fBLAN \fRtechnology type and is defined as follows: +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_TECH_ARCNET\fR +.ad +.RS 28n +.rt +Arcnet +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_TECH_ETHERNET\fR +.ad +.RS 28n +.rt +Ethernet +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_TECH_TOKENRING\fR +.ad +.RS 28n +.rt +Token Ring +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_TECH_LOCALTALK\fR +.ad +.RS 28n +.rt +Local Talk +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_TECH_FDDI\fR +.ad +.RS 28n +.rt +FDDI/CDDI +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_TECH_ATM\fR +.ad +.RS 28n +.rt +ATM +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_TECH_WIRELESS\fR +.ad +.RS 28n +.rt +Wireless +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBmedia\fR\fR +.ad +.RS 15n +.rt +This identifies the \fBLAN \fRmedia type and is defined as follows: +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_MEDIA_INHERENT\fR +.ad +.RS 30n +.rt +Generic interface +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_MEDIA_UTP\fR +.ad +.RS 30n +.rt +Unshielded twisted pair +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_MEDIA_STP\fR +.ad +.RS 30n +.rt +Shielded twisted pair +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_MEDIA_THIN_COAX\fR +.ad +.RS 30n +.rt +Thin coax +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_MEDIA_THICK_COAX\fR +.ad +.RS 30n +.rt +Thick coax +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_MEDIA_FIBER\fR +.ad +.RS 30n +.rt +Fiber +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_MEDIA_SSR_902\fR +.ad +.RS 30n +.rt +Spread spectrum radio 902-928 MHz +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_MEDIA_SSR_2_4\fR +.ad +.RS 30n +.rt +Spread spectrum radio 2.4 GHz +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_MEDIA_SSR_5_4\fR +.ad +.RS 30n +.rt +Spread spectrum radio 5.4 GHz +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_MEDIA_DIFFUSE_IR\fR +.ad +.RS 30n +.rt +Diffuse infra red +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFE_LAN_MEDIA_PTP_IR\fR +.ad +.RS 30n +.rt +Point to point infra red +.RE + +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_Parse_CISTPL_FUNCID\fR(9F), \fBcsx_RegisterClient\fR(9F), +\fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_FUNCID.9f b/usr/src/man/man9f/csx_Parse_CISTPL_FUNCID.9f new file mode 100644 index 0000000000..2a2085540e --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_FUNCID.9f @@ -0,0 +1,343 @@ +'\" 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_Parse_CISTPL_FUNCID 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_FUNCID \- parse Function Identification tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_FUNCID\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_funcid_t *\fR\fIcf\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcf\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBcistpl_funcid_t\fR structure which contains the parsed +\fBCISTPL_FUNCID\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Function Identification tuple, \fBCISTPL_FUNCID,\fR +into a form usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_FUNCID\fR tuple is used to describe information about the +functionality provided by a \fBPC \fRCard. Information is also provided to +enable system utilities to decide if the \fBPC \fRCard should be configured +during system initialization. If additional function specific information is +available, one or more function extension tuples of type \fBCISTPL_FUNCE\fR +follow this tuple (see \fBcsx_Parse_CISTPL_FUNCE\fR(9F)). +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_funcid_t\fR are: +.sp +.in +2 +.nf +uint32_t function; /* PC Card function code */ +uint32_t sysinit; /* system initialization mask */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBfunction\fR\fR +.ad +.RS 12n +.rt +This is the function type for \fBCISTPL_FUNCID:\fR +.sp +.ne 2 +.mk +.na +\fBTPLFUNC_MULTI\fR +.ad +.RS 27n +.rt +Vendor-specific multifunction card +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFUNC_MEMORY\fR +.ad +.RS 27n +.rt +Memory card +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFUNC_SERIAL\fR +.ad +.RS 27n +.rt +Serial I/O port +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFUNC_PARALLEL\fR +.ad +.RS 27n +.rt +Parallel printer port +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFUNC_FIXED\fR +.ad +.RS 27n +.rt +Fixed disk, silicon or removable +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFUNC_VIDEO\fR +.ad +.RS 27n +.rt +Video interface +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFUNC_LAN\fR +.ad +.RS 27n +.rt +Local Area Network adapter +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFUNC_AIMS\fR +.ad +.RS 27n +.rt +Auto Incrementing Mass Storage +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFUNC_SCSI\fR +.ad +.RS 27n +.rt +SCSI bridge +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFUNC_SECURITY\fR +.ad +.RS 27n +.rt +Security cards +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFUNC_VENDOR_SPECIFIC\fR +.ad +.RS 27n +.rt +Vendor specific +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLFUNC_UNKNOWN\fR +.ad +.RS 27n +.rt +Unknown function(s) +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsysinit\fR\fR +.ad +.RS 11n +.rt +This field is bit-mapped and defined as follows: +.sp +.ne 2 +.mk +.na +\fBTPLINIT_POST\fR +.ad +.RS 16n +.rt +POST should attempt configure +.RE + +.sp +.ne 2 +.mk +.na +\fBTPLINIT_ROM\fR +.ad +.RS 16n +.rt +Map ROM during sys init +.RE + +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_Parse_CISTPL_FUNCE\fR(9F), \fBcsx_RegisterClient\fR(9F), +\fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard, PCMCIA/JEIDA\fR diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_GEOMETRY.9f b/usr/src/man/man9f/csx_Parse_CISTPL_GEOMETRY.9f new file mode 100644 index 0000000000..3f1d073e04 --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_GEOMETRY.9f @@ -0,0 +1,195 @@ +'\" 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_Parse_CISTPL_GEOMETRY 9F "24 Jan 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_GEOMETRY \- parse the Geometry tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_GEOMETRY\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_geometry_t *\fR\fIpt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpt\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBcistpl_geometry_t\fR structure which contains the parsed +\fBCISTPL_GEOMETRY\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Geometry tuple, \fBCISTPL_GEOMETRY\fR, into a form +usable by \fBPC\fR Card drivers. +.sp +.LP +The \fBCISTPL_GEOMETRY\fR tuple indicates the geometry of a disk-like device. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_geometry_t\fR are: +.sp +.in +2 +.nf + uint32_t spt; + uint32_t tpc; + uint32_t ncyl; +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBspt\fR\fR +.ad +.RS 8n +.rt +This field indicates the number of sectors per track. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtpc\fR\fR +.ad +.RS 8n +.rt +This field indicates the number of tracks per cylinder. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBncyl\fR\fR +.ad +.RS 8n +.rt +This field indicates the number of cylinders. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC\fR Card in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (\fBCIS\fR) on \fBPC\fR Card. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA\fR hardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_JEDEC_C.9f b/usr/src/man/man9f/csx_Parse_CISTPL_JEDEC_C.9f new file mode 100644 index 0000000000..789eb87374 --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_JEDEC_C.9f @@ -0,0 +1,181 @@ +'\" 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_Parse_CISTPL_JEDEC_C 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_JEDEC_C, csx_Parse_CISTPL_JEDEC_A \- parse JEDEC Identifier +tuples +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_JEDEC_C\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_jedec_t *\fR\fIcj\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBcsx_Parse_CISTPL_JEDEC_A\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_jedec_t *\fR\fIcj\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcj\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBcistpl_jedec_t\fR structure which contains the parsed +\fBCISTPL_JEDEC_C\fR or \fBCISTPL_JEDEC_A\fR tuple information upon return from +these functions, respectively. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBcsx_Parse_CISTPL_JEDEC_C()\fR and \fBcsx_Parse_CISTPL_JEDEC_A()\fR parse the +\fBJEDEC\fR Identifier tuples, \fBCISTPL_JEDEC_C\fR and \fBCISTPL_JEDEC_A,\fR +respectively, into a form usable by \fBPC\fR Card drivers. +.sp +.LP +The \fBCISTPL_JEDEC_C\fR and \fBCISTPL_JEDEC_A\fR tuples are optional tuples +provided for cards containing programmable devices. They describe information +for Common Memory or Attribute Memory space, respectively. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_jedec_t\fR are: +.sp +.in +2 +.nf + uint32_t nid; /* # of JEDEC identifiers present */ + jedec_ident_t jid[CISTPL_JEDEC_MAX_IDENTIFIERS]; +.fi +.in -2 + +.sp +.LP +The structure members of \fBjedec_ident_t\fR are: +.sp +.in +2 +.nf + uint32_t id; /* manufacturer id */ + uint32_t info; /* manufacturer specific info */ +.fi +.in -2 + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC\fR Card in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (\fBCIS\fR) on \fBPC\fR Card. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA\fR hardware installed. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_Parse_CISTPL_DEVICE\fR(9F), \fBcsx_RegisterClient\fR(9F), +\fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_LINKTARGET.9f b/usr/src/man/man9f/csx_Parse_CISTPL_LINKTARGET.9f new file mode 100644 index 0000000000..3808cd25ed --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_LINKTARGET.9f @@ -0,0 +1,184 @@ +'\" 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 csx_Parse_CISTPL_LINKTARGET 9F "24 Jan 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_LINKTARGET \- parse the Link Target tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_LINKTARGET\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_linktarget_t *\fR\fIpt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpt\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBcistpl_linktarget_t\fR structure which contains the parsed +\fBCISTPL_LINKTARGET\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Link Target tuple, \fBCISTPL_LINKTARGET,\fR into a +form usable by \fBPC\fRCard drivers. +.sp +.LP +The \fBCISTPL_LINKTARGET\fR tuple is used to verify that tuple chains other +than the primary chain are valid. All secondary tuple chains are required to +contain this tuple as the first tuple of the chain. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_linktarget_t\fR are: +.sp +.in +2 +.nf +uint32_t length; +char tpltg_tag[CIS_MAX_TUPLE_DATA_LEN]; +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBlength\fR \fR +.ad +.RS 14n +.rt +This field indicates the number of bytes in \fBtpltg_tag\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtpltg_tag\fR \fR +.ad +.RS 14n +.rt +This field provides the Link Target tuple information. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR \fR +.ad +.RS 28n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR \fR +.ad +.RS 28n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR \fR +.ad +.RS 28n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_LONGLINK_A.9f b/usr/src/man/man9f/csx_Parse_CISTPL_LONGLINK_A.9f new file mode 100644 index 0000000000..c2c9c92fda --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_LONGLINK_A.9f @@ -0,0 +1,215 @@ +'\" 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 csx_Parse_CISTPL_LONGLINK_A 9F "24 Jan 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_LONGLINK_A, csx_Parse_CISTPL_LONGLINK_C \- parse the Long Link +A and C tuples +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_LONGLINK_A\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_longlink_ac_t *\fR\fIpt\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBcsx_Parse_CISTPL_LONGLINK_C\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_longlink_ac_t *\fR\fIpt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpt\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBcistpl_longlink_ac_t\fR structure which contains the parsed +\fBCISTPL_LONGLINK_A\fR or \fBCISTPL_LONGLINK_C\fR tuple information upon +return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Long Link A and C tuples, \fBCISTPL_LONGLINK_A\fR and +\fBCISTPL_LONGLINK_A,\fR into a form usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_LONGLINK_A\fR and \fBCISTPL_LONGLINK_C\fR tuples provide links to +Attribute and Common Memory. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_longlink_ac_t\fR are: +.sp +.in +2 +.nf +uint32_t flags; +uint32_t tpll_addr; +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBflags\fR \fR +.ad +.RS 14n +.rt +This field indicates the type of memory: +.sp +.ne 2 +.mk +.na +\fB\fBCISTPL_LONGLINK_AC_AM\fR\fR +.ad +.RS 25n +.rt +long link to Attribute Memory +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCISTPL_LONGLINK_AC_CM\fR\fR +.ad +.RS 25n +.rt +long link to Common Memory +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtpll_addr\fR \fR +.ad +.RS 14n +.rt +This field provides the offset from the beginning of the specified address +space. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR \fR +.ad +.RS 28n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR \fR +.ad +.RS 28n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR \fR +.ad +.RS 28n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_LONGLINK_MFC.9f b/usr/src/man/man9f/csx_Parse_CISTPL_LONGLINK_MFC.9f new file mode 100644 index 0000000000..1d798f0c7c --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_LONGLINK_MFC.9f @@ -0,0 +1,232 @@ +'\" 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 csx_Parse_CISTPL_LONGLINK_MFC 9F "24 Jan 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_LONGLINK_MFC \- parse the Multi-Function tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_LONGLINK_MFC\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_longlink_mfc_t *\fR\fIpt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpt\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBcistpl_longlink_mfc_t\fR structure which contains the parsed +\fBCISTPL_LONGLINK_MFC\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Multi-Function tuple, \fBCISTPL_LONGLINK_MFC,\fR into +a form usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_LONGLINK_MFC\fR tuple describes the start of the +function-specific \fBCIS \fRfor each function on a multi-function card. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_longlink_mfc_t\fR are: +.sp +.in +2 +.nf +uint32_t nfuncs; +uint32_t nregs; +uint32_t function[CIS_MAX_FUNCTIONS].tas +uint32_t function[CIS_MAX_FUNCTIONS].addr +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBnfuncs\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the number of functions on the \fBPC \fRcard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnregs\fR \fR +.ad +.sp .6 +.RS 4n +This field indicates the number of configuration register sets. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBfunction[CIS_MAX_FUNCTIONS].tas\fR \fR +.ad +.sp .6 +.RS 4n +This field provides the target address space for each function on the \fBPC +\fRcard. This field can be one of: +.sp +.ne 2 +.mk +.na +\fB\fBCISTPL_LONGLINK_MFC_TAS_AM\fR\fR +.ad +.sp .6 +.RS 4n +CIS in attribute memory +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCISTPL_LONGLINK_MFC_TAS_CM\fR\fR +.ad +.sp .6 +.RS 4n +CIS in common memory +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBfunction[CIS_MAX_FUNCTIONS].addr\fR \fR +.ad +.sp .6 +.RS 4n +This field provides the target address offset for each function on the \fBPC +\fRcard. +.RE + +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR \fR +.ad +.RS 28n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR \fR +.ad +.RS 28n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR \fR +.ad +.RS 28n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_MANFID.9f b/usr/src/man/man9f/csx_Parse_CISTPL_MANFID.9f new file mode 100644 index 0000000000..25581860d0 --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_MANFID.9f @@ -0,0 +1,161 @@ +'\" 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_Parse_CISTPL_MANFID 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_MANFID \- parse Manufacturer Identification tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_MANFID\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_manfid_t *\fR\fIcm\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcm\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBcistpl_manfid_t\fR structure which contains the parsed +\fBCISTPL_MANFID\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Manufacturer Identification tuple, +\fBCISTPL_MANFID,\fR into a form usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_MANFID\fR tuple is used to describe the information about the +manufacturer of a \fBPC \fRCard. There are two types of information, the \fBPC +\fRCard's manufacturer and a manufacturer card number. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_manfid_t\fR are: +.sp +.in +2 +.nf +uint32_t manf; /* PCMCIA assigned manufacturer code */ +uint32_t card; /* manufacturer information + (part number and/or revision) */ +.fi +.in -2 + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRcard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_ORG.9f b/usr/src/man/man9f/csx_Parse_CISTPL_ORG.9f new file mode 100644 index 0000000000..8a23b41b7c --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_ORG.9f @@ -0,0 +1,183 @@ +'\" 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 csx_Parse_CISTPL_ORG 9F "24 Jan 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_ORG \- parse the Data Organization tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_ORG\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_org_t *\fR\fIpt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpt\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBcistpl_org_t\fR structure which contains the parsed +\fBCISTPL_ORG\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Data Organization tuple, \fBCISTPL_ORG,\fR into a form +usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_ORG\fR tuple provides a text description of the organization. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_org_t\fR are: +.sp +.in +2 +.nf +uint32_t type; +char desc[CIS_MAX_TUPLE_DATA_LEN]; +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBtype\fR\fR +.ad +.sp .6 +.RS 4n +This field indicates type of data organization. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdesc[CIS_MAX_TUPLE_DATA_LEN]\fR\fR +.ad +.sp .6 +.RS 4n +This field provides the text description of this organization. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_SPCL.9f b/usr/src/man/man9f/csx_Parse_CISTPL_SPCL.9f new file mode 100644 index 0000000000..69787df1e9 --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_SPCL.9f @@ -0,0 +1,216 @@ +'\" 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_Parse_CISTPL_SPCL 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_SPCL \- parse the Special Purpose tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_SPCL\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_spcl_t *\fR\fIcsp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcsp\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBcistpl_spcl_t\fR structure which contains the parsed +\fBCISTPL_SPCL\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Special Purpose tuple, \fBCISTPL_SPCL,\fR into a form +usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_SPCL\fR tuple is identified by an identification field that is +assigned by \fBPCMCIA \fRor JEIDA. A sequence field allows a series of +\fBCISTPL_SPCL\fR tuples to be used when the data exceeds the size that can be +stored in a single tuple; the maximum data area of a series of +\fBCISTPL_SPCL\fR tuples is unlimited. Another field gives the number of bytes +in the data field in this tuple. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_date_t\fR are: +.sp +.in +2 +.nf +uint32_t id; /* tuple contents identification */ +uint32_t seq; /* data sequence number */ +uint32_t bytes; /* number of bytes following */ +uchar_t data[CIS_MAX_TUPLE_DATA_LEN]; +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBid\fR\fR +.ad +.RS 9n +.rt +This field contains a \fBPCMCIA \fRor \fBJEIDA \fRassigned value that +identifies this series of one or more \fBCISTPL_SPCL\fR tuples. These field +values are assigned by contacting either \fBPCMCIA \fRor \fBJEIDA\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBseq\fR\fR +.ad +.RS 9n +.rt +This field contains a data sequence number. \fBCISTPL_SPCL_SEQ_END\fR is the +last tuple in sequence. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBbytes\fR\fR +.ad +.RS 9n +.rt +This field contains the number of data bytes in the +\fBdata[CIS_MAX_TUPLE_DATA_LEN]\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdata\fR\fR +.ad +.RS 9n +.rt +The data component of this tuple. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_SWIL.9f b/usr/src/man/man9f/csx_Parse_CISTPL_SWIL.9f new file mode 100644 index 0000000000..11b27a1d39 --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_SWIL.9f @@ -0,0 +1,172 @@ +'\" 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 csx_Parse_CISTPL_SWIL 9F "24 Jan 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_SWIL \- parse the Software Interleaving tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_SWIL\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_swil_t *\fR\fIpt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpt\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBcistpl_swil_t\fR structure which contains the parsed +\fBCISTPL_SWIL\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Software Interleaving tuple, \fBCISTPL_SWIL,\fR into a +form usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_SWIL\fR tuple provides the software interleaving of data within a +partition on the card. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_swil_t\fR are: +.sp +.in +2 +.nf +uint32_t intrlv; +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBintrlv\fR\fR +.ad +.RS 10n +.rt +This field provides the software interleaving for a partition. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_VERS_1.9f b/usr/src/man/man9f/csx_Parse_CISTPL_VERS_1.9f new file mode 100644 index 0000000000..a5210f1144 --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_VERS_1.9f @@ -0,0 +1,163 @@ +'\" 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_Parse_CISTPL_VERS_1 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_VERS_1 \- parse Level-1 Version/Product Information tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_VERS_1\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_vers_1_t *\fR\fIcv1\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcv1\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBcistpl_vers_1_t\fR structure which contains the parsed +\fBCISTPL_VERS_1\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Level-1 Version/Product Information tuple, +\fBCISTPL_VERS_1,\fR into a form usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_VERS_1\fR tuple is used to describe the card Level-1 version +compliance and card manufacturer information. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_vers_1_t\fR are: +.sp +.in +2 +.nf +uint32_t major; /* major version number */ +uint32_t minor; /* minor version number */ +uint32_t ns; /* number of information strings */ +char pi[CISTPL_VERS_1_MAX_PROD_STRINGS] + [CIS_MAX_TUPLE_DATA_LEN]; + /* pointers to product information strings */ +.fi +.in -2 + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_Parse_CISTPL_VERS_2.9f b/usr/src/man/man9f/csx_Parse_CISTPL_VERS_2.9f new file mode 100644 index 0000000000..4704edcb1d --- /dev/null +++ b/usr/src/man/man9f/csx_Parse_CISTPL_VERS_2.9f @@ -0,0 +1,167 @@ +'\" 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_Parse_CISTPL_VERS_2 9F "20 Dec 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Parse_CISTPL_VERS_2 \- parse Level-2 Version and Information tuple +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_Parse_CISTPL_VERS_2\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR, + \fBcistpl_vers_2_t *\fR\fIcv2\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItu\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBtuple_t\fR structure (see \fBtuple\fR(9S)) returned by a call +to \fBcsx_GetFirstTuple\fR(9F) or \fBcsx_GetNextTuple\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcv2\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBcistpl_vers_2_t\fR structure which contains the parsed +\fBCISTPL_VERS_2\fR tuple information upon return from this function. +.RE + +.SH DESCRIPTION +.sp +.LP +This function parses the Level-2 Version and Information tuple, +\fBCISTPL_VERS_2,\fR into a form usable by \fBPC \fRCard drivers. +.sp +.LP +The \fBCISTPL_VERS_2\fR tuple is used to describe the card Level-2 information +which has the logical organization of the card's data. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcistpl_vers_2_t\fR are: +.sp +.in +2 +.nf +uint32_t vers; /* version number */ +uint32_t comply; /* level of compliance */ +uint32_t dindex; /* byte address of first data byte in card */ +uint32_t vspec8; /* vendor specific (byte 8) */ +uint32_t vspec9; /* vendor specific (byte 9) */ +uint32_t nhdr; /* number of copies of CIS present on device */ +char oem[CIS_MAX_TUPLE_DATA_LEN]; + /* Vendor of software that formatted card */ +char info[CIS_MAX_TUPLE_DATA_LEN]; + /* Informational message about card */ +.fi +.in -2 + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNKNOWN_TUPLE\fR\fR +.ad +.RS 27n +.rt +Parser does not know how to parse tuple. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No Card Information Structure (CIS) on \fBPC \fRCard. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S) +.sp +.LP +\fIPC Card 95 Standard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_Put8.9f b/usr/src/man/man9f/csx_Put8.9f new file mode 100644 index 0000000000..877c88e020 --- /dev/null +++ b/usr/src/man/man9f/csx_Put8.9f @@ -0,0 +1,102 @@ +'\" 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_Put8 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_Put8, csx_Put16, csx_Put32, csx_Put64 \- write to device register +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBvoid\fR \fBcsx_Put8\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint32_t\fR \fIoffset\fR, \fBuint8_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcsx_Put16\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint32_t\fR \fIoffset\fR, \fBuint16_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcsx_Put32\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint32_t\fR \fIoffset\fR, \fBuint32_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcsx_Put64\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint32_t\fR \fIoffset\fR, \fBuint64_t\fR \fIvalue\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 11n +.rt +The access handle returned from \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestWindow\fR(9F), or \fBcsx_DupHandle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR \fR +.ad +.RS 11n +.rt +The offset in bytes from the base of the mapped resource. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvalue\fR \fR +.ad +.RS 11n +.rt +The data to be written to the device. +.RE + +.SH DESCRIPTION +.sp +.LP +These functions generate a write of various sizes to the mapped memory or +device register. +.sp +.LP +The \fBcsx_Put8()\fR, \fBcsx_Put16()\fR, \fBcsx_Put32()\fR, and +\fBcsx_Put64()\fR functions write 8 bits, 16 bits, 32 bits, and 64 bits of +data, respectively, to the device address represented by the handle, +\fIhandle\fR, at an offset in bytes represented by the offset, \fIoffset\fR. +.sp +.LP +Data that consists of more than one byte will automatically be translated to +maintain a consistent view between the host and the device based on the encoded +information in the data access handle. The translation may involve byte +swapping if the host and the device have incompatible endian characteristics. +.SH CONTEXT +.sp +.LP +These functions may be called from user, kernel, or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBcsx_DupHandle\fR(9F), \fBcsx_Get8\fR(9F), \fBcsx_GetMappedAddr\fR(9F), +\fBcsx_RepGet8\fR(9F), \fBcsx_RepPut8\fR(9F), \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestWindow\fR(9F) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_RegisterClient.9f b/usr/src/man/man9f/csx_RegisterClient.9f new file mode 100644 index 0000000000..e9dce6ef00 --- /dev/null +++ b/usr/src/man/man9f/csx_RegisterClient.9f @@ -0,0 +1,361 @@ +'\" 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 csx_RegisterClient 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_RegisterClient \- register a client +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_RegisterClient\fR(\fBclient_handle_t *\fR\fIch\fR, \fBclient_reg_t *\fR\fIcr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBclient_handle_t\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImc\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBclient_reg_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function registers a client with Card Services and returns a unique client +handle for the client. The client handle must be passed to +\fBcsx_DeregisterClient\fR(9F) when the client terminates. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBclient_reg_t\fR are: +.sp +.in +2 +.nf + uint32_t Attributes; + uint32_t EventMask; + event_callback_args_t event_callback_args; + uint32_t Version; /* CS version to expect */ + csfunction_t *event_handler; + ddi_iblock_cookie_t *iblk_cookie; /* event iblk cookie */ + ddi_idevice_cookie_t *idev_cookie; /* event idev cookie */ + dev_info_t *dip; /* client's dip */ + char driver_name[MODMAXNAMELEN]; +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR\fR +.ad +.RS 23n +.rt +This field is bit-mapped and defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBINFO_MEM_CLIENT\fR\fR +.ad +.sp .6 +.RS 4n +Memory client device driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBINFO_MTD_CLIENT\fR\fR +.ad +.sp .6 +.RS 4n +Memory Technology Driver client. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBINFO_IO_CLIENT\fR\fR +.ad +.sp .6 +.RS 4n +\fBIO\fR client device driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBINFO_CARD_SHARE\fR\fR +.ad +.sp .6 +.RS 4n +Generate artificial \fBCS_EVENT_CARD_INSERTION\fR and +\fBCS_EVENT_REGISTRATION_COMPLETE\fR events. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBINFO_CARD_EXCL\fR\fR +.ad +.sp .6 +.RS 4n +Generate artificial \fBCS_EVENT_CARD_INSERTION\fR and +\fBCS_EVENT_REGISTRATION_COMPLETE\fR events. +.sp +.ne 2 +.mk +.na +\fB\fBINFO_MEM_CLIENT\fR\fR +.ad +.br +.na +\fB\fBINFO_MTD_CLIENT\fR\fR +.ad +.br +.na +\fB\fBINFO_IO_CLIENT\fR\fR +.ad +.sp .6 +.RS 4n +These bits are mutually exclusive (that is, only one bit may be set), but one +of the bits must be set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBINFO_CARD_SHARE\fR\fR +.ad +.br +.na +\fB\fBINFO_CARD_EXCL\fR\fR +.ad +.sp .6 +.RS 4n +If either of these bits is set, the client will receive a +\fBCS_EVENT_REGISTRATION_COMPLETE\fR event when Card Services has completed its +internal client registration processing and after a sucessful call to +\fBcsx_RequestSocketMask\fR(9F). +.sp +Also, if either of these bits is set, and if a card of the type that the client +can control is currently inserted in the socket (and after a successful call to +\fBcsx_RequestSocketMask\fR(9F)), the client will receive an artificial +\fBCS_EVENT_CARD_INSERTION\fR event. +.RE + +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEvent\fR \fBMask\fR\fR +.ad +.RS 23n +.rt +This field is bit-mapped and specifies the client's global event mask. Card +Services performs event notification based on this field. See +\fBcsx_event_handler\fR(9E) for valid event definitions and for additional +information about handling events. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBevent_callback_args\fR\fR +.ad +.RS 23n +.rt +The \fBevent_callback_args_t\fR structure members are: +.sp +.in +2 +.nf + void *client_data; +.fi +.in -2 + +The \fBclient_data\fR field may be used to provide data available to the event +handler (see \fBcsx_event_handler\fR(9E)). Typically, this is the client +driver's soft state pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBVersion\fR\fR +.ad +.RS 23n +.rt +This field contains the specific Card Services version number that the client +expects to use. Typically, the client will use the \fBCS_VERSION\fR macro to +specify to Card Services which version of Card Services the client expects. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBevent_handler\fR\fR +.ad +.RS 23n +.rt +The client event callback handler entry point is passed in the +\fBevent_handler\fR field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiblk_cookie\fR\fR +.ad +.br +.na +\fB\fBidev_cookie\fR\fR +.ad +.RS 23n +.rt +These fields must be used by the client to set up mutexes that are used in the +client's event callback handler when handling high priority events. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdip\fR\fR +.ad +.RS 23n +.rt +The client must set this field with a pointer to the client's dip. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdriver_name\fR\fR +.ad +.RS 23n +.rt +The client must copy a driver-unique name into this member. This name must be +identical across all instances of the driver. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_ATTRIBUTE\fR\fR +.ad +.RS 27n +.rt +No client type or more than one client type specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_OUT_OF_RESOURCE\fR\fR +.ad +.RS 27n +.rt +Card Services is unable to register client. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_VERSION\fR\fR +.ad +.RS 27n +.rt +Card Services version is incompatible with client. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client has already registered for this socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA\fR hardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_DeregisterClient\fR(9F), \fBcsx_RequestSocketMask\fR(9F) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_ReleaseConfiguration.9f b/usr/src/man/man9f/csx_ReleaseConfiguration.9f new file mode 100644 index 0000000000..8f79709e40 --- /dev/null +++ b/usr/src/man/man9f/csx_ReleaseConfiguration.9f @@ -0,0 +1,153 @@ +'\" 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_ReleaseConfiguration 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_ReleaseConfiguration \- release PC Card and socket configuration +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_ReleaseConfiguration\fR(\fBclient_handle_t\fR \fIch\fR, \fBrelease_config_t *\fR\fIrc\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrc\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBrelease_config_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function returns a \fBPC\fR Card and socket to a simple memory only +interface and sets the card to configuration zero by writing a \fB0\fR to the +\fBPC\fR card's \fBCOR\fR (Configuration Option Register). +.sp +.LP +Card Services may remove power from the socket if no clients have indicated +their usage of the socket by an active \fBcsx_RequestConfiguration\fR(9F) or +\fBcsx_RequestWindow\fR(9F). +.sp +.LP +Card Services is prohibited from resetting the \fBPC\fR Card and is not +required to cycle power through zero (\fB0\fR) volts. +.sp +.LP +After calling \fBcsx_ReleaseConfiguration()\fR any resources requested via the +request functions \fBcsx_RequestIO\fR(9F), \fBcsx_RequestIRQ\fR(9F), or +\fBcsx_RequestWindow\fR(9F) that are no longer needed should be returned to +Card Services via the corresponding \fBcsx_ReleaseIO\fR(9F), +\fBcsx_ReleaseIRQ\fR(9F), or \fBcsx_ReleaseWindow\fR(9F) functions. +\fBcsx_ReleaseConfiguration()\fR must be called to release the current card and +socket configuration before releasing any resources requested by the driver via +the request functions named above. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBrelease_config_t\fR are: +.sp +.in +2 +.nf +uint32_t Socket; /* socket number */ +.fi +.in -2 + +.sp +.LP +The \fBSocket\fR field is not used in Solaris, but for portability with other +Card Services implementations, it should be set to the logical socket number. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid or \fBcsx_RequestConfiguration\fR(9F) not done. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SOCKET\fR \fR +.ad +.RS 28n +.rt +Error getting or setting socket hardware parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR \fR +.ad +.RS 28n +.rt +No \fBPC\fR card in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA\fR hardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_RegisterClient\fR(9F), \fBcsx_RequestConfiguration\fR(9F), +\fBcsx_RequestIO\fR(9F), \fBcsx_RequestIRQ\fR(9F), \fBcsx_RequestWindow\fR(9F) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_RepGet8.9f b/usr/src/man/man9f/csx_RepGet8.9f new file mode 100644 index 0000000000..294e13ac20 --- /dev/null +++ b/usr/src/man/man9f/csx_RepGet8.9f @@ -0,0 +1,138 @@ +'\" 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_RepGet8 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_RepGet8, csx_RepGet16, csx_RepGet32, csx_RepGet64 \- read repetitively from +the device register +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBvoid\fR \fBcsx_RepGet8\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint8_t *\fR\fIhostaddr\fR, \fBuint32_t\fR \fIoffset\fR, + \fBuint32_t\fR \fIrepcount\fR, \fBuint32_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcsx_RepGet16\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint16_t *\fR\fIhostaddr\fR, \fBuint32_t\fR \fIoffset\fR, + \fBuint32_t\fR \fIrepcount\fR, \fBuint32_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcsx_RepGet32\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint32_t *\fR\fIhostaddr\fR, \fBuint32_t\fR \fIoffset\fR, + \fBuint32_t\fR \fIrepcount\fR, \fBuint32_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcsx_RepGet64\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint64_t *\fR\fIhostaddr\fR, \fBuint32_t\fR \fIoffset\fR, + \fBuint32_t\fR \fIrepcount\fR, \fBuint32_t\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 13n +.rt +The access handle returned from \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestWindow\fR(9F), or \fBcsx_DupHandle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhostaddr\fR \fR +.ad +.RS 13n +.rt +Source host address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR \fR +.ad +.RS 13n +.rt +The offset in bytes from the base of the mapped resource. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrepcount\fR \fR +.ad +.RS 13n +.rt +Number of data accesses to perform. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR \fR +.ad +.RS 13n +.rt +Device address flags. +.RE + +.SH DESCRIPTION +.sp +.LP +These functions generate multiple reads of various sizes from the mapped memory +or device register. +.sp +.LP +The \fBcsx_RepGet8()\fR, \fBcsx_RepGet16()\fR, \fBcsx_RepGet32()\fR, and +\fBcsx_RepGet64()\fR functions generate \fIrepcount\fR reads of 8 bits, 16 +bits, 32 bits, and 64 bits of data, respectively, from the device address +represented by the handle, \fIhandle\fR, at an offset in bytes represented by +the offset, \fIoffset\fR. The data read is stored consecutively into the buffer +pointed to by the host address pointer, \fIhostaddr\fR. +.sp +.LP +Data that consists of more than one byte will automatically be translated to +maintain a consistent view between the host and the device based on the encoded +information in the data access handle. The translation may involve byte +swapping if the host and the device have incompatible endian characteristics. +.sp +.LP +When the \fIflags\fR argument is set to \fBCS_DEV_AUTOINCR\fR, these functions +increment the device offset, \fIoffset\fR, after each datum read operation. +However, when the \fIflags\fR argument is set to \fBCS_DEV_NO_AUTOINCR\fR, the +same device offset will be used for every datum access. For example, this flag +may be useful when reading from a data register. +.SH CONTEXT +.sp +.LP +These functions may be called from user, kernel, or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBcsx_DupHandle\fR(9F), \fBcsx_Get8\fR(9F), \fBcsx_GetMappedAddr\fR(9F), +\fBcsx_Put8\fR(9F), \fBcsx_RepPut8\fR(9F), \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestWindow\fR(9F) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_RepPut8.9f b/usr/src/man/man9f/csx_RepPut8.9f new file mode 100644 index 0000000000..cd0342c2da --- /dev/null +++ b/usr/src/man/man9f/csx_RepPut8.9f @@ -0,0 +1,138 @@ +'\" 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_RepPut8 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_RepPut8, csx_RepPut16, csx_RepPut32, csx_RepPut64 \- write repetitively to +the device register +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBvoid\fR \fBcsx_RepPut8\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint8_t *\fR\fIhostaddr\fR, \fBuint32_t\fR \fIoffset\fR, + \fBuint32_t\fR \fIrepcount\fR, \fBuint32_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcsx_RepPut16\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint16_t *\fR\fIhostaddr\fR, \fBuint32_t\fR \fIoffset\fR, + \fBuint32_t\fR \fIrepcount\fR, \fBuint32_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcsx_RepPut32\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint32_t *\fR\fIhostaddr\fR, \fBuint32_t\fR \fIoffset\fR, + \fBuint32_t\fR \fIrepcount\fR, \fBuint32_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcsx_RepPut64\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint64_t *\fR\fIhostaddr\fR, \fBuint32_t\fR \fIoffset\fR, + \fBuint32_t\fR \fIrepcount\fR, \fBuint32_t\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 13n +.rt +The access handle returned from \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestWindow\fR(9F), or \fBcsx_DupHandle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhostaddr\fR \fR +.ad +.RS 13n +.rt +Source host address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR \fR +.ad +.RS 13n +.rt +The offset in bytes from the base of the mapped resource. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrepcount\fR \fR +.ad +.RS 13n +.rt +Number of data accesses to perform. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR \fR +.ad +.RS 13n +.rt +Device address flags. +.RE + +.SH DESCRIPTION +.sp +.LP +These functions generate multiple writes of various sizes to the mapped memory +or device register. +.sp +.LP +The \fBcsx_RepPut8()\fR, \fBcsx_RepPut16()\fR, \fBcsx_RepPut32()\fR, and +\fBcsx_RepPut64()\fR functions generate \fIrepcount\fR writes of 8 bits, 16 +bits, 32 bits, and 64 bits of data, respectively, to the device address +represented by the handle, \fIhandle\fR, at an offset in bytes represented by +the offset, \fIoffset\fR. The data written is read consecutively from the +buffer pointed to by the host address pointer, \fIhostaddr\fR. +.sp +.LP +Data that consists of more than one byte will automatically be translated to +maintain a consistent view between the host and the device based on the encoded +information in the data access handle. The translation may involve byte +swapping if the host and the device have incompatible endian characteristics. +.sp +.LP +When the \fIflags\fR argument is set to \fBCS_DEV_AUTOINCR\fR, these functions +increment the device offset, \fIoffset\fR, after each datum write operation. +However, when the \fIflags\fR argument is set to \fBCS_DEV_NO_AUTOINCR\fR, the +same device offset will be used for every datum access. For example, this flag +may be useful when writing to a data register. +.SH CONTEXT +.sp +.LP +These functions may be called from user, kernel, or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBcsx_DupHandle\fR(9F), \fBcsx_Get8\fR(9F), \fBcsx_GetMappedAddr\fR(9F), +\fBcsx_Put8\fR(9F), \fBcsx_RepGet8\fR(9F), \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestWindow\fR(9F) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_RequestConfiguration.9f b/usr/src/man/man9f/csx_RequestConfiguration.9f new file mode 100644 index 0000000000..0b5ac00122 --- /dev/null +++ b/usr/src/man/man9f/csx_RequestConfiguration.9f @@ -0,0 +1,510 @@ +'\" 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_RequestConfiguration 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_RequestConfiguration \- configure the PC Card and socket +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_RequestConfiguration\fR(\fBclient_handle_t\fR \fIch\fR, \fBconfig_req_t *\fR\fIcr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcr\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBconfig_req_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function configures the \fBPC\fR Card and socket. It must be used by +clients that require \fBI/O\fR or \fBIRQ\fR resources for their \fBPC\fR Card. +.sp +.LP +\fBcsx_RequestIO\fR(9F) and \fBcsx_RequestIRQ\fR(9F) must be used before +calling this function to specify the \fBI/O\fR and \fBIRQ\fR requirements for +the \fBPC\fR Card and socket if necessary. \fBcsx_RequestConfiguration()\fR +establishes the configuration in the socket adapter and \fBPC\fR Card, and it +programs the Base and Limit registers of multi-function \fBPC\fR Cards if these +registers exist. The values programmed into these registers depend on the +\fBIO\fR requirements of this configuration. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBconfig_req_t\fR are: +.sp +.in +2 +.nf +uint32_t Socket; /* socket number */ +uint32_t Attributes; /* configuration attributes */ +uint32_t Vcc; /* Vcc value */ +uint32_t Vpp1; /* Vpp1 value */ +uint32_t Vpp2; /* Vpp2 value */ +uint32_t IntType; /* socket interface type - mem or IO */ +uint32_t ConfigBase; /* offset from start of AM space */ +uint32_t Status; /* value to write to STATUS register */ +uint32_t Pin; /* value to write to PRR */ +uint32_t Copy; /* value to write to COPY register */ +uint32_t ConfigIndex; /* value to write to COR */ +uint32_t Present; /* which config registers present */ +uint32_t ExtendedStatus; /* value to write to EXSTAT register */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR\fR +.ad +.sp .6 +.RS 4n +Not used in Solaris, but for portability with other Card Services +implementations, it should be set to the logical socket number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR\fR +.ad +.sp .6 +.RS 4n +This field is bit-mapped. It indicates whether the client wishes the \fBIRQ\fR +resources to be enabled and whether Card Services should ignore the \fBVS\fR +bits on the socket interface. The following bits are defined: +.sp +.ne 2 +.mk +.na +\fB\fBCONF_ENABLE_IRQ_STEERING\fR\fR +.ad +.sp .6 +.RS 4n +Enable IRQ Steering. Set to connect the \fBPC\fR Card \fBIREQ\fR line to a +system interrupt previously selected by a call to \fBcsx_RequestIRQ\fR(9F). If +\fBCONF_ENABLE_IRQ_STEERING\fR is set, once \fBcsx_RequestConfiguration()\fR +has successfully returned, the client may start receiving \fBIRQ\fR callbacks +at the \fBIRQ\fR callback handler established in the call to +\fBcsx_RequestIRQ\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCONF_VSOVERRIDE\fR\fR +.ad +.sp .6 +.RS 4n +Override VS pins. After card insertion and prior to the first successful +\fBcsx_RequestConfiguration()\fR, the voltage levels applied to the card shall +be those indicated by the card's physical key and/or the VS[2:1] voltage sense +pins. For Low Voltage capable host systems (hosts which are capable of \fBVS\fR +pin decoding), if a client desires to apply a voltage not indicated by the +\fBVS\fR pin decoding, then \fBCONF_VSOVERRIDE\fR must be set in the +\fBAttributes\fR field; otherwise, \fBCS_BAD_VCC\fR shall be returned. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBVcc, Vpp1, Vpp2\fR\fR +.ad +.sp .6 +.RS 4n +These fields all represent voltages expressed in tenths of a volt. Values from +zero (\fB0\fR) to \fB25.5\fR volts may be set. To be valid, the exact voltage +must be available from the system. \fBPC\fR Cards indicate multiple \fBVcc\fR +voltage capability in their \fBCIS\fR via the \fBCISTPL_CFTABLE_ENTRY\fR tuple. +After card insertion, Card Services processes the \fBCIS\fR, and when multiple +\fBVcc\fR voltage capability is indicated, Card Services will allow the client +to apply \fBVcc\fR voltage levels which are contrary to the \fBVS\fR pin +decoding without requiring the client to set \fBCONF_VSOVERRIDE.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBIntType\fR\fR +.ad +.sp .6 +.RS 4n +This field is bit-mapped. It indicates how the socket should be configured. The +following bits are defined: +.sp +.ne 2 +.mk +.na +\fB\fBSOCKET_INTERFACE_MEMORY\fR\fR +.ad +.sp .6 +.RS 4n +Memory only interface. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSOCKET_INTERFACE_MEMORY_AND_IO\fR\fR +.ad +.sp .6 +.RS 4n +Memory and I/O interface. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBConfigBase\fR\fR +.ad +.sp .6 +.RS 4n +This field is the offset in bytes from the beginning of attribute memory of the +configuration registers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPresent\fR\fR +.ad +.sp .6 +.RS 4n +This field identifies which of the configuration registers are present. If +present, the corresponding bit is set. This field is bit-mapped as follows: +.sp +.ne 2 +.mk +.na +\fB\fBCONFIG_OPTION_REG_PRESENT\fR\fR +.ad +.RS 30n +.rt +Configuration Option Register (COR) present +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCONFIG_STATUS_REG_PRESENT\fR\fR +.ad +.RS 30n +.rt +Configuration Status Register (CCSR) present +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCONFIG_PINREPL_REG_PRESENT\fR\fR +.ad +.RS 30n +.rt +Pin Replacement Register (PRR) present +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCONFIG_COPY_REG_PRESENT\fR\fR +.ad +.RS 30n +.rt +Socket and Copy Register (SCR) present +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCONFIG_ESR_REG_PRESENT\fR\fR +.ad +.RS 30n +.rt +Extended Status Register (ESR) present +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBStatus, Pin, Copy, ExtendedStatus\fR\fR +.ad +.sp .6 +.RS 4n +These fields represent the initial values that should be written to those +registers if they are present, as indicated by the \fBPresent\fR field. +.sp +The \fBPin\fR field is also used to inform Card Services which pins in the +\fBPC\fR Card's \fBPRR\fR (Pin Replacement Register) are valid. Only those bits +which are set are considered valid. This affects how status is returned by the +\fBcsx_GetStatus\fR(9F) function. If a particular signal is valid in the +\fBPRR\fR, both the \fImask\fR (\fBSTATUS\fR) bit and the \fIchange\fR +(\fBEVENT\fR) bit must be set in the \fBPin\fR field. The following \fBPRR\fR +bit definitions are provided for client use: +.sp +.ne 2 +.mk +.na +\fB\fBPRR_WP_STATUS\fR\fR +.ad +.RS 20n +.rt +\fBWRITE PROTECT\fR mask +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPRR_READY_STATUS\fR\fR +.ad +.RS 20n +.rt +\fBREADY\fR mask +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPRR_BVD2_STATUS\fR\fR +.ad +.RS 20n +.rt +\fBBVD2\fR mask +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPRR_BVD1_STATUS\fR\fR +.ad +.RS 20n +.rt +\fBBVD1\fR mask +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPRR_WP_EVENT\fR\fR +.ad +.RS 20n +.rt +\fBWRITE PROTECT\fR changed +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPRR_READY_EVENT\fR\fR +.ad +.RS 20n +.rt +\fBREADY\fR changed +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPRR_BVD2_EVENT\fR\fR +.ad +.RS 20n +.rt +\fBBVD2\fR changed +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPRR_BVD1_EVENT\fR\fR +.ad +.RS 20n +.rt +\fBBVD1\fR changed +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBConfigIndex\fR\fR +.ad +.sp .6 +.RS 4n +This field is the value written to the \fBCOR\fR (Configuration Option +Register) for the configuration index required by the \fBPC\fR Card. Only the +least significant six bits of the \fBConfigIndex\fR field are significant; the +upper two (2) bits are ignored. The interrupt type in the \fBCOR\fR is always +set to \fIlevel\fR mode by Card Services. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid or \fBcsx_RequestConfiguration()\fR not done. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SOCKET\fR\fR +.ad +.RS 27n +.rt +Error in getting or setting socket hardware parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_VCC\fR\fR +.ad +.RS 27n +.rt +Requested \fBVcc\fR is not available on socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_VPP\fR\fR +.ad +.RS 27n +.rt +Requested \fBVpp\fR is not available on socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC\fR Card in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_TYPE\fR\fR +.ad +.RS 27n +.rt +\fBI/O\fR and memory interface not supported on socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_CONFIGURATION_LOCKED\fR\fR +.ad +.RS 27n +.rt +\fBcsx_RequestConfiguration()\fR already done. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA\fR hardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_AccessConfigurationRegister\fR(9F), \fBcsx_GetStatus\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_ReleaseConfiguration\fR(9F), +\fBcsx_RequestIO\fR(9F), \fBcsx_RequestIRQ\fR(9F) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_RequestIO.9f b/usr/src/man/man9f/csx_RequestIO.9f new file mode 100644 index 0000000000..64fcd65702 --- /dev/null +++ b/usr/src/man/man9f/csx_RequestIO.9f @@ -0,0 +1,535 @@ +'\" 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_RequestIO 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_RequestIO, csx_ReleaseIO \- request or release I/O resources for the client +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_RequestIO\fR(\fBclient_handle_t\fR \fIch\fR, \fBio_req_t *\fR\fIir\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBcsx_ReleaseIO\fR(\fBclient_handle_t\fR \fIch\fR, \fBio_req_t *\fR\fIir\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIir\fR\fR +.ad +.RS 6n +.rt +Pointer to an \fBio_req_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The functions \fBcsx_RequestIO()\fR and \fBcsx_ReleaseIO()\fR request or +release, respectively, \fBI/O\fR resources for the client. +.sp +.LP +If a client requires \fBI/O\fR resources, \fBcsx_RequestIO()\fR must be called +to request \fBI/O\fR resources from Card Services; then +\fBcsx_RequestConfiguration\fR(9F) must be used to establish the configuration. +\fBcsx_RequestIO()\fR can be called multiple times until a successful set of +\fBI/O\fR resources is found. \fBcsx_RequestConfiguration\fR(9F) only uses the +last configuration specified. +.sp +.LP +\fBcsx_RequestIO()\fR fails if it has already been called without a +corresponding \fBcsx_ReleaseIO()\fR. +.sp +.LP +\fBcsx_ReleaseIO()\fR releases previously requested \fBI/O\fR resources. The +Card Services window resource list is adjusted by this function. Depending on +the adapter hardware, the \fBI/O\fR window might also be disabled. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBio_req_t\fR are: +.sp +.in +2 +.nf +uint32_t Socket; /* socket number*/ + +uint32_t Baseport1.base; /* IO range base port address */ +acc_handle_t Baseport1.handle; /* IO range base address + /* or port num */ +uint32_t NumPorts1; /* first IO range number contiguous + /* ports */ +uint32_t Attributes1; /* first IO range attributes */ + +uint32_t Baseport2.base; /* IO range base port address */ +acc_handle_t Baseport2.handle; /* IO range base address or port num */ +uint32_t NumPorts2; /* second IO range number contiguous + /* ports */ +uint32_t Attributes2; /* second IO range attributes */ + +uint32_t IOAddrLines; /* number of IO address lines decoded */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR\fR +.ad +.RS 20n +.rt +Not used in Solaris, but for portability with other Card Services +implementations, it should be set to the logical socket number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBBasePort1.base\fR\fR +.ad +.br +.na +\fB\fBBasePort1.handle\fR\fR +.ad +.br +.na +\fB\fBBasePort2.base\fR\fR +.ad +.br +.na +\fB\fBBasePort2.handle\fR\fR +.ad +.RS 20n +.rt +Two \fBI/O\fR address ranges can be requested by \fBcsx_RequestIO()\fR. Each +\fBI/O\fR address range is specified by the \fBBasePort\fR, \fBNumPorts\fR, and +\fBAttributes\fR fields. If only a single \fBI/O\fR range is being requested, +the \fBNumPorts2\fR field must be reset to \fB0\fR. +.sp +When calling \fBcsx_RequestIO()\fR, the \fBBasePort.base\fR field specifies the +first port address requested. Upon successful return from +\fBcsx_RequestIO()\fR, the \fBBasePort.handle\fR field contains an access +handle, corresponding to the first byte of the allocated \fBI/O\fR window, +which the client must use when accessing the \fBPC\fR Card's \fBI/O\fR space +via the common access functions. A client \fImust not\fR make any assumptions +as to the format of the returned \fBBasePort.handle\fR field value. +.sp +If the \fBBasePort.base\fR field is set to \fB0\fR, Card Services returns an +\fBI/O\fR resource based on the available \fBI/O\fR resources and the number of +contiguous ports requested. When \fBBasePort.base\fR is \fB0\fR, Card Services +aligns the returned resource in the host system's \fBI/O\fR address space on a +boundary that is a multiple of the number of contiguous ports requested, +rounded up to the nearest power of two. For example, if a client requests two +\fBI/O\fR ports, the resource returned will be a multiple of two. If a client +requests five contiguous \fBI/O\fR ports, the resource returned will be a +multiple of eight. +.sp +If multiple ranges are being requested, at least one of the \fBBasePort.base\fR +fields must be non-zero. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNumPorts\fR\fR +.ad +.RS 20n +.rt +This field is the number of contiguous ports being requested. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR\fR +.ad +.RS 20n +.rt +This field is bit-mapped. The following bits are defined: +.sp +.ne 2 +.mk +.na +\fB\fBIO_DATA_WIDTH_8\fR\fR +.ad +.RS 27n +.rt +\fBI/O\fR resource uses 8-bit data path. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBIO_DATA_WIDTH_16\fR\fR +.ad +.RS 27n +.rt +\fBI/O\fR resource uses 16-bit data path. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_NEVER_SWAP\fR\fR +.ad +.RS 27n +.rt +Host endian byte ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_BIG_ENDIAN\fR\fR +.ad +.RS 27n +.rt +Big endian byte ordering +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_LITTLE_ENDIAN\fR\fR +.ad +.RS 27n +.rt +Little endian byte ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_STRICT_ORDER\fR\fR +.ad +.RS 27n +.rt +Program ordering references. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_UNORDERED_OK\fR\fR +.ad +.RS 27n +.rt +May re-order references. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_MERGING_OK\fR\fR +.ad +.RS 27n +.rt +Merge stores to consecutive locations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_LOADCACHING_OK\fR\fR +.ad +.RS 27n +.rt +May cache load operations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_STORECACHING_OK\fR\fR +.ad +.RS 27n +.rt +May cache store operations. +.RE + +For some combinations of host system busses and adapter hardware, the width of +an \fBI/O\fR resource can not be set via \fBRequestIO()\fR; on those systems, +the host bus cycle access type determines the \fBI/O\fR resource data path +width on a per-cycle basis. +.sp +\fBWIN_ACC_BIG_ENDIAN\fR and \fBWIN_ACC_LITTLE\fR \fBENDIAN\fR describe the +endian characteristics of the device as big endian or little endian, +respectively. Even though most of the devices will have the same endian +characteristics as their busses, there are examples of devices with an +\fBI/O\fR processor that has opposite endian characteristics of the busses. +When \fBWIN_ACC_BIG_ENDIAN\fR or \fBWIN_ACC_LITTLE\fR \fBENDIAN\fR is set, byte +swapping will automatically be performed by the system if the host machine and +the device data formats have opposite endian characteristics. The +implementation may take advantage of hardware platform byte swapping +capabilities. +.sp +When \fBWIN_ACC_NEVER_SWAP\fR is specified, byte swapping will not be invoked +in the data access functions. The ability to specify the order in which the +\fBCPU\fR will reference data is provided by the following \fBAttributes\fR +bits. Only one of the following bits may be specified: +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_STRICT_ORDER\fR\fR +.ad +.sp .6 +.RS 4n +The data references must be issued by a \fBCPU\fR in program order. Strict +ordering is the default behavior. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_UNORDERED_OK\fR\fR +.ad +.sp .6 +.RS 4n +The \fBCPU\fR may re-order the data references. This includes all kinds of +re-ordering (that is, a load followed by a store may be replaced by a store +followed by a load). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_MERGING_OK\fR\fR +.ad +.sp .6 +.RS 4n +The \fBCPU\fR may merge individual stores to consecutive locations. For +example, the \fBCPU\fR may turn two consecutive byte stores into one halfword +store. It may also batch individual loads. For example, the \fBCPU\fR may turn +two consecutive byte loads into one halfword load. \fBIO_MERGING_OK_ACC\fR also +implies re-ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_LOADCACHING_OK\fR\fR +.ad +.sp .6 +.RS 4n +The \fBCPU\fR may cache the data it fetches and reuse it until another store +occurs. The default behavior is to fetch new data on every load. +\fBWIN_ACC_LOADCACHING_OK\fR also implies merging and re-ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_STORECACHING_OK\fR\fR +.ad +.sp .6 +.RS 4n +The \fBCPU\fR may keep the data in the cache and push it to the device (perhaps +with other data) at a later time. The default behavior is to push the data +right away. \fBWIN_ACC_STORECACHING_OK\fR also implies load caching, merging, +and re-ordering. +.RE + +These values are advisory, not mandatory. For example, data can be ordered +without being merged or cached, even though a driver requests unordered, merged +and cached together. All other bits in the \fBAttributes\fR field must be set +to \fB0\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBIOAddrLines\fR\fR +.ad +.RS 20n +.rt +This field is the number of \fBI/O\fR address lines decoded by the \fBPC\fR +Card in the specified socket. +.RE + +.sp +.LP +On some systems, multiple calls to \fBcsx_RequestIO()\fR with different +\fBBasePort\fR, \fBNumPorts\fR, and/or \fBIOAddrLines\fR values will have to be +made to find an acceptable combination of parameters that can be used by Card +Services to allocate \fBI/O\fR resources for the client. (See \fBNOTES\fR). +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_ATTRIBUTE\fR\fR +.ad +.RS 27n +.rt +Invalid \fBAttributes\fR specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_BASE\fR\fR +.ad +.RS 27n +.rt +\fBBasePort\fR value is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_CONFIGURATION_LOCKED\fR\fR +.ad +.RS 27n +.rt +\fBcsx_RequestConfiguration\fR(9F) has already been done. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_IN_USE\fR\fR +.ad +.RS 27n +.rt +\fBcsx_RequestIO()\fR has already been done without a corresponding +\fBcsx_ReleaseIO()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC\fR Card in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_WINDOW\fR\fR +.ad +.RS 27n +.rt +Unable to allocate \fBI/O\fR resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_OUT_OF_RESOURCE\fR\fR +.ad +.RS 27n +.rt +Unable to allocate \fBI/O\fR resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA\fR hardware installed. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_RegisterClient\fR(9F), \fBcsx_RequestConfiguration\fR(9F) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA +.SH NOTES +.sp +.LP +It is important for clients to try to use the minimum amount of \fBI/O\fR +resources necessary. One way to do this is for the client to parse the +\fBCIS\fR of the \fBPC\fR Card and call \fBcsx_RequestIO()\fR first with any +\fBIOAddrLines\fR values that are \fB0\fR or that specify a minimum number of +address lines necessary to decode the \fBI/O\fR space on the \fBPC\fR Card. +Also, if no convenient minimum number of address lines can be used to decode +the \fBI/O\fR space on the \fBPC\fR Card, it is important to try to avoid +system conflicts with well-known architectural hardware features. diff --git a/usr/src/man/man9f/csx_RequestIRQ.9f b/usr/src/man/man9f/csx_RequestIRQ.9f new file mode 100644 index 0000000000..9ff5ac2697 --- /dev/null +++ b/usr/src/man/man9f/csx_RequestIRQ.9f @@ -0,0 +1,295 @@ +'\" 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 csx_RequestIRQ 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_RequestIRQ, csx_ReleaseIRQ \- request or release IRQ resource +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_RequestIRQ\fR(\fBclient_handle_t\fR \fIch\fR, \fBirq_req_t *\fR\fIir\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBcsx_ReleaseIRQ\fR(\fBclient_handle_t\fR \fIch\fR, \fBirq_req_t *\fR\fIir\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIir\fR \fR +.ad +.RS 7n +.rt +Pointer to an \fBirq_req_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The function \fBcsx_RequestIRQ()\fR requests an \fBIRQ\fR resource and +registers the client's \fBIRQ\fR handler with Card Services. +.sp +.LP +If a client requires an \fBIRQ\fR,\fBcsx_RequestIRQ()\fR must be called to +request an \fBIRQ\fR resource as well as to register the client's \fBIRQ\fR +handler with Card Services. The client will not receive callbacks at the +\fBIRQ\fR callback handler until \fBcsx_RequestConfiguration\fR(9F) or +\fBcsx_ModifyConfiguration\fR(9F) has successfully returned when either of +these functions are called with the \fBCONF_ENABLE_IRQ_STEERING\fR bit set. +.sp +.LP +The function \fBcsx_ReleaseIRQ()\fR releases a previously requested \fBIRQ\fR +resource. +.sp +.LP +The Card Services \fBIRQ\fR resource list is adjusted by +\fBcsx_ReleaseIRQ()\fR. Depending on the adapter hardware, the host bus +\fBIRQ\fR connection might also be disabled. Client \fBIRQ\fR handlers always +run above lock level and so should take care to perform only Solaris operations +that are appropriate for an above-lock-level \fBIRQ\fR handler. +.sp +.LP +\fBcsx_RequestIRQ()\fR fails if it has already been called without a +corresponding \fBcsx_ReleaseIRQ()\fR. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBirq_req_t\fR are: +.sp +.in +2 +.nf +uint32_t Socket; /* socket number */ +uint32_t Attributes; /* IRQ attribute flags */ +csfunction_t *irq_handler; /* IRQ handler */ +void *irq_handler_arg; /* IRQ handler argument */ +ddi_iblock_cookie_t *iblk_cookie; /* IRQ interrupt + /* block cookie */ +ddi_idevice_cookie_t *idev_cookie; /* IRQ interrupt device + /* cookie */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR \fR +.ad +.RS 20n +.rt +Not used in Solaris, but for portability with other Card Services +implementations, it should be set to the logical socket number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR \fR +.ad +.RS 20n +.rt +This field is bit-mapped. It specifies details about the type of \fBIRQ\fR +desired by the client. The following bits are defined: +.sp +.ne 2 +.mk +.na +\fB\fBIRQ_TYPE_EXCLUSIVE\fR\fR +.ad +.RS 22n +.rt +\fBIRQ\fR is exclusive to this socket. This bit must be set. It indicates that +the system IRQ is dedicated to this PC Card. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBirq_handler\fR \fR +.ad +.RS 20n +.rt +The client \fBIRQ\fR callback handler entry point is passed in the +\fBirq_handler\fR field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBirq_handler_arg\fR \fR +.ad +.RS 20n +.rt +The client can use the \fBirq_handler_arg\fR field to pass client-specific data +to the client \fBIRQ\fR callback handler. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBiblk_cookie\fR \fR +.ad +.br +.na +\fB\fBidev_cookie\fR \fR +.ad +.RS 20n +.rt +These fields must be used by the client to set up mutexes that are used in the +client's \fBIRQ\fR callback handler. +.RE + +.sp +.LP +For a specific \fBcsx_ReleaseIRQ()\fR call, the values in the \fBirq_req_t\fR +structure must be the same as those returned from the previous +\fBcsx_RequestIRQ()\fR call; otherwise, \fBCS_BAD_ARGS\fR is returned and no +changes are made to Card Services resources or the socket and adapter hardware. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_ARGS\fR \fR +.ad +.RS 28n +.rt +\fBIRQ\fR description does not match allocation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_ATTRIBUTE\fR \fR +.ad +.RS 28n +.rt +\fBIRQ_TYPE_EXCLUSIVE\fR not set, or an unsupported or reserved bit is set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid or \fBcsx_RequestConfiguration\fR(9F) not done. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_IRQ\fR \fR +.ad +.RS 28n +.rt +Unable to allocate \fBIRQ\fR resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_IN_USE\fR \fR +.ad +.RS 28n +.rt +\fBcsx_RequestIRQ()\fR already done or a previous \fBcsx_RequestIRQ()\fR has +not been done for a corresponding \fBcsx_ReleaseIRQ()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_CONFIGURATION_LOCKED\fR \fR +.ad +.RS 28n +.rt +\fBcsx_RequestConfiguration\fR(9F) already done or +\fBcsx_ReleaseConfiguration\fR(9F) has not been done. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR \fR +.ad +.RS 28n +.rt +No \fBPC\fR Card in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA\fR hardware installed. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_ReleaseConfiguration\fR(9F), \fBcsx_RequestConfiguration\fR(9F) +.sp +.LP +\fIPC Card Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_RequestSocketMask.9f b/usr/src/man/man9f/csx_RequestSocketMask.9f new file mode 100644 index 0000000000..03040b240e --- /dev/null +++ b/usr/src/man/man9f/csx_RequestSocketMask.9f @@ -0,0 +1,201 @@ +'\" 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_RequestSocketMask 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_RequestSocketMask, csx_ReleaseSocketMask \- set or clear the client's +client event mask +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_RequestSocketMask\fR(\fBclient_handle_t\fR \fIch\fR, + \fBrequest_socket_mask_t *\fR\fIsm\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBcsx_ReleaseSocketMask\fR(\fBclient_handle_t\fR \fIch\fR, + \fBrelease_socket_mask_t *\fR\fIrm\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsm\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBrequest_socket_mask_t\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrm\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBrelease_socket_mask_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The function \fBcsx_RequestSocketMask()\fR sets the client's client event mask +and enables the client to start receiving events at its event callback handler. +Once this function returns successfully, the client can start receiving events +at its event callback handler. Any pending events generated from the call to +\fBcsx_RegisterClient\fR(9F) will be delivered to the client after this call as +well. This allows the client to set up the event handler mutexes before the +event handler gets called. +.sp +.LP +\fBcsx_RequestSocketMask()\fR must be used before calling +\fBcsx_GetEventMask\fR(9F) or \fBcsx_SetEventMask\fR(9F) for the client event +mask for this socket. +.sp +.LP +The function \fBcsx_ReleaseSocketMask()\fR clears the client's client event +mask. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBrequest_socket_mask_t\fR are: +.sp +.in +2 +.nf + uint32_t Socket; /* socket number */ + uint32_t EventMask; /* event mask to set or return */ +.fi +.in -2 + +.sp +.LP +The structure members of \fBrelease_socket_mask_t\fR are: +.sp +.in +2 +.nf + uint32_t Socket; /* socket number */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR\fR +.ad +.RS 13n +.rt +Not used in Solaris, but for portability with other Card Services +implementations, it should be set to the logical socket number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEventMask\fR\fR +.ad +.RS 13n +.rt +This field is bit-mapped. Card Services performs event notification based on +this field. See \fBcsx_event_handler\fR(9E) for valid event definitions and for +additional information about handling events. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_IN_USE\fR\fR +.ad +.RS 27n +.rt +\fBcsx_ReleaseSocketMask()\fR has not been done. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SOCKET\fR\fR +.ad +.RS 27n +.rt +\fBcsx_RequestSocketMask()\fR has not been done. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA\fR hardware installed. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_event_handler\fR(9E), \fBcsx_GetEventMask\fR(9F), +\fBcsx_RegisterClient\fR(9F), \fBcsx_SetEventMask\fR(9F) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_RequestWindow.9f b/usr/src/man/man9f/csx_RequestWindow.9f new file mode 100644 index 0000000000..87d251b2b7 --- /dev/null +++ b/usr/src/man/man9f/csx_RequestWindow.9f @@ -0,0 +1,511 @@ +'\" te +.\" Copyright (c) 1999, 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_RequestWindow 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_RequestWindow, csx_ReleaseWindow \- request or release window resources +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_RequestWindow\fR(\fBclient_handle_t\fR \fIch\fR, \fBwindow_handle_t *\fR\fIwh\fR, + \fBwin_req_t *\fR\fIwr\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBcsx_ReleaseWindow\fR(\fBwindow_handle_t\fR \fIwh\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwh\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBwindow_handle_t\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwr\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBwin_req_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The function \fBcsx_RequestWindow()\fR requests a block of system address space +be assigned to a \fBPC \fRCard in a socket. +.sp +.LP +The function \fBcsx_ReleaseWindow()\fR releases window resources which were +obtained by a call to \fBcsx_RequestWindow()\fR. No adapter or socket hardware +is modified by this function. +.sp +.LP +The \fBcsx_MapMemPage\fR(9F) and \fBcsx_ModifyWindow\fR(9F) functions use the +window handle returned by \fBcsx_RequestWindow()\fR. This window handle must be +freed by calling \fBcsx_ReleaseWindow()\fR when the client is done using this +window. +.sp +.LP +The \fBPC\fR Card Attribute or Common Memory offset for this window is set by +\fBcsx_MapMemPage\fR(9F). +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBwin_req_t\fR are: +.sp +.in +2 +.nf +uint32_t Socket; /* socket number */ +uint32_t Attributes; /* window flags */ +uint32_t Base.base; /* requested window */ + /* base address */ +acc_handle_t Base.handle; /* returned handle for + /* base of window */ +uint32_t Size; /* window size requested */ + /* or granted */ +uint32_t win_params.AccessSpeed; /* window access speed */ +uint32_t win_params.IOAddrLines; /* IO address lines decoded */ +uint32_t ReqOffset; /* required window offest */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR\fR +.ad +.RS 26n +.rt +Not used in Solaris, but for portability with other Card Services +implementations, it should be set to the logical socket number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR\fR +.ad +.RS 26n +.rt +This field is bit-mapped and is defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBWIN_MEMORY_TYPE_IO\fR\fR +.ad +.sp .6 +.RS 4n +Points to I/O space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_MEMORY_TYPE_CM\fR\fR +.ad +.sp .6 +.RS 4n +Points to common memory space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_MEMORY_TYPE_AM\fR\fR +.ad +.sp .6 +.RS 4n +These bits select which type of window is being requested. One of these bits +must be set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ENABLE\fR\fR +.ad +.sp .6 +.RS 4n +The client must set this bit to enable the window. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_BIG_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +Describes device as big-endian. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_LITTLE_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +These bits describe the endian characteristics of the device as big endian or +little endian, respectively. Even though most of the devices will have the same +endian characteristics as their busses, there are examples of devices with an +\fBI/O \fRprocessor that has opposite endian characteristics of the busses. +When either of these bits are set, byte swapping will automatically be +performed by the system if the host machine and the device data formats have +opposite endian characteristics. The implementation may take advantage of +hardware platform byte swapping capabilities. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_NEVER_SWAP\fR\fR +.ad +.sp .6 +.RS 4n +When this is specified, byte swapping will not be invoked in the data access +functions. +.RE + +The ability to specify the order in which the \fBCPU\fR will reference data is +provided by the following \fBAttributes\fR bits, only one of which may be +specified: +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_STRICT_ORDER\fR\fR +.ad +.sp .6 +.RS 4n +The data references must be issued by a \fBCPU \fR in program order. Strict +ordering is the default behavior. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_UNORDERED_OK\fR\fR +.ad +.sp .6 +.RS 4n +The \fBCPU\fR may re-order the data references. This includes all kinds of +re-ordering (that is, a load followed by a store may be replaced by a store +followed by a load). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_MERGING_OK\fR\fR +.ad +.sp .6 +.RS 4n +The \fBCPU \fRmay merge individual stores to consecutive locations. For +example, the \fBCPU \fRmay turn two consecutive byte stores into one halfword +store. It may also batch individual loads. For example, the \fBCPU \fRmay turn +two consecutive byte loads into one halfword load. This bit also implies +re-ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_LOADCACHING_OK\fR\fR +.ad +.sp .6 +.RS 4n +The \fBCPU \fRmay cache the data it fetches and reuse it until another store +occurs. The default behavior is to fetch new data on every load. This bit also +implies merging and re-ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBWIN_ACC_STORECACHING_OK\fR\fR +.ad +.sp .6 +.RS 4n +The \fBCPU \fRmay keep the data in the cache and push it to the device (perhaps +with other data) at a later time. The default behavior is to push the data +right away. This bit also implies load caching, merging, and re-ordering. +.RE + +These values are advisory, not mandatory. For example, data can be ordered +without being merged or cached, even though a driver requests unordered, merged +and cached together. +.sp +All other bits in the \fBAttributes\fR field must be set to \fB0\fR. +.sp +On successful return from \fBcsx_RequestWindow()\fR, \fBWIN_OFFSET_SIZE\fR is +set in the \fBAttributes\fR field when the client must specify card offsets to +\fBcsx_MapMemPage\fR(9F) that are a multiple of the window size. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBBase.base\fR\fR +.ad +.RS 26n +.rt +This field must be set to \fB0\fR on calling \fBcsx_RequestWindow()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBBase.handle\fR\fR +.ad +.RS 26n +.rt +On successful return from \fBcsx_RequestWindow()\fR, the \fBBase.handle\fR +field contains an access handle corresponding to the first byte of the +allocated memory window which the client must use when accessing the \fBPC +\fRCard's memory space via the common access functions. A client must \fBnot\fR +make any assumptions as to the format of the returned \fBBase.handle\fR field +value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSize\fR\fR +.ad +.RS 26n +.rt +On calling \fBcsx_RequestWindow()\fR, the \fBSize\fR field is the size in bytes +of the memory window requested. \fBSize\fR may be zero to indicate that Card +Services should provide the smallest sized window available. On successful +return from \fBcsx_RequestWindow()\fR, the \fBSize\fR field contains the actual +size of the window allocated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBwin_params.AccessSpeed\fR\fR +.ad +.RS 26n +.rt +This field specifies the access speed of the window if the client is requesting +a memory window. The \fBAccessSpeed\fR field bit definitions use the format of +the extended speed byte of the Device \fBID \fRtuple. If the mantissa is +\fB0\fR (noted as reserved in the \fBPC Card 95 Standard\fR), the lower bits +are a binary code representing a speed from the following table: +.RE + +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +\fBCode\fR\fBSpeed\fR +_ +0(Reserved - do not use). +_ +1250 nsec +_ +2200 nsec +_ +3150 nsec +_ +4100 nse +_ +5-7(Reserved\(emdo not use.) +.TE + +.sp +.LP +To request a window that supports the \fBWAIT\fR signal, \fBOR-in\fR the +\fBWIN_USE_WAIT\fR bit to the \fBAccessSpeed\fR value before calling this +function. +.sp +.LP +It is recommended that clients use the \fBcsx_ConvertSpeed\fR(9F) function to +generate the appropriate \fBAccessSpeed\fR values rather than manually +perturbing the \fBAccessSpeed\fR field. +.sp +.ne 2 +.mk +.na +\fB\fBwin_params.IOAddrLines\fR\fR +.ad +.RS 26n +.rt +If the client is requesting an \fBI/O \fRwindow, the \fBIOAddrLines\fR field is +the number of \fBI/O \fRaddress lines decoded by the \fBPC \fRCard in the +specified socket. Access to the \fBI/O \fRwindow is not enabled until +\fBcsx_RequestConfiguration\fR(9F) has been invoked successfully. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBReqOffset\fR\fR +.ad +.RS 26n +.rt +This field is a Solaris-specific extension that can be used by clients to +generate optimum window offsets passed to \fBcsx_MapMemPage\fR(9F). +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_ATTRIBUTE\fR\fR +.ad +.RS 27n +.rt +\fBAttributes\fR are invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SPEED\fR\fR +.ad +.RS 27n +.rt +Speed is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SIZE\fR\fR +.ad +.RS 27n +.rt +Window size is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC \fRCard in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_OUT_OF_RESOURCE\fR\fR +.ad +.RS 27n +.rt +Unable to allocate window. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_ConvertSpeed\fR(9F), \fBcsx_MapMemPage\fR(9F), +\fBcsx_ModifyWindow\fR(9F), \fBcsx_RegisterClient\fR(9F), +\fBcsx_RequestConfiguration\fR(9F) +.sp +.LP +\fIPC\fR \fICard\fR \fI95\fR \fIStandard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_ResetFunction.9f b/usr/src/man/man9f/csx_ResetFunction.9f new file mode 100644 index 0000000000..1e82c72b1d --- /dev/null +++ b/usr/src/man/man9f/csx_ResetFunction.9f @@ -0,0 +1,171 @@ +'\" 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_ResetFunction 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_ResetFunction \- reset a function on a PC card +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_ResetFunction\fR(\fBclient_handle_t\fR \fIch\fR, \fBreset_function_t *\fR\fIrf\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrf\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBreset_function_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBcsx_ResetFunction()\fR requests that the specified function on the \fBPC\fR +card initiate a reset operation. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBreset_function_t\fR are: +.sp +.in +2 +.nf + uint32_t Socket; /* socket number */ + uint32_t Attributes; /* reset attributes */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR\fR +.ad +.RS 14n +.rt +Not used in Solaris, but for portability with other Card Services +implementations, it should be set to the logical socket number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR\fR +.ad +.RS 14n +.rt +Must be \fB0\fR. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Card Services has noted the reset request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_IN_USE\fR\fR +.ad +.RS 27n +.rt +This Card Services implementation does not permit configured cards to be reset. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR\fR +.ad +.RS 27n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC\fR card in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SOCKET\fR\fR +.ad +.RS 27n +.rt +Specified socket or function number is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA\fR hardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_event_handler\fR(9E), \fBcsx_RegisterClient\fR(9F) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA +.SH NOTES +.sp +.LP +\fBcsx_ResetFunction()\fR has not been implemented in this release and always +returns \fBCS_IN_USE\fR. diff --git a/usr/src/man/man9f/csx_SetEventMask.9f b/usr/src/man/man9f/csx_SetEventMask.9f new file mode 100644 index 0000000000..53ea1d19b9 --- /dev/null +++ b/usr/src/man/man9f/csx_SetEventMask.9f @@ -0,0 +1,196 @@ +'\" 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_SetEventMask 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_SetEventMask, csx_GetEventMask \- set or return the client event mask for +the client +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_SetEventMask\fR(\fBclient_handle_t\fR \fIch\fR, \fBsockevent_t *\fR\fIse\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBcsx_GetEventMask\fR(\fBclient_handle_t\fR \fIch\fR, \fBsockevent_t *\fR\fIse\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR \fR +.ad +.RS 7n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIse\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBsockevent_t\fR structure +.RE + +.SH DESCRIPTION +.sp +.LP +The function \fBcsx_SetEventMask()\fR sets the client or global event mask for +the client. +.sp +.LP +The function \fBcsx_GetEventMask()\fR returns the client or global event mask +for the client. +.sp +.LP +\fBcsx_RequestSocketMask\fR(9F) must be called before calling +\fBcsx_SetEventMask()\fR for the client event mask for this socket. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBsockevent_t\fR are: +.sp +.in +2 +.nf +uint32_t uint32_t /* attribute flags for call */ +uint32_t EventMask; /* event mask to set or return */ +uint32_t Socket; /* socket number if necessary */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBAttributes\fR\fR +.ad +.RS 14n +.rt +This is a bit-mapped field that identifies the type of event mask to be +returned. The field is defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBCONF_EVENT_MASK_GLOBAL\fR \fR +.ad +.RS 27n +.rt +Client's global event mask. If set, the client's global event mask is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCONF_EVENT_MASK_CLIENT\fR \fR +.ad +.RS 27n +.rt +Client's local event mask. If set, the client's local event mask is returned. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEventMask\fR \fR +.ad +.RS 14n +.rt +This field is bit-mapped. Card Services performs event notification based on +this field. See \fBcsx_event_handler\fR(9E) for valid event definitions and for +additional information about handling events. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR \fR +.ad +.RS 14n +.rt +Not used in Solaris, but for portability with other Card Services +implementations, it should be set to the logical socket number. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 28n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_HANDLE\fR \fR +.ad +.RS 28n +.rt +Client handle is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_BAD_SOCKET\fR \fR +.ad +.RS 28n +.rt +\fBcsx_RequestSocketMask\fR(9F) not called for \fBCONF_EVENT_MASK_CLIENT.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR \fR +.ad +.RS 28n +.rt +No \fBPCMCIA \fRhardware installed. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_event_handler\fR(9E), \fBcsx_RegisterClient\fR(9F), +\fBcsx_ReleaseSocketMask\fR(9F), \fBcsx_RequestSocketMask\fR(9F) +.sp +.LP +\fIPC Card 95 Standard,\fR PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_SetHandleOffset.9f b/usr/src/man/man9f/csx_SetHandleOffset.9f new file mode 100644 index 0000000000..358dc41c1b --- /dev/null +++ b/usr/src/man/man9f/csx_SetHandleOffset.9f @@ -0,0 +1,74 @@ +'\" 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 csx_SetHandleOffset 9F "16 May 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_SetHandleOffset \- set current access handle offset +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_SetHandleOffset\fR(\fBacc_handle_t\fR \fIhandle\fR, \fBuint32_t\fR \fIoffset\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 11n +.rt +Access handle returned by \fBcsx_RequestIRQ\fR(9F) or \fBcsx_RequestIO\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR \fR +.ad +.RS 11n +.rt +New access handle offset. +.RE + +.SH DESCRIPTION +.sp +.LP +This function sets the current offset for the access handle, \fIhandle\fR, to +\fIoffset\fR. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR \fR +.ad +.RS 15n +.rt +Successful operation. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetHandleOffset\fR(9F), \fBcsx_RequestIO\fR(9F), +\fBcsx_RequestIRQ\fR(9F) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9f/csx_ValidateCIS.9f b/usr/src/man/man9f/csx_ValidateCIS.9f new file mode 100644 index 0000000000..455f9ca74a --- /dev/null +++ b/usr/src/man/man9f/csx_ValidateCIS.9f @@ -0,0 +1,159 @@ +'\" 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_ValidateCIS 9F "19 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +csx_ValidateCIS \- validate the Card Information Structure (CIS) +.SH SYNOPSIS +.LP +.nf +#include <sys/pccard.h> + + + +\fBint32_t\fR \fBcsx_ValidateCIS\fR(\fBclient_handle_t\fR \fIch\fR, \fBcisinfo_t *\fR\fIci\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR Specific (Solaris \fBDDI\fR) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIch\fR\fR +.ad +.RS 6n +.rt +Client handle returned from \fBcsx_RegisterClient\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIci\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBcisinfo_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +This function validates the Card Information Structure (CIS) on the \fBPC\fR +Card in the specified socket. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBcisinfo_t\fR are: +.sp +.in +2 +.nf + uint32_t Socket; /* socket number to validate CIS on */ + uint32_t Chains; /* number of tuple chains in CIS */ + uint32_t Tuples; /* total number of tuples in CIS */ +.fi +.in -2 + +.sp +.LP +The fields are defined as follows: +.sp +.ne 2 +.mk +.na +\fB\fBSocket\fR\fR +.ad +.RS 10n +.rt +Not used in Solaris, but for portability with other Card Services +implementations, it should be set to the logical socket number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBChains\fR\fR +.ad +.RS 10n +.rt +This field returns the number of valid tuple chains located in the \fBCIS\fR. +If \fB0\fR is returned, the \fBCIS\fR is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTuples\fR\fR +.ad +.RS 10n +.rt +This field is a Solaris-specific extension and it returns the total number of +tuples on all the chains in the \fBPC\fR Card's \fBCIS\fR. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBCS_SUCCESS\fR\fR +.ad +.RS 27n +.rt +Successful operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CIS\fR\fR +.ad +.RS 27n +.rt +No \fBCIS\fR on \fBPC\fR Card or \fBCIS\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_NO_CARD\fR\fR +.ad +.RS 27n +.rt +No \fBPC\fR Card in socket. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR +.ad +.RS 27n +.rt +No \fBPCMCIA\fR hardware installed. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcsx_GetFirstTuple\fR(9F), \fBcsx_GetTupleData\fR(9F), +\fBcsx_ParseTuple\fR(9F), \fBcsx_RegisterClient\fR(9F) +.sp +.LP +\fIPC Card 95 Standard\fR, PCMCIA/JEIDA diff --git a/usr/src/man/man9f/datamsg.9f b/usr/src/man/man9f/datamsg.9f new file mode 100644 index 0000000000..fc4aa705cd --- /dev/null +++ b/usr/src/man/man9f/datamsg.9f @@ -0,0 +1,110 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH datamsg 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +datamsg \- test whether a message is a data message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBint\fR \fBdatamsg\fR(\fBunsigned char\fR \fItype\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 8n +.rt +The type of message to be tested. The \fBdb_type\fR field of the +\fBdatab\fR(9S) structure contains the message type. This field may be accessed +through the message block using \fBmp->b_datap->db_type\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdatamsg()\fR function tests the type of message to determine if it is a +data message type (\fBM_DATA\fR, \fBM_DELAY\fR, \fBM_PROTO\fR , or +\fBM_PCPROTO\fR). +.SH RETURN VALUES +.sp +.LP +\fBdatamsg\fR returns +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 5n +.rt +if the message is a data message +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +otherwise. +.RE + +.SH CONTEXT +.sp +.LP +The \fBdatamsg()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +The \fBput\fR(9E) routine enqueues all data messages for handling by the +\fBsrv\fR(9E) (service) routine. All non-data messages are handled in the +\fBput\fR(9E) routine. +.sp +.in +2 +.nf +1 \fIxxx\fRput(q, mp) +2 queue_t *q; +3 mblk_t *mp; +4 { +5 if (datamsg(mp->b_datap->db_type)) { +6 putq(q, mp); +7 return; +8 } +9 switch (mp->b_datap->db_type) { +10 case M_FLUSH: + \&.\|.\|. +11 } +12 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBput\fR(9E), \fBsrv\fR(9E), \fBallocb\fR(9F), \fBdatab\fR(9S), \fBmsgb\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/ddi_add_event_handler.9f b/usr/src/man/man9f/ddi_add_event_handler.9f new file mode 100644 index 0000000000..ae04d5b542 --- /dev/null +++ b/usr/src/man/man9f/ddi_add_event_handler.9f @@ -0,0 +1,204 @@ +'\" 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 ddi_add_event_handler 9F "62 Nov 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_add_event_handler \- add an NDI event service callback handler +.SH SYNOPSIS +.LP +.nf +#include <sys/dditypes.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_add_event_handler\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_eventcookie_t\fR \fIcookie\fR, + \fBvoid (*\fR\fIhandler\fR)(dev_info_t *, ddi_eventcookie_t, void *, void *), + \fBvoid *\fR\fIarg\fR, \fBddi_registration_id_t *\fR\fIid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fBdev_info_t *\fR\fIdip\fR\fR +.ad +.sp .6 +.RS 4n +Device node registering the callback. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_eventcookie_t\fR \fIcookie\fR\fR +.ad +.sp .6 +.RS 4n +Cookie returned from call to \fBddi_get_eventcookie\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBvoid (*\fR\fIhandler\fR\fB)(dev_info_t *, ddi_eventcookie_t, void *, void +*)\fR\fR +.ad +.sp .6 +.RS 4n +Callback handler responsible for handling an NDI event service notification. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBvoid *\fR\fIarg\fR\fR +.ad +.sp .6 +.RS 4n +Pointer to opaque data supplied by the caller. Typically, this would be a +pointer to the driver's \fBsoftstate\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_registration_id_t *\fR\fIid\fR\fR +.ad +.sp .6 +.RS 4n +Pointer to registration ID where a unique registration id will be returned. +Registration ID must be saved and used when calling +\fBddi_remove_event_handler\fR(9F) to unregister a callback. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_add_event_handler()\fR function adds a callback handler to be +invoked in the face of the event specifed by \fIcookie\fR. The process of +adding a callback handler is also known as subscribing to an event. Upon +successful subscription, the handler will be invoked by the system when the +event occurs. The handler can be unregistered by using +\fBddi_remove_event_handler\fR(9F). +.sp +.LP +An instance of a driver can register multiple handlers for an event or a single +handler for multiple events. Callback order is not defined and should assumed +to be random. +.sp +.LP +The routine handler will be invoked with the following arguments: +.sp +.ne 2 +.mk +.na +\fB\fBdev_info_t *\fR\fIdip\fR\fR +.ad +.RS 28n +.rt +Device node requesting the notification. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_eventcookie_t\fR \fIcookie\fR\fR +.ad +.RS 28n +.rt +Structure describing event that occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBvoid *\fR\fIarg\fR\fR +.ad +.RS 28n +.rt +Opaque data pointer provided, by the driver, during callback registration. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBvoid *\fR\fIimpl_data\fR\fR +.ad +.RS 28n +.rt +Pointer to event specific data defined by the framework which invokes the +callback function. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Callback handler registered successfully. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Failed to register callback handler. Possible reasons include lack of resources +or a bad cookie. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_add_event_handler()\fR and \fBhandler()\fR function can be called +from user and kernel contexts only. +.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 LevelCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_get_eventcookie\fR(9F), +\fBddi_remove_event_handler\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Drivers must remove all registered callback handlers for a device instance by +calling \fBddi_remove_event_handler\fR(9F) before detach completes. diff --git a/usr/src/man/man9f/ddi_add_intr.9f b/usr/src/man/man9f/ddi_add_intr.9f new file mode 100644 index 0000000000..efe1756fad --- /dev/null +++ b/usr/src/man/man9f/ddi_add_intr.9f @@ -0,0 +1,356 @@ +'\" te +.\" Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_add_intr 9F "19 Oct 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_add_intr, ddi_get_iblock_cookie, ddi_remove_intr \- hardware interrupt +handling routines +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_get_iblock_cookie\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinumber\fR, + \fBddi_iblock_cookie_t *\fR\fIiblock_cookiep\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_add_intr\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinumber\fR, + \fBddi_iblock_cookie_t *\fR\fIiblock_cookiep\fR, + \fBddi_idevice_cookie_t *\fR\fIidevice_cookiep\fR, + \fBuint_t (*\fR\fIint_handler\fR) (caddr_t), + \fBcaddr_t\fR \fIint_handler_arg\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_remove_intr\fR(\fBdev_info_t *\fR\fIdip\fR, + \fBuint_t\fR \fIinumber\fR, \fBddi_iblock_cookie_t\fR \fIiblock_cookie\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). These interfaces are obsolete. Use the new +interrupt interfaces referenced in \fBIntro\fR(9F). Refer to \fIWriting Device +Drivers\fR for more information. +.SH PARAMETERS +.sp +.LP +For \fBddi_get_iblock_cookie()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 18n +.rt +Pointer to \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinumber\fR\fR +.ad +.RS 18n +.rt +Interrupt number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIiblock_cookiep\fR\fR +.ad +.RS 18n +.rt +Pointer to an interrupt block cookie. +.RE + +.sp +.LP +For \fBddi_add_intr()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 19n +.rt +Pointer to \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinumber\fR\fR +.ad +.RS 19n +.rt +Interrupt number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIiblock_cookiep\fR\fR +.ad +.RS 19n +.rt +Optional pointer to an interrupt block cookie where a returned interrupt block +cookie is stored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIidevice_cookiep\fR\fR +.ad +.RS 19n +.rt +Optional pointer to an interrupt device cookie where a returned interrupt +device cookie is stored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIint_handler\fR\fR +.ad +.RS 19n +.rt +Pointer to interrupt handler. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIint_handler_arg\fR\fR +.ad +.RS 19n +.rt +Argument for interrupt handler. +.RE + +.sp +.LP +For \fBddi_remove_intr()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 17n +.rt +Pointer to \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinumber\fR\fR +.ad +.RS 17n +.rt +Interrupt number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIiblock_cookie\fR\fR +.ad +.RS 17n +.rt +Block cookie which identifies the interrupt handler to be removed. +.RE + +.SH DESCRIPTION +.SS "ddi_get_iblock_cookie(\|)" +.sp +.LP +\fBddi_get_iblock_cookie()\fR retrieves the interrupt block cookie associated +with a particular interrupt specification. This routine should be called before +\fBddi_add_intr()\fR to retrieve the interrupt block cookie needed to +initialize locks (\fBmutex\fR(9F), \fBrwlock\fR(9F)) used by the interrupt +routine. The interrupt number \fIinumber\fR determines for which interrupt +specification to retrieve the cookie. \fIinumber\fR is associated with +information provided either by the device (see \fBsbus\fR(4)) or the hardware +configuration file (see \fBsysbus\fR(4), \fBisa\fR(4), and +\fBdriver.conf\fR(4)). If only one interrupt is associated with the device, +\fIinumber\fR should be \fB0\fR. +.sp +.LP +On a successful return, \fI*iblock_cookiep\fR contains information needed for +initializing locks associated with the interrupt specification corresponding to +\fIinumber\fR (see \fBmutex_init\fR(9F) and \fBrw_init\fR(9F)). The driver can +then initialize locks acquired by the interrupt routine before calling +\fBddi_add_intr()\fR which prevents a possible race condition where the +driver's interrupt handler is called immediately \fBafter\fR the driver has +called \fBddi_add_intr()\fR but \fBbefore\fR the driver has initialized the +locks. This may happen when an interrupt for a different device occurs on the +same interrupt level. If the interrupt routine acquires the lock before the +lock has been initialized, undefined behavior may result. +.SS "ddi_add_intr(\|)" +.sp +.LP +\fBddi_add_intr()\fR adds an interrupt handler to the system. The interrupt +number \fIinumber\fR determines which interrupt the handler will be associated +with. (Refer to \fBddi_get_iblock_cookie()\fR above.) +.sp +.LP +On a successful return, \fIiblock_cookiep\fR contains information used for +initializing locks associated with this interrupt specification (see +\fBmutex_init\fR(9F) and \fBrw_init\fR(9F)). Note that the interrupt block +cookie is usually obtained using \fBddi_get_iblock_cookie()\fR to avoid the +race conditions described above (refer to \fBddi_get_iblock_cookie()\fR above). +For this reason, \fIiblock_cookiep\fR is no longer useful and should be set to +\fINULL\fR. +.sp +.LP +On a successful return, \fIidevice_cookiep\fR contains a pointer to a +\fBddi_idevice_cookie_t\fR structure (see \fBddi_idevice_cookie\fR(9S)) +containing information useful for some devices that have programmable +interrupts. If \fIidevice_cookiep\fR is set to \fINULL\fR, no value is +returned. +.sp +.LP +The routine \fIintr_handler\fR, with its argument \fIint_handler_arg\fR, is +called upon receipt of the appropriate interrupt. The interrupt handler should +return \fBDDI_INTR_CLAIMED\fR if the interrupt was claimed, +\fBDDI_INTR_UNCLAIMED\fR otherwise. +.sp +.LP +If successful, \fBddi_add_intr()\fR returns \fBDDI_SUCCESS\fR. If the interrupt +information cannot be found on the sun4u architecture, either +\fBDDI_INTR_NOTFOUND\fR or \fBDDI_FAILURE\fR can be returned. On i86pc and +sun4m architectures, if the interrupt information cannot be found, +\fBDDI_INTR_NOTFOUND\fR is returned. +.SS "ddi_remove_intr(\|)" +.sp +.LP +\fBddi_remove_intr()\fR removes an interrupt handler from the system. +Unloadable drivers should call this routine during their \fBdetach\fR(9E) +routine to remove their interrupt handler from the system. +.sp +.LP +The device interrupt routine for this instance of the device will not execute +after \fBddi_remove_intr()\fR returns. \fBddi_remove_intr()\fR may need to wait +for the device interrupt routine to complete before returning. Therefore, locks +acquired by the interrupt handler should not be held across the call to +\fBddi_remove_intr()\fR or deadlock may result. +.SS "For All Three Functions:" +.sp +.LP +For certain bus types, you can call these \fBDDI\fR functions from a +high-interrupt context. These types include \fBISA\fR and SBus buses. See +\fBsysbus\fR(4), \fBisa\fR(4), and \fBsbus\fR(4) for details. +.SH RETURN VALUES +.sp +.LP +\fBddi_add_intr()\fR and \fBddi_get_iblock_cookie()\fR return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 21n +.rt +On success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_INTR_NOTFOUND\fR\fR +.ad +.RS 21n +.rt +On failure to find the interrupt. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 21n +.rt +On failure. \fBDDI_FAILURE\fR can also be returned on failure to find interrupt +(\fBsun4u\fR). +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_add_intr()\fR, \fBddi_remove_intr()\fR, and +\fBddi_get_iblock_cookie()\fR can be called from user or kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBdriver.conf\fR(4), \fBisa\fR(4), \fBsbus\fR(4), \fBsysbus\fR(4), +\fBattach\fR(9E), \fBdetach\fR(9E), \fBddi_intr_hilevel\fR(9F), +\fBIntro\fR(9F), \fBmutex\fR(9F), \fBmutex_init\fR(9F), \fBrw_init\fR(9F), +\fBrwlock\fR(9F), \fBddi_idevice_cookie\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +\fBddi_get_iblock_cookie()\fR must not be called \fBafter\fR the driver adds an +interrupt handler for the interrupt specification corresponding to +\fIinumber\fR. +.sp +.LP +All consumers of these interfaces, checking return codes, should verify +\fBreturn_code != DDI_SUCCESS\fR. Checking for specific failure codes can +result in inconsistent behaviors among platforms. +.SH BUGS +.sp +.LP +The \fIidevice_cookiep\fR should really point to a data structure that is +specific to the bus architecture that the device operates on. Currently the +SBus and PCI buses are supported and a single data structure is used to +describe both. diff --git a/usr/src/man/man9f/ddi_add_softintr.9f b/usr/src/man/man9f/ddi_add_softintr.9f new file mode 100644 index 0000000000..a6887faf63 --- /dev/null +++ b/usr/src/man/man9f/ddi_add_softintr.9f @@ -0,0 +1,579 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_add_softintr 9F "19 Oct 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_add_softintr, ddi_get_soft_iblock_cookie, ddi_remove_softintr, +ddi_trigger_softintr \- software interrupt handling routines +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_get_soft_iblock_cookie\fR(\fBdev_info_t *\fR\fIdip\fR, +\fBint\fR \fIpreference\fR, \fBddi_iblock_cookie_t *\fR\fIiblock_cookiep\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_add_softintr\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIpreference\fR, \fBddi_softintr_t *\fR\fIidp\fR, + \fBddi_iblock_cookie_t *\fR\fIiblock_cookiep\fR, \fBddi_idevice_cookie_t *\fR + \fIidevice_cookiep\fR, + \fBuint_t(*\fR\fIint_handler\fR) (caddr_t \fIint_handler_arg\fR), \fBcaddr_t\fR + \fIint_handler_arg\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_remove_softintr\fR(\fBddi_softintr_t\fR \fIid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_trigger_softintr\fR(\fBddi_softintr_t\fR \fIid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). These interfaces are obsolete. Use the new +interrupt interfaces referenced in \fBIntro\fR(9F). Refer to \fIWriting Device +Drivers\fR for more information. +.SH PARAMETERS +.sp +.LP +\fBddi_get_soft_iblock_cookie()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 18n +.rt +Pointer to a \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpreference\fR\fR +.ad +.RS 18n +.rt +The type of soft interrupt to retrieve the cookie for. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIiblock_cookiep\fR\fR +.ad +.RS 18n +.rt +Pointer to a location to store the interrupt block cookie. +.RE + +.sp +.LP +\fBddi_add_softintr()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 19n +.rt +Pointer to \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpreference\fR\fR +.ad +.RS 19n +.rt +A hint value describing the type of soft interrupt to generate. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIidp\fR\fR +.ad +.RS 19n +.rt +Pointer to a soft interrupt identifier where a returned soft interrupt +identifier is stored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIiblock_cookiep\fR\fR +.ad +.RS 19n +.rt +Optional pointer to an interrupt block cookie where a returned interrupt block +cookie is stored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIidevice_cookiep\fR\fR +.ad +.RS 19n +.rt +Optional pointer to an interrupt device cookie where a returned interrupt +device cookie is stored (not used). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIint_handler\fR\fR +.ad +.RS 19n +.rt +Pointer to interrupt handler. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIint_handler_arg\fR\fR +.ad +.RS 19n +.rt +Argument for interrupt handler. +.RE + +.sp +.LP +\fBddi_remove_softintr()\fR +.sp +.ne 2 +.mk +.na +\fB\fIid\fR\fR +.ad +.RS 6n +.rt +The identifier specifying which soft interrupt handler to remove. +.RE + +.sp +.LP +\fBddi_trigger_softintr()\fR +.sp +.ne 2 +.mk +.na +\fB\fIid\fR\fR +.ad +.RS 6n +.rt +The identifier specifying which soft interrupt to trigger and which soft +interrupt handler will be called. +.RE + +.SH DESCRIPTION +.sp +.LP +For \fBddi_get_soft_iblock_cookie()\fR: +.sp +.LP +\fBddi_get_soft_iblock_cookie()\fR retrieves the interrupt block cookie +associated with a particular soft interrupt preference level. This routine +should be called before \fBddi_add_softintr()\fR to retrieve the interrupt +block cookie needed to initialize locks ( \fBmutex\fR(9F), \fBrwlock\fR(9F)) +used by the software interrupt routine. \fIpreference\fR determines which type +of soft interrupt to retrieve the cookie for. The possible values for +\fIpreference\fR are: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SOFTINT_LOW\fR\fR +.ad +.RS 20n +.rt +Low priority soft interrupt. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SOFTINT_MED\fR\fR +.ad +.RS 20n +.rt +Medium priority soft interrupt. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SOFTINT_HIGH\fR\fR +.ad +.RS 20n +.rt +High priority soft interrupt. +.RE + +.sp +.LP +On a successful return, \fIiblock_cookiep\fR contains information needed for +initializing locks associated with this soft interrupt (see +\fBmutex_init\fR(9F) and \fBrw_init\fR(9F)). The driver can then initialize +mutexes acquired by the interrupt routine before calling +\fBddi_add_softintr()\fR which prevents a possible race condition where the +driver's soft interrupt handler is called immediately \fBafter\fR the driver +has called \fBddi_add_softintr()\fR but \fBbefore\fR the driver has initialized +the mutexes. This can happen when a soft interrupt for a different device +occurs on the same soft interrupt priority level. If the soft interrupt routine +acquires the mutex before it has been initialized, undefined behavior may +result. +.sp +.LP +For \fBddi_add_softintr()\fR: +.sp +.LP +\fBddi_add_softintr()\fR adds a soft interrupt to the system. The user +specified hint \fIpreference\fR identifies three suggested levels for the +system to attempt to allocate the soft interrupt priority at. The value for +\fIpreference\fR should be the same as that used in the corresponding call to +\fBddi_get_soft_iblock_cookie()\fR. Refer to the description of +\fBddi_get_soft_iblock_cookie()\fR above. +.sp +.LP +The value returned in the location pointed at by \fIidp\fR is the soft +interrupt identifier. This value is used in later calls to +\fBddi_remove_softintr()\fR and \fBddi_trigger_softintr()\fR to identify the +soft interrupt and the soft interrupt handler. +.sp +.LP +The value returned in the location pointed at by \fIiblock_cookiep\fR is an +interrupt block cookie which contains information used for initializing mutexes +associated with this soft interrupt (see \fBmutex_init\fR(9F) and +\fBrw_init\fR(9F)). Note that the interrupt block cookie is normally obtained +using \fBddi_get_soft_iblock_cookie()\fR to avoid the race conditions described +above (refer to the description of \fBddi_get_soft_iblock_cookie()\fR above). +For this reason, \fIiblock_cookiep\fR is no longer useful and should be set to +\fINULL\fR. +.sp +.LP +\fIidevice_cookiep\fR is not used and should be set to \fINULL\fR. +.sp +.LP +The routine \fIint_handler\fR, with its argument \fIint_handler_arg\fR, is +called upon receipt of a software interrupt. Software interrupt handlers must +not assume that they have work to do when they run, since (like hardware +interrupt handlers) they may run because a soft interrupt occurred for some +other reason. For example, another driver may have triggered a soft interrupt +at the same level. For this reason, before triggering the soft interrupt, the +driver must indicate to its soft interrupt handler that it should do work. This +is usually done by setting a flag in the state structure. The routine +\fIint_handler\fR checks this flag, reachable through \fIint_handler_arg\fR, to +determine if it should claim the interrupt and do its work. +.sp +.LP +The interrupt handler must return \fBDDI_INTR_CLAIMED\fR if the interrupt was +claimed, \fBDDI_INTR_UNCLAIMED\fR otherwise. +.sp +.LP +If successful, \fBddi_add_softintr()\fR will return \fBDDI_SUCCESS\fR; if the +interrupt information cannot be found, it will return \fBDDI_FAILURE\fR. +.sp +.LP +For \fBddi_remove_softintr()\fR: +.sp +.LP +\fBddi_remove_softintr()\fR removes a soft interrupt from the system. The soft +interrupt identifier \fIid\fR, which was returned from a call to +\fBddi_add_softintr()\fR, is used to determine which soft interrupt and which +soft interrupt handler to remove. Drivers must remove any soft interrupt +handlers before allowing the system to unload the driver. +.sp +.LP +For \fBddi_trigger_softintr()\fR: +.sp +.LP +\fBddi_trigger_softintr()\fR triggers a soft interrupt. The soft interrupt +identifier \fIid\fR is used to determine which soft interrupt to trigger. This +function is used by device drivers when they wish to trigger a soft interrupt +which has been set up using \fBddi_add_softintr()\fR. +.SH RETURN VALUES +.sp +.LP +\fBddi_add_softintr()\fR and \fBddi_get_soft_iblock_cookie()\fR 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 CONTEXT +.sp +.LP +These functions can be called from user or kernel context. +\fBddi_trigger_softintr()\fR may be called from high-level interrupt context as +well. +.SH EXAMPLES +.LP +\fBExample 1 \fRdevice using high-level interrupts +.sp +.LP +In the following example, the device uses high-level interrupts. High-level +interrupts are those that interrupt at the level of the scheduler and above. +High level interrupts must be handled without using system services that +manipulate thread or process states, because these interrupts are not blocked +by the scheduler. In addition, high level interrupt handlers must take care to +do a minimum of work because they are not preemptable. See +\fBddi_intr_hilevel\fR(9F). + +.sp +.LP +In the example, the high-level interrupt routine minimally services the device, +and enqueues the data for later processing by the soft interrupt handler. If +the soft interrupt handler is not currently running, the high-level interrupt +routine triggers a soft interrupt so the soft interrupt handler can process the +data. Once running, the soft interrupt handler processes all the enqueued data +before returning. + +.sp +.LP +The state structure contains two mutexes. The high-level mutex is used to +protect data shared between the high-level interrupt handler and the soft +interrupt handler. The low-level mutex is used to protect the rest of the +driver from the soft interrupt handler. + +.sp +.in +2 +.nf +struct xxstate { + .\|.\|. + ddi_softintr_t id; + ddi_iblock_cookie_t high_iblock_cookie; + kmutex_t high_mutex; + ddi_iblock_cookie_t low_iblock_cookie; + kmutex_t low_mutex; + int softint_running; + .\|.\|. +}; +struct xxstate *xsp; +static uint_t xxsoftintr(caddr_t); +static uint_t xxhighintr(caddr_t); +\&.\|.\|. +.fi +.in -2 + +.LP +\fBExample 2 \fRsample \fBattach()\fR routine +.sp +.LP +The following code fragment would usually appear in the driver's +\fBattach\fR(9E) routine. \fBddi_add_intr\fR(9F) is used to add the high-level +interrupt handler and \fBddi_add_softintr()\fR is used to add the low-level +interrupt routine. + +.sp +.in +2 +.nf +static uint_t +xxattach(dev_info_t *dip, ddi_attach_cmd_t cmd) +{ + struct xxstate *xsp; + .\|.\|. + /* get high-level iblock cookie */ + if (ddi_get_iblock_cookie(dip, \fIinumber\fR, + &xsp->high_iblock_cookie) != DDI_SUCCESS) { + /* clean up */ + return (DDI_FAILURE); /* fail attach */ + } + + /* initialize high-level mutex */ + mutex_init(&xsp->high_mutex, "xx high mutex", MUTEX_DRIVER, + (void *)xsp->high_iblock_cookie); + + /* add high-level routine - xxhighintr() */ + if (ddi_add_intr(dip, \fIinumber\fR, NULL, NULL, + xxhighintr, (caddr_t) xsp) != DDI_SUCCESS) { + /* cleanup */ + return (DDI_FAILURE); /* fail attach */ + } + + /* get soft iblock cookie */ + if (ddi_get_soft_iblock_cookie(dip, DDI_SOFTINT_MED, + &xsp->low_iblock_cookie) != DDI_SUCCESS) { + /* clean up */ + return (DDI_FAILURE); /* fail attach */ + } + + /* initialize low-level mutex */ + mutex_init(&xsp->low_mutex, "xx low mutex", MUTEX_DRIVER, + (void *)xsp->low_iblock_cookie); + + /* add low level routine - xxsoftintr() */ + if ( ddi_add_softintr(dip, DDI_SOFTINT_MED, &xsp->id, + NULL, NULL, xxsoftintr, (caddr_t) xsp) != DDI_SUCCESS) { + /* cleanup */ + return (DDI_FAILURE); /* fail attach */ + } + + .\|.\|. +} +.fi +.in -2 + +.LP +\fBExample 3 \fRHigh-level interrupt routine +.sp +.LP +The next code fragment represents the high-level interrupt routine. The +high-level interrupt routine minimally services the device, and enqueues the +data for later processing by the soft interrupt routine. If the soft interrupt +routine is not already running, \fBddi_trigger_softintr()\fR is called to start +the routine. The soft interrupt routine will run until there is no more data on +the queue. + +.sp +.in +2 +.nf +static uint_t +xxhighintr(caddr_t arg) +{ + struct xxstate *xsp = (struct xxstate *) arg; + int need_softint; + .\|.\|. + mutex_enter(&xsp->high_mutex); + /* + * Verify this device generated the interrupt + * and disable the device interrupt. + * Enqueue data for xxsoftintr() processing. + */ + + /* is xxsoftintr() already running ? */ + if (xsp->softint_running) + need_softint = 0; + else + need_softint = 1; + mutex_exit(&xsp->high_mutex); + + /* read-only access to xsp->id, no mutex needed */ + if (need_softint) + ddi_trigger_softintr(xsp->id); + .\|.\|. + return (DDI_INTR_CLAIMED); +} + +static uint_t +xxsoftintr(caddr_t arg) +{ + struct xxstate *xsp = (struct xxstate *) arg; + .\|.\|. + mutex_enter(&xsp->low_mutex); + mutex_enter(&xsp->high_mutex); + + /* verify there is work to do */ + if (\fBwork queue empty\fR || xsp->softint_running ) { + mutex_exit(&xsp->high_mutex); + mutex_exit(&xsp->low_mutex); + return (DDI_INTR_UNCLAIMED); + } + + xsp->softint_running = 1; + + while ( \fBdata on queue\fR ) { + ASSERT(mutex_owned(&xsp->high_mutex)); + + /* de-queue data */ + + mutex_exit(&xsp->high_mutex); + + /* Process data on queue */ + + mutex_enter(&xsp->high_mutex); + } + + xsp->softint_running = 0; + mutex_exit(&xsp->high_mutex); + mutex_exit(&xsp->low_mutex); + + return (DDI_INTR_CLAIMED); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_add_intr\fR(9F), \fBddi_in_panic\fR(9F), \fBddi_intr_hilevel\fR(9F), +\fBddi_remove_intr\fR(9F), \fBIntro\fR(9F), \fBmutex_init\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +\fBddi_add_softintr()\fR may not be used to add the same software interrupt +handler more than once. This is true even if a different value is used for +\fIint_handler_arg\fR in each of the calls to \fBddi_add_softintr()\fR. +Instead, the argument passed to the interrupt handler should indicate what +service(s) the interrupt handler should perform. For example, the argument +could be a pointer to the device's soft state structure, which could contain +a 'which_service' field that the handler examines. The driver must set this field +to the appropriate value before calling \fBddi_trigger_softintr()\fR. diff --git a/usr/src/man/man9f/ddi_binding_name.9f b/usr/src/man/man9f/ddi_binding_name.9f new file mode 100644 index 0000000000..70aec76d9c --- /dev/null +++ b/usr/src/man/man9f/ddi_binding_name.9f @@ -0,0 +1,70 @@ +'\" 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 ddi_binding_name 9F "3 May 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_binding_name, ddi_get_name \- return driver binding name +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBchar *\fR\fBddi_binding_name\fR(\fBdev_info_t *\fR\fIdip\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBddi_get_name\fR(\fBdev_info_t *\fR\fIdip\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 8n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_binding_name()\fR and \fBddi_get_name()\fR return the driver binding +name. This is the name used to select a driver for the device. This name is +typically derived from the device \fBname\fR property or the device +\fBcompatible\fR property. The name returned may be a driver alias or the +driver name. +.SH RETURN VALUES +.sp +.LP +\fBddi_binding_name()\fR and \fBddi_get_name()\fR return the name used to bind +a driver to a device. +.SH CONTEXT +.sp +.LP +\fBddi_binding_name()\fR and \fBddi_get_name()\fR can be called from user, +kernel, or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBddi_node_name\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +The name returned by \fBddi_binding_name()\fR and \fBddi_get_name()\fR is +read-only. diff --git a/usr/src/man/man9f/ddi_btop.9f b/usr/src/man/man9f/ddi_btop.9f new file mode 100644 index 0000000000..ea2282bc17 --- /dev/null +++ b/usr/src/man/man9f/ddi_btop.9f @@ -0,0 +1,85 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_btop 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_btop, ddi_btopr, ddi_ptob \- page size conversions +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBunsigned long\fR \fBddi_btop\fR(\fBdev_info_t\fR \fI*dip\fR, \fBunsigned long\fR \fIbytes\fR); +.fi + +.LP +.nf +\fBunsigned long\fR \fBddi_btopr\fR(\fBdev_info_t\fR \fI*dip\fR, \fBunsigned long\fR \fIbytes\fR); +.fi + +.LP +.nf +\fBunsigned long\fR \fBddi_ptob\fR(\fBdev_info_t\fR \fI*dip\fR, \fBunsigned long\fR \fIpages\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +This set of routines use the parent nexus driver to perform conversions in page +size units. +.sp +.LP +The \fBddi_btop()\fR function converts the given number of bytes to the number +of memory pages that it corresponds to, rounding down in the case that the byte +count is not a page multiple. +.sp +.LP +The \fBddi_btopr()\fR function converts the given number of bytes to the number +of memory pages that it corresponds to, rounding up in the case that the byte +count is not a page multiple. +.sp +.LP +The \fBddi_ptob()\fR function converts the given number of pages to the number +of bytes that it corresponds to. +.sp +.LP +Because bus nexus may possess their own hardware address translation +facilities, these routines should be used in preference to the corresponding +DDI/DKI routines \fBbtop\fR(9F), \fBbtopr\fR(9F), and \fBptob\fR(9F), which +only deal in terms of the pagesize of the main system MMU. +.SH RETURN VALUES +.sp +.LP +The \fBddi_btop()\fR and \fBddi_btopr()\fR functions return the number of +corresponding pages. \fBddi_ptob()\fR returns the corresponding number of +bytes. There are no error return values. +.SH CONTEXT +.sp +.LP +This function can be called from user, interrupt, or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRFind the size (in bytes) of one page +.sp +.in +2 +.nf +pagesize = ddi_ptob(dip, 1L); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBbtop\fR(9F), \fBbtopr\fR(9F), \fBptob\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_can_receive_sig.9f b/usr/src/man/man9f/ddi_can_receive_sig.9f new file mode 100644 index 0000000000..8a7b8fa4a7 --- /dev/null +++ b/usr/src/man/man9f/ddi_can_receive_sig.9f @@ -0,0 +1,75 @@ +'\" 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 ddi_can_receive_sig 9F "15 Dec 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_can_receive_sig \- Test for ability to receive signals +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBboolean_t\fR ddi_can_receive_sig(\fBvoid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +None. +.SH DESCRIPTION +.sp +.LP +The \fBddi_can_receive_sig()\fR function returns a boolean value +indicating whether the current thread can receive signals sent by +\fBkill\fR(2). If the return value is \fBB_FALSE\fR, then the calling thread +cannot receive signals, and any call to \fBqwait_sig\fR(9F), +\fBcv_wait_sig\fR(9F), or \fBcv_timedwait_sig\fR(9F) implicitly becomes +\fBqwait\fR(9F), \fBcv_wait\fR(9F), or \fBcv_timedwait\fR(9F), respectively. +Drivers that can block indefinitely awaiting an event should use this function +to determine if additional means (such as \fBtimeout\fR(9F)) may be necessary +to avoid creating unkillable threads. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBB_FALSE\fR \fR +.ad +.RS 12n +.rt +The calling thread is in a state in which signals cannot be +received. For example, the thread is not associated with a user process or is +in the midst of \fBexit\fR(2) handling. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBB_TRUE\fR \fR +.ad +.RS 12n +.rt +The calling thread may receive a signal while blocked on a condition +variable. Note that this function does not check to determine whether signals +are blocked (see \fBsigprocmask\fR(2)). +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_can_receive_sig()\fR function may be called from user, kernel, or +interrupt context. +.SH SEE ALSO +.sp +.LP +\fBclose\fR(9E), \fBcv_wait\fR(9F), \fBqwait\fR(9F) diff --git a/usr/src/man/man9f/ddi_cb_register.9f b/usr/src/man/man9f/ddi_cb_register.9f new file mode 100644 index 0000000000..820d89b69c --- /dev/null +++ b/usr/src/man/man9f/ddi_cb_register.9f @@ -0,0 +1,605 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_cb_register 9F "30 Jan 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_cb_register, ddi_cb_unregister \- register and unregister a device driver +callback handler +.SH SYNOPSIS +.LP +.nf +#include <sys/sunddi.h> + +\fBint\fR \fBddi_cb_register\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_cb_flags_t\fR \fIflags\fR, + \fBddi_cb_func_t\fR \fIcbfunc\fR, \fBvoid *\fR\fIarg1\fR, \fBvoid *\fR\fIarg2\fR, + \fBddi_cb_handle_t *\fR \fIret_hdlp\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_cb_unregister\fR(\fBddi_cb_handle_t\fR \fIhdl\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +\fBddi_cb_register()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 12n +.rt +Pointer to the \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 12n +.rt +Flags to determine which callback events can be handled. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcbfunc\fR\fR +.ad +.RS 12n +.rt +Callback handler function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg1\fR\fR +.ad +.RS 12n +.rt +First argument to the callback handler. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg2\fR\fR +.ad +.RS 12n +.rt +Second (optional) argument to the callback handler. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIret_hdlp\fR\fR +.ad +.RS 12n +.rt +Pointer to return a handle to the registered callback. +.RE + +.sp +.LP +\fBddi_cb_unregister()\fR +.sp +.ne 2 +.mk +.na +\fB\fIhdl\fR\fR +.ad +.RS 7n +.rt +Handle to the registered callback handler that is to be unregistered. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_cb_register()\fR function installs a callback handler which +processes various actions that require the driver's attention while it is +attached. The driver specifies which callback actions it can handle through the +flags parameter. With each relevant action, the specified callback function +passes the \fIarg1\fR and \fIarg2\fR arguments along with the description of +each callback event to the driver. +.sp +.LP +The \fBddi_cb_unregister()\fR function removes a previously installed callback +handler and prevents future processing of actions. +.sp +.LP +The \fIflags\fR parameter consists of the following: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_CB_FLAG_INTR\fR\fR +.ad +.RS 20n +.rt +The device driver participates in interrupt resource management. The device +driver may receive additional interrupt resources from the system, but only +because it can accept callback notices informing it when it has more or less +resources available. Callback notices can occur at anytime after the driver is +attached. Interrupt availability varies based on the overall needs of the +system. +.RE + +.sp +.LP +The cdfunc is a callback handler with the following prototype: +.sp +.in +2 +.nf +typedef int (*ddi_cb_func_t)(dev_info_t *dip, + ddi_cb_action_t action, void *cbarg, + void *arg1, void *arg2); +.fi +.in -2 +.sp + +.sp +.LP +The \fIcbfunc\fR routine with the arguments \fIdip\fR, \fIaction\fR, +\fIcbarg\fR, \fIarg1\fR and \fIarg2\fR is called upon receipt of any callbacks +for which the driver is registered. The callback handler returns +\fBDDI_SUCCESS\fR if the callback was handled successfully, \fBDDI_ENOTSUP\fR +if it received a callback action that it did not know how to process, or +\fBDDI_FAILURE\fR if it has an internal failure while processing an action. +.sp +.LP +The \fIaction\fR parameter can be one of the following: +.sp +.ne 2 +.mk +.na +\fB\fIDDI_CB_INTR_ADD\fR\fR +.ad +.RS 22n +.rt +For interrupt resource management, the driver has more available interrupts. +The driver can allocate more interrupt vectors and then set up more interrupt +handling functions by using \fBddi_intr_alloc\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIDDI_CB_INTR_REMOVE\fR\fR +.ad +.RS 22n +.rt +For interrupt resource management, the driver has fewer available interrupts. +The driver must release any previously allocated interrupts in excess of what +is now available by using \fBddi_intr_free\fR(9F). +.RE + +.sp +.LP +The \fIcbarg\fR parameter points to an action-specific argument. Each class of +registered actions specifies its own data structure that a callback handler +should dereference when it receives those actions. +.sp +.LP +The \fIcbarg\fR parameter is defined as an integer in the case of +\fBDDI_CB_INTR_ADD\fR and \fBDDI_CB_INTR_REMOVE\fR actions. The callback +handler should cast the \fIcbarg\fR parameter to an integer. The integer +represents how many interrupts have been added or removed from the total number +available to the device driver. +.sp +.LP +If a driver participates in interrupt resource management, it must register a +callback with the \fBDDI_CB_FLAG_INTR\fR flag. The driver then receives the +actions \fBDDI_CB_INTR_ADD\fR and \fBDDI_CB_INTR_REMOVE\fR whenever its +interrupt availability has changed. The callback handler should use the +interrupt functions \fBddi_intr_alloc\fR(9F) and \fBddi_intr_free\fR(9F) +functions to respond accordingly. A driver is not required to allocate all +interrupts that are available to it, but it is required to manage its +allocations so that it never uses more interrupts than are currently available. +.SH RETURN VALUES +.sp +.LP +The \fBddi_cb_register()\fR and \fBddi_cb_unregister()\fR functions return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 16n +.rt +on success +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EINVAL\fR\fR +.ad +.RS 16n +.rt +An invalid parameter was given when registering a callback handler, or an +invalid handle was given when unregistering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EALREADY\fR\fR +.ad +.RS 16n +.rt +An attempt was made to register a callback handler while a previous +registration still exists. +.RE + +.sp +.LP +The \fIcbfunc\fR routine must 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_ENOTSUP\fR\fR +.ad +.RS 15n +.rt +The device does not support the operation +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Implementation specific failure +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from kernel, non-interrupt context. +.SH EXAMPLES +.LP +\fBExample 1 \fRddi_cb_register +.sp +.in +2 +.nf +/* + * attach(9F) routine. + * + * Creates soft state, registers callback handler, initializes + * hardware, and sets up interrupt handling for the driver. + */ + xx_attach(dev_info_t *dip, ddi_attach_cmd_t cmd) + { + xx_state_t *statep = NULL; + xx_intr_t *intrs = NULL; + ddi_intr_handle_t *hdls; + ddi_cb_handle_t cb_hdl; + int instance; + int type; + int types; + int nintrs; + int nactual; + int inum; + + /* Get device instance */ + instance = ddi_get_instance(dip); + + switch (cmd) { + case DDI_ATTACH: + + /* Get soft state */ + if (ddi_soft_state_zalloc(state_list, instance) != 0) + return (DDI_FAILURE); + statep = ddi_get_soft_state(state_list, instance); + ddi_set_driver_private(dip, (caddr_t)statep); + statep->dip = dip; + + /* Initialize hardware */ + xx_initialize(statep); + + /* Register callback handler */ + if (ddi_cb_register(dip, DDI_CB_FLAG_INTR, xx_cbfunc, + statep, NULL, &cb_hdl) != 0) { + ddi_soft_state_free(state_list, instance); + return (DDI_FAILURE); + } + statep->cb_hdl = cb_hdl; + + /* Select interrupt type */ + ddi_intr_get_supported_types(dip, &types); + if (types & DDI_INTR_TYPE_MSIX) { + type = DDI_INTR_TYPE_MSIX; + } else if (types & DDI_INTR_TYPE_MSI) { + type = DDI_INTR_TYPE_MSI; + } else { + type = DDI_INTR_TYPE_FIXED; + } + statep->type = type; + + /* Get number of supported interrupts */ + + ddi_intr_get_nintrs(dip, type, &nintrs); + + /* Allocate interrupt handle array */ + statep->hdls_size = nintrs * sizeof (ddi_intr_handle_t); + hdls = kmem_zalloc(statep->hdls_size, KMEM_SLEEP); + + /* Allocate interrupt setup array */ + statep->intrs_size = nintrs * sizeof (xx_intr_t); + statep->intrs = kmem_zalloc(statep->intrs_size, KMEM_SLEEP); + + /* Allocate interrupt vectors */ + ddi_intr_alloc(dip, hdls, type, 0, nintrs, &nactual, 0); + statep->nactual = nactual; + + /* Configure interrupt handling */ + xx_setup_interrupts(statep, nactual, statep->intrs); + + /* Install and enable interrupt handlers */ + for (inum = 0; inum < nactual; inum++) { + ddi_intr_add_handler(&statep->hdls[inum], + statep->intrs[inum].inthandler, + statep->intrs[inum].arg1, + statep->intrs[inum].arg2); + ddi_intr_enable(statep->hdls[inum]); + } + + break; + + case DDI_RESUME: + + /* Get soft state */ + statep = ddi_get_soft_state(state_list, instance); + if (statep == NULL) + return (DDI_FAILURE); + + /* Resume hardware */ + xx_resume(statep); + + break; + } + + return (DDI_SUCESS); + } + + /* + * detach(9F) routine. + * + * Stops the hardware, disables interrupt handling, unregisters + * a callback handler, and destroys the soft state for the driver. + */ + xx_detach(dev_info_t *dip, ddi_detach_cmd_t cmd) + { + xx_state_t *statep = NULL; + int instance; + int inum; + + + /* Get device instance */ + instance = ddi_get_instance(dip); + + switch (cmd) { + case DDI_DETACH: + + /* Get soft state */ + statep = ddi_get_soft_state(state_list, instance); + if (statep == NULL) + return (DDI_FAILURE); + + /* Stop device */ + xx_uninitialize(statep); + + /* Disable and free interrupts */ + for (inum = 0; inum < statep->nactual; inum++) { + ddi_intr_disable(statep->hdls[inum]); + ddi_intr_remove_handler(statep->hdls[inum]); + ddi_intr_free(statep->hdls[inum]); + } + + /* Unregister callback handler */ + ddi_cb_unregister(statep->cb_hdl); + + /* Free interrupt handle array */ + kmem_free(statep->hdls, statep->hdls_size); + + /* Free interrupt setup array */ + kmem_free(statep->intrs, statep->intrs_size); + + /* Free soft state */ + ddi_soft_state_free(state_list, instance); + + break; + + case DDI_SUSPEND: + + /* Get soft state */ + statep = ddi_get_soft_state(state_list, instance); + if (statep == NULL) + return (DDI_FAILURE); + + /* Suspend hardware */ + xx_quiesce(statep); + + break; + } + + return (DDI_SUCCESS); + } + + /* + * (*ddi_cbfunc)() routine. + * + * Adapt interrupt usage when availability changes. + */ + int + xx_cbfunc(dev_info_t *dip, ddi_cb_action_t cbaction, void *cbarg, + void *arg1, void *arg2) + { + xx_state_t *statep = (xx_state_t *)arg1; + int count; + int inum; + int nactual; + + switch (cbaction) { + case DDI_CB_INTR_ADD: + case DDI_CB_INTR_REMOVE: + + /* Get change in availability */ + count = (int)(uintptr_t)cbarg; + + /* Suspend hardware */ + xx_quiesce(statep); + + /* Tear down previous interrupt handling */ + for (inum = 0; inum < statep->nactual; inum++) { + ddi_intr_disable(statep->hdls[inum]); + ddi_intr_remove_handler(statep->hdls[inum]); + } + + /* Adjust interrupt vector allocations */ + if (cbaction == DDI_CB_INTR_ADD) { + + /* Allocate additional interrupt vectors */ + ddi_intr_alloc(dip, statep->hdls, statep->type, + statep->nactual, count, &nactual, 0); + + /* Update actual count of available interrupts */ + statep->nactual += nactual; + + } else { + + /* Free removed interrupt vectors */ + for (inum = statep->nactual - count; + inum < statep->nactual; inum++) { + ddi_intr_free(statep->hdls[inum]); + } + + /* Update actual count of available interrupts */ + statep->nactual -= count; + } + + /* Configure interrupt handling */ + xx_setup_interrupts(statep, statep->nactual, statep->intrs); + + /* Install and enable interrupt handlers */ + for (inum = 0; inum < statep->nactual; inum++) { + ddi_intr_add_handler(&statep->hdls[inum], + statep->intrs[inum].inthandler, + statep->intrs[inum].arg1, + statep->intrs[inum].arg2); + ddi_intr_enable(statep->hdls[inum]); + } + + /* Resume hardware */ + xx_resume(statep); + + break; + + default: + return (DDI_ENOTSUP); + } + + return (DDI_SUCCESS); + } +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityPrivate +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_intr_alloc\fR(9F), \fBddi_intr_free\fR(9F), +\fBddi_intr_set_nreq\fR(9F) +.SH NOTES +.sp +.LP +Users of these interfaces that register for \fBDDI_CB_FLAG_INTR\fR become +participants in interrupt resource management. With that participation comes a +responsibility to properly adjust interrupt usage. In the case of a +\fBDDI_CB_INTR_ADD\fR action, the system guarantees that a driver can allocate +a total number of interrupt resources up to its new number of available +interrupts. The total number of interrupt resources is the sum of all resources +allocated by the function \fBddi_intr_alloc\fR(9F), minus all previously +released by the function \fBddi_intr_free\fR(9F). In the case of a +\fBDDI_CB_INTR_REMOVE\fR action, the driver might have more interrupts +allocated than are now currently available. It is necessary for the driver to +release the excess interrupts, or it will have a negative impact on the +interrupt availability for other drivers in the system. +.sp +.LP +A failure to release interrupts in response to a \fBDDI_CB_INTR_REMOVE\fR +callback generates the following warning on the system console: +.sp +.in +2 +.nf +WARNING: <driver><instance>: failed to release interrupts for + IRM (nintrs = ##, navail=##). +.fi +.in -2 +.sp + +.sp +.LP +Participation in interrupt resource management ends when a driver uses the +\fBddi_cb_unregister()\fR function to unregister its callback function. The +callback function must still operate properly until after the call to the +\fBddi_cb_unregister()\fR function completes. If \fBaddinterrupts\fR were given +to the driver because of its participation, then a final use of the callback +function occurs to release the additional interrupts. The call to the +\fBddi_cb_unregister()\fR function blocks until the final use of the +registered callback function is finished. diff --git a/usr/src/man/man9f/ddi_check_acc_handle.9f b/usr/src/man/man9f/ddi_check_acc_handle.9f new file mode 100644 index 0000000000..2ccdb6fd91 --- /dev/null +++ b/usr/src/man/man9f/ddi_check_acc_handle.9f @@ -0,0 +1,139 @@ +'\" te +.\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_check_acc_handle 9F "13 August 1999" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_check_acc_handle, ddi_check_dma_handle \- Check data access and DMA handles +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_check_acc_handle\fR(\fBddi_acc_handle_t\fR \fI acc_handle\fR ); +.fi + +.LP +.nf +\fBint\fR \fBddi_check_dma_handle\fR(\fBddi_dma_handle_t\fR \fIdma_handle\fR ); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIacc_handle\fR \fR +.ad +.RS 15n +.rt +Data access handle obtained from a previous call to +\fBddi_regs_map_setup\fR(9F), \fBddi_dma_mem_alloc\fR(9F), or similar function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdma_handle\fR \fR +.ad +.RS 15n +.rt +DMA handle obtained from a previous call to \fBddi_dma_setup\fR(9F) or one of +its derivatives. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_check_acc_handle()\fR\fB and ddi_check_dma_handle()\fR functions +check for faults that can interfere with communication between a driver and the +device it controls. Each function checks a single handle of a specific type and +returns a status value indicating whether faults affecting the resource mapped +by the supplied handle have been detected. +.sp +.LP +If a fault is indicated when checking a data access handle, this implies that +the driver is no longer able to access the mapped registers or memory using +programmed I/O through that handle. Typically, this might occur after the +device has failed to respond to an I/O access (for example, has incurred a bus +error or timed out). The effect of programmed I/O accesses made after this +happens is undefined; for example, read accesses (for example, +\fBddi_get8\fR(9F)) may return random values, and write accesses (for example, +\fBddi_put8\fR(9F)) may or may not have any effect. This type of fault is +normally fatal to the operation of the device, and the driver should report it +via \fBddi_dev_report_fault\fR(9F) specifying \fBDDI_SERVICE_LOST\fR for the +impact, and \fBDDI_DATAPATH_FAULT\fR for the location. +.sp +.LP +If a fault is indicated when checking a DMA handle, it implies that a fault has +been detected that has (or will) affect DMA transactions between the device and +the memory currently bound to the handle (or most recently bound, if the handle +is currently unbound). Possible causes include the failure of a component in +the DMA data path, or an attempt by the device to make an invalid DMA access. +The driver may be able to continue by falling back to a non-DMA mode of +operation, but in general, DMA faults are non-recoverable. The contents of the +memory currently (or previously) bound to the handle should be regarded as +indeterminate. The fault indication associated with the current transaction is +lost once the handle is (re-)bound, but because the fault may persist, future +DMA operations may not succeed. +.sp +.LP +Note that some implementations cannot detect all types of failure. If a fault +is not indicated, this does not constitute a guarantee that communication is +possible. However, if a check fails, this is a positive indication that a +problem \fBdoes\fR exist with respect to communication using that handle. +.SH RETURN VALUES +.sp +.LP +The \fBddi_check_acc_handle()\fR and \fBddi_check_dma_handle()\fR functions +return \fBDDI_SUCCESS\fR if no faults affecting the supplied handle are +detected and \fBDDI_FAILURE\fR if any fault affecting the supplied handle is +detected. +.SH EXAMPLES +.sp +.in +2 +.nf +static int +xxattach(dev_info_t *dip, ddi_attach_cmd_t cmd) +{ + \&... + /* This driver uses only a single register-access handle */ + status = ddi_regs_map_setup(dip, REGSET_ZERO, ®addr, + 0, 0, , &acc_attrs, &acc_hdl); + if (status != DDI_SUCCESS) + return (DDI_FAILURE); + \&... +} + +static int +xxread(dev_t dev, struct uio *uio_p, cred_t *cred_p) +{ + \&... + if (ddi_check_acc_handle(acc_hdl) != DDI_SUCCESS) { + ddi_dev_report_fault(dip, DDI_SERVICE_LOST, + DDI_DATAPATH_FAULT, "register access fault during read"); + return (EIO); + } + \&... +.fi +.in -2 + +.SH CONTEXT +.sp +.LP +The \fBddi_check_acc_handle()\fR and \fBddi_check_dma_handle()\fR functions may +be called from user, kernel, or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBddi_regs_map_setup\fR(9F), \fBddi_dma_setup\fR(9F), +\fBddi_dev_report_fault\fR(9F), \fBddi_get8\fR(9F), \fBddi_put8\fR(9F) diff --git a/usr/src/man/man9f/ddi_copyin.9f b/usr/src/man/man9f/ddi_copyin.9f new file mode 100644 index 0000000000..7ce3c43695 --- /dev/null +++ b/usr/src/man/man9f/ddi_copyin.9f @@ -0,0 +1,211 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_copyin 9F "19 Apr 2000" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_copyin \- copy data to a driver buffer +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_copyin\fR(\fBconst void *\fR\fIbuf\fR, \fBvoid *\fR\fIdriverbuf\fR, \fBsize_t\fR \fIcn\fR, \fBint\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbuf\fR\fR +.ad +.RS 13n +.rt +Source address from which data is transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdriverbuf\fR\fR +.ad +.RS 13n +.rt +Driver destination address to which data is transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcn\fR\fR +.ad +.RS 13n +.rt +Number of bytes transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 13n +.rt +Set of flag bits that provide address space information about \fIbuf\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +This routine is designed for use in driver \fBioctl\fR(9E) routines for drivers +that support layered ioctls. \fBddi_copyin()\fR copies data from a source +address to a driver buffer. The driver developer must ensure that adequate +space is allocated for the destination address. +.sp +.LP +The \fIflags\fR argument determines the address space information about +\fIbuf\fR. If the \fBFKIOCTL\fR flag is set, this indicates that \fIbuf\fR is a +kernel address, and \fBddi_copyin()\fR behaves like \fBbcopy\fR(9F). +Otherwise, \fIbuf\fR is interpreted as a user buffer address, and +\fBddi_copyin()\fR behaves like \fBcopyin\fR(9F). +.sp +.LP +Addresses that are word-aligned are moved most efficiently. However, the +driver developer is not obliged to ensure alignment. This function +automatically finds the most efficient move according to address alignment. +.SH RETURN VALUES +.sp +.LP +\fBddi_copyin()\fR returns \fB0\fR, indicating a successful copy. It returns +\(mi\fB1\fR if one of the following occurs: +.RS +4 +.TP +.ie t \(bu +.el o +Paging fault; the driver tried to access a page of memory for which it did not +have read or write access. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Invalid user address, such as a user area or stack area. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Invalid address that would have resulted in data being copied into the user +block. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Hardware fault; a hardware error prevented access to the specified user memory. +For example, an uncorrectable parity or \fBECC\fR error occurred. +.RE +.sp +.LP +If \(mi\fB1\fR is returned to the caller, driver entry point routines should +return \fBEFAULT\fR. +.SH CONTEXT +.sp +.LP +\fBddi_copyin()\fR can be called from user or kernel context only. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBddi_copyin()\fR example +.sp +.LP +A driver \fBioctl\fR(9E) routine (line 12) can be used to get or set device +attributes or registers. For the \fBXX_SETREGS\fR condition (line 25), the +driver copies the user data in \fIarg\fR to the device registers. If the +specified argument contains an invalid address, an error code is returned. + +.sp +.in +2 +.nf +1 struct device { /* layout of physical device registers */ + 2 int control; /* physical device control word */ + 3 int status; /* physical device status word */ + 4 short recv_char; /* receive character from device */ + 5 short xmit_char /* transmit character to device */ + 6 }; + 7 struct device_state { + 8 volatile struct device *regsp; /* pointer to device registers */ + 9 kmutex_t reg_mutex; /* protect device registers */ + . . . +10 }; + +11 static void *statep; /* for soft state routines */ + +12 xxioctl(dev_t dev, int cmd, int arg, int mode, +13 cred_t *cred_p, int *rval_p) +14 { +15 struct device_state *sp; +16 volatile struct device *rp; +17 struct device reg_buf; /* temporary buffer for registers */ +18 int instance; + +19 instance = getminor(dev); +20 sp = ddi_get_soft_state(statep, instance); +21 if (sp == NULL) +22 return (ENXIO); +23 rp = sp->regsp; + . . . +24 switch (cmd) { + +25 case XX_GETREGS: /* copy data to temp. regs. buf */ +26 if (ddi_copyin(arg, ®_buf, +27 sizeof (struct device), mode) != 0) { +28 return (EFAULT); +29 } + +30 mutex_enter(&sp->reg_mutex); +31 /* +32 * Copy data from temporary device register +33 * buffer to device registers. +34 * e.g. rp->control = reg_buf.control; +35 */ +36 mutex_exit(&sp->reg_mutex); + +37 break; +38 } +39 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBioctl\fR(9E), \fBbcopy\fR(9F), \fBcopyin\fR(9F), \fBcopyout\fR(9F), +\fBddi_copyout\fR(9F), \fBuiomove\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The value of the \fIflags\fR argument to \fBddi_copyin()\fR should be passed +through directly from the \fImode\fR argument of \fBioctl()\fR untranslated. +.sp +.LP +Driver defined locks should not be held across calls to this function. +.sp +.LP +\fBddi_copyin()\fR should not be used from a streams driver. See \fBM_COPYIN\fR +and \fBM_COPYOUT\fR in \fISTREAMS Programming Guide\fR. diff --git a/usr/src/man/man9f/ddi_copyout.9f b/usr/src/man/man9f/ddi_copyout.9f new file mode 100644 index 0000000000..c4d15a3fa2 --- /dev/null +++ b/usr/src/man/man9f/ddi_copyout.9f @@ -0,0 +1,211 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_copyout 9F "19 Apr 2000" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_copyout \- copy data from a driver +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_copyout\fR(\fBconst void *\fR\fIdriverbuf\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIcn\fR, \fBint\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdriverbuf\fR\fR +.ad +.RS 13n +.rt +Source address in the driver from which the data is transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuf\fR\fR +.ad +.RS 13n +.rt +Destination address to which the data is transferred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcn\fR\fR +.ad +.RS 13n +.rt +Number of bytes to copy. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 13n +.rt +Set of flag bits that provide address space information about \fIbuf\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +This routine is designed for use in driver \fBioctl\fR(9E) routines for drivers +that support layered ioctls. \fBddi_copyout()\fR copies data from a driver +buffer to a destination address, \fIbuf\fR. +.sp +.LP +The \fIflags\fR argument determines the address space information about +\fIbuf\fR. If the \fBFKIOCTL\fR flag is set, this indicates that \fIbuf\fR is a +kernel address, and \fBddi_copyout()\fR behaves like \fBbcopy\fR(9F). +Otherwise, \fIbuf\fR is interpreted as a user buffer address, and +\fBddi_copyout()\fR behaves like \fBcopyout\fR(9F). +.sp +.LP +Addresses that are word-aligned are moved most efficiently. However, the +driver developer is not obliged to ensure alignment. This function +automatically finds the most efficient move algorithm according to address +alignment. +.SH RETURN VALUES +.sp +.LP +Under normal conditions, \fB0\fR is returned to indicate a successful copy. +Otherwise, \(mi\fB1\fR is returned if one of the following occurs: +.RS +4 +.TP +.ie t \(bu +.el o +Paging fault; the driver tried to access a page of memory for which it did not +have read or write access. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Invalid user address, such as a user area or stack area. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Invalid address that would have resulted in data being copied into the user +block. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Hardware fault; a hardware error prevented access to the specified user memory. +For example, an uncorrectable parity or \fBECC\fR error occurred. +.RE +.sp +.LP +If \(mi\fB1\fR is returned to the caller, driver entry point routines should +return \fBEFAULT\fR. +.SH CONTEXT +.sp +.LP +\fBddi_copyout()\fR can be called from user or kernel context only. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBddi_copyout()\fR example +.sp +.LP +A driver \fBioctl\fR(9E) routine (line 12) can be used to get or set device +attributes or registers. In the \fBXX_GETREGS\fR condition (line 25), the +driver copies the current device register values to another data area. If the +specified argument contains an invalid address, an error code is returned. + +.sp +.in +2 +.nf +1 struct device { /* layout of physical device registers */ + 2 int control; /* physical device control word */ + 3 int status; /* physical device status word */ + 4 short recv_char; /* receive character from device */ + 5 short xmit_char; /* transmit character to device */ + 6 }; + + 7 struct device_state { + 8 volatile struct device *regsp; /* pointer to device registers */ + 9 kmutex_t reg_mutex; /* protect device registers */ + . . . +10 }; + +11 static void *statep; /* for soft state routines */ + +12 xxioctl(dev_t dev, int cmd, int arg, int mode, +13 cred_t *cred_p, int *rval_p) +14 { +15 struct device_state *sp; +16 volatile struct device *rp; +17 struct device reg_buf; /* temporary buffer for registers */ +18 int instance; + +19 instance = getminor(dev); +20 sp = ddi_get_soft_state(statep, instance); +21 if (sp == NULL) +22 return (ENXIO); +23 rp = sp->regsp; + . . . +24 switch (cmd) { + +25 case XX_GETREGS: /* copy registers to arg */ +26 mutex_enter(&sp->reg_mutex); +27 /* +28 * Copy data from device registers to +29 * temporary device register buffer +30 * e.g. reg_buf.control = rp->control; +31 */ +32 mutex_exit(&sp->reg_mutex); +33 if (ddi_copyout(®_buf, arg, +34 sizeof (struct device), mode) != 0) { +35 return (EFAULT); +36 } + +37 break; +38 } +39 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBioctl\fR(9E), \fBbcopy\fR(9F), \fBcopyin\fR(9F), \fBcopyout\fR(9F), +\fBddi_copyin\fR(9F), \fBuiomove\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The value of the \fIflags\fR argument to \fBddi_copyout()\fR should be passed +through directly from the \fImode\fR argument of \fBioctl()\fR untranslated. +.sp +.LP +Driver defined locks should not be held across calls to this function. +.sp +.LP +\fBddi_copyout()\fR should not be used from a streams driver. See +\fBM_COPYIN\fR and \fBM_COPYOUT\fR in \fISTREAMS Programming Guide\fR. diff --git a/usr/src/man/man9f/ddi_create_minor_node.9f b/usr/src/man/man9f/ddi_create_minor_node.9f new file mode 100644 index 0000000000..14b6e9149c --- /dev/null +++ b/usr/src/man/man9f/ddi_create_minor_node.9f @@ -0,0 +1,336 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_create_minor_node 9F "14 Dec 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_create_minor_node \- Create a minor node for this device +.SH SYNOPSIS +.LP +.nf +#include <sys/stat.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_create_minor_node\fR(\fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR, \fBint\fR \fIspec_type\fR, + \fBminor_t\fR \fIminor_num\fR, \fBchar *\fR\fInode_type\fR, \fBint\fR \fIflag\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 14n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR \fR +.ad +.RS 14n +.rt +The name of this particular minor device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIspec_type\fR \fR +.ad +.RS 14n +.rt +\fBS_IFCHR\fR or \fBS_IFBLK\fR for character or block minor devices +respectively. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIminor_num\fR \fR +.ad +.RS 14n +.rt +The minor number for this particular minor device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInode_type\fR \fR +.ad +.RS 14n +.rt +Any string literal that uniquely identifies the type of node. The following +predefined node types are provided with this release: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_NT_SERIAL\fR \fR +.ad +.RS 24n +.rt +For serial ports +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_NT_SERIAL_MB\fR \fR +.ad +.RS 24n +.rt +For on board serial ports +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_NT_SERIAL_DO\fR \fR +.ad +.RS 24n +.rt +For dial out ports +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_NT_SERIAL_MB_DO\fR \fR +.ad +.RS 24n +.rt +For on board dial out ports +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_NT_BLOCK\fR \fR +.ad +.RS 24n +.rt +For hard disks +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_NT_BLOCK_CHAN\fR \fR +.ad +.RS 24n +.rt +For hard disks with channel or target numbers +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_NT_CD\fR \fR +.ad +.RS 24n +.rt +For CDROM drives +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_NT_CD_CHAN\fR \fR +.ad +.RS 24n +.rt +For CDROM drives with channel or target numbers +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_NT_FD\fR \fR +.ad +.RS 24n +.rt +For floppy disks +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_NT_TAPE\fR \fR +.ad +.RS 24n +.rt +For tape drives +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_NT_NET\fR \fR +.ad +.RS 24n +.rt +For DLPI style 1 or style 2 network devices +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_NT_DISPLAY\fR \fR +.ad +.RS 24n +.rt +For display devices +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PSEUDO\fR \fR +.ad +.RS 24n +.rt +For pseudo devices +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR \fR +.ad +.RS 14n +.rt +If the device is a clone device then this flag is set to \fBCLONE_DEV\fR else +it is set to \fB0\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_create_minor_node()\fR provides the necessary information to enable the +system to create the \fB/dev\fR and \fB/devices\fR hierarchies. The \fIname\fR +is used to create the minor name of the block or character special file under +the \fB/devices\fR hierarchy. At-sign (\fB@\fR), slash (\fB/\fR), and space are +not allowed. The \fIspec_type\fR specifies whether this is a block or character +device. The \fIminor_num\fR is the minor number for the device. The +\fInode_type\fR is used to create the names in the \fB/dev\fR hierarchy that +refers to the names in the \fB/devices\fR hierarchy. See \fBdisks\fR(1M), +\fBports\fR(1M), \fBtapes\fR(1M), \fBdevlinks\fR(1M). Finally \fIflag\fR +determines if this is a clone device or not, and what device class the node +belongs to. +.SH RETURN VALUES +.sp +.LP +\fBddi_create_minor_node()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR \fR +.ad +.RS 16n +.rt +Was able to allocate memory, create the minor data structure, and place it into +the linked list of minor devices for this driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR \fR +.ad +.RS 16n +.rt +Minor node creation failed. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_create_minor_node()\fR function can be called from user context. It +is typically called from \fBattach\fR(9E) or \fBioctl\fR(9E). +.SH EXAMPLES +.LP +\fBExample 1 \fRCreate Data Structure Describing Minor Device with Minor Number +of 0 +.sp +.LP +The following example creates a data structure describing a minor device called +\fIfoo\fR which has a minor number of 0. It is of type \fBDDI_NT_BLOCK\fR (a +block device) and it is not a clone device. + +.sp +.in +2 +.nf +ddi_create_minor_node(dip, "foo", S_IFBLK, 0, DDI_NT_BLOCK, 0); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBadd_drv\fR(1M), \fBdevlinks\fR(1M), \fBdisks\fR(1M), \fBdrvconfig\fR(1M), +\fBports\fR(1M), \fBtapes\fR(1M), \fBattach\fR(9E), +\fBddi_remove_minor_node\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +If the driver is for a network device (\fInode_type\fR \fBDDI_NT_NET\fR), note +that the driver name will undergo the driver name constraints identified in the +NOTES section of \fBdlpi\fR(7P). Additionally, the minor name must match the +driver name for a DLPI style 2 provider. If the driver is a DLPI style 1 +provider, the minor name must also match the driver name with the exception +that the ppa is appended to the minor name. +.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 +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(9E) 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(9E) 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. +.SH WARNING +.sp +.LP +Drivers must remove references to GLOBAL_DEV, NODEBOUND_DEV, NODESPECIFIC_DEV, +and ENUMERATED_DEV to compile under Solaris 10 and later versions. diff --git a/usr/src/man/man9f/ddi_cred.9f b/usr/src/man/man9f/ddi_cred.9f new file mode 100644 index 0000000000..74837d36e1 --- /dev/null +++ b/usr/src/man/man9f/ddi_cred.9f @@ -0,0 +1,230 @@ +'\" 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 ddi_cred 9F "6 Aug 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_cred, crgetuid, crgetruid, crgetsuid, crgetgid, crgetrgid, crgetsgid, +crgetzoneid, crgetgroups, crgetngroups \- access and change parts of the cred_t +structure +.SH SYNOPSIS +.LP +.nf +#include <sys/cred.h> + + + +\fBuid_t\fR \fBcrgetuid\fR(\fBconst cred_t *\fR\fIcr\fR); +.fi + +.LP +.nf +\fBuid_t\fR \fBcrgetruid\fR(\fBconst cred_t *\fR\fIcr\fR); +.fi + +.LP +.nf +\fBuid_t\fR \fBcrgetsuid\fR(\fBconst cred_t *\fR\fIcr\fR); +.fi + +.LP +.nf +\fBgid_t\fR \fBcrgetgid\fR(\fBconst cred_t *\fR\fIcr\fR); +.fi + +.LP +.nf +\fBgid_t\fR \fBcrgetrgid\fR(\fBconst cred_t *\fR\fIcr\fR); +.fi + +.LP +.nf +\fBgid_t\fR \fBcrgetsgid\fR(\fBconst cred_t *\fR\fIcr\fR); +.fi + +.LP +.nf +\fBzoneid_t\fR \fBcrgetzoneid\fR(\fBconst cred_t *\fR\fIcr\fR); +.fi + +.LP +.nf +\fBconst gid_t *\fR\fBcrgetgroups\fR(\fBconst cred_t *\fR\fIcr\fR); +.fi + +.LP +.nf +\fBint\fR \fBcrgetngroups\fR(\fBconst cred_t *\fR\fIcr\fR); +.fi + +.LP +.nf +\fBint\fR \fBcrsetresuid\fR(\fBcred_t *\fR\fIcr\fR, \fBuid_t\fR \fIruid\fR, \fBuid_t\fR \fIeuid\fR, \fBuid_t\fR \fIsuid\fR); +.fi + +.LP +.nf +\fBint\fR \fBcrsetresgid\fR(\fBcred_t *\fR\fIcr\fR, \fBgid_t\fR \fIrgid\fR, \fBgid_t\fR \fIegid\fR, \fBgid_t\fR \fIsgid\fR); +.fi + +.LP +.nf +\fBint\fR \fBcrsetugid\fR(\fBcred_t *\fR\fIcr\fR, \fBuid_t\fR \fIuid\fR, \fBgid_t\fR \fIgid\fR); +.fi + +.LP +.nf +\fBint\fR \fBcrsetgroups\fR(\fBcred_t *\fR\fIcr\fR, \fBint\fR \fIngroups\fR, \fBgid_t\fR \fIgids\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcr\fR\fR +.ad +.RS 25n +.rt +pointer to the user credential structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuid\fR, \fIruid\fR, \fIeuid\fR, \fIsuid\fR\fR +.ad +.RS 25n +.rt +new user id, real, effective and saved user id +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIgid\fR, \fIrgid\fR, \fIegid\fR, \fIsgid\fR\fR +.ad +.RS 25n +.rt +new group id, real, effective and saved group id +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIngroups\fR\fR +.ad +.RS 25n +.rt +number of groups in the group array +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIgids\fR\fR +.ad +.RS 25n +.rt +pointer to array of new groups +.RE + +.SH DESCRIPTION +.sp +.LP +The user credential is a shared, read-only, ref-counted data structure. Its +actual size and layout are subject to change. The functions described in this +page allow the programmer to retrieve fields from the structure and to +initialize newly allocated credential structures. +.sp +.LP +\fBcrgetuid()\fR, \fBcrgetruid()\fR, and \fBcrgetsuid()\fR return, +respectively, the effective, real, and saved user id from the user credential +pointed to by \fIcr\fR. +.sp +.LP +\fBcrgetgid()\fR, \fBcrgetrgid()\fR, and \fBcrgetsgid()\fR return, +respectively, the effective, real, and saved group id from the user credential +pointed to by \fIcr\fR. +.sp +.LP +\fBcrgetzoneid()\fR returns the zone id from the user credential pointed to by +\fIcr\fR. +.sp +.LP +\fBcrgetgroups()\fR returns the group list of the user credential pointed to by +\fIcr\fR. +.sp +.LP +\fBcrgetngroups()\fR returns the number of groups in the user credential +pointed to by \fIcr\fR. +.sp +.LP +\fBcrsetresuid()\fR sets the real, effective and saved user id. All but one can +be specified as -1, which causes the original value not to change. +.sp +.LP +\fBcrsetresgid()\fR sets the real, effective and saved group id. All but one +can be specified as -1, which causes the original value not to change. +.sp +.LP +\fBcrsetugid()\fR initializes the real, effective and saved user id \fBall\fR +to \fIuid\fR. It initializes the real, effective, and saved group id \fBall\fR +to \fIgid\fR. +.sp +.LP +\fBcrsetgroups()\fR sets the number of groups in the user credential to +\fIngroups\fR and copies the groups from \fIgids\fR to the user credential. If +\fIngroups\fR is 0, \fIgids\fR need not point to valid storage. +.sp +.LP +It is an error to call this any of the \fBcrset*()\fR functions on a user +credential structure that was newly allocated. +.SH RETURN VALUES +.sp +.LP +The \fBcrget*()\fR functions return the requested information. +.sp +.LP +The \fBcrset*id()\fR functions return 0 on success and -1 if any of the +specified ids are invalid. The functions might cause a system panic if called +on a user credential structure that is referenced by other parts of the system. +.SH CONTEXT +.sp +.LP +These functions can be called from user and kernel contexts. +.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 +_ +ArchitectureAll +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBprivileges\fR(5), \fBdrv_priv\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dev_is_needed.9f b/usr/src/man/man9f/ddi_dev_is_needed.9f new file mode 100644 index 0000000000..a26918b6ae --- /dev/null +++ b/usr/src/man/man9f/ddi_dev_is_needed.9f @@ -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 ddi_dev_is_needed 9F "7 Dec 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dev_is_needed \- inform the system that a device's component is required +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dev_is_needed\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIcomponent\fR, \fBint\fR \fIlevel\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 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 which is needed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlevel\fR\fR +.ad +.RS 13n +.rt +Power level at which the component is needed. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dev_is_needed()\fR function is obsolete and will be removed in a +future release. It is recommended that device drivers use +\fBpm_raise_power\fR(9F) and \fBpm_lower_power\fR(9F). +.sp +.LP +The \fBddi_dev_is_needed()\fR function informs the system that a device +component is needed at the specified power level. The \fIlevel\fR argument must +be non-zero. +.sp +.LP +This function sets a \fIcomponent\fR to the required level and sets all devices +which depend on this to their normal power levels. +.sp +.LP +The state of the device should be examined before each physical access. The +\fBddi_dev_is_needed()\fR function should be called to set a \fIcomponent\fR to +the required power level if the operation to be performed requires the +component to be at a power level other than its current level. +.sp +.LP +The \fBddi_dev_is_needed()\fR function might cause re-entry of the driver. +Deadlock may result if driver locks are held across the call to +\fBddi_dev_is_needed()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dev_is_needed()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Power successfully set to the requested level. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +An error occurred. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRdisk driver code +.sp +.LP +A hypothetical disk driver might include this code: + +.sp +.in +2 +.nf + static int +xxdisk_spun_down(struct xxstate *xsp) +{ + return (xsp->power_level[DISK_COMPONENT] < POWER_SPUN_UP); +} +static int +xxdisk_strategy(struct buf *bp) +{ + +\&.\|.\|. + + mutex_enter(&xxstate_lock); + /* + * Since we have to drop the mutex, we have to do this in a loop + * in case we get preempted and the device gets taken away from + * us again + */ + while (device_spun_down(sp)) { + mutex_exit(&xxstate_lock); + if (ddi_dev_is_needed(xsp->mydip, + XXDISK_COMPONENT, XXPOWER_SPUN_UP) != DDI_SUCCESS) { + bioerror(bp,EIO); + biodone(bp); + return (0); + } + mutex_enter(&xxstate_lock); + } + xsp->device_busy++; + mutex_exit(&xxstate_lock); + +\&.\|.\|. + +} +.fi +.in -2 + +.SH CONTEXT +.sp +.LP +This function can be called from user or kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBpm\fR(7D), \fBpm-components\fR(9P), \fBattach\fR(9E), \fBdetach\fR(9E), +\fBpower\fR(9E), \fBpm_busy_component\fR(9F), \fBpm_idle_component\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dev_is_sid.9f b/usr/src/man/man9f/ddi_dev_is_sid.9f new file mode 100644 index 0000000000..3c7bde5153 --- /dev/null +++ b/usr/src/man/man9f/ddi_dev_is_sid.9f @@ -0,0 +1,102 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dev_is_sid 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dev_is_sid \- tell whether a device is self-identifying +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dev_is_sid\fR(\fBdev_info_t *\fR\fIdip\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 \fBddi_dev_is_sid()\fR function tells the caller whether the device +described by \fIdip\fR is self-identifying, that is, a device that can +unequivocally tell the system that it exists. This is useful for drivers that +support both a self-identifying as well as a non-self-identifying variants of a +device (and therefore must be probed). +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Device is self-identifying. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Device is not self-identifying. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dev_is_sid()\fR function can be called from user, interrupt, or +kernel context. +.SH EXAMPLES +.sp +.in +2 +.nf +1 ... +2 int +3 bz_probe(dev_info_t *dip) +4 { +5 ... +6 if (ddi_dev_is_sid(dip) == DDI_SUCCESS) { +7 /* +8 * This is the self-identifying version (OpenBoot). +9 * No need to probe for it because we know it is there. +10 * The existence of dip && ddi_dev_is_sid() proves this. +11 */ +12 return (DDI_PROBE_DONTCARE); +13 } +14 /* +15 * Not a self-identifying variant of the device. Now we have to +16 * do some work to see whether it is really attached to the +17 * system. +18 */ +19 ... +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBprobe\fR(9E) \fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dev_nintrs.9f b/usr/src/man/man9f/ddi_dev_nintrs.9f new file mode 100644 index 0000000000..a4379d1832 --- /dev/null +++ b/usr/src/man/man9f/ddi_dev_nintrs.9f @@ -0,0 +1,88 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dev_nintrs 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dev_nintrs \- return the number of interrupt specifications a device has +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dev_nintrs\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint *\fR\fIresultp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). This interface is obsolete. Use the new +interrupt interfaces referenced in \fBIntro\fR(9F). Refer to \fIWriting Device +Drivers\fR for more information. +.SH DESCRIPTION +.sp +.LP +The \fBddi_dev_nintrs()\fR function returns the number of interrupt +specifications a device has in \fB*\fR\fIresultp\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dev_nintrs()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +A successful return. The number of interrupt specifications that the device has +is set in \fIresultp\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +The device has no interrupt specifications. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dev_nintrs()\fR function can be called from user, interrupt, or +kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBisa\fR(4), \fBsbus\fR(4), \fBddi_add_intr\fR(9F), \fBddi_dev_nregs\fR(9F), +\fBddi_dev_regsize\fR(9F), \fBIntro\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dev_nregs.9f b/usr/src/man/man9f/ddi_dev_nregs.9f new file mode 100644 index 0000000000..344c38c95b --- /dev/null +++ b/usr/src/man/man9f/ddi_dev_nregs.9f @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dev_nregs 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dev_nregs \- return the number of register sets a device has +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dev_nregs\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint *\fR\fIresultp\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 11n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIresultp\fR\fR +.ad +.RS 11n +.rt +Pointer to an integer that holds the number of register sets on return. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dev_nregs()\fR function returns the number of sets of registers the +device has. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dev_nregs()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +A successful return. The number of register sets is returned in \fIresultp\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +The device has no registers. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dev_nregs()\fR function can be called from user, interrupt, or +kernel context. +.SH SEE ALSO +.sp +.LP +\fBddi_dev_nintrs\fR(9F), \fBddi_dev_regsize\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dev_regsize.9f b/usr/src/man/man9f/ddi_dev_regsize.9f new file mode 100644 index 0000000000..134958a3d7 --- /dev/null +++ b/usr/src/man/man9f/ddi_dev_regsize.9f @@ -0,0 +1,108 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dev_regsize 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dev_regsize \- return the size of a device's register +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dev_regsize\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIrnumber\fR, \fBoff_t *\fR\fIresultp\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 11n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrnumber\fR\fR +.ad +.RS 11n +.rt +The ordinal register number. Device registers are associated with a +\fBdev_info\fR and are enumerated in arbitrary sets from \fB0\fR on up. The +number of registers a device has can be determined from a call to +\fBddi_dev_nregs\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIresultp\fR\fR +.ad +.RS 11n +.rt +Pointer to an integer that holds the size, in bytes, of the described register +(if it exists). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dev_regsize()\fR function returns the size, in bytes, of the device +register specified by \fIdip\fR and \fIrnumber\fR. This is useful when, for +example, one of the registers is a frame buffer with a varying size known only +to its proms. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dev_regsize()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +A successful return. The size, in bytes, of the specified register, is set in +\fIresultp\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +An invalid (nonexistent) register number was specified. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dev_regsize()\fR function can be called from user, interrupt, or +kernel context. +.SH SEE ALSO +.sp +.LP +\fBddi_dev_nintrs\fR(9F), \fBddi_dev_nregs\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dev_report_fault.9f b/usr/src/man/man9f/ddi_dev_report_fault.9f new file mode 100644 index 0000000000..6bda17c2f9 --- /dev/null +++ b/usr/src/man/man9f/ddi_dev_report_fault.9f @@ -0,0 +1,245 @@ +'\" te +.\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dev_report_fault 9F "13 August 1999" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dev_report_fault \- Report a hardware failure +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_dev_report_fault\fR (\fBdev_info_t *\fR\fIdip\fR, + \fBddi_fault_impact_t\fR \fIimpact\fR, \fB ddi_fault_location_t\fR \fIlocation\fR, + \fBconst char *\fR\fImessage \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 13n +.rt +Pointer to the driver's \fBdev_info\fR structure to which the fault report +relates. (Normally the caller's own \fBdev_info\fR pointer). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIimpact\fR \fR +.ad +.RS 13n +.rt +One of a set of enumerated values indicating the impact of the fault on the +device's ability to provide normal service. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlocation\fR \fR +.ad +.RS 13n +.rt +One of a set of enumerated values indicating the location of the fault, +relative to the hardware controlled by the driver specified by \fBdip\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImessage\fR \fR +.ad +.RS 13n +.rt +Text of the message describing the fault being reported. +.RE + +.SH DESCRIPTION +.sp +.LP +This function provides a standardized mechanism through which device drivers +can report hardware faults. Use of this reporting mechanism enables systems +equipped with a fault management system to respond to faults discovered by a +driver. On a suitably equipped system, this might include automatic failover to +an alternative device and/or scheduling replacement of the faulty hardware. +.sp +.LP +The driver must indicate the impact of the fault being reported on its ability +to provide service by passing one of the following values for the impact +parameter: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SERVICE_LOST\fR\fR +.ad +.RS 26n +.rt +Indicates a total loss of service. The driver is unable to implement the normal +functions of its hardware. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SERVICE_DEGRADED\fR\fR +.ad +.RS 26n +.rt +The driver is unable to provide normal service, but can provide a partial or +degraded level of service. The driver may have to make repeated attempts to +perform an operation before it succeeds, or it may be running at less than its +configured speed. A driver may use this value to indicate that an alternative +device should be used if available, but that it can continue operation if no +alternative exists. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SERVICE_UNAFFECTED\fR\fR +.ad +.RS 26n +.rt +The service provided by the device is currently unaffected by the reported +fault. This value may be used to report recovered errors for predictive failure +analysis. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SERVICE_RESTORED\fR\fR +.ad +.RS 26n +.rt +The driver has resumed normal service, following a previous report that service +was lost or degraded. This message implies that any previously reported fault +condition no longer exists. +.RE + +.sp +.LP +The location parameter should be one of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DATAPATH_FAULT\fR\fR +.ad +.RS 22n +.rt +The fault lies in the datapath between the driver and the device. The device +may be unplugged, or a problem may exist in the bus on which the device +resides. This value is appropriate if the device is not responding to +accesses, (for example, the device may not be present) or if a call to +\fBddi_check_acc_handle\fR(9F) returns \fBDDI_FAILURE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEVICE_FAULT\fR\fR +.ad +.RS 22n +.rt +The fault lies in the device controlled by the driver. This value is +appropriate if the device returns an error from a selftest function, or if the +driver is able to determine that device is present and accessible, but is not +functioning correctly. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EXTERNAL_FAULT\fR\fR +.ad +.RS 22n +.rt +The fault is external to the device. For example, an Ethernet driver would use +this value when reporting a cable fault. +.sp +If a device returns detectably bad data during normal operation (an +"impossible" value in a register or DMA status area, for example), the driver +should check the associated handle using \fBddi_check_acc_handle\fR(9F) or +\fBddi_check_dma_handle\fR(9F) before reporting the fault. If the fault is +associated with the handle, the driver should specify \fBDDI_DATAPATH_FAULT\fR +rather than \fBDDI_DEVICE_FAULT\fR. As a consequence of this call, the device's +state may be updated to reflect the level of service currently available. See +\fBddi_get_devstate\fR(9F). +.sp +Note that if a driver calls \fBddi_get_devstate\fR(9F) and discovers that its +device is down, a fault should not be reported- the device is down as the +result of a fault that has already been reported. Additionally, a driver should +avoid incurring or reporting additional faults when the device is already known +to be unusable. The \fBddi_dev_report_fault()\fR call should only be used to +report hardware (device) problems and should not be used to report purely +software problems such as memory (or other resource) exhaustion. +.RE + +.SH EXAMPLES +.sp +.LP +An Ethernet driver receives an error interrupt from its device if various fault +conditions occur. The driver must read an error status register to determine +the nature of the fault, and report it appropriately: +.sp +.in +2 +.nf +static int +xx_error_intr(xx_soft_state *ssp) +{ + ... + error_status = ddi_get32(ssp->handle, &ssp->regs->xx_err_status); + if (ddi_check_acc_handle(ssp->handle) != DDI_SUCCESS) { + ddi_dev_report_fault(ssp->dip, DDI_SERVICE_LOST, + DDI_DATAPATH_FAULT, "register access fault"); + return DDI_INTR_UNCLAIMED; + } + if (ssp->error_status & XX_CABLE_FAULT) { + ddi_dev_report_fault(ssp->dip, DDI_SERVICE_LOST, + DDI_EXTERNAL_FAULT, "cable fault") + return DDI_INTR_CLAIMED; + } + if (ssp->error_status & XX_JABBER) { + ddi_dev_report_fault(ssp->dip, DDI_SERVICE_DEGRADED, + DDI_EXTERNAL_FAULT, "jabbering detected") + return DDI_INTR_CLAIMED; + } + ... +} +.fi +.in -2 + +.SH CONTEXT +.sp +.LP +The \fBddi_dev_report_fault()\fR function may be called from user, kernel, or +interrupt context. +.SH SEE ALSO +.sp +.LP +\fBddi_check_acc_handle\fR(9F), \fBddi_check_dma_handle\fR(9F), +\fBddi_get_devstate\fR(9F) diff --git a/usr/src/man/man9f/ddi_device_copy.9f b/usr/src/man/man9f/ddi_device_copy.9f new file mode 100644 index 0000000000..ee93dd0a3e --- /dev/null +++ b/usr/src/man/man9f/ddi_device_copy.9f @@ -0,0 +1,223 @@ +'\" 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 ddi_device_copy 9F "15 Nov 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_device_copy \- copy data from one device register to another device +register +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_device_copy\fR(\fBddi_acc_handle_t\fR \fIsrc_handle\fR, \fBcaddr_t\fR \fIsrc_addr\fR, + \fBssize_t\fR \fIsrc_advcnt\fR, \fBddi_acc_handle_t\fR \fIdest_handle\fR, + \fBcaddr_t\fR \fIdest_addr\fR, \fBssize_t\fR \fIdest_advcnt\fR, + \fBsize_t\fR \fIbytecount\fR, \fBuint_t\fR \fIdev_datasz\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsrc_handle\fR \fR +.ad +.RS 16n +.rt +The data access handle of the source device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsrc_addr\fR \fR +.ad +.RS 16n +.rt +Base data source address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsrc_advcnt\fR \fR +.ad +.RS 16n +.rt +Number of \fIdev_datasz\fR units to advance on every access. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdest_handle\fR \fR +.ad +.RS 16n +.rt +The data access handle of the destination device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdest_addr\fR \fR +.ad +.RS 16n +.rt +Base data destination address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdest_advcnt\fR \fR +.ad +.RS 16n +.rt +Number of \fIdev_datasz\fR units to advance on every access. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbytecount\fR \fR +.ad +.RS 16n +.rt +Number of bytes to transfer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_datasz\fR \fR +.ad +.RS 16n +.rt +The size of each data word. Possible values are defined as: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DATA_SZ01_ACC\fR \fR +.ad +.RS 22n +.rt +1 byte data size +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DATA_SZ02_ACC\fR \fR +.ad +.RS 22n +.rt +2 bytes data size +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DATA_SZ04_ACC\fR \fR +.ad +.RS 22n +.rt +4 bytes data size +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DATA_SZ08_ACC\fR \fR +.ad +.RS 22n +.rt +8 bytes data size +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_device_copy()\fR copies \fIbytecount\fR bytes from the source address, +\fIsrc_addr\fR, to the destination address, \fIdest_addr\fR. The attributes +encoded in the access handles, \fIsrc_handle\fR and \fIdest_handle\fR, govern +how data is actually copied from the source to the destination. Only matching +data sizes between the source and destination are supported. +.sp +.LP +Data will automatically be translated to maintain a consistent view between +the source and the destination. The translation may involve byte-swapping if +the source and the destination devices have incompatible endian +characteristics. +.sp +.LP +The \fIsrc_advcnt\fR and \fIdest_advcnt\fR arguments specifies the number of +\fIdev_datasz\fR units to advance with each access to the device addresses. A +value of \fB0\fR will use the same source and destination device address on +every access. A positive value increments the corresponding device address by +certain number of data size units in the next access. On the other hand, a +negative value decrements the device address. +.sp +.LP +The \fIdev_datasz\fR argument determines the size of the data word on each +access. The data size must be the same between the source and destination. +.SH RETURN VALUES +.sp +.LP +\fBddi_device_copy()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR \fR +.ad +.RS 16n +.rt +Successfully transferred the data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR \fR +.ad +.RS 16n +.rt +The byte count is not a multiple \fIdev_datasz\fR. +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_device_copy()\fR can be called from user, kernel, or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBddi_regs_map_free\fR(9F), \fBddi_regs_map_setup\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_device_zero.9f b/usr/src/man/man9f/ddi_device_zero.9f new file mode 100644 index 0000000000..17b546e708 --- /dev/null +++ b/usr/src/man/man9f/ddi_device_zero.9f @@ -0,0 +1,178 @@ +'\" 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 ddi_device_zero 9F "25 Sep 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_device_zero \- zero fill the device +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_device_zero\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBcaddr_t\fR \fIdev_addr\fR, + \fBsize_t\fR \fIbytecount\fR, \fBssize_t\fR \fIdev_advcnt\fR, \fBuint_t\fR \fIdev_datasz\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 15n +.rt +The data access handle returned from setup calls, such as +\fBddi_regs_map_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_addr\fR \fR +.ad +.RS 15n +.rt +Beginning of the device address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbytecount\fR \fR +.ad +.RS 15n +.rt +Number of bytes to zero. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_advcnt\fR \fR +.ad +.RS 15n +.rt +Number of \fIdev_datasz\fR units to advance on every access. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_datasz\fR \fR +.ad +.RS 15n +.rt +The size of each data word. Possible values are defined as: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DATA_SZ01_ACC\fR \fR +.ad +.RS 22n +.rt +1 byte data size +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DATA_SZ02_ACC\fR \fR +.ad +.RS 22n +.rt +2 bytes data size +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DATA_SZ04_ACC\fR \fR +.ad +.RS 22n +.rt +4 bytes data size +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DATA_SZ08_ACC\fR \fR +.ad +.RS 22n +.rt +8 bytes data size +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_device_zero()\fR function fills the given, \fIbytecount\fR, number of +byte of zeroes to the device register or memory. +.sp +.LP +The \fIdev_advcnt\fR argument determines the value of the device address, +\fIdev_addr\fR, on each access. A value of \fB0\fR will use the same device +address, \fIdev_addr\fR, on every access. A positive value increments the +device address in the next access while a negative value decrements the +address. The device address is incremented and decremented in \fIdev_datasz\fR +units. +.sp +.LP +The \fIdev_datasz\fR argument determines the size of data word on each access. +.SH RETURN VALUES +.sp +.LP +\fBddi_device_zero()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR \fR +.ad +.RS 16n +.rt +Successfully zeroed the data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR \fR +.ad +.RS 16n +.rt +The byte count is not a multiple of \fIdev_datasz\fR. +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_device_zero()\fR can be called from user, kernel, or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBddi_regs_map_free\fR(9F), \fBddi_regs_map_setup\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_devid_compare.9f b/usr/src/man/man9f/ddi_devid_compare.9f new file mode 100644 index 0000000000..a874609acc --- /dev/null +++ b/usr/src/man/man9f/ddi_devid_compare.9f @@ -0,0 +1,611 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_devid_compare 9F "21 May 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_devid_compare, ddi_devid_free, ddi_devid_init, ddi_devid_register, +ddi_devid_sizeof, ddi_devid_str_decode, ddi_devid_str_encode, +ddi_devid_str_free, ddi_devid_get, ddi_devid_unregister, ddi_devid_valid \- +kernel interfaces for device ids +.SH SYNOPSIS +.LP +.nf +\fBint\fR \fBddi_devid_compare\fR(\fBddi_devid_t\fR \fIdevid1\fR, \fBddi_devid_t\fR \fIdevid2\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBddi_devid_sizeof\fR(\fBddi_devid_t\fR \fIdevid\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_devid_init\fR(\fBdev_info_t *\fR\fIdip\fR, \fBushort_t\fR \fIdevid_type\fR, + \fBushort_t\fR \fInbytes\fR, \fBvoid *\fR\fIid\fR, \fBddi_devid_t *\fR\fIretdevid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_devid_free\fR(\fBddi_devid_t\fR \fIdevid\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_devid_register\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_devid_t\fR \fIdevid\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_devid_str_decode\fR(\fBchar *\fR\fIdevidstr\fR, \fBddi_devid_t *\fR\fIretdevid\fR, + \fBchar **\fR\fIretminor_name\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_devid_str_encode\fR(\fBddi_devid_t\fR \fIdevid\fR, \fBchar *\fR\fIminor_name\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_devid_str_free\fR(\fBchar *\fR\fIdevidstr\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_devid_get\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_devid_t *\fR\fIretdevid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_devid_unregister\fR(\fBdev_info_t *\fR\fIdip\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_devid_valid\fR(\fBddi_devid_t\fR \fIdevid\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdevid\fR\fR +.ad +.RS 14n +.rt +The device id address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdevidstr\fR\fR +.ad +.RS 14n +.rt +The \fIdevid\fR and \fIminor_name\fR represented as a string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdevid1\fR\fR +.ad +.RS 14n +.rt +The first of two device id addresses to be compared calling +\fBddi_devid_compare()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdevid2\fR\fR +.ad +.RS 14n +.rt +The second of two device id addresses to be compared calling +\fBddi_devid_compare()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 14n +.rt +A \fBdev_info\fR pointer, which identifies the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdevid_type\fR\fR +.ad +.RS 14n +.rt +The following device id types may be accepted by the \fBddi_devid_init()\fR +function: +.sp +.ne 2 +.mk +.na +\fB\fBDEVID_SCSI3_WWN\fR\fR +.ad +.RS 21n +.rt +World Wide Name associated with SCSI-3 devices. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDEVID_SCSI_SERIAL\fR\fR +.ad +.RS 21n +.rt +Vendor \fBID\fRand serial number associated with a SCSI device. Note: This may +only be used if known to be unique; otherwise a fabricated device id must be +used. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDEVID_ENCAP\fR\fR +.ad +.RS 21n +.rt +Device \fBID\fR of another device. This is for layered device driver usage. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDEVID_FAB\fR\fR +.ad +.RS 21n +.rt +Fabricated device \fBID\fR. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIminor_name\fR\fR +.ad +.RS 17n +.rt +The minor name to be encoded. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInbytes\fR\fR +.ad +.RS 17n +.rt +The length in bytes of device \fBID\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIretdevid\fR\fR +.ad +.RS 17n +.rt +The return address of the device \fBID\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIretminor_name\fR\fR +.ad +.RS 17n +.rt +The return address of a minor name. Free string with +\fBddi_devid_str_free()\fR. +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The following routines are used to provide unique identifiers, device +\fBID\fRs, for devices. Specifically, kernel modules use these interfaces to +identify and locate devices, independent of the device's physical connection or +its logical device name or number. +.sp +.LP +\fBddi_devid_compare()\fR compares two device \fBID\fRs byte-by-byte and +determines both equality and sort order. +.sp +.LP +\fBddi_devid_sizeof()\fR returns the number of bytes allocated for the passed +in device \fBID\fR (\fIdevid\fR). +.sp +.LP +\fBddi_devid_init()\fR allocates memory and initializes the opaque device +\fBID\fR structure. This function does not store the \fIdevid\fR. If the device +id is not derived from the device's firmware, it is the driver's responsibility +to store the \fIdevid\fR on some reliable store. When a \fIdevid_type\fR of +either \fBDEVID_SCSI3_WWN,\fR \fBDEVID_SCSI_SERIAL\fR, or \fBDEVID_ENCAP\fR is +accepted, an array of bytes (\fIid\fR) must be passed in (\fInbytes\fR). +.sp +.LP +When the \fIdevid_type\fR \fBDEVID_FAB\fR is used, the array of bytes +(\fIid\fR) must be \fBNULL\fR and the length (\fInbytes\fR) must be zero. The +fabricated device ids, \fBDEVID_FAB\fR will be initialized with the machine's +host id and a timestamp. +.sp +.LP +Drivers must free the memory allocated by this function, using the +\fBddi_devid_free()\fR function. +.sp +.LP +\fBddi_devid_free()\fR frees the memory allocated for the returned \fIdevid\fR +by the \fBddi_devid_init()\fR and \fBdevid_str_decode()\fR functions. +.sp +.LP +\fBddi_devid_register()\fR registers the device \fBID\fR address (\fIdevid\fR) +with the \fBDDI\fR framework, associating it with the \fBdev_info\fR passed in +(\fIdip\fR). The drivers must register device \fBID\fRs at attach time. See +\fBattach\fR(9E). +.sp +.LP +\fBddi_devid_unregister()\fR removes the device \fBID\fR address from the +\fBdev_info\fR passed in (\fIdip\fR). Drivers must use this function to +unregister the device \fBID\fR when devices are being detached. This function +does not free the space allocated for the device \fBID\fR. The driver must free +the space allocated for the device \fBID\fR, using the \fBddi_devid_free()\fR +function. See \fBdetach\fR(9E). +.sp +.LP +\fBddi_devid_valid()\fR validates the device \fBID\fR (\fIdevid\fR) passed in. +The driver must use this function to validate any fabricated device \fBID\fR +that has been stored on a device. +.sp +.LP +The \fBddi_devid_get()\fR function returns a pointer to the device ID structure +through \fIretdevid\fR if there is already a registered device ID associated +with the \fBdev_info\fR node. A driver can use this interface to check and get +the device ID associated with the \fBdev_info\fR node. It returns +\fBDDI_FAILURE\fR if no device ID is registered for the node. +.sp +.LP +The \fBddi_devid_get()\fR function allocates memory for the opaque device ID +structure and initializes it with the associated device ID and returns the +pointer to it. The driver must free the memory allocated by this function using +the \fBddi_devid_free()\fR function. +.sp +.LP +The \fBddi_devid_str_encode()\fR function encodes a \fIdevid\fR and minor_name +into a null-terminated ASCII string, returning a pointer to that string. If +both a \fIdevid\fR and a \fIminor_name\fR are non-null, then a slash (\fB/\fR) +is used to separate the \fIdevid\fR from the \fIminor_name\fR in the encoded +string. If \fIminor_name\fR is null, then only the \fIdevid\fR is encoded. If +the \fIdevid\fR is null, then the special string \fBid0\fR is returned. Note +that you cannot compare the returned string against another string with +\fBstrcmp()\fR to determine \fIdevid\fR equality. The returned string must be +freed by calling \fBdevid_str_free()\fR. +.sp +.LP +The \fBddi_devid_str_decode()\fR function takes a string previously produced by +the \fBdevid_str_encode\fR(3DEVID) or \fBddi_devid_str_encode()\fR function and +decodes the contained device ID and minor_name, allocating and returning +pointers to the extracted parts through the \fIretdevid\fR and +\fIretminor_name\fR arguments. If the special \fIdevidstr\fR \fBid0\fR was +specified then the returned device ID and minor name will both be null. A +non-null returned \fIdevid\fR must be freed by the caller through the +\fBddi_devid_free()\fR function. A non-null returned minor name must be freed +by calling \fBddi_devid_str_free()\fR. +.sp +.LP +The \fBddi_devid_str_free()\fR function is used to free all strings returned by +the \fBddi_devid\fR functions (the \fBddi_devid_str_encode()\fR function return +value and the returned \fIretminor_name\fR argument). +.SH RETURN VALUES +.sp +.LP +\fBddi_devid_init()\fR returns the following values: +.sp +.ne 2 +.mk +.na +\fB \fR +.ad +.RS 5n +.rt +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Out of memory. An invalid \fIdevid_type\fR was passed in. +.RE + +.RE + +.sp +.LP +\fBddi_devid_valid()\fR returns the following values: +.sp +.ne 2 +.mk +.na +\fB \fR +.ad +.RS 5n +.rt +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Valid device \fBID\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Invalid device \fBID\fR. +.RE + +.RE + +.sp +.LP +\fBddi_devid_register()\fR returns the following values: +.sp +.ne 2 +.mk +.na +\fB \fR +.ad +.RS 5n +.rt +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Failure. The device \fBID\fR is already registered or the device \fBID\fR is +invalid. +.RE + +.RE + +.sp +.LP +\fBddi_devid_valid()\fR returns the following values: +.sp +.ne 2 +.mk +.na +\fB \fR +.ad +.RS 5n +.rt +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Valid device \fBID\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Invalid device \fBID\fR. +.RE + +.RE + +.sp +.LP +\fBddi_devid_get()\fR returns the following values: +.sp +.ne 2 +.mk +.na +\fB \fR +.ad +.RS 5n +.rt +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Device \fBID\fR is present and a pointer to it is returned in \fIretdevid\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +No device \fBID\fR is defined for this \fBdev_info\fR node. +.RE + +.RE + +.sp +.LP +\fBddi_devid_compare()\fR returns the following values: +.sp +.ne 2 +.mk +.na +\fB \fR +.ad +.RS 5n +.rt +.sp +.ne 2 +.mk +.na +\fB\fB\(mi1\fR\fR +.ad +.RS 9n +.rt +The first device ID is less than the second device ID. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 9n +.rt +The first device ID is equal to the second device ID. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 9n +.rt +The first device ID is greater than the second device ID. +.RE + +.RE + +.sp +.LP +\fBddi_devid_sizeof()\fR returns the size of the \fIdevid\fR in bytes. If +called with a null, then the number of bytes that must be allocated and +initialized to determine the size of a complete device ID is returned. +.sp +.LP +\fBddi_devid_str_encode()\fR returns a value of null to indicate failure. +Failure can be caused by attempting to encode an invalid \fIdevid\fR. If the +return value is non-null then the caller must free the returned string by using +the \fBdevid_str_free()\fR function. +.sp +.LP +\fBddi_devid_str_decode()\fR returns the following values: +.sp +.ne 2 +.mk +.na +\fB \fR +.ad +.RS 5n +.rt +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Failure; the \fIdevidstr\fR string was not valid. +.RE + +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from a user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBdevid_get\fR(3DEVID), , \fBlibdevid\fR(3LIB), \fBattributes\fR(5), +\fBattach\fR(9E), \fBdetach\fR(9E), \fBkmem_free\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_addr_bind_handle.9f b/usr/src/man/man9f/ddi_dma_addr_bind_handle.9f new file mode 100644 index 0000000000..183a45736f --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_addr_bind_handle.9f @@ -0,0 +1,452 @@ +'\" 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 ddi_dma_addr_bind_handle 9F "26 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_addr_bind_handle \- binds an address to a DMA handle +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_addr_bind_handle\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBstruct as *\fR\fIas\fR, + \fBcaddr_t\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBuint_t\fR \fIflags\fR, \fBint (*\fR\fIcallback\fR) (caddr_t) , + \fBcaddr_t\fR \fIarg\fR, \fBddi_dma_cookie_t *\fR\fIcookiep\fR, \fBuint_t *\fR\fIccountp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 13n +.rt +The \fBDMA\fR handle previously allocated by a call to +\fBddi_dma_alloc_handle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIas\fR \fR +.ad +.RS 13n +.rt +A pointer to an address space structure. This parameter should be set to +\fINULL\fR, which implies kernel address space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR \fR +.ad +.RS 13n +.rt +Virtual address of the memory object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR \fR +.ad +.RS 13n +.rt +Length of the memory object in bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR \fR +.ad +.RS 13n +.rt +Valid flags include: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_WRITE\fR \fR +.ad +.RS 23n +.rt +Transfer direction is from memory to I/O. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_READ\fR \fR +.ad +.RS 23n +.rt +Transfer direction is from I/O to memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_RDWR\fR \fR +.ad +.RS 23n +.rt +Both read and write. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_REDZONE\fR \fR +.ad +.RS 23n +.rt +Establish an \fBMMU\fR redzone at end of the object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_PARTIAL\fR \fR +.ad +.RS 23n +.rt +Partial resource allocation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_CONSISTENT\fR \fR +.ad +.RS 23n +.rt +Nonsequential, random, and small block transfers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_STREAMING\fR \fR +.ad +.RS 23n +.rt +Sequential, unidirectional, block-sized, and block-aligned transfers. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR \fR +.ad +.RS 13n +.rt +The address of a function to call back later if resources are not currently +available. The following special function addresses may also be used. +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_SLEEP\fR \fR +.ad +.RS 21n +.rt +Wait until resources are available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_DONTWAIT\fR \fR +.ad +.RS 21n +.rt +Do not wait until resources are available and do not schedule a callback. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR \fR +.ad +.RS 13n +.rt +Argument to be passed to the callback function, \fIcallback\fR, if such a +function is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookiep\fR \fR +.ad +.RS 13n +.rt +A pointer to the first \fBddi_dma_cookie\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIccountp\fR \fR +.ad +.RS 13n +.rt +Upon a successful return, \fIccountp\fR points to a value representing the +number of cookies for this \fBDMA\fR object. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_dma_addr_bind_handle()\fR allocates \fBDMA\fR resources for a memory +object such that a device can perform \fBDMA\fR to or from the object. +\fBDMA\fR resources are allocated considering the device's \fBDMA\fR attributes +as expressed by \fBddi_dma_attr\fR(9S) (see \fBddi_dma_alloc_handle\fR(9F)). +.sp +.LP +\fBddi_dma_addr_bind_handle()\fR fills in the first \fBDMA\fR cookie pointed to +by \fIcookiep\fR with the appropriate address, length, and bus type. +\fB*\fR\fIccountp\fR is set to the number of \fBDMA\fR cookies representing +this \fBDMA\fR object. Subsequent \fBDMA\fR cookies must be retrieved by +calling \fBddi_dma_nextcookie\fR(9F) the number of times specified by +\fB*\fR\fIcountp\fR-1. +.sp +.LP +When a \fBDMA\fR transfer completes, the driver frees up system \fBDMA\fR +resources by calling \fBddi_dma_unbind_handle\fR(9F). +.sp +.LP +The \fIflags\fR argument contains information for mapping routines. +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_WRITE\fR, \fBDDI_DMA_READ\fR, \fBDDI_DMA_RDWR\fR\fR +.ad +.sp .6 +.RS 4n +These flags describe the intended direction of the \fBDMA\fR transfer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_STREAMING\fR \fR +.ad +.sp .6 +.RS 4n +This flag should be set if the device is doing sequential, unidirectional, +block-sized, and block-aligned transfers to or from memory. The alignment and +padding constraints specified by the \fBminxfer\fR and \fBburstsizes\fR fields +in the \fBDMA\fR attribute structure, \fBddi_dma_attr\fR(9S) (see +\fBddi_dma_alloc_handle\fR(9F)) is used to allocate the most effective hardware +support for large transfers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_CONSISTENT\fR \fR +.ad +.sp .6 +.RS 4n +This flag should be set if the device accesses memory randomly, or if +synchronization steps using \fBddi_dma_sync\fR(9F) need to be as efficient as +possible. I/O parameter blocks used for communication between a device and a +driver should be allocated using \fBDDI_DMA_CONSISTENT\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_REDZONE\fR \fR +.ad +.sp .6 +.RS 4n +If this flag is set, the system attempts to establish a protected red zone +after the object. The \fBDMA\fR resource allocation functions do not guarantee +the success of this request as some implementations may not have the hardware +ability to support a red zone. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_PARTIAL\fR \fR +.ad +.sp .6 +.RS 4n +Setting this flag indicates the caller can accept resources for part of the +object. That is, if the size of the object exceeds the resources available, +only resources for a portion of the object are allocated. The system indicates +this condition by returning status \fBDDI_DMA_PARTIAL_MAP\fR. At a later point, +the caller can use \fBddi_dma_getwin\fR(9F) to change the valid portion of the +object for which resources are allocated. If resources were allocated for only +part of the object, \fBddi_dma_addr_bind_handle()\fR returns resources for the +first \fBDMA\fRwindow. Even when \fBDDI_DMA_PARTIAL\fR is set, the system may +decide to allocate resources for the entire object (less overhead) in which +case \fBDDI_DMA_MAPPED\fR is returned. +.RE + +.sp +.LP +The callback function \fIcallback\fR indicates how a caller wants to handle the +possibility of resources not being available. If \fIcallback\fR is set to +\fBDDI_DMA_DONTWAIT\fR, the caller does not care if the allocation fails, and +can handle an allocation failure appropriately. If \fIcallback\fR is set to +\fBDDI_DMA_SLEEP\fR, the caller wishes to have the allocation routines wait for +resources to become available. If any other value is set and a \fBDMA\fR +resource allocation fails, this value is assumed to be the address of a +function to be called when resources become available. When the specified +function is called, \fIarg\fR is passed to it as an argument. The specified +callback function must return either \fBDDI_DMA_CALLBACK_RUNOUT\fR or +\fBDDI_DMA_CALLBACK_DONE\fR. \fBDDI_DMA_CALLBACK_RUNOUT\fR indicates that the +callback function attempted to allocate \fBDMA\fR resources but failed. In +this case, the callback function is put back on a list to be called again +later. \fBDDI_DMA_CALLBACK_DONE\fR indicates that either the allocation of +\fBDMA\fR resources was successful or the driver no longer wishes to retry. +.sp +.LP +The callback function is called in interrupt context. Therefore, only system +functions accessible from interrupt context are be available. The callback +function must take whatever steps are necessary to protect its critical +resources, data structures, queues, and so on. +.SH RETURN VALUES +.sp +.LP +\fBddi_dma_addr_bind_handle()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_MAPPED\fR \fR +.ad +.RS 24n +.rt +Successfully allocated resources for the entire object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_PARTIAL_MAP\fR \fR +.ad +.RS 24n +.rt +Successfully allocated resources for a part of the object. This is acceptable +when partial transfers are permitted by setting the \fBDDI_DMA_PARTIAL\fR flag +in \fIflags\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_INUSE\fR \fR +.ad +.RS 24n +.rt +Another I/O transaction is using the \fBDMA\fR handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_NORESOURCES\fR \fR +.ad +.RS 24n +.rt +No resources are available at the present time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_NOMAPPING\fR \fR +.ad +.RS 24n +.rt +The object cannot be reached by the device requesting the resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_TOOBIG\fR \fR +.ad +.RS 24n +.rt +The object is too big. A request of this size can never be satisfied on this +particular system. The maximum size varies depending on machine and +configuration. +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_dma_addr_bind_handle()\fR can be called from user, kernel, or interrupt +context, except when \fIcallback\fR is set to \fBDDI_DMA_SLEEP\fR, in which +case it can only be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_free_handle\fR(9F), +\fBddi_dma_getwin\fR(9F), \fBddi_dma_mem_alloc\fR(9F), +\fBddi_dma_mem_free\fR(9F), \fBddi_dma_nextcookie\fR(9F), +\fBddi_dma_sync\fR(9F), \fBddi_dma_unbind_handle\fR(9F), +\fBddi_umem_iosetup\fR(9F), \fBddi_dma_attr\fR(9S), \fBddi_dma_cookie\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +If the driver permits partial mapping with the \fBDDI_DMA_PARTIAL\fR flag, the +number of cookies in each window may exceed the size of the device's +scatter/gather list as specified in the \fBdma_attr_sgllen\fR field in the +\fBddi_dma_attr\fR(9S) structure. In this case, each set of cookies comprising +a \fBDMA\fR window will satisfy the \fBDMA\fR attributes as described in the +\fBddi_dma_attr\fR(9S) structure in all aspects. The driver should set up its +\fBDMA\fR engine and perform one transfer for each set of cookies sufficient +for its scatter/gather list, up to the number of cookies for this window, +before advancing to the next window using \fBddi_dma_getwin\fR(9F). diff --git a/usr/src/man/man9f/ddi_dma_addr_setup.9f b/usr/src/man/man9f/ddi_dma_addr_setup.9f new file mode 100644 index 0000000000..9b2d5c7fb8 --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_addr_setup.9f @@ -0,0 +1,175 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_addr_setup 9F "04 Apr 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_addr_setup \- easier DMA setup for use with virtual addresses +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_dma_addr_setup\fR(\fBdev_info_t *\fR\fIdip\fR, \fBstruct as *\fR\fIas\fR, \fBcaddr_t\fR \fIaddr\fR, + \fBsize_t\fR \fIlen\fR, \fBuint_t\fR \fIflags\fR, \fBint (*\fR\fIwaitfp\fR) (caddr_t), \fBcaddr_t\fR \fIarg\fR, + \fBddi_dma_lim_t *\fR \fIlim\fR, \fBddi_dma_handle_t *\fR\fIhandlep\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. \fBddi_dma_addr_bind_handle\fR(9F) should be used +instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 11n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIas\fR\fR +.ad +.RS 11n +.rt +A pointer to an address space structure. Should be set to \fINULL\fR, which +implies kernel address space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR\fR +.ad +.RS 11n +.rt +Virtual address of the memory object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 11n +.rt +Length of the memory object in bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 11n +.rt +Flags that would go into the \fBddi_dma_req\fR structure (see +\fBddi_dma_req\fR(9S)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwaitfp\fR\fR +.ad +.RS 11n +.rt +The address of a function to call back later if resources aren't available now. +The special function addresses \fBDDI_DMA_SLEEP\fR and \fBDDI_DMA_DONTWAIT\fR +(see \fBddi_dma_req\fR(9S)) are taken to mean, respectively, wait until +resources are available or, do not wait at all and do not schedule a callback. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 11n +.rt +Argument to be passed to a callback function, if such a function is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlim\fR\fR +.ad +.RS 11n +.rt +A pointer to a \fBDMA\fR limits structure for this device (see +\fBddi_dma_lim_sparc\fR(9S) or \fBddi_dma_lim_x86\fR(9S)). If this pointer is +\fINULL\fR, a default set of \fBDMA\fR limits is assumed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandlep\fR\fR +.ad +.RS 11n +.rt +Pointer to a \fBDMA\fR handle. See \fBddi_dma_setup\fR(9F) for a discussion of +handle. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_addr_setup()\fR function is an interface to +\fBddi_dma_setup\fR(9F). It uses its arguments to construct an appropriate +\fBddi_dma_req\fR structure and calls \fBddi_dma_setup\fR(9F) with it. +.SH RETURN VALUES +.sp +.LP +See \fBddi_dma_setup\fR(9F) for the possible return values for this function. +.SH CONTEXT +.sp +.LP +The \fBddi_dma_addr_setup()\fR can be called from user, interrupt, or kernel +context, except when \fIwaitfp\fR is set to \fBDDI_DMA_SLEEP\fR, in which case +it cannot be called from interrupt context. +.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 +\fBattributes\fR(5), \fBddi_dma_buf_setup\fR(9F), \fBddi_dma_free\fR(9F), +\fBddi_dma_htoc\fR(9F), \fBddi_dma_setup\fR(9F), \fBddi_dma_sync\fR(9F), +\fBddi_iopb_alloc\fR(9F), \fBddi_dma_lim_sparc\fR(9S), +\fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_alloc_handle.9f b/usr/src/man/man9f/ddi_dma_alloc_handle.9f new file mode 100644 index 0000000000..7edb35365d --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_alloc_handle.9f @@ -0,0 +1,195 @@ +'\" 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 ddi_dma_alloc_handle 9F "22 Sep 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_alloc_handle \- allocate DMA handle +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_alloc_handle\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_attr_t *\fR\fIattr\fR, + \fBint (*\fR\fIcallback\fR) (caddr_t), \fBcaddr_t\fR \fIarg\fR, \fBddi_dma_handle_t *\fR\fIhandlep\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 12n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIattr\fR\fR +.ad +.RS 12n +.rt +Pointer to a \fBDMA\fR attribute structure for this device (see +\fBddi_dma_attr\fR(9S)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 12n +.rt +The address of a function to call back later if resources aren't available now. +The following special function addresses may also be used. +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_SLEEP\fR\fR +.ad +.RS 20n +.rt +Wait until resources are available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_DONTWAIT\fR\fR +.ad +.RS 20n +.rt +Do not wait until resources are available and do not schedule a callback. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 12n +.rt +Argument to be passed to a callback function, if such a function is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandlep\fR\fR +.ad +.RS 12n +.rt +Pointer to the \fBDMA\fR handle to be initialized. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_dma_alloc_handle()\fR allocates a new \fBDMA\fR handle. A \fBDMA\fR +handle is an opaque object used as a reference to subsequently allocated +\fBDMA\fR resources. \fBddi_dma_alloc_handle()\fR accepts as parameters the +device information referred to by \fIdip\fR and the device's \fBDMA\fR +attributes described by a \fBddi_dma_attr\fR(9S) structure. A successful call +to \fBddi_dma_alloc_handle()\fR fills in the value pointed to by +\fIhandlep\fR. A \fBDMA\fR handle must only be used by the device for which it +was allocated and is only valid for one I/O transaction at a time. +.sp +.LP +The callback function, \fIcallback\fR, indicates how a caller wants to handle +the possibility of resources not being available. If \fIcallback\fR is set to +\fBDDI_DMA_DONTWAIT\fR, then the caller does not care if the allocation fails, +and can handle an allocation failure appropriately. If \fIcallback\fR is set +to \fBDDI_DMA_SLEEP\fR, then the caller wishes to have the allocation routines +wait for resources to become available. If any other value is set, and a +\fBDMA\fR resource allocation fails, this value is assumed to be a function to +call at a later time when resources may become available. When the specified +function is called, it is passed \fIarg\fR as an argument. The specified +callback function must return either \fBDDI_DMA_CALLBACK_RUNOUT\fR or +\fBDDI_DMA_CALLBACK_DONE\fR. \fBDDI_DMA_CALLBACK_RUNOUT\fR indicates that the +callback routine attempted to allocate \fBDMA\fR resources but failed to do so, +in which case the callback function is put back on a list to be called again +later. \fBDDI_DMA_CALLBACK_DONE\fR indicates either success at allocating +\fBDMA\fR resources or the driver no longer wishes to retry. +.sp +.LP +The callback function is called in interrupt context. Therefore, only system +functions that are accessible from interrupt context is available. The +callback function must take whatever steps necessary to protect its critical +resources, data structures, queues, and so forth. +.sp +.LP +When a \fBDMA\fR handle is no longer needed, \fBddi_dma_free_handle\fR(9F) +must be called to free the handle. +.SH RETURN VALUES +.sp +.LP +\fBddi_dma_alloc_handle()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 23n +.rt +Successfully allocated a new \fBDMA\fR handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_BADATTR\fR\fR +.ad +.RS 23n +.rt +The attributes specified in the \fBddi_dma_attr\fR(9S) structure make it +impossible for the system to allocate potential \fBDMA\fR resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_NORESOURCES\fR\fR +.ad +.RS 23n +.rt +No resources are available. +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_dma_alloc_handle()\fR can be called from user, kernel, or interrupt +context, except when \fIcallback\fR is set to \fBDDI_DMA_SLEEP\fR, in which +case it can be called from user or kernel context only. +.SH SEE ALSO +.sp +.LP +\fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), +\fBddi_dma_burstsizes\fR(9F), \fBddi_dma_free_handle\fR(9F), +\fBddi_dma_unbind_handle\fR(9F), \fBddi_dma_attr\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_buf_bind_handle.9f b/usr/src/man/man9f/ddi_dma_buf_bind_handle.9f new file mode 100644 index 0000000000..5241d9c55b --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_buf_bind_handle.9f @@ -0,0 +1,428 @@ +'\" 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 ddi_dma_buf_bind_handle 9F "27 Jul 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_buf_bind_handle \- binds a system buffer to a DMA handle +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_buf_bind_handle\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBstruct buf *\fR\fIbp\fR, + \fBuint_t\fR \fIflags\fR, \fBint (*\fR\fIcallback\fR)(caddr_t), \fBcaddr_t\fR + \fIarg\fR, \fBddi_dma_cookie_t *\fR\fIcookiep\fR, \fBuint_t *\fR\fIccountp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 12n +.rt +The \fBDMA\fR handle previously allocated by a call to +\fBddi_dma_alloc_handle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 12n +.rt +A pointer to a system buffer structure (see \fBbuf\fR(9S)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 12n +.rt +Valid flags include: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_WRITE\fR\fR +.ad +.RS 22n +.rt +Transfer direction is from memory to I/O +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_READ\fR\fR +.ad +.RS 22n +.rt +Transfer direction is from I/O to memory +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_RDWR\fR\fR +.ad +.RS 22n +.rt +Both read and write +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_REDZONE\fR\fR +.ad +.RS 22n +.rt +Establish an \fBMMU\fR redzone at end of the object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_PARTIAL\fR\fR +.ad +.RS 22n +.rt +Partial resource allocation +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_CONSISTENT\fR\fR +.ad +.RS 22n +.rt +Nonsequential, random, and small block transfers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_STREAMING\fR\fR +.ad +.RS 22n +.rt +Sequential, unidirectional, block-sized, and block-aligned transfers. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 12n +.rt +The address of a function to call back later if resources are not available +now. The following special function addresses may also be used. +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_SLEEP\fR\fR +.ad +.RS 20n +.rt +Wait until resources are available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_DONTWAIT\fR\fR +.ad +.RS 20n +.rt +Do not wait until resources are available and do not schedule a callback. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 12n +.rt +Argument to be passed to the callback function, \fIcallback\fR, if such a +function is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookiep\fR\fR +.ad +.RS 12n +.rt +A pointer to the first \fBddi_dma_cookie\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIccountp\fR\fR +.ad +.RS 12n +.rt +Upon a successful return, \fIccountp\fR points to a value representing the +number of cookies for this \fBDMA\fR object. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_dma_buf_bind_handle()\fR allocates \fBDMA\fR resources for a system +buffer such that a device can perform \fBDMA\fR to or from the buffer. +\fBDMA\fR resources are allocated considering the device's \fBDMA\fR attributes +as expressed by \fBddi_dma_attr\fR(9S) (see \fBddi_dma_alloc_handle\fR(9F)). +.sp +.LP +\fBddi_dma_buf_bind_handle()\fR fills in the first \fBDMA\fR cookie pointed to +by \fIcookiep\fR with the appropriate address, length, and bus type. +\fB*\fR\fIccountp\fR is set to the number of \fBDMA\fR cookies representing +this \fBDMA\fR object. Subsequent \fBDMA\fR cookies must be retrieved by +calling \fBddi_dma_nextcookie\fR(9F) \fB*\fR\fIcountp\fR-1 times. +.sp +.LP +When a \fBDMA\fR transfer completes, the driver should free up system \fBDMA\fR +resources by calling \fBddi_dma_unbind_handle\fR(9F). +.sp +.LP +The \fIflags\fR argument contains information for mapping routines. +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_WRITE\fR, \fBDDI_DMA_READ\fR, \fBDDI_DMA_RDWR\fR\fR +.ad +.sp .6 +.RS 4n +These flags describe the intended direction of the \fBDMA\fR transfer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_STREAMING\fR \fR +.ad +.sp .6 +.RS 4n +This flag should be set if the device is doing sequential, unidirectional, +block-sized, and block-aligned transfers to or from memory. The alignment and +padding constraints specified by the \fBminxfer\fR and \fBburstsizes\fR fields +in the \fBDMA\fR attribute structure, \fBddi_dma_attr\fR(9S) (see +\fBddi_dma_alloc_handle\fR(9F)) is used to allocate the most effective hardware +support for large transfers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_CONSISTENT\fR \fR +.ad +.sp .6 +.RS 4n +This flag should be set if the device accesses memory randomly, or if +synchronization steps using \fBddi_dma_sync\fR(9F) need to be as efficient as +possible. I/O parameter blocks used for communication between a device and a +driver should be allocated using \fBDDI_DMA_CONSISTENT\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_REDZONE\fR \fR +.ad +.sp .6 +.RS 4n +If this flag is set, the system attempts to establish a protected red zone +after the object. The \fBDMA\fR resource allocation functions do not guarantee +the success of this request as some implementations may not have the hardware +ability to support a red zone. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_PARTIAL\fR \fR +.ad +.sp .6 +.RS 4n +Setting this flag indicates the caller can accept resources for part of the +object. That is, if the size of the object exceeds the resources available, +only resources for a portion of the object are allocated. The system indicates +this condition returning status \fBDDI_DMA_PARTIAL_MAP\fR. At a later point, +the caller can use \fBddi_dma_getwin\fR(9F) to change the valid portion of the +object for which resources are allocated. If resources were allocated for only +part of the object, \fBddi_dma_addr_bind_handle()\fR returns resources for the +first \fBDMA\fR window. Even when \fBDDI_DMA_PARTIAL\fR is set, the system may +decide to allocate resources for the entire object (less overhead) in which +case \fBDDI_DMA_MAPPED\fR is returned. +.RE + +.sp +.LP +The callback function, \fIcallback\fR, indicates how a caller wants to handle +the possibility of resources not being available. If \fIcallback\fR is set to +\fBDDI_DMA_DONTWAIT\fR, the caller does not care if the allocation fails, and +can handle an allocation failure appropriately. If \fIcallback\fR is set to +\fBDDI_DMA_SLEEP\fR, the caller wishes to have the allocation routines wait for +resources to become available. If any other value is set, and a \fBDMA\fR +resource allocation fails, this value is assumed to be the address of a +function to call at a later time when resources may become available. When the +specified function is called, it is passed \fIarg\fR as an argument. The +specified callback function must return either \fBDDI_DMA_CALLBACK_RUNOUT\fR or +\fBDDI_DMA_CALLBACK_DONE\fR. \fBDDI_DMA_CALLBACK_RUNOUT\fR indicates that the +callback function attempted to allocate \fBDMA\fR resources but failed to do +so. In this case the callback function is put back on a list to be called again +later. \fBDDI_DMA_CALLBACK_DONE\fR indicates either a successful allocation of +\fBDMA\fR resources or that the driver no longer wishes to retry. +.sp +.LP +The callback function is called in interrupt context. Therefore, only system +functions accessible from interrupt context are be available. The callback +function must take whatever steps necessary to protect its critical resources, +data structures, queues, etc. +.SH RETURN VALUES +.sp +.LP +\fBddi_dma_buf_bind_handle()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_MAPPED\fR\fR +.ad +.RS 23n +.rt +Successfully allocated resources for the entire object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_PARTIAL_MAP\fR\fR +.ad +.RS 23n +.rt +Successfully allocated resources for a part of the object. This is acceptable +when partial transfers are permitted by setting the \fBDDI_DMA_PARTIAL\fR flag +in \fIflags\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_INUSE\fR\fR +.ad +.RS 23n +.rt +Another I/O transaction is using the \fBDMA\fR handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_NORESOURCES\fR\fR +.ad +.RS 23n +.rt +No resources are available at the present time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_NOMAPPING\fR\fR +.ad +.RS 23n +.rt +The object cannot be reached by the device requesting the resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_TOOBIG\fR\fR +.ad +.RS 23n +.rt +The object is too big. A request of this size can never be satisfied on this +particular system. The maximum size varies depending on machine and +configuration. +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_dma_buf_bind_handle()\fR can be called from user, kernel, or interrupt +context, except when \fIcallback\fR is set to \fBDDI_DMA_SLEEP\fR, in which +case it can be called from user or kernel context only. +.SH SEE ALSO +.sp +.LP +\fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F), +\fBddi_dma_free_handle\fR(9F), \fBddi_dma_getwin\fR(9F), +\fBddi_dma_nextcookie\fR(9F), \fBddi_dma_sync\fR(9F), +\fBddi_dma_unbind_handle\fR(9F), \fBbuf\fR(9S), \fBddi_dma_attr\fR(9S), +\fBddi_dma_cookie\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +If the driver permits partial mapping with the \fBDDI_DMA_PARTIAL\fR flag, the +number of cookies in each window may exceed the size of the device's +scatter/gather list as specified in the \fBdma_attr_sgllen\fR field in the +\fBddi_dma_attr\fR(9S) structure. In this case, each set of cookies comprising +a \fBDMA\fR window will satisfy the \fBDMA\fR attributes as described in the +\fBddi_dma_attr\fR(9S) structure in all aspects. The driver should set up its +\fBDMA\fR engine and perform one transfer for each set of cookies sufficient +for its scatter/gather list, up to the number of cookies for this window, +before advancing to the next window using \fBddi_dma_getwin\fR(9F). diff --git a/usr/src/man/man9f/ddi_dma_buf_setup.9f b/usr/src/man/man9f/ddi_dma_buf_setup.9f new file mode 100644 index 0000000000..f6b52af7a7 --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_buf_setup.9f @@ -0,0 +1,153 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_buf_setup 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_buf_setup \- easier DMA setup for use with buffer structures +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_buf_setup\fR(\fBdev_info_t *\fR\fIdip\fR, \fBstruct buf *\fR\fIbp\fR, \fBuint_t\fR \fIflags\fR, + \fBint (*\fR\fIwaitfp\fR) (caddr_t),, \fBcaddr_t\fR \fIarg\fR, \fBddi_dma_lim_t *\fR\fIlim\fR, + \fBddi_dma_handle_t *\fR\fIhandlep\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. \fBddi_dma_buf_bind_handle\fR(9F) should be used +instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 11n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 11n +.rt +A pointer to a system buffer structure (see \fBbuf\fR(9S)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 11n +.rt +Flags that go into a \fBddi_dma_req\fR structure (see \fBddi_dma_req\fR(9S)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwaitfp\fR\fR +.ad +.RS 11n +.rt +The address of a function to call back later if resources aren't available now. +The special function addresses \fBDDI_DMA_SLEEP\fR and \fBDDI_DMA_DONTWAIT\fR +(see \fBddi_dma_req\fR(9S)) are taken to mean, respectively, wait until +resources are available, or do not wait at all and do not schedule a callback. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 11n +.rt +Argument to be passed to a callback function, if such a function is specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlim\fR\fR +.ad +.RS 11n +.rt +A pointer to a \fBDMA\fR limits structure for this device (see +\fBddi_dma_lim_sparc\fR(9S) or \fBddi_dma_lim_x86\fR(9S)). If this pointer is +\fINULL\fR, a default set of \fBDMA\fR limits is assumed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandlep\fR\fR +.ad +.RS 11n +.rt +Pointer to a \fBDMA\fR handle. See \fBddi_dma_setup\fR(9F) for a discussion of +handle. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_buf_setup()\fR function is an interface to +\fBddi_dma_setup\fR(9F). It uses its arguments to construct an appropriate +\fBddi_dma_req\fR structure and calls \fBddi_dma_setup()\fR with it. +.SH RETURN VALUES +.sp +.LP +See \fBddi_dma_setup\fR(9F) for the possible return values for this function. +.SH CONTEXT +.sp +.LP +The \fBddi_dma_buf_setup()\fR function can be called from user, interrupt, or +kernel context, except when \fIwaitfp\fR is set to \fBDDI_DMA_SLEEP\fR, in +which case it cannot be called from interrupt context. +.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 +\fBattributes\fR(5), \fBddi_dma_addr_setup\fR(9F), \fBddi_dma_free\fR(9F), +\fBddi_dma_htoc\fR(9F), \fBddi_dma_setup\fR(9F), \fBddi_dma_sync\fR(9F), +\fBphysio\fR(9F), \fBbuf\fR(9S), \fBddi_dma_lim_sparc\fR(9S), +\fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_burstsizes.9f b/usr/src/man/man9f/ddi_dma_burstsizes.9f new file mode 100644 index 0000000000..6c6df2fb2b --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_burstsizes.9f @@ -0,0 +1,63 @@ +'\" te +.\" Copyright (c) 1994, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_burstsizes 9F "1 Feb 1994" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_burstsizes \- find out the allowed burst sizes for a DMA mapping +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_burstsizes\fR(\fBddi_dma_handle_t\fR \fIhandle\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 11n +.rt +A \fBDMA\fR handle that was filled in by a successful call to +\fBddi_dma_setup\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_dma_burstsizes()\fR returns the allowed burst sizes for a \fBDMA\fR +mapping. This value is derived from the \fBdlim_burstsizes\fR member of the +\fBddi_dma_lim_sparc\fR(9S) structure, but it shows the allowable burstsizes +\fBafter\fR imposing on it the limitations of other device layers in addition +to device's own limitations. +.SH RETURN VALUES +.sp +.LP +\fBddi_dma_burstsizes()\fR returns a binary encoded value of the allowable +\fBDMA\fR burst sizes. See \fBddi_dma_lim_sparc\fR(9S) for a discussion of +\fBDMA\fR burst sizes. +.SH CONTEXT +.sp +.LP +This function can be called from user or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBddi_dma_devalign\fR(9F), \fBddi_dma_setup\fR(9F), +\fBddi_dma_lim_sparc\fR(9S), \fBddi_dma_req\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_coff.9f b/usr/src/man/man9f/ddi_dma_coff.9f new file mode 100644 index 0000000000..a3b4b7ca92 --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_coff.9f @@ -0,0 +1,128 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_coff 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_coff \- convert a DMA cookie to an offset within a DMA handle. +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_coff\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBddi_dma_cookie_t *\fR\fIcookiep\fR, + \fBoff_t *\fR\fIoffp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris SPARC DDI (Solaris SPARC DDI). This interface is obsolete. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 11n +.rt +The \fIhandle\fR filled in by a call to \fBddi_dma_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookiep\fR\fR +.ad +.RS 11n +.rt +A pointer to a \fBDMA\fR cookie (see \fBddi_dma_cookie\fR(9S)) that contains +the appropriate address, length and bus type to be used in programming the +\fBDMA\fR engine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffp\fR\fR +.ad +.RS 11n +.rt +A pointer to an offset to be filled in. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_coff()\fR function converts the values in \fBDMA\fR cookie +pointed to by \fIcookiep\fR to an offset (in bytes) from the beginning of the +object that the DMA\fBhandle\fR has mapped. +.sp +.LP +The \fBddi_dma_coff()\fR function allows a driver to update a \fBDMA\fR cookie +with values it reads from its device's \fBDMA\fR engine after a transfer +completes and convert that value into an offset into the object that is mapped +for \fBDMA\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dma_coff()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Successfully filled in \fIoffp\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Failed to successfully fill in \fIoffp\fR. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dma_coff()\fR function can be called from user, interrupt, or kernel +context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_dma_setup\fR(9F), \fBddi_dma_sync\fR(9F), \fBddi_dma_cookie\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_curwin.9f b/usr/src/man/man9f/ddi_dma_curwin.9f new file mode 100644 index 0000000000..a86a6fe7f5 --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_curwin.9f @@ -0,0 +1,124 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_curwin 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_curwin \- report current DMA window offset and size +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_curwin\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBoff_t *\fR\fIoffp\fR, \fBuint_t *\fR\fIlenp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. \fBddi_dma_getwin\fR(9F) should be used instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 10n +.rt +The \fBDMA\fR handle filled in by a call to \fBddi_dma_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffp\fR\fR +.ad +.RS 10n +.rt +A pointer to a value which will be filled in with the current offset from the +beginning of the object that is mapped for \fBDMA\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlenp\fR\fR +.ad +.RS 10n +.rt +A pointer to a value which will be filled in with the size, in bytes, of the +current window onto the object that is mapped for \fBDMA\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_curwin()\fR function reports the current \fBDMA\fR window offset +and size. If a \fBDMA\fR mapping allows partial mapping, that is if the +\fBDDI_DMA_PARTIAL\fR flag in the \fBddi_dma_req\fR(9S) structure is set, its +current (effective) \fBDMA\fR window offset and size can be obtained by a call +to \fBddi_dma_curwin()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dma_curwin()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +The current length and offset can be established. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Otherwise. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dma_curwin()\fR function can be called from user, interrupt, or +kernel context. +.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 +\fBattributes\fR(5), \fBddi_dma_getwin\fR(9F), \fBddi_dma_movwin\fR(9F), +\fBddi_dma_setup\fR(9F), \fBddi_dma_req\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_devalign.9f b/usr/src/man/man9f/ddi_dma_devalign.9f new file mode 100644 index 0000000000..92e2cde16f --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_devalign.9f @@ -0,0 +1,124 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_devalign 9F "04 Apr 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_devalign \- find DMA mapping alignment and minimum transfer size +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_devalign\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBuint_t *\fR\fIalignment\fR, + \fBuint_t *\fR\fIminxfr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). This interface is obsolete. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 13n +.rt +The DMA\fBhandle\fR filled in by a successful call to \fBddi_dma_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIalignment\fR\fR +.ad +.RS 13n +.rt +A pointer to an unsigned integer to be filled in with the minimum required +alignment for \fBDMA\fR. The alignment is guaranteed to be a power of two. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIminxfr\fR\fR +.ad +.RS 13n +.rt +A pointer to an unsigned integer to be filled in with the minimum effective +transfer size (see \fBddi_iomin\fR(9F), \fBddi_dma_lim_sparc\fR(9S) and +\fBddi_dma_lim_x86\fR(9S)). This also is guaranteed to be a power of two. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_devalign()\fR Function determines after a successful \fBDMA\fR +mapping (see \fBddi_dma_setup\fR(9F)) the minimum required data alignment and +minimum \fBDMA\fR transfer size. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dma_devalign()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +The \fIalignment\fR and \fIminxfr\fR values have been filled. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +The handle was illegal. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dma_devalign()\fR function can be called from user, interrupt, or +kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_dma_setup\fR(9F), \fBddi_iomin\fR(9F), \fBddi_dma_lim_sparc\fR(9S), +\fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_free.9f b/usr/src/man/man9f/ddi_dma_free.9f new file mode 100644 index 0000000000..ab021e59be --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_free.9f @@ -0,0 +1,102 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_free 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_free \- release system DMA resources +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_free\fR(\fBddi_dma_handle_t\fR \fIhandle\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. \fBddi_dma_free_handle\fR(9F) should be used +instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 10n +.rt +The handle filled in by a call to \fBddi_dma_setup\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_free()\fR function releases system \fBDMA\fR resources set up by +\fBddi_dma_setup\fR(9F). When a \fBDMA\fR transfer completes, the driver should +free up system \fBDMA\fR resources established by a call to +\fBddi_dma_setup\fR(9F). This is done by a call to \fBddi_dma_free()\fR. +\fBddi_dma_free()\fR does an implicit \fBddi_dma_sync\fR(9F) for you so any +further synchronization steps are not necessary. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dma_free()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Successfully released resources +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Failed to free resources +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dma_free()\fR function can be called from user, interrupt, or kernel +context. +.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 +\fBattributes\fR(5), \fBddi_dma_addr_setup\fR(9F), \fBddi_dma_buf_setup\fR(9F), +\fBddi_dma_free_handle\fR(9F), \fBddi_dma_htoc\fR(9F), \fBddi_dma_sync\fR(9F), +\fBddi_dma_req\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_free_handle.9f b/usr/src/man/man9f/ddi_dma_free_handle.9f new file mode 100644 index 0000000000..6578374851 --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_free_handle.9f @@ -0,0 +1,56 @@ +'\" te +.\" Copyright (c) 1994, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_free_handle 9F "26 Sep 1994" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_free_handle \- free DMA handle +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_dma_free_handle\fR(\fBddi_dma_handle_t *\fR\fIhandle\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 11n +.rt +A pointer to the \fBDMA\fR handle previously allocated by a call to +\fBddi_dma_alloc_handle\fR(9F). +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +\fBddi_dma_free_handle()\fR destroys the \fBDMA \fRhandle pointed to by +\fIhandle\fR. Any further references to the \fBDMA\fR handle will have +undefined results. Note that \fBddi_dma_unbind_handle\fR(9F) must be called +prior to \fBddi_dma_free_handle()\fR to free any resources the system may be +caching on the handle. +.SH CONTEXT +.sp +.LP +\fBddi_dma_free_handle()\fR can be called from user, kernel, or interrupt +context. +.SH SEE ALSO +.sp +.LP +\fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_unbind_handle\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_get_attr.9f b/usr/src/man/man9f/ddi_dma_get_attr.9f new file mode 100644 index 0000000000..4cc9825d3d --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_get_attr.9f @@ -0,0 +1,102 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_get_attr 9F "12 Oct 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_get_attr \- get the device DMA attribute structure from a DMA handle +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_get_attr\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBddi_dma_attr_t *\fR\fIattrp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). This interface is obsolete. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 10n +.rt +The handle filled in by a call to \fBddi_dma_alloc_handle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIattrp\fR\fR +.ad +.RS 10n +.rt +Pointer to a buffer suitable for holding a DMA attribute structure. See +\fBddi_dma_attr\fR(9S). +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_dma_get_attr()\fR is used to get a \fBddi_dma_attr\fR(9S) structure. +This structure describes the attributes of the DMA data path to which any +memory object bound to the given handle will be subject. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 19n +.rt +Successfully passed back attribute structure in buffer pointed to by +\fIattrp\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_BADATTR\fR\fR +.ad +.RS 19n +.rt +A valid attribute structure could not be passed back. +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_dma_get_attr()\fR can be called from any context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_attr\fR(9S) diff --git a/usr/src/man/man9f/ddi_dma_getwin.9f b/usr/src/man/man9f/ddi_dma_getwin.9f new file mode 100644 index 0000000000..749387c31a --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_getwin.9f @@ -0,0 +1,171 @@ +'\" 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 ddi_dma_getwin 9F "15 Nov 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_getwin \- activate a new DMA window +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_getwin\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBuint_t\fR \fIwin\fR, + \fBoff_t *\fR\fIoffp\fR, \fBsize_t *\fR\fIlenp\fR, \fBddi_dma_cookie_t\fR \fI*cookiep\fR, + \fBuint_t *\fR\fIccountp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 12n +.rt +The \fBDMA\fR handle previously allocated by a call to +\fBddi_dma_alloc_handle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwin\fR \fR +.ad +.RS 12n +.rt +Number of the window to activate. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffp\fR \fR +.ad +.RS 12n +.rt +Pointer to an offset. Upon a successful return, \fIoffp\fR will contain the +new offset indicating the beginning of the window within the object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlenp\fR \fR +.ad +.RS 12n +.rt +Upon a successful return, \fIlenp\fR will contain the size, in bytes, of the +current window. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookiep\fR \fR +.ad +.RS 12n +.rt +A pointer to the first \fBddi_dma_cookie\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIccountp\fR \fR +.ad +.RS 12n +.rt +Upon a successful return, \fIccountp\fR will contain the number of cookies for +this \fBDMA\fR window. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_dma_getwin()\fR activates a new \fBDMA\fR window. If a \fBDMA\fR +resource allocation request returns \fBDDI_DMA_PARTIAL_MAP\fR indicating that +resources for less than the entire object were allocated, the current +\fBDMA\fR window can be changed by a call to \fBddi_dma_getwin()\fR. +.sp +.LP +The caller must first determine the number of \fBDMA\fR windows, \fIN\fR, +using \fBddi_dma_numwin\fR(9F). \fBddi_dma_getwin()\fR takes a \fBDMA\fR +window number from the range \fI[0..N-1]\fR as the parameter \fIwin\fR and +makes it the current \fBDMA\fR window. +.sp +.LP +\fBddi_dma_getwin()\fR fills in the first \fBDMA\fR cookie pointed to by +\fIcookiep\fR with the appropriate address, length, and bus type. +\fB*\fR\fIccountp\fR is set to the number of \fBDMA\fR cookies representing +this \fBDMA \fRobject. Subsequent \fBDMA\fR cookies must be retrieved using +\fBddi_dma_nextcookie\fR(9F). +.sp +.LP +\fBddi_dma_getwin()\fR takes care of underlying resource synchronizations +required to shift the window. However accessing the data prior to or after +moving the window requires further synchronization steps using +\fBddi_dma_sync\fR(9F). +.sp +.LP +\fBddi_dma_getwin()\fR is normally called from an interrupt routine. The first +invocation of the \fBDMA\fR engine is done from the driver. All subsequent +invocations of the \fBDMA\fR engine are done from the interrupt routine. The +interrupt routine checks to see if the request has been completed. If it has, +the interrupt routine returns without invoking another \fBDMA\fR transfer. +Otherwise, it calls \fBddi_dma_getwin()\fR to shift the current window and +start another \fBDMA\fR transfer. +.SH RETURN VALUES +.sp +.LP +\fBddi_dma_getwin()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR \fR +.ad +.RS 16n +.rt +Resources for the specified \fBDMA\fR window are allocated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR \fR +.ad +.RS 16n +.rt +\fIwin\fR is not a valid window index. +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_dma_getwin()\fR can be called from user, kernel, or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F), +\fBddi_dma_buf_bind_handle\fR(9F), \fBddi_dma_nextcookie\fR(9F), +\fBddi_dma_numwin\fR(9F), \fBddi_dma_sync\fR(9F), +\fBddi_dma_unbind_handle\fR(9F), \fBddi_dma_cookie\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_htoc.9f b/usr/src/man/man9f/ddi_dma_htoc.9f new file mode 100644 index 0000000000..8fea2aef0d --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_htoc.9f @@ -0,0 +1,125 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_htoc 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_htoc \- convert a DMA handle to a DMA address cookie +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_htoc\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBoff_t\fR \fIoff\fR, + \fBddi_dma_cookie_t *\fR\fIcookiep\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. \fBddi_dma_addr_bind_handle\fR(9F) or +\fBddi_dma_buf_bind_handle\fR(9F) should be used instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 11n +.rt +The handle filled in by a call to \fBddi_dma_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoff\fR\fR +.ad +.RS 11n +.rt +An offset into the object that \fIhandle\fR maps. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookiep\fR\fR +.ad +.RS 11n +.rt +A pointer to a \fBddi_dma_cookie\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_htoc()\fR function takes a \fBDMA\fR handle (established by +\fBddi_dma_setup\fR(9F)), and fills in the cookie pointed to by \fIcookiep\fR +with the appropriate address, length, and bus type to be used to program the +\fBDMA\fR engine. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dma_htoc()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Successfully filled in the cookie pointed to by \fIcookiep\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Failed to successfully fill in the cookie. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dma_htoc()\fR function can be called from user, interrupt, or kernel +context. +.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 +\fBattributes\fR(5), \fBddi_dma_addr_bind_handle\fR(9F), +\fBddi_dma_addr_setup\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), +\fBddi_dma_buf_setup\fR(9F), \fBddi_dma_setup\fR(9F), \fBddi_dma_sync\fR(9F), +\fBddi_dma_cookie\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_mem_alloc.9f b/usr/src/man/man9f/ddi_dma_mem_alloc.9f new file mode 100644 index 0000000000..68365063b2 --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_mem_alloc.9f @@ -0,0 +1,315 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_mem_alloc 9F "05 Jun 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_mem_alloc \- allocate memory for DMA transfer +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_mem_alloc\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBsize_t\fR \fIlength\fR, + \fBddi_device_acc_attr_t *\fR\fIaccattrp\fR, \fBuint_t\fR \fIflags\fR, + \fBint (*\fR\fIwaitfp\fR) (caddr_t), \fBcaddr_t\fR \fIarg\fR, \fBcaddr_t *\fR\fIkaddrp\fR, + \fBsize_t *\fR\fIreal_length\fR, \fBddi_acc_handle_t *\fR\fIhandlep\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 15n +.rt +The \fBDMA\fR handle previously allocated by a call to +\fBddi_dma_alloc_handle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlength\fR\fR +.ad +.RS 15n +.rt +The length in bytes of the desired allocation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaccattrp\fR\fR +.ad +.RS 15n +.rt +Pointer to a \fBddi_device_acc_attr()\fR structure of the device. See +\fBddi_device_acc_attr\fR(9S). The value in \fBdevacc_attr_dataorder\fR is +ignored in the current release. The value in \fBdevacc_attr_endian_flags\fR is +meaningful on the SPARC architecture only. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 15n +.rt +Used to determine the data transfer mode and/or the cache attribute. +.sp +Possible values of the data transfer are: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_STREAMING\fR\fR +.ad +.RS 22n +.rt +Sequential, unidirectional, block-sized, and block-aligned transfers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_CONSISTENT\fR\fR +.ad +.RS 22n +.rt +Nonsequential transfers of small objects. +.RE + +Possible values of the cache attribute are: +.sp +.ne 2 +.mk +.na +\fB\fBIOMEM_DATA_CACHED\fR\fR +.ad +.RS 28n +.rt +The CPU can cache the data it fetches and push it to memory at a later time. +This is the default attribute that is used if no cache attributes are +specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBIOMEM_DATA_UC_WR_COMBINE\fR\fR +.ad +.RS 28n +.rt +The CPU never caches the data, but writes can occur out of order or can be +combined. Reordering is implied. +.sp +If \fBIOMEM_DATA_UC_WR_COMBINE\fR is specified but not supported, +\fBIOMEM_DATA_UNCACHED\fR is used instead. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBIOMEM_DATA_UNCACHED\fR\fR +.ad +.RS 28n +.rt +The CPU never caches data, but has uncacheable access to memory. Strict +ordering is implied. +.RE + +The cache attributes are mutually exclusive. Any combination of the values +leads to a failure. On the SPARC architecture, only \fBIOMEM_DATA_CACHED\fR is +meaningful. Others lead to a failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwaitfp\fR\fR +.ad +.RS 15n +.rt +The address of a function to call back later if resources are not available +now. The callback function indicates how a caller wants to handle the +possibility of resources not being available. If callback is set to +\fBDDI_DMA_DONTWAIT\fR, the caller does not care if the allocation fails, and +can handle an allocation failure appropriately. If callback is set to +\fBDDI_DMA_SLEEP\fR, the caller wishes to have the allocation routines wait for +resources to become available. If any other value is set and a DMA resource +allocation fails, this value is assumed to be the address of a function to be +called when resources become available. When the specified function is called, +\fIarg\fR is passed to it as an argument. The specified callback function must +return either \fBDDI_DMA_CALLBACK_RUNOUT\fR or \fBDDI_DMA_CALLBACK_DONE\fR. +\fBDDI_DMA_CALLBACK_RUNOUT\fR indicates that the callback function attempted to +allocate DMA resources but failed. In this case, the callback function is put +back on a list to be called again later. \fBDDI_DMA_CALLBACK_DONE\fR indicates +that either the allocation of DMA resources was successful or the driver no +longer wishes to retry. The callback function is called in interrupt context. +Therefore, only system functions accessible from interrupt context are +available. +.sp +The callback function must take whatever steps are necessary to protect its +critical resources, data structures, queues, and so on. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 15n +.rt +Argument to be passed to the callback function, if such a function is +specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIkaddrp\fR\fR +.ad +.RS 15n +.rt +On successful return, \fIkaddrp\fR points to the allocated memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreal_length\fR\fR +.ad +.RS 15n +.rt +The amount of memory, in bytes, allocated. Alignment and padding requirements +may require \fBddi_dma_mem_alloc()\fR to allocate more memory than requested in +\fIlength\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandlep\fR\fR +.ad +.RS 15n +.rt +Pointer to a data access handle. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_mem_alloc()\fR function allocates memory for \fBDMA\fR transfers +to or from a device. The allocation will obey the alignment, padding +constraints and device granularity as specified by the \fBDMA\fR attributes +(see \fBddi_dma_attr\fR(9S)) passed to \fBddi_dma_alloc_handle\fR(9F) and the +more restrictive attributes imposed by the system. +.sp +.LP +The \fIflags\fR parameter should be set to \fBDDI_DMA_STREAMING\fR if the +device is doing sequential, unidirectional, block-sized, and block-aligned +transfers to or from memory. The alignment and padding constraints specified by +the \fBminxfer\fR and \fBburstsizes\fR fields in the \fBDMA\fR attribute +structure, \fBddi_dma_attr\fR(9S) (see \fBddi_dma_alloc_handle\fR(9F)) will be +used to allocate the most effective hardware support for large transfers. For +example, if an I/O transfer can be sped up by using an I/O cache, which has a +minimum transfer of one cache line, \fBddi_dma_mem_alloc()\fR will align the +memory at a cache line boundary and it will round up \fIreal_length\fR to a +multiple of the cache line size. +.sp +.LP +The \fIflags\fR parameter should be set to \fBDDI_DMA_CONSISTENT\fR if the +device accesses memory randomly, or if synchronization steps using +\fBddi_dma_sync\fR(9F) need to be as efficient as possible. I/O parameter +blocks used for communication between a device and a driver should be allocated +using \fBDDI_DMA_CONSISTENT\fR. +.sp +.LP +The device access attributes are specified in the location pointed by the +\fIaccattrp\fR argument (see \fBddi_device_acc_attr\fR(9S)). +.sp +.LP +The data access handle is returned in \fIhandlep\fR. \fIhandlep\fR is opaque - +drivers may not attempt to interpret its value. To access the data content, the +driver must invoke \fBddi_get8\fR(9F) or \fBddi_put8\fR(9F) (depending on the +data transfer direction) with the data access handle. +.sp +.LP +\fBDMA\fR resources must be established before performing a \fBDMA\fR transfer +by passing \fIkaddrp\fR and \fIreal_length\fR as returned from +\fBddi_dma_mem_alloc()\fR and the flag \fBDDI_DMA_STREAMING\fR or +\fBDDI_DMA_CONSISTENT\fR to \fBddi_dma_addr_bind_handle\fR(9F). In addition, to +ensure the consistency of a memory object shared between the \fBCPU\fR and the +device after a \fBDMA\fR transfer, explicit synchronization steps using +\fBddi_dma_sync\fR(9F) or \fBddi_dma_unbind_handle\fR(9F) are required. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dma_mem_alloc()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Memory successfully allocated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Memory allocation failed. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dma_mem_alloc()\fR function can be called from user, interrupt, or +kernel context except when \fIwaitfp\fR is set to \fBDDI_DMA_SLEEP\fR, in which +case it cannot be called from interrupt context. +.SH SEE ALSO +.sp +.LP +\fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F), +\fBddi_dma_mem_free\fR(9F), \fBddi_dma_sync\fR(9F), +\fBddi_dma_unbind_handle\fR(9F), \fBddi_get8\fR(9F), \fBddi_put8\fR(9F), +\fBddi_device_acc_attr\fR(9S), \fBddi_dma_attr\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +If \fBDDI_NEVERSWAP_ACC\fR is specified, memory can be used for any purpose; +but if either endian mode is specified, you must use \fBddi_get/put*\fR and +never anything else. diff --git a/usr/src/man/man9f/ddi_dma_mem_free.9f b/usr/src/man/man9f/ddi_dma_mem_free.9f new file mode 100644 index 0000000000..8150a97200 --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_mem_free.9f @@ -0,0 +1,53 @@ +'\" te +.\" Copyright (c) 1994, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_mem_free 9F "26 Sep 1994" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_mem_free \- free previously allocated memory +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_dma_mem_free\fR(\fBddi_acc_handle_t *\fR\fIhandlep\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandlep\fR \fR +.ad +.RS 12n +.rt +Pointer to the data access handle previously allocated by a call to +\fBddi_dma_mem_alloc\fR(9F). +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +\fBddi_dma_mem_free()\fR deallocates the memory acquired by +\fBddi_dma_mem_alloc\fR(9F). In addition, it destroys the data access handle +\fIhandlep\fR associated with the memory. +.SH CONTEXT +.sp +.LP +\fBddi_dma_mem_free()\fR can be called from user, kernel, or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBddi_dma_mem_alloc\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_movwin.9f b/usr/src/man/man9f/ddi_dma_movwin.9f new file mode 100644 index 0000000000..84afd4cea2 --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_movwin.9f @@ -0,0 +1,168 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_movwin 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_movwin \- shift current DMA window +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_movwin\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBoff_t *\fR\fIoffp\fR, + \fBuint_t *\fR\fIlenp\fR, \fBddi_dma_cookie_t *\fR\fIcookiep\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. \fBddi_dma_getwin\fR(9F) should be used instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 11n +.rt +The \fBDMA\fR handle filled in by a call to \fBddi_dma_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffp\fR\fR +.ad +.RS 11n +.rt +A pointer to an offset to set the \fBDMA\fR window to. Upon a successful +return, it will be filled in with the new offset from the beginning of the +object resources are allocated for. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlenp\fR\fR +.ad +.RS 11n +.rt +A pointer to a value which must either be the current size of the \fBDMA\fR +window (as known from a call to \fBddi_dma_curwin\fR(9F) or from a previous +call to \fBddi_dma_movwin()\fR). Upon a successful return, it will be filled in +with the size, in bytes, of the current window. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookiep\fR\fR +.ad +.RS 11n +.rt +A pointer to a \fBDMA\fR cookie (see \fBddi_dma_cookie\fR(9S)). Upon a +successful return, cookiep is filled in just as if an implicit +\fBddi_dma_htoc\fR(9F) had been made. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_movwin()\fR function shifts the current \fBDMA\fR window. If a +\fBDMA\fR request allows the system to allocate resources for less than the +entire object by setting the \fBDDI_DMA_PARTIAL\fR flag in the +\fBddi_dma_req\fR(9S) structure, the current \fBDMA\fR window can be shifted by +a call to \fBddi_dma_movwin()\fR. +.sp +.LP +The caller must first determine the current \fBDMA\fR window size by a call to +\fBddi_dma_curwin\fR(9F). Using the current offset and size of the window thus +retrieved, the caller of \fBddi_dma_movwin()\fR may change the window onto the +object by changing the offset by a value which is some multiple of the size of +the \fBDMA\fR window. +.sp +.LP +The \fBddi_dma_movwin()\fR function takes care of underlying resource +synchronizations required to \fBshift\fR the window. However, if you want to +\fBaccess\fR the data prior to or after moving the window, further +synchronizations using \fBddi_dma_sync\fR(9F) are required. +.sp +.LP +This function is normally called from an interrupt routine. The first +invocation of the \fBDMA\fR engine is done from the driver. All subsequent +invocations of the \fBDMA\fR engine are done from the interrupt routine. The +interrupt routine checks to see if the request has been completed. If it has, +it returns without invoking another \fBDMA\fR transfer. Otherwise it calls +\fBddi_dma_movwin()\fR to shift the current window and starts another \fBDMA\fR +transfer. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dma_movwin()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +The current length and offset are legal and have been set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Otherwise. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dma_movwin()\fR function can be called from user, interrupt, or +kernel context. +.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 +\fBattributes\fR(5), \fBddi_dma_curwin\fR(9F), \fBddi_dma_getwin\fR(9F), +\fBddi_dma_htoc\fR(9F), \fBddi_dma_setup\fR(9F), \fBddi_dma_sync\fR(9F), +\fBddi_dma_cookie\fR(9S), \fBddi_dma_req\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +The caller must guarantee that the resources used by the object are inactive +prior to calling this function. diff --git a/usr/src/man/man9f/ddi_dma_nextcookie.9f b/usr/src/man/man9f/ddi_dma_nextcookie.9f new file mode 100644 index 0000000000..4f3bb2a6fd --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_nextcookie.9f @@ -0,0 +1,108 @@ +'\" te +.\" Copyright (c) 1994, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_nextcookie 9F "26 Sep 1994" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_nextcookie \- retrieve subsequent DMA cookie +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_dma_nextcookie\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, + \fBddi_dma_cookie_t *\fR\fIcookiep\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 11n +.rt +The handle previously allocated by a call to \fBddi_dma_alloc_handle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookiep\fR\fR +.ad +.RS 11n +.rt +A pointer to a \fBddi_dma_cookie\fR(9S) structure. +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +\fBddi_dma_nextcookie()\fR retrieves subsequent \fBDMA\fR cookies for a +\fBDMA\fR object. \fBddi_dma_nextcookie()\fR fills in the +\fBddi_dma_cookie\fR(9S) structure pointed to by \fIcookiep\fR. The +\fBddi_dma_cookie\fR(9S) structure must be allocated prior to calling +\fBddi_dma_nextcookie()\fR. +.sp +.LP +The \fBDMA\fR cookie count returned by \fBddi_dma_buf_bind_handle\fR(9F), +\fBddi_dma_addr_bind_handle\fR(9F), or \fBddi_dma_getwin\fR(9F) indicates the +number of \fBDMA\fR cookies a \fBDMA\fR object consists of. If the resulting +cookie count, \fIN\fR, is larger than 1, \fBddi_dma_nextcookie()\fR must be +called \fIN\fR-1 times to retrieve all \fBDMA\fR cookies. +.SH CONTEXT +.sp +.LP +\fBddi_dma_nextcookie()\fR can be called from user, kernel, or interrupt +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRProcess a scatter-gather list of I/O requests. +.sp +.LP +This example demonstrates the use of \fBddi_dma_nextcookie()\fR to process a +scatter-gather list of I/O requests. + +.sp +.in +2 +.nf +/* setup scatter-gather list with multiple DMA cookies */ +ddi_dma_cookie_t dmacookie; +uint_t ccount; +\&... + +status = ddi_dma_buf_bind_handle(handle, bp, DDI_DMA_READ, + NULL, NULL, &dmacookie, &ccount); + +if (status == DDI_DMA_MAPPED) { + + /* program DMA engine with first cookie */ + + while (--ccount > 0) { + ddi_dma_nextcookie(handle, &dmacookie); + /* program DMA engine with next cookie */ + } +} +\&... +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F), +\fBddi_dma_buf_bind_handle\fR(9F), \fBddi_dma_unbind_handle\fR(9F), +\fBddi_dma_cookie\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_nextseg.9f b/usr/src/man/man9f/ddi_dma_nextseg.9f new file mode 100644 index 0000000000..32bf77b56e --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_nextseg.9f @@ -0,0 +1,157 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_nextseg 9F "04 Apr 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_nextseg \- get next DMA segment +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_nextseg\fR(\fBddi_dma_win_t\fR \fIwin\fR, \fBddi_dma_seg_t\fR \fIseg\fR, + \fBddi_dma_seg_t *\fR\fInseg\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. \fBddi_dma_nextcookie\fR(9F) should be used +instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIwin\fR\fR +.ad +.RS 8n +.rt +A \fBDMA\fR window. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIseg\fR\fR +.ad +.RS 8n +.rt +The current \fBDMA\fR segment or \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInseg\fR\fR +.ad +.RS 8n +.rt +A pointer to the next \fBDMA\fR segment to be filled in. If \fIseg\fR is +\fINULL\fR, a pointer to the first segment within the specified window is +returned. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_nextseg()\fR function gets the next \fBDMA\fR segment within the +specified window \fIwin\fR. If the current segment is \fINULL\fR, the first +\fBDMA\fR segment within the window is returned. +.sp +.LP +A \fBDMA\fR segment is always required for a \fBDMA\fR window. A \fBDMA\fR +segment is a contiguous portion of a \fBDMA\fR window (see +\fBddi_dma_nextwin\fR(9F)) which is entirely addressable by the device for a +data transfer operation. +.sp +.LP +An example where multiple \fBDMA\fR segments are allocated is where the system +does not contain \fBDVMA\fR capabilities and the object may be non-contiguous. +In this example the object will be broken into smaller contiguous \fBDMA\fR +segments. Another example is where the device has an upper limit on its +transfer size (for example an 8-bit address register) and has expressed this in +the \fBDMA\fR limit structure (see \fBddi_dma_lim_sparc\fR(9S) or +\fBddi_dma_lim_x86\fR(9S)). In this example the object will be broken into +smaller addressable \fBDMA\fR segments. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dma_nextseg()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 17n +.rt +Successfully filled in the next segment pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_DONE\fR\fR +.ad +.RS 17n +.rt +There is no next segment. The current segment is the final segment within the +specified window. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_STALE\fR\fR +.ad +.RS 17n +.rt +\fIwin\fR does not refer to the currently active window. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dma_nextseg()\fR function can be called from user, interrupt, or +kernel context. +.SH EXAMPLES +.sp +.LP +For an example, see \fBddi_dma_segtocookie\fR(9F). +.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 +_ +Stability LevelObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_dma_addr_setup\fR(9F), \fBddi_dma_buf_setup\fR(9F), +\fBddi_dma_nextcookie\fR(9F), \fBddi_dma_nextwin\fR(9F), +\fBddi_dma_segtocookie\fR(9F), \fBddi_dma_sync\fR(9F), +\fBddi_dma_lim_sparc\fR(9S), \fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_nextwin.9f b/usr/src/man/man9f/ddi_dma_nextwin.9f new file mode 100644 index 0000000000..a177186321 --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_nextwin.9f @@ -0,0 +1,168 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_nextwin 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_nextwin \- get next DMA window +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_nextwin\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBddi_dma_win_t\fR \fIwin\fR, + \fBddi_dma_win_t *\fR\fInwin\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. \fBddi_dma_getwin\fR(9F) should be used instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 10n +.rt +A \fBDMA\fR handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwin\fR\fR +.ad +.RS 10n +.rt +The current \fBDMA\fR window or \fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInwin\fR\fR +.ad +.RS 10n +.rt +A pointer to the next \fBDMA\fR window to be filled in. If \fIwin\fR is +\fINULL\fR, a pointer to the first window within the object is returned. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_nextwin()\fR function shifts the current \fBDMA\fR window +\fIwin\fR within the object referred to by \fIhandle\fR to the next \fBDMA\fR +window \fInwin\fR. If the current window is \fINULL\fR, the first window within +the object is returned. A \fBDMA\fR window is a portion of a \fBDMA\fR object +or might be the entire object. A \fBDMA\fR window has system resources +allocated to it and is prepared to accept data transfers. Examples of system +resources are \fBDVMA\fR mapping resources and intermediate transfer buffer +resources. +.sp +.LP +All \fBDMA\fR objects require a window. If the \fBDMA\fR window represents the +whole \fBDMA\fR object it has system resources allocated for the entire data +transfer. However, if the system is unable to setup the entire \fBDMA\fR object +due to system resource limitations, the driver writer may allow the system to +allocate system resources for less than the entire \fBDMA\fR object. This can +be accomplished by specifying the \fBDDI_DMA_PARTIAL\fR flag as a parameter to +\fBddi_dma_buf_setup\fR(9F) or \fBddi_dma_addr_setup\fR(9F) or as part of a +\fBddi_dma_req\fR(9S) structure in a call to \fBddi_dma_setup\fR(9F). +.sp +.LP +Only the window that has resources allocated is valid per object at any one +time. The currently valid window is the one that was most recently returned +from \fBddi_dma_nextwin()\fR. Furthermore, because a call to +\fBddi_dma_nextwin()\fR will reallocate system resources to the new window, the +previous window will become invalid. It is a \fBsevere\fR error to call +\fBddi_dma_nextwin()\fR before any transfers into the current window are +complete. +.sp +.LP +The \fBddi_dma_nextwin()\fR function takes care of underlying memory +synchronizations required to shift the window. However, if you want to access +the data before or after moving the window, further synchronizations using +\fBddi_dma_sync\fR(9F) are required. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dma_nextwin()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 17n +.rt +Successfully filled in the next window pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_DONE\fR\fR +.ad +.RS 17n +.rt +There is no next window. The current window is the final window within the +specified object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_STALE\fR\fR +.ad +.RS 17n +.rt +\fIwin\fR does not refer to the currently active window. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dma_nextwin()\fR function can be called from user, interrupt, or +kernel context. +.SH EXAMPLES +.sp +.LP +For an example see \fBddi_dma_segtocookie\fR(9F). +.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 +\fBattributes\fR(5), \fBddi_dma_addr_setup\fR(9F), \fBddi_dma_buf_setup\fR(9F), +\fBddi_dma_getwin\fR(9F), \fBddi_dma_nextseg\fR(9F), +\fBddi_dma_segtocookie\fR(9F), \fBddi_dma_sync\fR(9F), \fBddi_dma_req\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_numwin.9f b/usr/src/man/man9f/ddi_dma_numwin.9f new file mode 100644 index 0000000000..c536b54f9f --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_numwin.9f @@ -0,0 +1,91 @@ +'\" te +.\" Copyright (c) 1994, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_numwin 9F "29 Sep 1994" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_numwin \- retrieve number of DMA windows +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_numwin\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBuint_t *\fR\fInwinp\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 11n +.rt +The \fBDMA\fR handle previously allocated by a call to +\fBddi_dma_alloc_handle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInwinp\fR \fR +.ad +.RS 11n +.rt +Upon a successful return, \fInwinp\fR will contain the number of \fBDMA\fR +windows for this object. +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +\fBddi_dma_numwin()\fR returns the number of \fBDMA\fR windows for a +\fBDMA\fR object if partial resource allocation was permitted. +.SH RETURN VALUES +.sp +.LP +\fBddi_dma_numwin()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR \fR +.ad +.RS 16n +.rt +Successfully filled in the number of \fBDMA\fR windows. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR \fR +.ad +.RS 16n +.rt +\fBDMA\fR windows are not activated. +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_dma_numwin()\fR can be called from user, kernel, or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F), +\fBddi_dma_buf_bind_handle\fR(9F), \fBddi_dma_unbind_handle\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_segtocookie.9f b/usr/src/man/man9f/ddi_dma_segtocookie.9f new file mode 100644 index 0000000000..6d58bfda23 --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_segtocookie.9f @@ -0,0 +1,162 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_segtocookie 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_segtocookie \- convert a DMA segment to a DMA address cookie +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_segtocookie\fR(\fBddi_dma_seg_t\fR \fIseg\fR, \fBoff_t *\fR\fIoffp\fR, \fBoff_t *\fR\fIlenp\fR, + \fBddi_dma_cookie_t *\fR\fIcookiep\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. \fBddi_dma_nextcookie\fR(9F) should be used +instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIseg\fR\fR +.ad +.RS 11n +.rt +A \fBDMA\fR segment. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffp\fR\fR +.ad +.RS 11n +.rt +A pointer to an \fBoff_t\fR. Upon a successful return, it is filled in with the +offset. This segment is addressing within the object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlenp\fR\fR +.ad +.RS 11n +.rt +The byte length. This segment is addressing within the object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookiep\fR\fR +.ad +.RS 11n +.rt +A pointer to a \fBDMA\fR cookie (see \fBddi_dma_cookie\fR(9S)). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_segtocookie()\fR function takes a \fBDMA\fR segment and fills in +the cookie pointed to by \fIcookiep\fR with the appropriate address, length, +and bus type to be used to program the \fBDMA\fR engine. +\fBddi_dma_segtocookie()\fR also fills in \fI*offp\fR and \fI*lenp\fR, which +specify the range within the object. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dma_segtocookie()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Successfully filled in all values. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Failed to successfully fill in all values. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dma_segtocookie()\fR function can be called from user, interrupt, or +kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBddi_dma_segtocookie()\fR example +.sp +.in +2 +.nf +for (win = NULL; (retw = ddi_dma_nextwin(handle, win, &nwin)) != + DDI_DMA_DONE; win = nwin) { + if (retw != DDI_SUCCESS) { + /* do error handling */ + } else { + for (seg = NULL; (rets = ddi_dma_nextseg(nwin, seg, &nseg)) != + DDI_DMA_DONE; seg = nseg) { + if (rets != DDI_SUCCESS) { + + /* do error handling */ + } else { + ddi_dma_segtocookie(nseg, &off, &len, &cookie); + + /* program DMA engine */ + } + } + } +} +.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 +\fBattributes\fR(5), \fBddi_dma_nextcookie\fR(9F). \fBddi_dma_nextseg\fR(9F), +\fBddi_dma_nextwin\fR(9F), \fBddi_dma_sync\fR(9F), \fBddi_dma_cookie\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_set_sbus64.9f b/usr/src/man/man9f/ddi_dma_set_sbus64.9f new file mode 100644 index 0000000000..e9e0b1d93c --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_set_sbus64.9f @@ -0,0 +1,129 @@ +'\" te +.\" Copyright (c) 1997, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_set_sbus64 9F "1 Jan 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_set_sbus64 \- allow 64-bit transfers on SBus +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_set_sbus64\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBuint_t\fR \fIburstsizes\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 15n +.rt +The handle filled in by a call to \fBddi_dma_alloc_handle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIburstsizes\fR \fR +.ad +.RS 15n +.rt +The possible burst sizes the device's \fBDMA\fR engine can accept in 64-bit +mode. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_dma_set_sbus64()\fR informs the system that the device wishes to perform +64-bit data transfers on the SBus. The driver must first allocate a \fBDMA\fR +handle using \fBddi_dma_alloc_handle\fR(9F) with a \fBddi_dma_attr\fR(9S) +structure describing the \fBDMA\fR attributes for a 32-bit transfer mode. +.sp +.LP +\fIburstsizes\fR describes the possible burst sizes the device's \fBDMA\fR +engine can accept in 64-bit mode. It may be distinct from the burst sizes for +32-bit mode set in the \fBddi_dma_attr\fR(9S) structure. The system will +activate 64-bit SBus transfers if the SBus supports them. Otherwise, the SBus +will operate in 32-bit mode. +.sp +.LP +After \fBDMA\fR resources have been allocated (see +\fBddi_dma_addr_bind_handle\fR(9F) or \fBddi_dma_buf_bind_handle\fR(9F)), the +driver should retrieve the available burst sizes by calling +\fBddi_dma_burstsizes\fR(9F). This function will return the burst sizes in +64-bit mode if the system was able to activate 64-bit transfers. Otherwise +burst sizes will be returned in 32-bit mode. +.SH RETURN VALUES +.sp +.LP +\fBddi_dma_set_sbus64()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR \fR +.ad +.RS 16n +.rt +Successfully set the SBus to 64-bit mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR \fR +.ad +.RS 16n +.rt +64-bit mode could not be set. +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_dma_set_sbus64()\fR can be called from user, kernel, or interrupt +context. +.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) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +ArchitectureSBus +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_dma_addr_bind_handle\fR(9F), +\fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), +\fBddi_dma_burstsizes\fR(9F), \fBddi_dma_attr\fR(9S) +.SH NOTES +.sp +.LP +64-bit SBus mode is activated on a per SBus slot basis. If there are multiple +SBus cards in one slot, they all must operate in 64-bit mode or they all must +operate in 32-bit mode. diff --git a/usr/src/man/man9f/ddi_dma_setup.9f b/usr/src/man/man9f/ddi_dma_setup.9f new file mode 100644 index 0000000000..42da49001d --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_setup.9f @@ -0,0 +1,199 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_setup 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_setup \- setup DMA resources +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_setup\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_req_t *\fR\fIdmareqp\fR, + \fBddi_dma_handle_t *\fR\fIhandlep\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. The functions \fBddi_dma_addr_bind_handle\fR(9F), +\fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), +\fBddi_dma_free_handle\fR(9F), and \fBddi_dma_unbind_handle\fR(9F) should be +used instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 11n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdmareqp\fR\fR +.ad +.RS 11n +.rt +A pointer to a \fBDMA\fR request structure (see \fBddi_dma_req\fR(9S)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandlep\fR\fR +.ad +.RS 11n +.rt +A pointer to a \fBDMA\fR handle to be filled in. See below for a discussion of +a handle. If \fIhandlep\fR is \fINULL\fR, the call to \fBddi_dma_setup()\fR is +considered an advisory call, in which case no resources are allocated, but a +value indicating the legality and the feasibility of the request is returned. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_setup()\fR function allocates resources for a memory object such +that a device can perform \fBDMA\fR to or from that object. +.sp +.LP +A call to \fBddi_dma_setup()\fR informs the system that device referred to by +\fIdip\fR wishes to perform \fBDMA\fR to or from a memory object. The memory +object, the device's \fBDMA\fR capabilities, the device driver's policy on +whether to wait for resources, are all specified in the \fBddi_dma_req\fR +structure pointed to by \fIdmareqp\fR. +.sp +.LP +A successful call to \fBddi_dma_setup()\fR fills in the value pointed to by +\fIhandlep\fR. This is an opaque object called a \fBDMA\fR handle. This handle +is then used in subsequent \fBDMA\fR calls, until \fBddi_dma_free\fR(9F) is +called. +.sp +.LP +Again a \fBDMA\fR handle is opaque\(emdrivers may \fBnot\fR attempt to +interpret its value. When a driver wants to enable its \fBDMA\fR engine, it +must retrieve the appropriate address to supply to its \fBDMA\fR engine using a +call to \fBddi_dma_htoc\fR(9F), which takes a pointer to a \fBDMA\fR handle +and returns the appropriate \fBDMA\fR address. +.sp +.LP +When \fBDMA\fR transfer completes, the driver should free up the allocated +\fBDMA\fR resources by calling \fBddi_dma_free()\fR +.SH RETURN VALUES +.sp +.LP +The \fBddi_dma_setup()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_MAPPED\fR\fR +.ad +.RS 23n +.rt +Successfully allocated resources for the object. In the case of an +\fBadvisory\fR call, this indicates that the request is legal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_PARTIAL_MAP\fR\fR +.ad +.RS 23n +.rt +Successfully allocated resources for a \fBpart\fR of the object. This is +acceptable when partial transfers are allowed using a flag setting in the +\fBddi_dma_req\fR structure (see \fBddi_dma_req\fR(9S) and +\fBddi_dma_movwin\fR(9F)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_NORESOURCES\fR\fR +.ad +.RS 23n +.rt +When no resources are available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_NOMAPPING\fR\fR +.ad +.RS 23n +.rt +The object cannot be reached by the device requesting the resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_TOOBIG\fR\fR +.ad +.RS 23n +.rt +The object is too big and exceeds the available resources. The maximum size +varies depending on machine and configuration. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dma_setup()\fR function can be called from user, interrupt, or +kernel context, except when the \fBdmar_fp\fR member of the \fBddi_dma_req\fR +structure pointed to by \fIdmareqp\fR is set to \fBDDI_DMA_SLEEP\fR, in which +case it cannot be called from interrupt context. +.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 +\fBattributes\fR(5), \fBddi_dma_addr_bind_handle\fR(9F), +\fBddi_dma_alloc_handle\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), +\fBddi_dma_free_handle\fR(9F), +\fBddi_dma_unbind_handle\fR(9F)\fBddi_dma_addr_setup\fR(9F), +\fBddi_dma_buf_setup\fR(9F), \fBddi_dma_free\fR(9F), \fBddi_dma_htoc\fR(9F), +\fBddi_dma_movwin\fR(9F), \fBddi_dma_sync\fR(9F), \fBddi_dma_req\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The construction of the \fBddi_dma_req\fR structure is complicated. Use of the +provided interface functions such as \fBddi_dma_buf_setup\fR(9F) simplifies +this task. diff --git a/usr/src/man/man9f/ddi_dma_sync.9f b/usr/src/man/man9f/ddi_dma_sync.9f new file mode 100644 index 0000000000..cb1b7c0354 --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_sync.9f @@ -0,0 +1,157 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_sync 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_sync \- synchronize CPU and I/O views of memory +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_dma_sync\fR(\fBddi_dma_handle_t\fR \fIhandle\fR, \fBoff_t\fR \fIoffset\fR, + \fBsize_t\fR \fIlength\fR, \fBuint_t\fR \fItype\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 10n +.rt +The \fIhandle\fR filled in by a call to \fBddi_dma_alloc_handle\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR\fR +.ad +.RS 10n +.rt +The offset into the object described by the \fIhandle\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlength\fR\fR +.ad +.RS 10n +.rt +The length, in bytes, of the area to synchronize. When \fIlength\fR is zero, +the entire range starting from \fIoffset\fR to the end of the object has the +requested operation applied to it. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 10n +.rt +Indicates the caller's desire about what view of the memory object to +synchronize. The possible values are \fBDDI_DMA_SYNC_FORDEV\fR, +\fBDDI_DMA_SYNC_FORCPU\fR and \fBDDI_DMA_SYNC_FORKERNEL\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_dma_sync()\fR function is used to selectively synchronize either a +\fBDMA\fR device's or a \fBCPU\fR's view of a memory object that has \fBDMA\fR +resources allocated for I/O . This may involve operations such as flushes of +\fBCPU\fR or I/O caches, as well as other more complex operations such as +stalling until hardware write buffers have drained. +.sp +.LP +This function need only be called under certain circumstances. When resources +are allocated for \fBDMA\fR using \fBddi_dma_addr_bind_handle()\fR or +\fBddi_dma_buf_bind_handle()\fR, an implicit \fBddi_dma_sync()\fR is done. When +\fBDMA\fR resources are deallocated using \fBddi_dma_unbind_handle\fR(9F), an +implicit \fBddi_dma_sync()\fR is done. However, at any time between \fBDMA\fR +resource allocation and deallocation, if the memory object has been modified by +either the \fBDMA\fR device or a \fBCPU\fR and you wish to ensure that the +change is noticed by the party that did \fBnot\fR do the modifying, a call to +\fBddi_dma_sync()\fR is required. This is true independent of any attributes of +the memory object including, but not limited to, whether or not the memory was +allocated for consistent mode I/O (see \fBddi_dma_mem_alloc\fR(9F)) or whether +or not \fBDMA\fR resources have been allocated for consistent mode I/O (see +\fBddi_dma_addr_bind_handle\fR(9F) or \fBddi_dma_buf_bind_handle\fR(9F)). +.sp +.LP +If a consistent view of the memory object must be ensured between the time +\fBDMA\fR resources are allocated for the object and the time they are +deallocated, you \fBmust\fR call \fBddi_dma_sync()\fR to ensure that either a +\fBCPU\fR or a \fBDMA\fR device has such a consistent view. +.sp +.LP +What to set \fBtype\fR to depends on the view you are trying to ensure +consistency for. If the memory object is modified by a \fBCPU\fR, and the +object is going to be \fBread\fR by the \fBDMA\fR engine of the device, use +\fBDDI_DMA_SYNC_FORDEV\fR. This ensures that the device's \fBDMA\fR engine sees +any changes that a \fBCPU\fR has made to the memory object. If the \fBDMA\fR +engine for the device has \fBwritten\fR to the memory object, and you are going +to \fBread\fR (with a \fBCPU\fR) the object (using an extant virtual address +mapping that you have to the memory object), use \fBDDI_DMA_SYNC_FORCPU\fR. +This ensures that a \fBCPU\fR's view of the memory object includes any changes +made to the object by the device's \fBDMA\fR engine. If you are only interested +in the kernel's view (kernel-space part of the \fBCPU\fR's view) you may use +\fBDDI_DMA_SYNC_FORKERNEL\fR. This gives a hint to the system\(emthat is, if it +is more economical to synchronize the kernel's view only, then do so; +otherwise, synchronize for \fBCPU\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_dma_sync()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Caches are successfully flushed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +The address range to be flushed is out of the address range established by +\fBddi_dma_addr_bind_handle\fR(9F) or \fBddi_dma_buf_bind_handle\fR(9F). +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_dma_sync()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F), +\fBddi_dma_buf_bind_handle\fR(9F), \fBddi_dma_mem_alloc\fR(9F), +\fBddi_dma_unbind_handle\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dma_unbind_handle.9f b/usr/src/man/man9f/ddi_dma_unbind_handle.9f new file mode 100644 index 0000000000..32a54adde8 --- /dev/null +++ b/usr/src/man/man9f/ddi_dma_unbind_handle.9f @@ -0,0 +1,83 @@ +'\" te +.\" Copyright (c) 1994, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dma_unbind_handle 9F "26 Sep 1994" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dma_unbind_handle \- unbinds the address in a DMA handle +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_dma_unbind_handle\fR(\fBddi_dma_handle_t\fR \fIhandle\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 11n +.rt +The \fBDMA\fR handle previously allocated by a call to +\fBddi_dma_alloc_handle\fR(9F). +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +\fBddi_dma_unbind_handle()\fR frees all \fBDMA\fR resources associated with an +existing \fBDMA\fR handle. When a \fBDMA\fR transfer completes, the driver +should call \fBddi_dma_unbind_handle()\fR to free system \fBDMA\fR resources +established by a call to \fBddi_dma_buf_bind_handle\fR(9F) or +\fBddi_dma_addr_bind_handle\fR(9F). \fBddi_dma_unbind_handle()\fR does an +implicit \fBddi_dma_sync\fR(9F) making further synchronization steps +unnecessary. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR \fR +.ad +.RS 16n +.rt +on success +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR \fR +.ad +.RS 16n +.rt +on failure +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_dma_unbind_handle()\fR can be called from user, kernel, or interrupt +context. +.SH SEE ALSO +.sp +.LP +\fBddi_dma_addr_bind_handle\fR(9F), \fBddi_dma_alloc_handle\fR(9F), +\fBddi_dma_buf_bind_handle\fR(9F), \fBddi_dma_free_handle\fR(9F), +\fBddi_dma_sync\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_dmae.9f b/usr/src/man/man9f/ddi_dmae.9f new file mode 100644 index 0000000000..5ab022852e --- /dev/null +++ b/usr/src/man/man9f/ddi_dmae.9f @@ -0,0 +1,434 @@ +'\" te +.\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_dmae 9F "04 Apr 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_dmae, ddi_dmae_alloc, ddi_dmae_release, ddi_dmae_prog, ddi_dmae_disable, +ddi_dmae_enable, ddi_dmae_stop, ddi_dmae_getcnt, ddi_dmae_1stparty, +ddi_dmae_getlim, ddi_dmae_getattr \- system DMA engine functions +.SH SYNOPSIS +.LP +.nf +\fBint\fR \fBddi_dmae_alloc\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR, \fBint (*\fR\fIcallback\fR) (caddr_t), + \fBcaddr_t\fR \fIarg\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_dmae_release\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_dmae_prog\fR(\fBdev_info_t *\fR\fIdip\fR, \fBstruct ddi_dmae_req *\fR\fIdmaereqp\fR, + \fBddi_dma_cookie_t *\fR\fIcookiep\fR, \fBint\fR \fIchnl\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_dmae_disable\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_dmae_enable\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_dmae_stop\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_dmae_getcnt\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR, \fBint *\fR\fIcountp\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_dmae_1stparty\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIchnl\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_dmae_getlim\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_lim_t *\fR\fIlimitsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_dmae_getattr\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_attr_t *\fR\fIattrp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_dmae_getlim()\fR interface, +described below, is obsolete. Use \fBddi_dmae_getattr()\fR, also described +below, to replace it. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 12n +.rt +A \fBdev_info\fR pointer that identifies the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIchnl\fR\fR +.ad +.RS 12n +.rt +A \fBDMA\fR channel number. On \fBISA\fR buses this number must be \fB0\fR, +\fB1\fR, \fB2\fR, \fB3\fR, \fB5\fR, \fB6\fR, or \fB7\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 12n +.rt +The address of a function to call back later if resources are not currently +available. The following special function addresses may also be used: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_SLEEP\fR\fR +.ad +.RS 20n +.rt +Wait until resources are available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_DONTWAIT\fR\fR +.ad +.RS 20n +.rt +Do not wait until resources are available and do not schedule a callback. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 12n +.rt +Argument to be passed to the callback function, if specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdmaereqp\fR\fR +.ad +.RS 12n +.rt +A pointer to a \fBDMA\fR engine request structure. See \fBddi_dmae_req\fR(9S). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookiep\fR\fR +.ad +.RS 12n +.rt +A pointer to a \fBddi_dma_cookie\fR(9S) object, obtained from +\fBddi_dma_segtocookie\fR(9F), which contains the address and count. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcountp\fR\fR +.ad +.RS 12n +.rt +A pointer to an integer that will receive the count of the number of bytes not +yet transferred upon completion of a \fBDMA\fR operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlimitsp\fR\fR +.ad +.RS 12n +.rt +A pointer to a \fBDMA\fR limit structure. See \fBddi_dma_lim_x86\fR(9S). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIattrp\fR\fR +.ad +.RS 12n +.rt +A pointer to a \fBDMA \fR attribute structure. See \fBddi_dma_attr\fR(9S). +.RE + +.SH DESCRIPTION +.sp +.LP +There are three possible ways that a device can perform \fBDMA\fR engine +functions: +.sp +.ne 2 +.mk +.na +\fBBus master DMA\fR +.ad +.RS 19n +.rt +If the device is capable of acting as a true bus master, then the driver should +program the device's \fBDMA\fR registers directly and not make use of the +\fBDMA\fR engine functions described here. The driver should obtain the +\fBDMA\fR address and count from \fBddi_dma_segtocookie\fR(9F). See +\fBddi_dma_cookie\fR(9S) for a description of a \fBDMA\fR cookie. +.RE + +.sp +.ne 2 +.mk +.na +\fBThird-party \fBDMA\fR\fR +.ad +.RS 19n +.rt +This method uses the system \fBDMA\fR engine that is resident on the main +system board. In this model, the device cooperates with the system's \fBDMA\fR +engine to effect the data transfers between the device and memory. The driver +uses the functions documented here, except \fBddi_dmae_1stparty()\fR, to +initialize and program the \fBDMA\fR engine. For each \fBDMA\fR data transfer, +the driver programs the \fBDMA\fR engine and then gives the device a command +to initiate the transfer in cooperation with that engine. +.RE + +.sp +.ne 2 +.mk +.na +\fBFirst-party DMA\fR +.ad +.RS 19n +.rt +Using this method, the device uses its own \fBDMA\fR bus cycles, but requires a +channel from the system's \fBDMA\fR engine. After allocating the \fBDMA\fR +channel, the \fBddi_dmae_1stparty()\fR function may be used to perform whatever +configuration is necessary to enable this mode. +.RE + +.SS "\fBddi_dmae_alloc()\fR" +.sp +.LP +The \fBddi_dmae_alloc()\fR function is used to acquire a \fBDMA\fR channel of +the system \fBDMA\fR engine. \fBddi_dmae_alloc()\fR allows only one device at a +time to have a particular \fBDMA\fR channel allocated. It must be called prior +to any other system \fBDMA\fR engine function on a channel. If the device +allows the channel to be shared with other devices, it must be freed using +\fBddi_dmae_release()\fR after completion of the \fBDMA\fR operation. In any +case, the channel must be released before the driver successfully detaches. See +\fBdetach\fR(9E). No other driver may acquire the \fBDMA\fR channel until it is +released. +.sp +.LP +If the requested channel is not immediately available, the value of +\fIcallback\fR determines what action will be taken. If the value of +\fIcallback\fR is \fBDDI_DMA_DONTWAIT\fR, \fBddi_dmae_alloc()\fR will return +immediately. The value \fBDDI_DMA_SLEEP\fR will cause the thread to sleep and +not return until the channel has been acquired. Any other value is assumed to +be a callback function address. In that case, \fBddi_dmae_alloc()\fR returns +immediately, and when resources might have become available, the callback +function is called (with the argument \fIarg\fR) from interrupt context. When +the callback function is called, it should attempt to allocate the \fBDMA\fR +channel again. If it succeeds or no longer needs the channel, it must return +the value \fBDDI_DMA_CALLBACK_DONE\fR. If it tries to allocate the channel but +fails to do so, it must return the value \fBDDI_DMA_CALLBACK_RUNOUT\fR. In this +case, the callback function is put back on a list to be called again later. +.SS "\fBddi_dmae_prog()\fR" +.sp +.LP +The \fBddi_dmae_prog()\fR function programs the \fBDMA\fR channel for a +\fBDMA\fR transfer. The \fBddi_dmae_req\fR structure contains all the +information necessary to set up the channel, except for the memory address and +count. Once the channel has been programmed, subsequent calls to +\fBddi_dmae_prog()\fR may specify a value of \fINULL\fR for \fIdmaereqp\fR if +no changes to the programming are required other than the address and count +values. It disables the channel prior to setup, and enables the channel before +returning. The \fBDMA\fR address and count are specified by passing +\fBddi_dmae_prog()\fR a cookie obtained from \fBddi_dma_segtocookie\fR(9F). +Other \fBDMA\fR engine parameters are specified by the \fBDMA\fR engine request +structure passed in through \fIdmaereqp\fR. The fields of that structure are +documented in \fBddi_dmae_req\fR(9S). +.sp +.LP +Before using \fBddi_dmae_prog()\fR, you must allocate system \fBDMA\fR +resources using \fBDMA\fR setup functions such as \fBddi_dma_buf_setup\fR(9F). +\fBddi_dma_segtocookie\fR(9F) can then be used to retrieve a cookie which +contains the address and count. Then this cookie is passed to +\fBddi_dmae_prog()\fR. +.SS "\fBddi_dmae_disable()\fR" +.sp +.LP +The \fBddi_dmae_disable()\fR function disables the \fBDMA\fR channel so that it +no longer responds to a device's \fBDMA\fR service requests. +.SS "\fBddi_dmae_enable()\fR" +.sp +.LP +The \fBddi_dmae_enable()\fR function enables the \fBDMA\fR channel for +operation. This may be used to re-enable the channel after a call to +\fBddi_dmae_disable()\fR. The channel is automatically enabled after successful +programming by \fBddi_dmae_prog()\fR. +.SS "\fBddi_dmae_stop()\fR" +.sp +.LP +The \fBddi_dmae_stop()\fR function disables the channel and terminates any +active operation. +.SS "\fBddi_dmae_getcnt()\fR" +.sp +.LP +The \fBddi_dmae_getcnt()\fR function examines the count register of the +\fBDMA\fR channel and sets \fI*countp\fR to the number of bytes remaining to be +transferred. The channel is assumed to be stopped. +.SS "\fBddi_dmae_1stparty()\fR" +.sp +.LP +In the case of \fBISA\fR buses, \fBddi_dmae_1stparty()\fR configures a channel +in the system's \fBDMA\fR engine to operate in a ``slave'' (``cascade'') mode. +.sp +.LP +When operating in \fBddi_dmae_1stparty()\fR mode, the \fBDMA\fR channel must +first be allocated using \fBddi_dmae_alloc()\fR and then configured using +\fBddi_dmae_1stparty()\fR. The driver then programs the device to perform the +I/O, including the necessary \fBDMA\fR address and count values obtained from +\fBddi_dma_segtocookie\fR(9F). +.SS "\fBddi_dmae_getlim()\fR" +.sp +.LP +This function is obsolete. Use \fBddi_dmae_getattr()\fR, described below, +instead. +.sp +.LP +The \fBddi_dmae_getlim()\fR function fills in the \fBDMA\fR limit structure, +pointed to by \fIlimitsp\fR, with the \fBDMA\fR limits of the system \fBDMA\fR +engine. Drivers for devices that perform their own bus mastering or use +first-party \fBDMA\fR must create and initialize their own \fBDMA\fR limit +structures; they should not use \fBddi_dmae_getlim()\fR. The \fBDMA\fR limit +structure must be passed to the \fBDMA\fR setup routines so that they will know +how to break the \fBDMA\fR request into windows and segments (see +\fBddi_dma_nextseg\fR(9F) and \fBddi_dma_nextwin\fR(9F)). If the device has any +particular restrictions on transfer size or granularity (such as the size of +disk sector), the driver should further restrict the values in the structure +members before passing them to the \fBDMA\fR setup routines. The driver must +not relax any of the restrictions embodied in the structure after it is filled +in by \fBddi_dmae_getlim()\fR. After calling \fBddi_dmae_getlim()\fR, a driver +must examine, and possibly set, the size of the \fBDMA\fR engine's +scatter/gather list to determine whether \fBDMA\fR chaining will be used. See +\fBddi_dma_lim_x86\fR(9S) and \fBddi_dmae_req\fR(9S) for additional information +on scatter/gather DMA. +.SS "\fBddi_dmae_getattr()\fR" +.sp +.LP +The \fBddi_dmae_getattr()\fR function fills in the \fBDMA\fR attribute +structure, pointed to by \fIattrp\fR, with the \fBDMA\fR attributes of the +system \fBDMA\fR engine. Drivers for devices that perform their own bus +mastering or use first-party \fBDMA\fR must create and initialize their own +\fBDMA\fR attribute structures; they should not use \fBddi_dmae_getattr()\fR. +The \fBDMA\fR attribute structure must be passed to the \fBDMA\fR resource +allocation functions to provide the information necessary to break the +\fBDMA\fR request into \fBDMA\fR windows and \fBDMA\fR cookies. See +\fBddi_dma_nextcookie\fR(9F) and \fBddi_dma_getwin\fR(9F). +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 23n +.rt +Upon success, for all of these routines. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 23n +.rt +May be returned due to invalid arguments. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DMA_NORESOURCES\fR\fR +.ad +.RS 23n +.rt +May be returned by \fBddi_dmae_alloc()\fR if the requested resources are not +available and the value of \fIdmae_waitfp\fR is not \fBDDI_DMA_SLEEP\fR. +.RE + +.SH CONTEXT +.sp +.LP +If \fBddi_dmae_alloc()\fR is called from interrupt context, then its +\fIdmae_waitfp\fR argument and the callback function must not have the value +\fBDDI_DMA_SLEEP\fR. Otherwise, all these routines can be called from user, +interrupt, or kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architecturex86 +.TE + +.SH SEE ALSO +.sp +.LP +\fBisa\fR(4), \fBattributes\fR(5), \fBddi_dma_buf_setup\fR(9F), +\fBddi_dma_getwin\fR(9F), \fBddi_dma_nextcookie\fR(9F), +\fBddi_dma_nextseg\fR(9F), \fBddi_dma_nextwin\fR(9F), +\fBddi_dma_segtocookie\fR(9F), \fBddi_dma_setup\fR(9F), \fBddi_dma_attr\fR(9S), +\fBddi_dma_cookie\fR(9S), \fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S), +\fBddi_dmae_req\fR(9S) diff --git a/usr/src/man/man9f/ddi_driver_major.9f b/usr/src/man/man9f/ddi_driver_major.9f new file mode 100644 index 0000000000..36d831f485 --- /dev/null +++ b/usr/src/man/man9f/ddi_driver_major.9f @@ -0,0 +1,55 @@ +'\" 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 ddi_driver_major 9F "18 Jun 2001" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_driver_major \- return driver's major device number +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBmajor_t\fR \fBddi_driver_major\fR(\fBdev_info_t *\fR\fIdip\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +\fBddi_driver_major()\fR returns the major device number for the driver +associated with the supplied \fBdev_info node\fR. This value can then be used +as an argument to \fBmakedevice\fR(9F) to construct a complete \fBdev_t\fR. +.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 RETURN VALUES +.sp +.LP +\fBddi_driver_major()\fR returns the major number of the driver bound to a +device, if any, or \fBDDI_MAJOR_T_NONE\fR otherwise. +.SH CONTEXT +.sp +.LP +\fBddi_driver_major()\fR can be called from kernel or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBddi_driver_name\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_driver_name.9f b/usr/src/man/man9f/ddi_driver_name.9f new file mode 100644 index 0000000000..a8c9a3a5f2 --- /dev/null +++ b/usr/src/man/man9f/ddi_driver_name.9f @@ -0,0 +1,60 @@ +'\" te +.\" Copyright (c) 1998, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_driver_name 9F "2 Dec 1998" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_driver_name \- return normalized driver name +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBconst char *\fR\fBddi_driver_name\fR(\fBdev_info_t *\fR\fIdevi\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fBdip\fR \fR +.ad +.RS 8n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_driver_name()\fR returns the normalized driver name. This name is +typically derived from the device name property or the device compatible +property. If this name is a driver alias, the corresponding driver name is +returned. +.SH RETURN VALUES +.sp +.LP +\fBddi_driver_name()\fR returns the actual name of the driver bound to a +device. +.SH CONTEXT +.sp +.LP +\fBddi_driver_name()\fR can be called from kernel, or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBddi_get_name\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +The name returned by \fBddi_driver_name()\fR is read-only. diff --git a/usr/src/man/man9f/ddi_enter_critical.9f b/usr/src/man/man9f/ddi_enter_critical.9f new file mode 100644 index 0000000000..00aeb182eb --- /dev/null +++ b/usr/src/man/man9f/ddi_enter_critical.9f @@ -0,0 +1,89 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_enter_critical 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_enter_critical, ddi_exit_critical \- enter and exit a critical region of +control +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBunsigned int\fR \fBddi_enter_critical\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_exit_critical\fR(\fBunsignedint\fR \fIddic\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIddic\fR\fR +.ad +.RS 8n +.rt +The returned value from the call to \fBddi_enter_critical()\fR must be passed +to \fBddi_exit_critical()\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +Nearly all driver operations can be done without any special synchronization +and protection mechanisms beyond those provided by, for example, mutexes (see +\fBmutex\fR(9F)). However, for certain devices there can exist a very short +critical region of code which \fBmust\fR be allowed to run uninterrupted. The +function \fBddi_enter_critical()\fR provides a mechanism by which a driver can +ask the system to guarantee to the best of its ability that the current thread +of execution will neither be preempted nor interrupted. This stays in effect +until a bracketing call to \fBddi_exit_critical()\fR is made (with an argument +which was the returned value from \fBddi_enter_critical()\fR). +.sp +.LP +The driver may not call any functions external to itself in between the time it +calls \fBddi_enter_critical()\fR and the time it calls +\fBddi_exit_critical()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_enter_critical()\fR function returns an opaque unsigned integer +which must be used in the subsequent call to \fBddi_exit_critical()\fR. +.SH CONTEXT +.sp +.LP +This function can be called from user, interrupt, or kernel context. +.SH WARNINGS +.sp +.LP +Driver writers should note that in a multiple processor system this function +does not temporarily suspend other processors from executing. This function +also cannot guarantee to actually block the hardware from doing such things as +interrupt acknowledge cycles. What it \fBcan\fR do is guarantee that the +currently executing thread will not be preempted. +.sp +.LP +Do not write code bracketed by \fBddi_enter_critical()\fR and +\fBddi_exit_critical()\fR that can get caught in an infinite loop, as the +machine may crash if you do. +.SH SEE ALSO +.sp +.LP +\fBmutex\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_ffs.9f b/usr/src/man/man9f/ddi_ffs.9f new file mode 100644 index 0000000000..d6a4478d46 --- /dev/null +++ b/usr/src/man/man9f/ddi_ffs.9f @@ -0,0 +1,82 @@ +'\" te +.\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_ffs 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_ffs, ddi_fls \- find first (last) bit set in a long integer +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR\fBddi_ffs\fR(\fBlong\fR \fImask\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_fls\fR(\fBlong\fR \fImask\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImask\fR\fR +.ad +.RS 8n +.rt +A 32-bit argument value to search through. +.RE + +.SH DESCRIPTION +.sp +.LP +The function \fBddi_ffs()\fR takes its argument and returns the shift count +that the first (least significant) bit set in the argument corresponds to. The +function \fBddi_fls()\fR does the same, only it returns the shift count for the +last (most significant) bit set in the argument. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +No bits are set in mask. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIN\fR\fR +.ad +.RS 5n +.rt +Bit \fIN\fR is the least significant (\fBddi_ffs\fR) or most significant +(\fBddi_fls\fR) bit set in mask. Bits are numbered from \fB1\fR to \fB32\fR, +with bit \fB1\fR being the least significant bit position and bit \fB32\fR the +most significant position. +.RE + +.SH CONTEXT +.sp +.LP +This function can be called from user, interrupt, or kernel context. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_fm_acc_err_clear.9f b/usr/src/man/man9f/ddi_fm_acc_err_clear.9f new file mode 100644 index 0000000000..b59fc6b50a --- /dev/null +++ b/usr/src/man/man9f/ddi_fm_acc_err_clear.9f @@ -0,0 +1,99 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_fm_acc_err_clear 9F "10 May 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_fm_acc_err_clear, ddi_fm_dma_err_clear \- clear the error status for an +access or DMA handle +.SH SYNOPSIS +.LP +.nf +#include <sys/ndifma.h> + +\fBvoid\fR \fBddi_fm_acc_err_clear\fR(\fBddi_acc_handle_t\fR \fIacc_handle\fR, + \fBint\fR \fIversion\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_fm_dma_err_clear\fR(\fBddi_dma_handle_t\fR \fIdma_handle\fR, + \fBint\fR \fIversion\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIacc_handle\fR\fR +.ad +.RS 14n +.rt +Data access handle obtained from a previous call to +\fBddi_regs_map_setup\fR(9F), \fBddi_dma_mem_alloc\fR(9F), or to a similar +function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdma_handle\fR\fR +.ad +.RS 14n +.rt +\fBDMA\fR handle obtained from a previous call to \fBddi_dma_mem_alloc\fR(9F) +or one of its derivatives. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIversion\fR\fR +.ad +.RS 14n +.rt +Version number of \fBddi_fm_error_t\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_fm_dma_err_clear()\fR and \fBddi_fm_acc_err_clear()\fR functions +clear the error status of a \fBDMA\fR or access handle respectively. +.sp +.LP +Once cleared, the driver is again able to access the mapped registers or memory +using programmed \fBI/O\fR through the handle. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_dma_mem_alloc\fR(9F), \fBddi_fm_acc_err_get\fR(9F), +\fBddi_fm_dma_err_get\fR(9F), \fBddi_regs_map_setup\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_fm_acc_err_get.9f b/usr/src/man/man9f/ddi_fm_acc_err_get.9f new file mode 100644 index 0000000000..109ef90362 --- /dev/null +++ b/usr/src/man/man9f/ddi_fm_acc_err_get.9f @@ -0,0 +1,151 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_fm_acc_err_get 9F "13 May 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_fm_acc_err_get, ddi_fm_dma_err_get \- get the error status for an access or +DMA handle +.SH SYNOPSIS +.LP +.nf +#include <sys/ndifma.h> + +\fBvoid\fR \fBddi_fm_acc_err_get\fR(\fBddi_acc_handle_t\fR \fIacc_handle\fR, + \fBddi_fm_error_t\fR *\fIerror_status\fR, \fBint\fR \fIversion\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_fm_dma_err_get\fR(\fBddi_dma_handle_t\fR \fIdma_handle\fR, + \fBddi_fm_error_t\fR *\fIerror_status\fR, \fBint\fR \fIversion\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIacc_handle\fR\fR +.ad +.RS 16n +.rt +Data access handle obtained from a previous call to +\fBddi_regs_map_setup\fR(9F), \fBddi_dma_mem_alloc\fR(9F), or to a similar +function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdma_handle\fR\fR +.ad +.RS 16n +.rt +\fBDMA\fR handle obtained from a previous call to \fBddi_dma_mem_alloc\fR(9F) +or one of its derivatives. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerror_status\fR\fR +.ad +.RS 16n +.rt +Pointer to where the error status for the access or \fBDMA\fR handle should be +returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIversion\fR\fR +.ad +.RS 16n +.rt +Version number of \fBddi_fm_error_t\fR. The driver should always set this to +\fBDDI_FME_VERSION\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_fm_dma_err_get()\fR and \fBddi_fm_acc_err_get()\fR functions return +the error status for a \fBDMA\fR or access handle respectively. If a fault has +occurred that affects the resource mapped by the supplied handle, the supplied +\fIerror_status\fR structure is updated to reflect error information captured +during error handling by a bus or other device driver in the \fBI/O\fR data +path. +.sp +.LP +If an error is indicated for an access handle, the driver might no longer be +able to access the mapped registers or memory using programmed \fBI/O\fR +through the handle. Typically, this might occur after the device has failed to +respond to an \fBI/O\fR access - in the case of a bus error, for instance, or a +timeout. The effect of programmed \fBI/O\fR access made at the time of a fault +is undefined. Read access via \fBddi_get8\fR(9F), for example, can return +random values, while write access via \fBddi_put8\fR(9F) might or might not +have an effect. It is possible, however, that the error might be transient. In +that case, the driver can attempt to recover by calling +\fBddi_fm_acc_err_clear()\fR, resetting the device to return it to a known +state, then retrying any potentially failed transactions. +.sp +.LP +If an error is indicated for a \fBDMA\fR handle, it implies that an error has +been detected that has or will affect \fBDMA\fR transactions between the device +and the memory currently bound to the handle - or the memory most recently +bound, if the handle is currently unbound. Possible causes include the failure +of a component in the \fBDMA\fR data path or an attempt by the device to make +an invalid \fBDMA\fR access. The contents of any memory currently or previously +bound to the handle should be considered indeterminate. The driver might be +able to continue by freeing memory that is bound to the handle back to the +system, resetting the device to return it to a known state, then retrying any +potentially failed transactions. +.sp +.LP +If the driver is unable to recover, the operating state should be changed by a +call to \fBddi_fm_service_impact()\fR that specifies \fBDDI_SERVICE_LOST\fR for +the impacted device instance. If the recovery and retry succeed, a call should +still be made to \fBddi_fm_service_impact()\fR but \fBDDI_SERVICE_UNAFFECTED\fR +should be specified. +.SH CONTEXT +.sp +.LP +The \fBddi_fm_acc_err_get()\fR and \fBddi_fm_dma_err_get()\fR functions can be +called from user, kernel, or high-level interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_dma_mem_alloc\fR(9F), +\fBddi_fm_acc_err_clear\fR(9F), \fBddi_fm_service_impact\fR(9F), +\fBddi_get8\fR(9F), \fBddi_put8\fR(9F), \fBddi_regs_map_setup\fR(9F), +\fBddi_fm_error\fR(9S), +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_fm_ereport_post.9f b/usr/src/man/man9f/ddi_fm_ereport_post.9f new file mode 100644 index 0000000000..d575c99e4d --- /dev/null +++ b/usr/src/man/man9f/ddi_fm_ereport_post.9f @@ -0,0 +1,215 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_fm_ereport_post 9F "14 May 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_fm_ereport_post \- post an FMA Protocol Error Report Event +.SH SYNOPSIS +.LP +.nf +#include <sys/ddifm.h> + +\fBvoid\fR \fBddi_fm_ereport_post\fR(\fBdev_info_t\fR *\fIdip\fR, \fBchar\fR *\fIereport_class\fR, + \fBuint64_t\fR \fIena\fR, \fBint\fR *\fIsflag\fR, ... /* name-value pair args */); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 17n +.rt +Pointer to the \fBdev_info\fR structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIereport_class\fR\fR +.ad +.RS 17n +.rt +\fBFMA\fR Event Protocol error class +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIena\fR\fR +.ad +.RS 17n +.rt +Error Numeric Association +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsflag\fR\fR +.ad +.RS 17n +.rt +Determines whether caller can sleep for memory or other event resources. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_fm_ereport_post()\fR function causes an encoded fault management +error report name-value pair list to be queued for delivery to the Fault +Manager daemon, \fBfmd\fR(1M). The \fIsflag\fR parameter indicates whether or +not the caller is willing to wait for system memory and event channel resources +to become available. +.sp +.LP +The following \fIereport_class\fR strings are available for use by any leaf +device driver: +.sp +.ne 2 +.mk +.na +\fB\fBdevice.inval_state\fR\fR +.ad +.RS 24n +.rt +A leaf driver discovers that the device is in an invalid or inconsistent state. +For example, the driver might detect that receive or send ring descriptor +indices are corrupted. It might also find an invalid value in a register or a +driver-to-device protocol violation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevice.no_response\fR\fR +.ad +.RS 24n +.rt +A leaf driver times out waiting for a response from the device. For example, +timeouts can occur when no confirmation is seen after resetting, enabling, or +disabling part of the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevice.badint_limit\fR\fR +.ad +.RS 24n +.rt +A leaf device sends too many consecutive interrupts with no work to do. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevice.intern_corr\fR\fR +.ad +.RS 24n +.rt +A leaf device reports to the driver that it has itself detected an internal +correctable error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevice.intern_uncorr\fR\fR +.ad +.RS 24n +.rt +A leaf device reports to the driver that it has itself detected an internal +uncorrectable error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdevice.stall\fR\fR +.ad +.RS 24n +.rt +A leaf driver determines that data transmission has stalled indefinitely. +.RE + +.sp +.LP +The \fIena\fR indicates the Format 1 Error Numeric Association for this error +report. It might have already been initialized by another error-detecting +software module. For example, if \fBddi_fm_ereport_post()\fR is called from an +error handler callback function, the \fIfme_ena\fR field from the passed-in +\fBddi_fm_error\fR argument should be used. Otherwise it should be set to +\fB0\fR and will be initialized by \fBddi_fm_ereport_post()\fR. +.sp +.LP +The name-value pair \fIargs\fR variable argument list contains one or more +(names, type, value pointer) nvpair tuples for non-array \fBdata_type_t\fR +types or one or more (name, type, number of elements, value pointer) tuples for +\fBdata_type_t\fR array types. There is one mandatory tuple to describe the +\fBereport\fR version. This should contain the following values: +.RS +4 +.TP +.ie t \(bu +.el o +name - \fBFM_VERSION\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +type - \fBDATA_TYPE_UINT8\fR +.RE +.RS +4 +.TP +.ie t \(bu +.el o +value - \fBFM_EREPORT_VERS0\fR +.RE +.sp +.LP +Additional nvpair tuples can describe error conditions for logging purposes, +but are not interpreted by the \fBI/O\fR framework or fault manager. The end of +the argument list is specified by \fINULL\fR. +.SH CONTEXT +.sp +.LP +The \fBddi_fm_ereport_post()\fR function can be called from user, kernel, or +high-level interrupt context. +.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 +\fBfmd\fR(1M), \fBattributes\fR(5), \fBddi_fm_service_impact\fR(9F) diff --git a/usr/src/man/man9f/ddi_fm_handler_register.9f b/usr/src/man/man9f/ddi_fm_handler_register.9f new file mode 100644 index 0000000000..0760c0b6bd --- /dev/null +++ b/usr/src/man/man9f/ddi_fm_handler_register.9f @@ -0,0 +1,214 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_fm_handler_register 9F "14 May 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_fm_handler_register, ddi_fm_handler_unregister \- register or unregister an +error handling callback +.SH SYNOPSIS +.LP +.nf +#include <sys/ddifm.h> + +\fBvoid\fR \fBddi_fm_handler_register\fR(\fBdev_info_t\fR *\fIdip\fR, + \fBddi_err_func_t\fR \fIerror_handler\fR, \fBvoid\fR *\fIimpl_data\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_fm_handler_unregister\fR(\fBdev_info_t\fR *\fIdip\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 17n +.rt +Pointer to the \fBdev_info\fR structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerror_handler\fR\fR +.ad +.RS 17n +.rt +Pointer to an error handler callback function +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIimpl_data\fR\fR +.ad +.RS 17n +.rt +Pointer to private data for use by the caller +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_fm_handler_register()\fR function registers an error handler +callback routine with the \fBI/O\fR Fault Management framework. The error +handler callback, \fIerror_handler\fR, is called to process error conditions +detected by the system. In addition to its device instance, \fIdip\fR, the +error handler is called with a pointer to a fault management error status +structure, \fBddi_fm_error_t\fR. For example: +.sp +.in +2 +.nf +int (*ddi_err_func_t)(dev_info_t *dip, ddi_fm_error_t *error_status); +.fi +.in -2 + +.sp +.LP +A driver error handling callback is passed the following arguments: +.RS +4 +.TP +.ie t \(bu +.el o +a pointer to the device instance registered for this callback. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +a data structure containing common fault management data and status for error +handling. +.RE +.sp +.LP +The primary responsibilities of the error handler include: +.RS +4 +.TP +.ie t \(bu +.el o +to check for outstanding hardware or software errors. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +where possible, to isolate the device that might have caused the errors. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +to report errors that were detected. +.RE +.sp +.LP +During the invocation of an error handler, a device driver might need to +quiesce or suspend all \fBI/O\fR activities in order to check for error +conditions or status in: +.RS +4 +.TP +.ie t \(bu +.el o +hardware control and status registers. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +outstanding \fBI/O\fR transactions. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +access or \fBDMA\fR handles. +.RE +.sp +.LP +For each error detected, the driver must formulate and post an error report via +\fBddi_fm_ereport_post()\fR for problem analysis by the Solaris Fault Manager +\fBfmd\fR(1M). +.sp +.LP +For a \fBPCI\fR, \fBPCI/X\fR, or \fBPCI Express\fR leaf device, the +\fBpci_ereport_post()\fR function is provided to carry out reporting +responsibilities on behalf of the driver. In many cases, an error handler +callback function of the following form can be used: +.sp +.in +2 +.nf +xxx_err_cb(dev_info_t *dip, ddi_fm_error_t *errp) { + pci_ereport_post(dip, errp, NULL); + return (errp->fme_status); +} +.fi +.in -2 + +.sp +.LP +In addition, the driver might be able to carry out further device specific +checks within the error handler. +.sp +.LP +Error handlers can be called from kernel, interrupt, or high-level interrupt +context. The interrupt block cookie returned from \fBddi_fm_init()\fR should be +used to allocate and initialize any synchronization variables and locks that +might be used within the error handler callback function. Such locks may not be +held by the driver when a device register is accessed with functions such as +\fBddi_get8\fR(9F) and \fBddi_put8\fR(9F). +.sp +.LP +The data structure, \fBddi_fm_error_t\fR, contains an \fBFMA\fR protocol +(format 1) \fBENA\fR for the current error propagation chain, the status of the +error handler callback, an error expectation flag, and any potential access or +\fBDMA\fR handles associated with an error detected by the parent nexus. +.sp +.LP +The \fBddi_fm_handler_unregister()\fR function removes a previously registered +error handling callback for the device instance specified by the \fIdip\fR. +.SH CONTEXT +.sp +.LP +The \fBddi_fm_handler_register()\fR and \fBddi_fm_handler_unregister()\fR +functions must be called from kernel context in an \fBattach\fR(9E) or +\fBdetach\fR(9E) entry point. The registered error handler, +\fIerror_handler\fR, callback can be called from kernel, interrupt, or high +level interrupt context. +.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 +\fBfmd\fR(1M), \fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E), +\fBddi_fm_ereport_post\fR(9F), \fBddi_fm_init\fR(9F), \fBddi_get8\fR(9F), +\fBddi_put8\fR(9F), \fBpci_ereport_post\fR(9F), \fBddi_fm_error\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_fm_init.9f b/usr/src/man/man9f/ddi_fm_init.9f new file mode 100644 index 0000000000..db34bf8b58 --- /dev/null +++ b/usr/src/man/man9f/ddi_fm_init.9f @@ -0,0 +1,206 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_fm_init 9F "14 May 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_fm_init, ddi_fm_fini, ddi_fm_capable \- initialize and get the FM +capabilities for a device instance +.SH SYNOPSIS +.LP +.nf +#include <sys/ddifm.h> + +\fBvoid\fR \fBddi_fm_init\fR(\fBdev_info_t\fR *\fIdip\fR, \fBint\fR *\fIfm_capability\fR, + \fBddi_iblock_cookie_t\fR *\fIibcp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_fm_fini\fR(\fBdev_info_t\fR *\fIdip\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_fm_capable\fR(\fBdev_info_t\fR *\fIdip\fR, \fBint\fR *\fIfm_capability\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.LP +\fBddi_fm_init()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 17n +.rt +Pointer to the \fBdev_info\fR structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfm_capability\fR\fR +.ad +.RS 17n +.rt +Fault Management capability bit mask +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIibcp\fR\fR +.ad +.RS 17n +.rt +Pointer to where the interrupt block cookie should be returned. +.RE + +.SH DESCRIPTION +.sp +.LP +A device driver can declare its fault management capabilities to the \fBI/O\fR +Fault Management framework by calling \fBddi_fm_init()\fR. The +\fBddi_fm_init()\fR function allocates and initializes resources according to +the bitwise-inclusive-OR of the fault management capabilities, described in the +following and supported by the driver's immediate nexus parent. +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_NOT_CAPABLE\fR\fR +.ad +.RS 26n +.rt +The driver does not support any \fBFMA\fR features. This is the default value +assigned to device drivers. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_EREPORT_CAPABLE\fR\fR +.ad +.RS 26n +.rt +The driver generates \fBFMA\fR protocol error events (\fBereports\fR) upon the +detection of an error condition. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_ACCCHK_CAPABLE\fR\fR +.ad +.RS 26n +.rt +The driver checks for errors upon the completion of one or more access +\fBI/O\fR transactions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_DMACHK_CAPABLE\fR\fR +.ad +.RS 26n +.rt +The driver checks for errors upon the completion of one or more \fBDMA\fR +\fBI/O\fR transactions. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_ERRCB_CAPABLE\fR\fR +.ad +.RS 26n +.rt +The driver is capable of error handler callback registration. +.RE + +.sp +.LP +If the parent nexus is not capable of supporting any one of the requested +capabilities, the associated bit will not be set and returned as such to the +driver. Before returning from \fBddi_fm_init()\fR, the \fBI/O\fR Fault +Management framework creates a set of fault management capability properties: +\fBfm-ereport-capable\fR, \fBfm-errcb-capable\fR, \fBfm-accchk-capable\fR, and +\fBfm-dmachk-capable\fR. The current supported fault management capability +levels are observable via \fBprtconf\fR(1M). +.sp +.LP +A driver can support the administrative selection of fault management +capabilities by exporting and setting a fault management capability level +property in its \fBdriver.conf\fR(4) file to the values described above. The +\fBfm_capable\fR properties must be set and read prior to calling +\fBddi_fm_init()\fR with the desired capability list. +.sp +.ne 2 +.mk +.na +\fB\fBddi_fm_fini()\fR\fR +.ad +.RS 17n +.rt +This function cleans up resources allocated to support fault management for the +\fIdip\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_fm_capable()\fR\fR +.ad +.RS 20n +.rt +This function returns the capability bit mask currently set for the \fIdip\fR +structure. +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from kernel context in a driver \fBattach\fR(9E) +or \fBdetach\fR(9E) operation. +.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 +\fBprtconf\fR(1M), \fBdriver.conf\fR(4), \fBattributes\fR(5), \fBattach\fR(9E), +\fBdetach\fR(9E) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_fm_service_impact.9f b/usr/src/man/man9f/ddi_fm_service_impact.9f new file mode 100644 index 0000000000..d013d06003 --- /dev/null +++ b/usr/src/man/man9f/ddi_fm_service_impact.9f @@ -0,0 +1,128 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_fm_service_impact 9F "14 May 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_fm_service_impact \- report the impact of an error +.SH SYNOPSIS +.LP +.nf +#include <sys/ddifm.h> + +\fBvoid\fR \fBddi_fm_service_impact\fR(\fBdev_info_t\fR *\fIdip\fR, \fBint\fR *\fIimpact\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 10n +.rt +Pointer to the \fBdev_info\fR structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIimpact\fR\fR +.ad +.RS 10n +.rt +Impact of error +.RE + +.SH DESCRIPTION +.sp +.LP +The following service impact values are accepted by +\fBddi_fm_service_impact()\fR: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SERVICE_LOST\fR\fR +.ad +.RS 26n +.rt +The service provided by the device is unavailable due to an error. The +operational state of the device will transition to \fBDEVI_DEVICE_DOWN\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SERVICE_DEGRADED\fR\fR +.ad +.RS 26n +.rt +The driver is unable to provide normal service, but it can provide a partial or +degraded level of service. The driver might have to make repeated attempts to +perform an operation before it succeeds, or it may be running at less than its +configured speed. A driver may use this value to indicate that an alternative +device should be used if available, but that it can continue operation if no +alternative exists. The operational state of the device will transition to +\fBDEVI_DEVICE_DEGRADED\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SERVICE_RESTORED\fR\fR +.ad +.RS 26n +.rt +The service provided by the device has been restored. The operational state of +the device will transition to its pre-error condition state and +\fBDEVI_DEVICE_DOWN\fR or \fBDEVI_DEVICE_DEGRADED\fR is removed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SERVICE_UNAFFECTED\fR\fR +.ad +.RS 26n +.rt +The service provided by the device was unaffected by the error. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_fm_service_impact()\fR function can be called from user, kernel, or +high-level interrupt context. +.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 +\fBfmd\fR(1M), \fBattributes\fR(5), \fBddi_fm_ereport_post\fR(9F), +\fBpci_ereport_post\fR(9F) diff --git a/usr/src/man/man9f/ddi_get8.9f b/usr/src/man/man9f/ddi_get8.9f new file mode 100644 index 0000000000..8ca84c60fb --- /dev/null +++ b/usr/src/man/man9f/ddi_get8.9f @@ -0,0 +1,119 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_get8 9F "1 Nov 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_get8, ddi_get16, ddi_get32, ddi_get64, ddi_getb, ddi_getw, ddi_getl, +ddi_getll \- read data from the mapped memory address, device register or +allocated DMA memory address +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBuint8_t\fR \fBddi_get8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint8_t *\fR\fIdev_addr\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBddi_get16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint16_t *\fR\fIdev_addr\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBddi_get32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint32_t *\fR\fIdev_addr\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBddi_get64\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint64_t *\fR\fIdev_addr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_getb()\fR, \fBddi_getl()\fR, +\fBddi_getll()\fR, and \fBddi_getw()\fR functions are obsolete. The +\fBddi_get8()\fR function replaces \fBddi_getb()\fR. The \fBddi_get32()\fR +function replaces \fBddi_getl()\fR. The \fBddi_get64()\fR function replaces +\fBddi_getll()\fR. The \fBddi_get16()\fR function replaces \fBddi_getw()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 12n +.rt +The data access handle returned from setup calls, such as +\fBddi_regs_map_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_addr\fR\fR +.ad +.RS 12n +.rt +Base device address. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_get8()\fR, \fBddi_get16()\fR, \fBddi_get32()\fR, and +\fBddi_get64()\fR functions read 8 bits, 16 bits, 32 bits and 64 bits of data, +respectively, from the device address, \fIdev_addr\fR. +.sp +.LP +Each individual datum will automatically be translated to maintain a consistent +view between the host and the device based on the encoded information in the +data access handle. The translation may involve byte-swapping if the host and +the device have incompatible endian characteristics. +.sp +.LP +For certain bus types, you can call these \fBDDI\fR functions from a +high-interrupt context. These types include \fBISA\fR and SBus buses. See +\fBsysbus\fR(4), \fBisa\fR(4), and \fBsbus\fR(4) for details. For the PCI bus, +you can, under certain conditions, call these \fBDDI\fR functions from a +high-interrupt context. See \fBpci\fR(4). +.SH RETURN VALUES +.sp +.LP +These functions return the value read from the mapped address. +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel, or interrupt context. +.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 StabilityT{ +\fBddi_getb()\fR, \fBddi_getl()\fR, \fBddi_getll()\fR, and \fBddi_getw()\fR are Obsolete; \fBddi_get8()\fR, \fBddi_get16()\fR, \fBddi_get32()\fR, \fBddi_get64()\fR are Committed +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_put8\fR(9F), \fBddi_regs_map_free\fR(9F), \fBddi_regs_map_setup\fR(9F), +\fBddi_rep_get8\fR(9F), \fBddi_rep_put8\fR(9F) diff --git a/usr/src/man/man9f/ddi_get_cred.9f b/usr/src/man/man9f/ddi_get_cred.9f new file mode 100644 index 0000000000..b6bcabd280 --- /dev/null +++ b/usr/src/man/man9f/ddi_get_cred.9f @@ -0,0 +1,41 @@ +'\" 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 ddi_get_cred 9F "11 Apr 1991" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_get_cred \- returns a pointer to the credential structure of the caller +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBcred_t *\fR\fBddi_get_cred\fR(void) +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +\fBddi_get_cred()\fR returns a pointer to the user credential structure of the +caller. +.SH RETURN VALUES +.sp +.LP +\fBddi_get_cred()\fR returns a pointer to the caller's credential structure. +.SH CONTEXT +.sp +.LP +\fBddi_get_cred()\fR can be called from user context only. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_get_devstate.9f b/usr/src/man/man9f/ddi_get_devstate.9f new file mode 100644 index 0000000000..b19ce5ba8c --- /dev/null +++ b/usr/src/man/man9f/ddi_get_devstate.9f @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_get_devstate 9F "13 August 1999" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_get_devstate \- Check device state +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBddi_devstate_t\fR \fBddi_get_devstate\fR(\fBdev_info_t *\fR\fIdip\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 8n +.rt +Pointer to the device's \fBdev_info\fR structure +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_get_devstate()\fR function returns a value indicating the state of +the device specified by \fB dip\fR, as derived from the configuration +operations that have been performed on it (or on the bus on which it resides) +and any fault reports relating to it. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEVSTATE_OFFLINE\fR\fR +.ad +.RS 25n +.rt +The device is offline. In this state, the device driver is not attached, nor +will it be attached automatically. The device cannot be used until it is +brought online. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEVSTATE_DOWN\fR\fR +.ad +.RS 25n +.rt + The device is online but unusable due to a fault. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEVSTATE_QUIESCED\fR\fR +.ad +.RS 25n +.rt + The bus on which the device resides has been quiesced. This is not a fault, +but no operations on the device should be performed while the bus remains +quiesced. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEVSTATE_DEGRADED\fR\fR +.ad +.RS 25n +.rt + The device is online but only able to provide a partial or degraded service, +due to a fault. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEVSTATE_UP\fR\fR +.ad +.RS 25n +.rt + The device is online and fully operational. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_get_devstate()\fR function may be called from user, kernel, or +interrupt context. +.SH NOTES +.sp +.LP +A device driver should call this function to check its own state at each major +entry point, and before committing resources to a requested operation. If a +driver discovers that its device is already down, it should perform required +cleanup actions and return as soon as possible. If appropriate, it should +return an error to its caller, indicating that the device has failed (for +example, a driver's \fBread\fR(9E) routine would return \fBEIO\fR). +.sp +.LP +Depending on the driver, some non-I/O operations (for example, calls to the +driver's \fBioctl\fR(9E) routine) may still succeed; only functions which would +require fully accessible and operational hardware will necessarily fail. If the +bus on which the device resides is quiesced, the driver may return a value +indicating the operation should be retried later (for example, \fBEAGAIN\fR). +Alternatively, for some classes of device, it may be appropriate for the driver +to enqueue the operation and service it once the bus has been unquiesced. Note +that not all busses support the quiesce/unquiesce operations, so this value may +never be seen by some drivers. +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBioctl\fR(9E), \fBopen\fR(9E), \fBread\fR(9E), +\fBstrategy\fR(9E), \fBwrite\fR(9E), \fBddi_dev_report_fault\fR(9F) diff --git a/usr/src/man/man9f/ddi_get_driver_private.9f b/usr/src/man/man9f/ddi_get_driver_private.9f new file mode 100644 index 0000000000..0ba0f9fdd1 --- /dev/null +++ b/usr/src/man/man9f/ddi_get_driver_private.9f @@ -0,0 +1,95 @@ +'\" te +.\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_get_driver_private 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_get_driver_private, ddi_set_driver_private \- get or set the address of the +device's private data area +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_set_driver_private\fR(\fBdev_info_t *\fR\fIdip\fR, \fBvoid\fR *\fIdata\fR); +.fi + +.LP +.nf +\fBvoid\fR *\fBddi_get_driver_private\fR(\fBdev_info_t *\fR\fIdip\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +\fBddi_get_driver_private()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 7n +.rt +Pointer to device information structure to get from. +.RE + +.sp +.LP +\fBddi_set_driver_private()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 8n +.rt +Pointer to device information structure to set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdata\fR\fR +.ad +.RS 8n +.rt +Data area address to set. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_get_driver_private()\fR function returns the address of the device's +private data area from the device information structure pointed to by +\fIdip\fR. +.sp +.LP +The \fBddi_set_driver_private()\fR function sets the address of the device's +private data area in the device information structure pointed to by \fIdip\fR +with the value of \fIdata\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_get_driver_private()\fR function returns the contents of +\fBdevi_driver_data\fR. If \fBddi_set_driver_private()\fR has not been +previously called with \fIdip\fR, an unpredictable value is returned. +.SH CONTEXT +.sp +.LP +These functions can be called from user , interrupt, or kernel context. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_get_eventcookie.9f b/usr/src/man/man9f/ddi_get_eventcookie.9f new file mode 100644 index 0000000000..9b2edc05a7 --- /dev/null +++ b/usr/src/man/man9f/ddi_get_eventcookie.9f @@ -0,0 +1,122 @@ +'\" 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 ddi_get_eventcookie 9F "6 Nov 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_get_eventcookie \- retrieve a NDI event service cookie handle +.SH SYNOPSIS +.LP +.nf +#include <sys/dditypes.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_get_eventcookie\fR(\fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR, + \fBddi_eventcookie_t *\fR\fIevent_cookiep\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fBdev_info_t *\fR\fIdip\fR\fR +.ad +.sp .6 +.RS 4n +Child device node requesting the cookie. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBchar *\fR\fIname\fR\fR +.ad +.sp .6 +.RS 4n +NULL-terminated string containing the name of the event. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_eventcookie_t *\fR\fIevent_cookiep\fR\fR +.ad +.sp .6 +.RS 4n +Pointer to cookie where event cookie will be returned. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_get_eventcookie()\fR function queries the device tree for a cookie +matching the given event name and returns a reference to that cookie. The +search is performed by a calling up the device tree hierarchy until the request +is satisfied by a bus nexus driver, or the top of the \fBdev_info\fR tree is +reached. +.sp +.LP +The cookie returned by this function can be used to register a callback +handler, unregister a callback handler, or post an event. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Cookie handle is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Request was not serviceable by any nexus driver in the driver's ancestral +device tree hierarchy. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_get_eventcookie()\fR function can be called from user and kernel +contexts only. +.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 +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_add_event_handler\fR(9F), +\fBddi_remove_event_handler\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_get_instance.9f b/usr/src/man/man9f/ddi_get_instance.9f new file mode 100644 index 0000000000..0883d0debb --- /dev/null +++ b/usr/src/man/man9f/ddi_get_instance.9f @@ -0,0 +1,73 @@ +'\" te +.\" Copyright (c) 2006 Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_get_instance 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_get_instance \- get device instance number +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_get_instance\fR(\fBdev_info_t *\fR\fIdip\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 +Pointer to \fBdev_info\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_get_instance()\fR function returns the instance number of the device +corresponding to \fIdip\fR. +.sp +.LP +The system assigns an instance number to every device. Instance numbers for +devices attached to the same driver are unique. This provides a way for the +system and the driver to uniquely identify one or more devices of the same +type. The instance number is derived by the system from different properties +for different device types in an implementation specific manner. +.sp +.LP +Once an instance number has been assigned to a device, it will remain the same +even across reconfigurations and reboots. Therefore, instance numbers seen by a +driver may not appear to be in consecutive order. For example, if device +\fBfoo0\fR has been assigned an instance number of \fB0\fR and device +\fBfoo1\fR has been assigned an instance number of \fB1\fR, if \fBfoo0\fR is +removed, \fBfoo1\fR will continue to be associated with instance number \fB1\fR +(even though \fBfoo1\fR is now the only device of its type on the system). +.SH RETURN VALUES +.sp +.LP +The \fBddi_get_instance()\fR function returns the instance number of the device +corresponding to \fIdip\fR. +.SH CONTEXT +.sp +.LP +The \fBddi_get_instance()\fR function can be called from user, interrupt, or +kernel context. +.SH SEE ALSO +.sp +.LP +\fBpath_to_inst\fR(4) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_get_kt_did.9f b/usr/src/man/man9f/ddi_get_kt_did.9f new file mode 100644 index 0000000000..0544e3a4f8 --- /dev/null +++ b/usr/src/man/man9f/ddi_get_kt_did.9f @@ -0,0 +1,51 @@ +'\" 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 ddi_get_kt_did 9F "15 May 2001" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_get_kt_did \- get identifier of current thread +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBkt_did_t\fR \fBddi_get_kt_did\fR(\fB\fR\fIvoid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBddi_get_kt_did()\fR function returns a unique 64-bit identifier for the +currently running thread. +.SH CONTEXT +.sp +.LP +This routine can be called from user, kernel, or interrupt context. This +routine cannot be called from a high-level interrupt context. +.SH RETURN VALUES +.sp +.LP +\fBddi_get_kt_did()\fR always returns the identifier for the current thread. +There are no error conditions. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The value returned by this function can also be seen in \fBadb\fR or \fBmdb\fR +as the \fBdid\fR field displayed when using the \fBthread\fR macro. +.sp +.LP +This interface is intended for tracing and debugging purposes. diff --git a/usr/src/man/man9f/ddi_get_lbolt.9f b/usr/src/man/man9f/ddi_get_lbolt.9f new file mode 100644 index 0000000000..12b09992e1 --- /dev/null +++ b/usr/src/man/man9f/ddi_get_lbolt.9f @@ -0,0 +1,51 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_get_lbolt 9F "18 Feb 1998" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_get_lbolt \- returns the value of lbolt +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBclock_t\fR \fBddi_get_lbolt\fR(\fBvoid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +\fBddi_get_lbolt()\fR returns the value of \fBlbolt\fR where \fBlbolt\fR is an +integer that represents the number of clock ticks since the last system reboot. +This value is used as a counter or timer inside the system kernel. The tick +frequency can be determined by using \fBdrv_usectohz\fR(9F) which converts +microseconds into clock ticks. +.SH RETURN VALUES +.sp +.LP +\fBddi_get_lbolt()\fR returns the value of \fBlbolt\fR. +.SH CONTEXT +.sp +.LP + This routine can be called from any context. +.SH SEE ALSO +.sp +.LP +\fBddi_get_time\fR(9F), \fBdrv_getparm\fR(9F), \fBdrv_usectohz\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP + \fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/ddi_get_parent.9f b/usr/src/man/man9f/ddi_get_parent.9f new file mode 100644 index 0000000000..9ced039d7b --- /dev/null +++ b/usr/src/man/man9f/ddi_get_parent.9f @@ -0,0 +1,54 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_get_parent 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_get_parent \- find the parent of a device information structure +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBdev_info_t *\fR\fBddi_get_parent\fR(\fBdev_info_t *\fR\fIdip\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 +Pointer to a device information structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_get_parent()\fR function returns a pointer to the device information +structure which is the parent of the one pointed to by \fIdip\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_get_parent()\fR function returns a pointer to a device information +structure. +.SH CONTEXT +.sp +.LP +The \fBddi_get_parent()\fR function can be called from user, interrupt, or +kernel context. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_get_pid.9f b/usr/src/man/man9f/ddi_get_pid.9f new file mode 100644 index 0000000000..c81f516158 --- /dev/null +++ b/usr/src/man/man9f/ddi_get_pid.9f @@ -0,0 +1,50 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_get_pid 9F "18 Feb 1998" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_get_pid \- returns the process \fBID\fR +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBpid_t\fR \fBddi_get_pid\fR(\fBvoid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +\fBddi_get_pid()\fR obtains the process \fBID\fR of the current process. This +value can be used to allow only a select process to perform a certain +operation. It can also be used to determine whether a device context belongs to +the current process. +.SH RETURN VALUES +.sp +.LP +\fBddi_get_pid()\fR returns the process \fBID\fR. +.SH CONTEXT +.sp +.LP + This routine can be called from user context only. +.SH SEE ALSO +.sp +.LP +\fBdrv_getparm\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP + \fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/ddi_get_time.9f b/usr/src/man/man9f/ddi_get_time.9f new file mode 100644 index 0000000000..965dea20ee --- /dev/null +++ b/usr/src/man/man9f/ddi_get_time.9f @@ -0,0 +1,48 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_get_time 9F "18 Feb 1998" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_get_time \- returns the current time in seconds +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBtime_t\fR \fBddi_get_time\fR(\fBvoid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +\fBddi_get_time()\fR returns the current time in seconds since 00:00:00 UTC, +January 1, 1970. This value can be used to set of wait or expiration intervals. +.SH RETURN VALUES +.sp +.LP +\fBddi_get_time()\fR returns the time in seconds. +.SH CONTEXT +.sp +.LP + This routine can be called from any context. +.SH SEE ALSO +.sp +.LP +\fBddi_get_lbolt\fR(9F), \fBdrv_getparm\fR(9F), \fBdrv_usectohz\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP + \fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/ddi_getiminor.9f b/usr/src/man/man9f/ddi_getiminor.9f new file mode 100644 index 0000000000..13b5cd7288 --- /dev/null +++ b/usr/src/man/man9f/ddi_getiminor.9f @@ -0,0 +1,95 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_getiminor 9F "18 Nov 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_getiminor \- get kernel internal minor number from an external dev_t +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/mkdev.h> +#include <sys/ddi.h> + + + +\fBminor_t\fR \fBddi_getiminor\fR(\fBdev_t\fR \fIdev\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +This interface is obsolete. \fBgetminor\fR(9F) should be used instead. +.SH PARAMETERS +.sp +.LP +The following parameters are supported: +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 7n +.rt +Device number. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_getiminor()\fR extracts the minor number from a device number. This call +should be used only for device numbers that have been passed to the kernel from +the user space through opaque interfaces such as the contents of +\fBioctl\fR(9E) and \fBputmsg\fR(2). The device numbers passed in using +standard device entry points must continue to be interpreted using the +\fBgetminor\fR(9F) interface. This new interface is used to translate between +user visible device numbers and in kernel device numbers. The two numbers may +differ in a clustered system. +.sp +.LP +For certain bus types, you can call this \fBDDI\fR function from a +high-interrupt context. These types include \fBISA\fR and SBus buses. See +\fBsysbus\fR(4), \fBisa\fR(4), and \fBsbus\fR(4) for details. +.SH CONTEXT +.sp +.LP +\fBddi_getiminor()\fR can be called from user context only. +.SH RETURN VALUES +.sp +.LP +The minor number or \fBEMINOR_UNKNOWN\fR if the minor number of the device is +invalid. +.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 +\fBattributes\fR(5), \fBgetmajor\fR(9F), \fBgetminor\fR(9F), +\fBmakedevice\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +Drivers are required to replace calls to \fBddi_getminor.9f\fR by +\fBgetminor\fR(9F)) in order to compile under Solaris 10 and later versions. diff --git a/usr/src/man/man9f/ddi_in_panic.9f b/usr/src/man/man9f/ddi_in_panic.9f new file mode 100644 index 0000000000..8f021af385 --- /dev/null +++ b/usr/src/man/man9f/ddi_in_panic.9f @@ -0,0 +1,57 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_in_panic 9F "23 Jun 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_in_panic \- determine if system is in panic state +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_in_panic\fR(\fBvoid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +Drivers controlling devices on which the system may write a kernel crash dump +in the event of a panic can call \fBddi_in_panic()\fR to determine if the +system is panicking. +.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 \fBdelay\fR(9F) be relied upon, since it is implemented via +\fBtimeout\fR(9F). +.sp +.LP +Drivers that need to enforce a time delay such as \fBSCSI \fRbus reset delay +time must busy-wait when the system is panicking. +.SH RETURN VALUES +.sp +.LP +\fBddi_in_panic()\fR returns \fB1\fR if the system is in panic, or \fB0\fR +otherwise. +.SH CONTEXT +.sp +.LP +\fBddi_in_panic()\fR may be called from any context. +.SH SEE ALSO +.sp +.LP +\fBdump\fR(9E), \fBdelay\fR(9F), \fBddi_trigger_softintr\fR(9F), +\fBtimeout\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_intr_add_handler.9f b/usr/src/man/man9f/ddi_intr_add_handler.9f new file mode 100644 index 0000000000..9326ed69cf --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_add_handler.9f @@ -0,0 +1,224 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_intr_add_handler 9F "22 Apr 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_add_handler, ddi_intr_remove_handler \- add or remove interrupt +handler +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_intr_add_handler\fR(\fBddi_intr_handle_t *\fR\fIh\fR, + \fBddi_intr_handler_t\fR \fIinthandler\fR, \fBvoid *\fR\fIarg1\fR, + \fBvoid *\fR\fIarg2\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_intr_remove_handler\fR(\fBddi_intr_handle_t\fR \fIh\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +\fBddi_intr_add_handler()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 14n +.rt +Pointer to the DDI interrupt handle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinthandler\fR\fR +.ad +.RS 14n +.rt +Pointer to interrupt handler +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg1\fR\fR +.ad +.RS 14n +.rt +First argument for the interrupt handler +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg2\fR\fR +.ad +.RS 14n +.rt +Second, optional, argument for the interrupt handler +.RE + +.sp +.LP +\fBddi_intr_remove_handler()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 5n +.rt +DDI interrupt handle +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_intr_add_handler()\fR function adds an interrupt handler given by +the \fIinthandler\fR argument to the system with the handler arguments +\fIarg1\fR and \fIarg2\fR for the previously allocated interrupt handle +specified by the \fIh\fR pointer. The arguments \fIarg1\fR and \fIarg2\fR are +passed as the first and second arguments, respectively, to the interrupt +handler \fIinthandler\fR. See \fB<sys/ddi_intr.h>\fR for the definition of the +interrupt handler. +.sp +.LP +The routine \fIinthandler\fR with the arguments \fIarg1\fR and \fIarg2\fR is +called upon receipt of the appropriate interrupt. The interrupt handler should +return \fBDDI_INTR_CLAIMED\fR if the interrupt is claimed and +\fBDDI_INTR_UNCLAIMED\fR otherwise. +.sp +.LP +The \fBddi_intr_add_handler()\fR function must be called after +\fBddi_intr_alloc()\fR, but before \fBddi_intr_enable()\fR is called. The +interrupt must be enabled through \fBddi_intr_enable()\fR or +\fBddi_intr_block_enable()\fR before it can be used. +.sp +.LP +The \fBddi_intr_remove_handler()\fR function removes the handler association, +added previously with \fBddi_intr_add_handler()\fR, for the interrupt +identified by the interrupt handle \fIh\fR argument. Unloadable drivers should +call this routine during their \fBdetach\fR(9E) routine to remove the interrupt +handler from the system. +.sp +.LP +The \fBddi_intr_remove_handler()\fR function is used to disassociate the +handler after the interrupt is disabled to remove \fBdup-ed\fR interrupt +handles. See \fBddi_intr_dup_handler\fR(9F) for \fBdup-ed\fR interrupt handles. +If a handler is duplicated with the \fBddi_intr_dup_handler()\fR function, all +added and duplicated instances of the handler must be removed with +\fBddi_intr_remove_handler()\fR in order for the handler to be completely +removed. +.SH RETURN VALUES +.sp +.LP +The \fBddi_intr_add_handler()\fR and \fBddi_intr_remove_handler()\fR functions +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_EINVAL\fR\fR +.ad +.RS 15n +.rt +On encountering invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +On any implementation specific failure. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_intr_add_handler()\fR and \fBddi_intr_remove_handler()\fR functions +can be called from kernel non-interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E), +\fBddi_intr_alloc\fR(9F), \fBddi_intr_block_enable\fR(9F), +\fBddi_intr_disable\fR(9F), \fBddi_intr_dup_handler\fR(9F), +\fBddi_intr_enable\fR(9F), \fBddi_intr_free\fR(9F), +\fBddi_intr_get_supported_types\fR(9F), \fBmutex\fR(9F), \fBmutex_init\fR(9F), +\fBrw_init\fR(9F), \fBrwlock\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Consumers of these interfaces should verify that the return value is not equal +to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in +inconsistent behavior among platforms. +.sp +.LP +If a device driver that uses \fBMSI\fR and \fBMSI-X\fR interrupts resets the +device, the device might reset its configuration space modifications. Such a +reset could cause a device driver to lose any \fBMSI\fR and \fBMSI-X\fR +interrupt usage settings that have been applied. +.sp +.LP +The second argument, \fIarg2\fR, is optional. Device drivers are free to use +the two arguments however they see fit. There is no officially recommended +model or restrictions. For example, an interrupt handler may wish to use the +first argument as the pointer to its softstate and the second argument as the +value of the MSI vector. diff --git a/usr/src/man/man9f/ddi_intr_add_softint.9f b/usr/src/man/man9f/ddi_intr_add_softint.9f new file mode 100644 index 0000000000..169f3e0dce --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_add_softint.9f @@ -0,0 +1,575 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_intr_add_softint 9F "16 Oct 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_add_softint, ddi_intr_remove_softint, ddi_intr_trigger_softint, +ddi_intr_get_softint_pri, ddi_intr_set_softint_pri \- software interrupt +handling routines +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_intr_add_softint\fR(\fBdev_info_t *\fR\fIdip\fR, + \fBddi_softint_handle_t *\fR\fIh\fR, \fBint\fR \fIsoft_pri\fR, + \fBddi_intr_handler_t\fR \fIhandler\fR, \fBvoid *\fR\fIarg1\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_intr_trigger_softint\fR(\fBddi_softint_handle_t\fR \fIh\fR, + \fBvoid *\fR\fIarg2\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_intr_remove_softint\fR(\fBddi_softint_handle_t\fR \fIh\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_intr_get_softint_pri\fR(\fBddi_softint_handle_t\fR \fIh\fR, + \fBuint *\fR\fIsoft_prip\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_intr_set_softint_pri\fR(\fBddi_softint_handle_t\fR \fIh\fR, + \fBuint\fR \fIsoft_pri\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +\fBddi_intr_add_softint()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 12n +.rt +Pointer to a \fBdev_info\fR structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 12n +.rt +Pointer to the DDI soft interrupt handle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsoft_pri\fR\fR +.ad +.RS 12n +.rt +Priority to associate with a soft interrupt +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandler\fR\fR +.ad +.RS 12n +.rt +Pointer to soft interrupt handler +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg1\fR\fR +.ad +.RS 12n +.rt +Argument for the soft interrupt handler +.RE + +.sp +.LP +\fBddi_intr_trigger_softint()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 8n +.rt +DDI soft interrupt handle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg2\fR\fR +.ad +.RS 8n +.rt +Additional argument for the soft interrupt handler +.RE + +.sp +.LP +\fBddi_intr_remove_softint()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 5n +.rt +DDI soft interrupt handle +.RE + +.sp +.LP +\fBddi_intr_get_softint_pri()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 13n +.rt +DDI soft interrupt handle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsoft_prip\fR\fR +.ad +.RS 13n +.rt +Soft interrupt priority of the handle +.RE + +.sp +.LP +\fBddi_intr_set_softint_pri()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 13n +.rt +DDI soft interrupt handle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsoft_prip\fR\fR +.ad +.RS 13n +.rt +Soft interrupt priority of the handle +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_intr_add_softint()\fR function adds the soft interrupt handler given +by the \fIhandler\fR argument \fIarg1\fR. The \fIhandler\fR runs at the soft +interrupt priority given by the \fIsoft_pri\fR argument. +.sp +.LP +The value returned in the location pointed at by \fIh\fR is the soft interrupt +handle. This value is used in later calls to \fBddi_intr_remove_softint()\fR, +\fBddi_intr_trigger_softint()\fR and \fBddi_intr_set_softint_pri()\fR. +.sp +.LP +The software priority argument \fIsoft_pri\fR is a relative priority value +within the range of \fBDDI_INTR_SOFTPRI_MIN\fR and \fBDDI_INTR_SOFTPRI_MAX\fR. +If the driver does not know what priority to use, the default \fIsoft_pri\fR +value of \fBDDI_INTR_SOFTPRI_DEFAULT\fR could be specified. The default value +is the lowest possible soft interrupt priority value. +.sp +.LP +The \fIsoft_pri\fR argument contains the value needed to initialize the lock +associated with a soft interrupt. See \fBmutex_init\fR(9F) and +\fBrw_init\fR(9F). The handler cannot be triggered until the lock is +initiatized. +.sp +.LP +The \fBddi_intr_remove_softint()\fR function removes the handler for the soft +interrupt identified by the interrupt handle \fIh\fR argument. Once removed, +the soft interrupt can no longer be triggered, although any trigger calls in +progress can still be delivered to the handler. +.sp +.LP +Drivers must remove any soft interrupt handlers before allowing the system to +unload the driver. Otherwise, kernel resource leaks might occur. +.sp +.LP +The \fBddi_intr_trigger_softint()\fR function triggers the soft interrupt +specified by the interrupt handler \fIh\fR argument. A driver may optionally +specify an additional argument \fIarg2\fR that is passed to the soft interrupt +handler. Subsequent \fBddi_intr_trigger_softint()\fR events, along with +\fIarg2\fR, will be dropped until the one pending is serviced and returns the +error code \fBDDI_EPENDING\fR. +.sp +.LP +The routine \fIhandler\fR, with the \fIarg1\fR and \fIarg2\fR arguments, is +called upon the receipt of a software interrupt. These were registered through +a prior call to \fBddi_intr_add_softint()\fR. Software interrupt handlers must +not assume that they have work to do when they run. Like hardware interrupt +handlers, they may run because a soft interrupt has occurred for some other +reason. For example, another driver may have triggered a soft interrupt at the +same level. Before triggering the soft interrupt, the driver must indicate to +the soft interrupt handler that it has work to do. This is usually done by +setting a flag in the state structure. The routine \fIhandler\fR checks this +flag, reached through \fIarg1\fR and \fIarg2\fR, to determine if it should +claim the interrupt and do its work. +.sp +.LP +The interrupt handler must return \fBDDI_INTR_CLAIMED\fR if the interrupt was +claimed and \fBDDI_INTR_UNCLAIMED\fR otherwise. +.sp +.LP +The \fBddi_intr_get_softint_pri()\fR function retrieves the soft interrupt +priority, a small integer value, associated with the soft interrupt handle. The +handle is defined by the \fIh\fR argument, and the priority returned is in the +value of the integer pointed to by the \fIsoft_prip\fR argument. +.SH RETURN VALUES +.sp +.LP +The \fBddi_intr_add_softint()\fR, \fBddi_intr_remove_softint()\fR, +\fBddi_intr_trigger_softint()\fR, \fBddi_intr_get_softint_pri()\fR, +\fBddi_intr_set_softint_pri()\fR functions return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 16n +.rt +On success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EAGAIN\fR\fR +.ad +.RS 16n +.rt +On encountering internal error regarding currently unavailable resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EINVAL\fR\fR +.ad +.RS 16n +.rt +On encountering invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 16n +.rt +On any implementation specific failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EPENDING\fR\fR +.ad +.RS 16n +.rt +On encountering a previously triggered softint event that is pending. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_intr_add_softint()\fR, \fBddi_intr_remove_softint()\fR, +\fBddi_intr_trigger_softint()\fR, \fBddi_intr_get_softint_pri()\fR, +\fBddi_intr_set_softint_pri()\fR functions can be called from either user or +kernel non-interrupt context. +.SH EXAMPLES +.LP +\fBExample 1 \fRDevice using high-level interrupts +.sp +.LP +In the following example, the device uses high-level interrupts. High-level +interrupts are those that interrupt at the level of the scheduler and above. +High-level interrupts must be handled without using system services that +manipulate thread or process states, because these interrupts are not blocked +by the scheduler. In addition, high-level interrupt handlers must take care to +do a minimum of work because they are not preemptable. See +\fBddi_intr_get_hilevel_pri\fR(9F). + +.sp +.LP +In the example, the high-level interrupt routine minimally services the device, +and enqueues the data for later processing by the soft interrupt handler. If +the soft interrupt handler is not currently running, the high-level interrupt +routine triggers a soft interrupt so the soft interrupt handler can process the +data. Once running, the soft interrupt handler processes all the enqueued data +before returning. + +.sp +.LP +The state structure contains two mutexes. The high-level mutex is used to +protect data shared between the high-level interrupt handler and the soft +interrupt handler. The low-level mutex is used to protect the rest of the +driver from the soft interrupt handler. + +.sp +.in +2 +.nf +struct xxstate { + ... + ddi_intr_handle_t int_hdl; + int high_pri; + kmutex_t high_mutex; + ddi_softint_handle_t soft_hdl; + int low_soft_pri; + kmutex_t low_mutex; + int softint_running; + ... +}; + +struct xxstate *xsp; +static uint_t xxsoftint_handler(void *, void *); +static uint_t xxhighintr(void *, void *); +\&... +.fi +.in -2 + +.LP +\fBExample 2 \fRSample \fBattach()\fR routine +.sp +.LP +The following code fragment would usually appear in the driver's +\fBattach\fR(9E) routine. \fBddi_intr_add_handler\fR(9F) is used to add the +high-level interrupt handler and \fBddi_intr_add_softint()\fR is used to add +the low-level interrupt routine. + +.sp +.in +2 +.nf +static uint_t +xxattach(dev_info_t *dip, ddi_attach_cmd_t cmd) +{ + int types; + int *actual; + int nintrs; + struct xxstate *xsp; + ... + + (void) ddi_intr_get_supported_types(dip, &types); + (void) ddi_intr_get_nintrs(dip< DDI_INTR_TYPE_FIXED, *nintrs); + (void) ddi_intr_alloc(dip, &xsp->int_hdl, DDI_INTR_TYPE_FIXED, + 1, nintrs, *actual, 0); + + /* initialize high-level mutex */ + (void) ddi_intr_get_pri(xsp->int_hdl, &>high_pri); + mutex_init(&xsp->high_mutex, NULL, MUTEX_DRIVER, + DDI_INTR_PRI(xsp->high_pri)); + + /* Ensure that this is a hi-level interrupt */ + if (ddi_intr_get_hilevel_pri(h) != DDI_SUCCESS) { + /* cleanup */ + return (DDI_FAILURE); /* fail attach */ + } + + /* add high-level routine - xxhighintr() */ + if (ddi_intr_add_handler(xsp->int_hdl, xxhighintr, + arg1, NULL) != DDI_SUCCESS) { + /* cleanup */ + return (DDI_FAILURE); /* fail attach */ + } + + /* Enable high-level routine - xxhighintr() */ + if (ddi_intr_enable(xsp->int_hdl) != DDI_SUCCESS) { + /* cleanup */ + return (DDI_FAILURE); /* fail attach */ + } + + /* Enable soft interrupts */ + xsp->low_soft_pri = DDI_INTR_SOFTPRI_MIN; + if (ddi_intr_add_softint(dip, &xsp>soft_hdl, + xsp->low_soft_pri, xxsoftint_handler, arg1) != DDI_SUCCESS) { + /* clean up */ + return (DDI_FAILURE); /* fail attach */ + } + + /* initialize low-level mutex */ + mutex_init(&xsp->low_mutex, NULL, MUTEX_DRIVER, + DDI_INTR_PRI(xsp->low_soft_pri)); + + ... +} +.fi +.in -2 + +.LP +\fBExample 3 \fRHigh-level interrupt routine +.sp +.LP +The next code fragment represents the high-level interrupt routine. The +high-level interrupt routine minimally services the device and enqueues the +data for later processing by the soft interrupt routine. If the soft interrupt +routine is not already running, \fBddi_intr_trigger_softint()\fR is called to +start the routine. The soft interrupt routine will run until there is no more +data on the queue. + +.sp +.in +2 +.nf +static uint_t +xxhighintr(void *arg1, void *arg2) +{ + struct xxstate *xsp = (struct xxstate *)arg1; + int need_softint; + ... + mutex_enter(&xsp->high_mutex); + /* + * Verify this device generated the interrupt + * and disable the device interrupt. + * Enqueue data for xxsoftint_handler() processing. + */ + + /* is xxsoftint_handler() already running ? */ + need_softint = (xsp->softint_running) ? 0 : 1; + mutex_exit(&xsp->high_mutex); + + /* read-only access to xsp->id, no mutex needed */ + if (xsp->soft_hdl && need_softint) + ddi_intr_trigger_softint(xsp->soft_hdl, arg2); + ... + return (DDI_INTR_CLAIMED); +} + + +static uint_t +xxsoftint_handler(void *arg1, void *arg2) +{ + struct xxstate *xsp = (struct xxstate *)arg1; + ... + mutex_enter(&xsp->low_mutex); + mutex_enter(&xsp->high_mutex); + + /* verify there is work to do */ + if (work queue empty || xsp->softint_running ) { + mutex_exit(&xsp->high_mutex); + mutex_exit(&xsp->low_mutex); + return (DDI_INTR_UNCLAIMED); + } + + xsp->softint_running = 1; + + while ( data on queue ) { + ASSERT(mutex_owned(&xsp->high_mutex)); + /* de-queue data */ + mutex_exit(&xsp->high_mutex); + + /* Process data on queue */ + mutex_enter(&xsp->high_mutex); + } + + xsp->softint_running = 0; + mutex_exit(&xsp->high_mutex); + mutex_exit(&xsp->low_mutex); + return (DDI_INTR_CLAIMED); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBattach\fR(9E), \fBddi_intr_alloc\fR(9F), +\fBddi_intr_free\fR(9F), \fBddi_intr_get_hilevel_pri\fR(9F), +\fBmutex_init\fR(9F), \fBrw_init\fR(9F), \fBrwlock\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Consumers of these interfaces should verify that the return value is not equal +to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in +inconsistent behavior among platforms. +.sp +.LP +The \fBddi_intr_add_softint()\fR may not be used to add the same software +interrupt handler more than once. This is true even if a different value is +used for \fIarg1\fR in each of the calls to \fBddi_intr_add_softint()\fR. +Instead, the argument passed to the interrupt handler should indicate what +service(s) the interrupt handler should perform. For example, the argument +could be a pointer to the soft state structure of the device that could contain +a \fBwhich_service\fR field that the handler examines. The driver must set this +field to the appropriate value before calling \fBddi_intr_trigger_softint()\fR. +.sp +.LP +Every time a modifiable valid second argument, \fIarg2\fR, is provided when +\fBddi_intr_trigger_softint()\fR is invoked, the DDI framework saves \fIarg2\fR +internally and passes it to the interrupt handler \fIhandler\fR. +.sp +.LP +A call to \fBddi_intr_set_softint_pri()\fR could fail if a previously scheduled +soft interrupt trigger is still pending. diff --git a/usr/src/man/man9f/ddi_intr_alloc.9f b/usr/src/man/man9f/ddi_intr_alloc.9f new file mode 100644 index 0000000000..069b1428cd --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_alloc.9f @@ -0,0 +1,284 @@ +'\" 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 ddi_intr_alloc 9F "23 Apr 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_alloc, ddi_intr_free \- allocate or free interrupts for a given +interrupt type +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_intr_alloc\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_intr_handle_t *\fR\fIh_array\fR, \fBint\fR \fItype\fR, + \fBint\fR \fIinum\fR, \fBint\fR \fIcount\fR, \fBint *\fR\fIactualp\fR, \fBint\fR \fIbehavior\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_intr_free\fR(\fBddi_intr_handle_t\fR \fIh\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +\fBddi_intr_alloc()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 12n +.rt +Pointer to the \fBdev_info\fR structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIh_array\fR\fR +.ad +.RS 12n +.rt +Pointer to an array of DDI interrupt handles +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 12n +.rt +Interrupt type +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinum\fR\fR +.ad +.RS 12n +.rt +Interrupt number +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcount\fR\fR +.ad +.RS 12n +.rt +Number of interrupts requested. The \fIcount\fR should not exceed the total +number of interrupts supported by the device, as returned by a call to +\fBddi_intr_get_nintrs\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIactualp\fR\fR +.ad +.RS 12n +.rt +Pointer to the number of interrupts actually allocated +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbehavior\fR\fR +.ad +.RS 12n +.rt +Flag to determine the allocation algorithm +.RE + +.sp +.LP +\fBddi_intr_free()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 5n +.rt +DDI interrupt handle +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_intr_alloc()\fR function allocates interrupts of the interrupt type +given by the \fItype\fR argument beginning at the interrupt number \fIinum\fR. +If \fBddi_intr_alloc()\fR allocates any interrupts, it returns the actual +number of interrupts allocated in the integer pointed to by the \fIactualp\fR +argument and returns the number of interrupt handles in the interrupt handle +array pointed to by the \fIh_array\fR argument. +.sp +.LP +Specific interrupts are always specified by the combination of interrupt +\fItype\fR and \fIinum\fR. For legacy devices, \fIinum\fR refers to the nth +interrupt, typically as defined by the devices \fBinterrupts\fR property. For +PCI fixed interrupts, \fIinum\fR refers to the interrupt number. The \fIinum\fR +is the relative interrupt vector number, from \fB0\fR to \fB31\fR for MSI, from +\fB0\fR to \fB2047\fR for MSI-X. The first interrupt vector is \fB0\fR. The +last relative vector is \fB31\fR for MSI or \fB2047\fR for MSI-X. +.sp +.LP +The \fIh_array\fR must be pre-allocated by the caller as a \fIcount\fR sized +array of ddi_intr_handle_t's. +.sp +.LP +If MSI interrupts are being allocated, the \fIcount\fR argument passed should +be a number between \fB1\fR and \fB32\fR, specified as a power of two. If +\fIcount\fR is not specified as a power of two, the error \fBDDI_EINVAL\fR is +returned. +.sp +.LP +The behavior flag controls the interrupt allocation algorithm. It takes one of +two input values: \fBDDI_INTR_ALLOC_NORMAL\fR or \fBDDI_INTR_ALLOC_STRICT\fR. +If the \fIcount\fR value used is greater than \fBNINTRs\fR, then the call fails +with \fBDDI_EINVAL\fR unconditionally. When set to \fBDDI_INTR_ALLOC_STRICT\fR, +the call succeeds if and only if \fIcount\fR interrupts are allocated. +Otherwise, the call fails, and the number of available interrupts is returned +in \fIactualp\fR. When set to \fBDDI_INTR_ALLOC_NORMAL\fR, the call succeeds if +at least one interrupt is allocated, and the number of allocated interrupts is +returned in actualp. +.sp +.LP +The handle for each allocated interrupt, if any, is returned in the array of +handles given by the \fIh_array\fR argument. +.sp +.LP +The \fBddi_intr_free()\fR function releases the system resources and interrupt +vectors associated with the ddi_intr_handle_t \fIh\fR, including any resources +associated with the handle \fIh\fR itself. Once freed, the handle \fIh\fR +should not be used in any further calls. +.sp +.LP +The \fBddi_intr_free()\fR function should be called once for each handle in the +handle array. +.SH RETURN VALUES +.sp +.LP +The \fBddi_intr_alloc()\fR and \fBddi_intr_free()\fR functions return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 21n +.rt +On success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EAGAIN\fR\fR +.ad +.RS 21n +.rt +Not enough interrupt resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EINVAL\fR\fR +.ad +.RS 21n +.rt +On encountering invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_INTR_NOTFOUND\fR\fR +.ad +.RS 21n +.rt +On failure to find the interrupt. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 21n +.rt +On any implementation specific failure. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_intr_alloc()\fR and \fBddi_intr_free()\fR functions can be called +from kernel non-interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_intr_add_handler\fR(9F), +\fBddi_intr_block_enable\fR(9F), \fBddi_intr_disable\fR(9F), +\fBddi_intr_enable\fR(9F), \fBddi_intr_get_cap\fR(9F), +\fBddi_intr_get_nintrs\fR(9F), \fBddi_intr_get_pri\fR(9F), +\fBddi_intr_get_supported_types\fR(9F), \fBddi_intr_remove_handler\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Consumers of these interfaces should verify that the return value is not equal +to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in +inconsistent behavior among platforms. +.sp +.LP +If a device driver that uses \fBMSI\fR and \fBMSI-X\fR interrupts resets the +device, the device might reset its configuration space modifications. Such a +reset could cause a device driver to lose any \fBMSI\fR and \fBMSI-X\fR +interrupt usage settings that have been applied. diff --git a/usr/src/man/man9f/ddi_intr_dup_handler.9f b/usr/src/man/man9f/ddi_intr_dup_handler.9f new file mode 100644 index 0000000000..26618f16e2 --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_dup_handler.9f @@ -0,0 +1,312 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_intr_dup_handler 9F "09 May 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_dup_handler \- reuse interrupt handler and arguments for MSI-X +interrupts +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_intr_dup_handler\fR(\fBddi_intr_handle_t\fR \fIprimary\fR, \fBint\fR \fIvector\fR, + \fBddi_intr_handle_t *\fR\fInew\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIprimary\fR\fR +.ad +.RS 11n +.rt +Original DDI interrupt handle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvector\fR\fR +.ad +.RS 11n +.rt +Interrupt number to duplicate +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInew\fR\fR +.ad +.RS 11n +.rt +Pointer to new DDI interrupt handle +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_intr_dup_handler()\fR function is a feature for MSI-X interrupts +that allows an unallocated interrupt vector of a device to use a previously +initialized or added primary MSI-X interrupt vector in order to share the same +vector address, vector data, interrupt handler, and handler arguments. This +feature allows a driver to alias the resources provided by the Solaris +Operating System to the unallocated interrupt vectors on an associated device. +For example, if 2 MSI-X interrupts were allocated to a driver and 32 interrupts +were supported on the device, the driver could alias the 2 interrupts it +received to the 30 remaining on the device. +.sp +.LP +The \fBddi_intr_dup_handler()\fR function must be called after the primary +interrupt handle has been added to the system or enabled by +\fBddi_intr_add_handler\fR(9F) and \fBddi_intr_enable\fR(9F) calls, +respectively. If successful, the function returns the new interrupt handle for +a given vector in the \fInew\fR argument passed to the function. The new +interrupt handle must not have been previously allocated with +\fBddi_intr_alloc\fR(9F). Otherwise, the \fBddi_intr_dup_handler()\fR call will +fail. +.sp +.LP +The only supported calls on \fIdup-ed\fR interrupt handles are +\fBddi_intr_set_mask\fR(9F), \fBddi_intr_clr_mask\fR(9F), +\fBddi_intr_get_pending\fR(9F), \fBddi_intr_enable\fR(9F), +\fBddi_intr_disable\fR(9F), and \fBddi_intr_free\fR(9F). +.sp +.LP +A call to \fBddi_intr_dup_handler()\fR does not imply that the interrupt source +is automatically enabled. Initially, the dup-ed handle is in the disabled state +and must be enabled before it can be used by calling \fBddi_intr_enable()\fR. +Likewise, \fBddi_intr_disable()\fR must be called to disable the enabled dup-ed +interrupt source. +.sp +.LP +A dup-ed interrupt is removed by calling \fBddi_intr_free()\fR after it has +been disabled. The \fBddi_intr_remove_handler\fR(9F) call is not required for a +dup-ed handle. +.sp +.LP +Before removing the original MSI-X interrupt handler, all dup-ed interrupt +handlers associated with this MSI-X interrupt must have been disabled and +freed. Otherwise, calls to \fBddi_intr_remove_handler()\fR will fail with +\fBDDI_FAILURE\fR. +.sp +.LP +See the EXAMPLES section for code that illustrates the use of the +\fBddi_intr_dup_handler()\fR function. +.SH RETURN VALUES +.sp +.LP +The \fBddi_intr_dup_handler()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +On success. +.sp +Note that the interface should be verified to ensure that the return value is +not equal to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could +result in inconsistent behavior among platforms. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EINVAL\fR\fR +.ad +.RS 15n +.rt +On encountering invalid input parameters. \fBDDI_EINVAL\fR is also returned if +a dup is attempted from a dup-ed interrupt or if the hardware device is found +not to support MSI-X interrupts. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +On any implementation specific failure. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing the \fBddi_intr_dup_handler()\fR function +.sp +.in +2 +.nf +int +add_msix_interrupts(intr_state_t *state) +{ + int x, y; + + /* + * For this example, assume the device supports multiple + * interrupt vectors, but only request to be allocated + * 1 MSI-X to use and then dup the rest. + */ + if (ddi_intr_get_nintrs(state->dip, DDI_INTR_TYPE_MSIX, + &state->intr_count) != DDI_SUCCESS) { + cmn_err(CE_WARN, "Failed to retrieve the MSI-X interrupt count"); + return (DDI_FAILURE); + } + + state->intr_size = state->intr_count * sizeof (ddi_intr_handle_t); + state->intr_htable = kmem_zalloc(state->intr_size, KM_SLEEP); + + /* Allocate one MSI-X interrupt handle */ + if (ddi_intr_alloc(state->dip, state->intr_htable, + DDI_INTR_TYPE_MSIX, state->inum, 1, &state->actual, + DDI_INTR_ALLOC_STRICT) != DDI_SUCCESS) { + cmn_err(CE_WARN, "Failed to allocate MSI-X interrupt"); + kmem_free(state->intr_htable, state->intr_size); + return (DDI_FAILURE); + } + + /* Get the count of how many MSI-X interrupts we dup */ + state->dup_cnt = state->intr_count - state->actual; + + if (ddi_intr_get_pri(state->intr_htable[0], + &state->intr_pri) != DDI_SUCCESS) { + cmn_err(CE_WARN, "Failed to get interrupt priority"); + goto error1; + } + + /* Make sure the MSI-X priority is below 'high level' */ + if (state->intr_pri >= ddi_intr_get_hilevel_pri()) { + cmn_err(CE_WARN, "Interrupt PRI is too high"); + goto error1; + } + + /* + * Add the handler for the interrupt + */ + if (ddi_intr_add_handler(state->intr_htable[0], + (ddi_intr_handler_t *)intr_isr, (caddr_t)state, + NULL) != DDI_SUCCESS) { + cmn_err(CE_WARN, "Failed to add interrupt handler"); + goto error1; + } + + /* Enable the main MSI-X handle first */ + if (ddi_intr_enable(state->intr_htable[0]) != DDI_SUCCESS) { + cmn_err(CE_WARN, "Failed to enable interrupt"); + goto error2; + } + + /* + * Create and enable dups of the original MSI-X handler, note + * that the inum we are using starts at 0. + */ + for (x = 1; x < state->dup_cnt; x++) { + if (ddi_intr_dup_handler(state->intr_htable[0], + state->inum + x, &state->intr_htable[x]) != DDI_SUCCESS) { + for (y = x - 1; y > 0; y--) { + (void) ddi_intr_disable(state->intr_htable[y]); + (void) ddi_intr_free(state->intr_htable[y]); + } + + goto error2; + } + if (ddi_intr_enable(state->intr_htable[x]) != DDI_SUCCESS) { + for (y = x; y > 0; y--) { + (void) ddi_intr_disable(state->intr_htable[y]); + (void) ddi_intr_free(state->intr_htable[y]); + } + + goto error2; + } + } + + return (DDI_SUCCESS); + +error2: + (void) ddi_intr_remove_handler(state->intr_htable[0]); +error1: + (void) ddi_intr_free(state->intr_htable[0]); + + kmem_free(state->intr_htable, state->intr_size); + return (DDI_FAILURE); +} + +void +remove_msix_interrupts(intr_state_t *state) +{ + int x; + + /* + * Disable all the handles and free the dup-ed handles + * before we can remove the main MSI-X interrupt handle. + */ + for (x = 1; x < state->dup_cnt; x++) { + (void) ddi_intr_disable(state->intr_htable[x]); + (void) ddi_intr_free(state->intr_htable[x]); + } + + /* + * We can remove and free the main MSI-X handler now + * that all the dups have been freed. + */ + (void) ddi_intr_disable(state->intr_htable[0]); + (void) ddi_intr_remove_handler(state->intr_htable[0]); + (void) ddi_intr_free(state->intr_htable[0]); + + kmem_free(state->intr_htable, state->intr_size); +} +.fi +.in -2 + +.SH CONTEXT +.sp +.LP +The \fBddi_intr_dup_handler()\fR function can be called from kernel +non-interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_intr_add_handler\fR(9F), \fBddi_intr_alloc\fR(9F), +\fBddi_intr_clr_mask\fR(9F), \fBddi_intr_disable\fR(9F), +\fBddi_intr_enable\fR(9F), \fBddi_intr_free\fR(9F), +\fBddi_intr_get_pending\fR(9F), \fBddi_intr_get_supported_types\fR(9F), +\fBddi_intr_set_mask\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_intr_enable.9f b/usr/src/man/man9f/ddi_intr_enable.9f new file mode 100644 index 0000000000..550c4d9a70 --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_enable.9f @@ -0,0 +1,262 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_intr_enable 9F "22 Apr 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_enable, ddi_intr_block_enable, ddi_intr_disable, +ddi_intr_block_disable \- enable or disable a given interrupt or range of +interrupts +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_intr_enable\fR(\fBddi_intr_handle_t\fR \fIh\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_intr_block_enable\fR(\fBddi_intr_handle_t *\fR\fIh_array\fR, \fBint\fR \fIcount\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_intr_disable\fR(\fBddi_intr_handle_t\fR \fIh\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_intr_block_disable\fR(\fBddi_intr_handle_t *\fR\fIh_array\fR, \fBint\fR \fIcount\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +\fBddi_intr_enable()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 5n +.rt +DDI interrupt handle +.RE + +.sp +.LP +\fBddi_intr_block_enable()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh_array\fR\fR +.ad +.RS 11n +.rt +Pointer to an array of DDI interrupt handles +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcount\fR\fR +.ad +.RS 11n +.rt +Number of interrupts +.RE + +.sp +.LP +\fBddi_intr_disable()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 5n +.rt +DDI interrupt handle +.RE + +.sp +.LP +\fBddi_intr_block_disable()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh_array\fR\fR +.ad +.RS 11n +.rt +Pointer to an array of DDI interrupt handles +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcount\fR\fR +.ad +.RS 11n +.rt +Number of interrupts +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_intr_enable()\fR function enables the interrupt given by the +interrupt handle \fIh\fR. +.sp +.LP +The \fBddi_intr_block_enable()\fR function enables a range of interrupts given +by the \fIcount\fR and \fIh_array\fR arguments, where \fIcount\fR must be at +least \fB1\fR and \fIh_array\fR is pointer to a count-sized array of interrupt +handles. +.sp +.LP +The \fBddi_intr_block_enable()\fR function can be used only if the device or +host bridge supports the block enable/disable feature. The +\fBddi_intr_get_cap()\fR function returns the \fBRO\fR flag +\fBDDI_INTR_FLAG_BLOCK\fR if the device or host bridge supports the interrupt +block enable/disable feature for the given interrupt type. The +\fBddi_intr_block_enable()\fR function is useful for enabling MSI interrupts +when the optional per-vector masking capability is not supported. +.sp +.LP +The \fBddi_intr_enable()\fR or \fBddi_intr_block_enable()\fR functions must be +called after the required interrupt resources are allocated with +\fBddi_intr_alloc()\fR, the interrupt handlers are added through +\fBddi_intr_add_handler()\fR, and the required locks are initialized by +\fBmutex\fR(9F) or \fBrwlock\fR(9F). +.sp +.LP +Once enabled by either of the enable calls, the interrupt can be taken and +passed to the driver's interrupt service routine. Enabling an interrupt implies +clearing any system or device mask bits associated with the interrupt. +.sp +.LP +The \fBddi_intr_disable()\fR function disables the interrupt given by the +interrupt handle \fIh\fR. +.sp +.LP +The \fBddi_intr_block_disable()\fR function disables a range of interrupts +given by the \fIcount\fR and \fIh_array\fR arguments, where \fIcount\fR must be +at least \fB1\fR and \fIh_array\fR is pointer to a count-sized array of +interrupt handles. +.sp +.LP +The \fBddi_intr_block_disable()\fR function can be used only if the device or +host bridge supports the block enable/disable feature. The +\fBddi_intr_get_cap()\fR function returns the \fBRO\fR flag +\fBDDI_INTR_FLAG_BLOCK\fR if the device or host bridge supports the interrupt +block enable/disable feature for the given interrupt type. The +\fBddi_intr_block_disable()\fR function is useful for disabling MSI interrupts +when the optional per-vector masking capability is not supported. +.sp +.LP +The \fBddi_intr_disable()\fR or \fBddi_intr_block_disable()\fR functions must +be called before removing the interrupt handler and freeing the corresponding +interrupt with \fBddi_intr_remove_handler()\fR and \fBddi_intr_free()\fR, +respectively. The \fBddi_intr_block_disable()\fR function should be called if +the \fBddi_intr_block_enable()\fR function was used to enable the interrupts. +.SH RETURN VALUES +.sp +.LP +The \fBddi_intr_enable()\fR, \fBddi_intr_block_enable()\fR, +\fBddi_intr_disable()\fR, and \fBddi_intr_block_disable()\fR functions 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_EINVAL\fR\fR +.ad +.RS 15n +.rt +On encountering invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +On any implementation specific failure. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_intr_enable()\fR, \fBddi_intr_block_enable()\fR, +\fBddi_intr_disable()\fR, and \fBddi_intr_block_disable()\fR functions can be +called from kernel non-interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_intr_add_handler\fR(9F), \fBddi_intr_alloc\fR(9F), +\fBddi_intr_dup_handler\fR(9F), \fBddi_intr_free\fR(9F), +\fBddi_intr_get_cap\fR(9F), \fBddi_intr_remove_handler\fR(9F), \fBmutex\fR(9F), +\fBrwlock\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Consumers of these interfaces should verify that the return value is not equal +to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in +inconsistent behavior among platforms. +.sp +.LP +If a device driver that uses \fBMSI\fR and \fBMSI-X\fR interrupts resets the +device, the device might reset its configuration space modifications. Such a +reset could cause a device driver to lose any \fBMSI\fR and \fBMSI-X\fR +interrupt usage settings that have been applied. diff --git a/usr/src/man/man9f/ddi_intr_get_cap.9f b/usr/src/man/man9f/ddi_intr_get_cap.9f new file mode 100644 index 0000000000..4f01280e67 --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_get_cap.9f @@ -0,0 +1,248 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_intr_get_cap 9F "20 Apr 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_get_cap, ddi_intr_set_cap \- get or set interrupt capabilities for a +given interrupt type +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_intr_get_cap\fR(\fBddi_intr_handle_t\fR \fIh\fR, \fBint *\fR\fIflagsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_intr_set_cap\fR(\fBddi_intr_handle_t\fR \fIh\fR, \fBint\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +\fBddi_intr_get_cap()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 10n +.rt +DDI interrupt handle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflagsp\fR\fR +.ad +.RS 10n +.rt +Pointer to the capability flags returned for this handle +.RE + +.sp +.LP +\fBddi_intr_set_cap()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 9n +.rt +DDI interrupt handle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 9n +.rt +Contains the capability flag to be set +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_intr_get_cap()\fR function returns the interrupt capability flags +for the interrupt handle \fIh\fR. Upon a successful return, the flags are +returned in the integer pointed to by the \fIflagsp\fR argument. +.sp +.LP +These flags are typically combinations of the following: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_INTR_FLAG_EDGE\fR\fR +.ad +.RS 26n +.rt +For discrete interrupts, the host supports \fBedge\fR type of trigger. This +flag is not returned for \fBDDI_INTR_TYPE_MSI\fR or \fBDDI_INTR_TYPE_MSIX\fR +interrupt types. This is a read-write (RW) flag. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_INTR_FLAG_LEVEL\fR\fR +.ad +.RS 26n +.rt +For discrete interrupts the host supports \fBlevel\fR, \fBedge\fR, or both +types of triggers. This flag is not returned for \fBDDI_INTR_TYPE_MSI\fR or +\fBDDI_INTR_TYPE_MSIX\fR interrupt types. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_INTR_FLAG_MASKABLE\fR\fR +.ad +.RS 26n +.rt +The interrupt can be masked either by the device or by the host bridge, or +optionally by the host. This is a read-only (\fBRO\fR) flag. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_INTR_FLAG_PENDING\fR\fR +.ad +.RS 26n +.rt +The interrupt supports an interrupt pending bit. This is a read-only (\fBRO\fR) +flag. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_INTR_FLAG_BLOCK\fR\fR +.ad +.RS 26n +.rt +All interrupts of the given type must be block-enabled and are not individually +maskable. This is a read-only (\fBRO\fR) flag. +.RE + +.sp +.LP +The \fBddi_intr_set_cap()\fR function allows a driver to specify the capability +flags for the interrupt handle \fIh\fR. Only \fBDDI_INTR_FLAG_LEVEL\fR and +\fBDDI_INTR_FLAG_EDGE\fR flags can be set. Some devices can support both level +and edge capability and either can be set by using the \fBddi_intr_set_cap()\fR +function. Setting the capability flags is device and platform dependent. +.sp +.LP +The \fBddi_intr_set_cap()\fR function can be called after interrupts are +allocated and prior to adding the interrupt handler. For all other times it +returns failure. +.SH RETURN VALUES +.sp +.LP +The \fBddi_intr_get_cap()\fR and \fBddi_intr_set_cap()\fR functions 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_EINVAL\fR\fR +.ad +.RS 15n +.rt +On encountering invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +On any implementation specific failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_ENOTSUP\fR\fR +.ad +.RS 15n +.rt +On device not supporting operation. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_intr_get_cap()\fR and \fBddi_intr_set_cap()\fR functions can be +called from either user or kernel non-interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_intr_alloc\fR(9F), \fBddi_intr_block_enable\fR(9F), +\fBddi_intr_get_nintrs\fR(9F), \fBddi_intr_get_pending\fR(9F), +\fBddi_intr_get_supported_types\fR(9F), \fBddi_intr_set_mask\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Consumers of these interfaces should verify that the return value is not equal +to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in +inconsistent behavior among platforms. diff --git a/usr/src/man/man9f/ddi_intr_get_hilevel_pri.9f b/usr/src/man/man9f/ddi_intr_get_hilevel_pri.9f new file mode 100644 index 0000000000..2edc8bba4b --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_get_hilevel_pri.9f @@ -0,0 +1,93 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_intr_get_hilevel_pri 9F "07 Apr 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_get_hilevel_pri \- get minimum priority level for a high-level +interrupt +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_intr_get_hilevel_pri\fR(\fBvoid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +Upon a successful return, the \fBddi_intr_get_hilevel_pri()\fR function returns +the minimum priority level for a high-level interrupt. The return priority +value can be used to compare to other priority values, such as those returned +from \fBddi_intr_get_pri\fR(9F), to determine if a given interrupt priority is +a high-level interrupt. +.sp +.LP +High-level interrupts must be handled without using system services that +manipulate thread or process states, because such interrupts are not blocked by +the scheduler. +.sp +.LP +In addition, high-level interrupt handlers must take care to do a minimum of +work because they cannot be preempted. +.sp +.LP +A typical high-level interrupt handler puts data into a circular buffer and +schedule a soft interrupt by calling \fBddi_intr_trigger_softint()\fR. The +circular buffer can be protected by using a mutex that is properly initialized +for the interrupt handler. +.sp +.LP +The \fBddi_intr_get_hilevel_pri()\fR function can be used before calling +\fBddi_intr_add_handler()\fR to help determine which type of interrupt handler +can be used. Most device drivers are designed with the knowledge that supported +devices always generate low level interrupts. On some machines, however, +interrupts are high-level above the scheduler level and on other machines they +are not. Devices such as those those using SBus interrupts or VME bus level 6 +or 7 interrupts must use the \fBddi_intr_get_hilevel_pri()\fR function to test +the type of interrupt handler that can be used. +.SH RETURN VALUES +.sp +.LP +The \fBddi_intr_get_hilevel_pri()\fR function returns the priority value for a +high-level interrupt. +.SH CONTEXT +.sp +.LP +The \fBddi_intr_get_hilevel_pri()\fR function can be called from either user or +kernel non-interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_intr_add_handler\fR(9F), \fBddi_intr_alloc\fR(9F), +\fBddi_intr_enable\fR(9F), \fBddi_intr_get_pri\fR(9F), +\fBddi_intr_trigger_softint\fR(9F), \fBmutex\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_intr_get_nintrs.9f b/usr/src/man/man9f/ddi_intr_get_nintrs.9f new file mode 100644 index 0000000000..da8f72d885 --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_get_nintrs.9f @@ -0,0 +1,230 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_intr_get_nintrs 9F "13 November 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_get_nintrs, ddi_intr_get_navail \- return number of interrupts +supported or available for a given interrupt type +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_intr_get_nintrs\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fItype\fR, \fBint *\fR\fInintrsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_intr_get_navail\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fItype\fR, \fBint *\fR\fInavailp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +\fBddi_intr_get_nintrs()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 11n +.rt +Pointer to \fBdev_info\fR structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 11n +.rt +Interrupt type +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInintrsp\fR\fR +.ad +.RS 11n +.rt +Pointer to number of interrupts of the given type that are supported by the +system +.RE + +.sp +.LP +\fBddi_intr_get_navail()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 11n +.rt +Pointer to \fBdev_info\fR structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 11n +.rt +Interrupt type +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInavailp\fR\fR +.ad +.RS 11n +.rt +Pointer to number of interrupts of the given type that are currently available +from the system +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_intr_get_nintrs()\fR function returns the number of interrupts of +the given \fItype\fR supported by a particular hardware device. On a successful +return, the number of supported interrupts is returned as an integer pointed to +by the \fInintrsp\fR argument. +.sp +.LP +If the hardware device is not found to support any interrupts of the given +\fItype\fR, the \fBDDI_INTR_NOTFOUND\fR failure is returned rather than a zero +in \fInintrsp\fR. +.sp +.LP +The \fBddi_intr_get_navail()\fR function returns the number of interrupts of a +given \fItype\fR that is available to a particular hardware device. On a +successful return, the number of available interrupts is returned as an integer +pointed to by \fInavailp\fR. +.sp +.LP +The hardware device may support more than one interrupt and can request that +all interrupts be allocated. The host software can then use policy-based +decisions to determine how many interrupts are made available to the device. +Based on the determination, a value is returned that should be used to allocate +interrupts with the \fBddi_int_alloc()\fR function. +.sp +.LP +The \fBddi_intr_get_supported_types\fR(9F) function returns a list of valid +supported types for the given hardware device. It must be called prior to +calling either the \fBddi_intr_get_nintrs()\fR or \fBddi_intr_get_navail()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_intr_get_nintrs()\fR and \fBddi_intr_get_navail()\fR functions +return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 21n +.rt +On success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EINVAL\fR\fR +.ad +.RS 21n +.rt +On encountering invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_INTR_NOTFOUND\fR\fR +.ad +.RS 21n +.rt +On not finding any interrupts for the given interrupt type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 21n +.rt +On any implementation specific failure. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_intr_get_nintrs()\fR and \fBddi_intr_get_navail()\fR functions can +be called from either user or kernel non-interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_intr_alloc\fR(9F), \fBddi_intr_enable\fR(9F), +\fBddi_intr_get_supported_types\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The \fBddi_intr_get_nintrs()\fR and \fBddi_intr_get_navail()\fR functions can +be called at any time, even if the driver has added an interrupt handler for a +given interrupt specification. +.sp +.LP +On x86 platforms, the number of interrupts returned by the +\fBddi_intr_get_navail()\fR function might need to be further reduced by the +number of interrupts available for each interrupt priority on the system. In +that case, drivers should use different priorities for some of the interrupts. +.sp +.LP +Consumers of these interfaces should verify that the return value is not equal +to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in +inconsistent behavior among platforms. diff --git a/usr/src/man/man9f/ddi_intr_get_pending.9f b/usr/src/man/man9f/ddi_intr_get_pending.9f new file mode 100644 index 0000000000..fcce848eb9 --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_get_pending.9f @@ -0,0 +1,147 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_intr_get_pending 9F "07Apr 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_get_pending \- get pending bit for a given interrupt +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_intr_get_pending\fR(\fBddi_intr_handle_t\fR \fIh\fR, \fBint *\fR\fIpendingp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 12n +.rt +DDI interrupt handle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpendingp\fR\fR +.ad +.RS 12n +.rt +Pointer to the pending capability returned for this handle +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_intr_get_pending()\fR function returns non-zero as the integer +pointed to by the \fIpendingp\fR argument if a corresponding interrupt is +pending. The corresponding interrupt handle \fIh\fR must already be allocated. +The call succeeds if the device or host bridge supports the ability to read the +interrupt pending bits of its interrupts. The driver should use +\fBddi_intr_get_cap()\fR function to see if the \fBDDI_INTR_FLAG_PENDING\fR +flag is returned to indicate that interrupts support interrupt pending bits. +.sp +.LP +If the \fBDDI_INTR_FLAG_PENDING\fR capability is not supported, +\fBddi_intr_get_pending()\fR returns \fBDDI_ENOTSUP\fR and zero in +\fIpendingp\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_intr_get_pending()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +On success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EINVAL\fR\fR +.ad +.RS 15n +.rt +On encountering invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +On any implementation specific failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_ENOTSUP\fR\fR +.ad +.RS 15n +.rt +On device not supporting operation. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_intr_get_pending()\fR function can be called from either user or +kernel non-interrupt context. +.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 StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_intr_block_enable\fR(9F), +\fBddi_intr_block_disable\fR(9F), \fBddi_intr_clr_mask\fR(9F), +\fBddi_intr_disable\fR(9F), \fBddi_intr_enable\fR(9F), +\fBddi_intr_set_mask\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Any consumer of this interface should verify that the return value is not equal +to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in +inconsistent behavior among platforms. diff --git a/usr/src/man/man9f/ddi_intr_get_pri.9f b/usr/src/man/man9f/ddi_intr_get_pri.9f new file mode 100644 index 0000000000..d5392bb981 --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_get_pri.9f @@ -0,0 +1,195 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_intr_get_pri 9F "04 Jun 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_get_pri, ddi_intr_set_pri \- get or set priority of a given interrupt +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_intr_get_pri\fR(\fBddi_intr_handle_t\fR \fIh\fR, \fBuint_t\fR *\fIprip\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_intr_set_pri\fR(\fBddi_intr_handle_t\fR \fIh\fR, \fBuint_t\fR \fIpri\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +\fBddi_intr_get_pri()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 8n +.rt +DDI interrupt handle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprip\fR\fR +.ad +.RS 8n +.rt +Pointer to the priority returned for this handle +.RE + +.sp +.LP +\fBddi_intr_set_pri()\fR +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 7n +.rt +DDI interrupt handle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpri\fR\fR +.ad +.RS 7n +.rt +Contains the priority to be set +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_intr_get_pri()\fR function returns the current priority of the +interrupt handle \fIh\fR of a given device. Upon a successful return, +\fIprip\fR points to a small integer value, typically in the +\fBDDI_INTR_PRI_MIN\fR...\fBDDI_INTR_PRI_MAX\fR range, that represents the +current software priority setting for the interrupt. See <\fBsys/ddi_intr.h\fR> +for values of \fBDDI_INTR_PRI_MIN\fR or \fBDDI_INTR_PRI_MAX\fR. +.sp +.LP +The \fBddi_intr_get_pri()\fR function can be called any time, even if the +driver adds an interrupt handler for the interrupt specification. +.sp +.LP +The software priority returned from \fBddi_intr_get_pri()\fR can be used in +calls to \fBmutex_init()\fR and \fBrw_init()\fR. +.sp +.LP +The \fBddi_intr_set_pri()\fR function sets the priority \fIpri\fR of the +interrupt handle \fIh\fR of a given device. The function validates that the +argument is within the supported range. +.sp +.LP +The \fBddi_intr_set_pri()\fR function can only be called prior to adding the +interrupt handler or when an interrupt handler is unassigned. \fBDDI_FAILURE\fR +is returned in all other cases. +.SH RETURN VALUES +.sp +.LP +The \fBddi_intr_get_pri()\fR and \fBddi_intr_set_pri()\fR functions 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_EINVAL\fR\fR +.ad +.RS 15n +.rt +On encountering invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +On any implementation specific failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_ENOTSUP\fR\fR +.ad +.RS 15n +.rt +On device not supporting operation. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_intr_get_pri()\fR and \fBddi_intr_set_pri()\fR functions can be +called from kernel non-interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_intr_alloc\fR(9F), \fBddi_intr_enable\fR(9F), +\fBmutex_init\fR(9F), \fBrw_init\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The priority returned from \fBddi_intr_get_pri()\fR should be typecast by +calling the \fBDDI_INTR_PRI\fR macro before passing it onto +\fBmutex_init\fR(9F). +.sp +.LP +Consumers of these interfaces should verify that the return value is not equal +to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in +inconsistent behavior among platforms. diff --git a/usr/src/man/man9f/ddi_intr_get_supported_types.9f b/usr/src/man/man9f/ddi_intr_get_supported_types.9f new file mode 100644 index 0000000000..e16f361e6c --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_get_supported_types.9f @@ -0,0 +1,149 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_intr_get_supported_types 9F "07 Apr 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_get_supported_types \- return information on supported hardware +interrupt types +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_intr_get_supported_types\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint *\fR\fItypesp\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 10n +.rt +Pointer to \fBdev_info\fR structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItypesp\fR\fR +.ad +.RS 10n +.rt +Pointer to supported interrupt types +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_intr_get_supported_types()\fR function retrieves the interrupt types +supported by a particular hardware device and by the system software. Upon +successful return, the supported types are returned as a bit mask in the +integer pointed to by the \fItypesp\fR argument. See <\fBsys/ddi_intr.h\fR> for +a list of interrupts that can be returned by a hardware device. +.sp +.LP +For PCI devices that support MSI and/or MSI-X based hardware, this interface +returns only the interrupt types that are supported by all the hardware in the +path to the hardware device. +.sp +.LP +An interrupt type is usable by the hardware device if it is returned by the +\fBddi_intr_get_supported_types()\fR function. The device driver can be +programmed to use one of the returned interrupt types to receive hardware +interrupts. +.SH RETURN VALUES +.sp +.LP +The \fBddi_intr_get_supported_types()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 21n +.rt +On success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EINVAL\fR\fR +.ad +.RS 21n +.rt +On encountering invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_INTR_NOTFOUND\fR\fR +.ad +.RS 21n +.rt +Returned when the hardware device is found not to support any hardware +interrupts. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_intr_get_supported_types()\fR function can be called from user or +kernel non-interrupt context. +.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 +\fBpci\fR(4), \fBattributes\fR(5), \fBpcmcia\fR(7D), \fBsysbus\fR(4), +\fBddi_intr_add_handler\fR(9F), \fBddi_intr_alloc\fR(9F), +\fBddi_intr_enable\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The \fBddi_intr_get_supported_types()\fR function can be called by the device +driver even at any time if the driver has added an interrupt handler for a +given interrupt type. +.sp +.LP +Soft interrupts are always usable and are not returned by this interface. +.sp +.LP +Any consumer of this interface should verify that the return value is not equal +to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in +inconsistent behavior among platforms. diff --git a/usr/src/man/man9f/ddi_intr_hilevel.9f b/usr/src/man/man9f/ddi_intr_hilevel.9f new file mode 100644 index 0000000000..165e70bdcf --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_hilevel.9f @@ -0,0 +1,117 @@ +'\" te +.\" Copyright (c) ,2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_intr_hilevel 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_hilevel \- indicate interrupt handler type +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_intr_hilevel\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinumber\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). This interface is obsolete. Use the new +interrupt interfaces referenced in \fBIntro\fR(9F). Refer to \fIWriting Device +Drivers\fR for more information. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 11n +.rt +Pointer to \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinumber\fR\fR +.ad +.RS 11n +.rt +Interrupt number. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_intr_hilevel()\fR function returns non-zero if the specified +interrupt is a "high level" interrupt. +.sp +.LP +High level interrupts must be handled without using system services that +manipulate thread or process states, because these interrupts are not blocked +by the scheduler. +.sp +.LP +In addition, high level interrupt handlers must take care to do a minimum of +work because they are not preemptable. +.sp +.LP +A typical high level interrupt handler would put data into a circular buffer +and schedule a soft interrupt by calling \fBddi_trigger_softintr()\fR. The +circular buffer could be protected by using a mutex that was properly +initialized for the interrupt handler. +.sp +.LP +The \fBddi_intr_hilevel()\fR function can be used before calling +\fBddi_add_intr()\fR to decide which type of interrupt handler should be used. +Most device drivers are designed with the knowledge that the devices they +support will always generate low level interrupts, however some devices, for +example those using SBus or VME bus level 6 or 7 interrupts must use this test +because on some machines those interrupts are high level (above the scheduler +level) and on other machines they are not. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fBnon-zero\fR +.ad +.RS 12n +.rt +indicates a high-level interrupt. +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from useruser, interrupt, or kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_add_intr\fR(9F), \fBIntro\fR(9F), \fBmutex\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_intr_set_mask.9f b/usr/src/man/man9f/ddi_intr_set_mask.9f new file mode 100644 index 0000000000..315e79170e --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_set_mask.9f @@ -0,0 +1,150 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_intr_set_mask 9F "05 Apri 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_set_mask, ddi_intr_clr_mask \- set or clear mask for a given interrupt +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_intr_set_mask\fR(\fBddi_intr_handle_t\fR \fIh\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_intr_clr_mask\fR(\fBddi_intr_handle_t\fR \fIh\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIh\fR\fR +.ad +.RS 5n +.rt +DDI interrupt handle +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_intr_set_mask()\fR function masks the given interrupt pointed to by +the device's interrupt handle \fIh\fR if the device or host bridge supports the +masking operation. The \fBddi_intr_get_cap()\fR function returns the \fBRO\fR +flag \fBDDI_INTR_FLAG_MASKABLE\fR if the device or host bridge supports +interrupt mask bits for the given interrupt type. In flight interrupts can +still be taken and delivered to the driver. +.sp +.LP +The \fBddi_intr_clr_mask()\fR function unmasks the given interrupt pointed by +the device's interrupt handle \fIh\fR if the device or host bridge supports the +masking operation. +.sp +.LP +The \fBddi_intr_set_mask()\fR and \fBddi_intr_clr_mask()\fR functions should be +called only if an interrupt is enabled. Otherwise the framework will return +\fBDDI_EINVAL\fR to such calls. +.sp +.LP +The mask cannot be cleared directly if the OS implementation has also +temporarily masked the interrupt. A call to \fBddi_intr_clr_mask()\fR must be +preceded by a call to \fBddi_intr_set_mask()\fR. It is not necessary to call +\fBddi_intr_clr_mask()\fR when adding and enabling the interrupt. +.SH RETURN VALUES +.sp +.LP +The \fBddi_intr_set_mask()\fR and \fBddi_intr_clr_mask()\fR functions 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_EINVAL\fR\fR +.ad +.RS 15n +.rt +On encountering invalid input parameters or when an interrupt is not enabled. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +On any implementation specific failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_ENOTSUP\fR\fR +.ad +.RS 15n +.rt +On device not supporting operation. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_intr_set_mask()\fR and \fBddi_intr_clr_mask()\fR functions can be +called from any context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_intr_block_disable\fR(9F), +\fBddi_intr_block_enable\fR(9F), \fBddi_intr_disable\fR(9F), +\fBddi_intr_enable\fR(9F), \fBddi_intr_get_pending\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Consumers of these interfaces should verify that the return value is not equal +to \fBDDI_SUCCESS\fR. Incomplete checking for failure codes could result in +inconsistent behavior among platforms. diff --git a/usr/src/man/man9f/ddi_intr_set_nreq.9f b/usr/src/man/man9f/ddi_intr_set_nreq.9f new file mode 100644 index 0000000000..1b9ebb4979 --- /dev/null +++ b/usr/src/man/man9f/ddi_intr_set_nreq.9f @@ -0,0 +1,167 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_intr_set_nreq 9F "5 Jan 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_intr_set_nreq \- set the number of interrupts requested for a device driver +instance +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi_intr.h> + + + +\fBint\fR \fBddi_intr_set_nreq\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fInreq\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 8n +.rt +Pointer to the \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInreq\fR\fR +.ad +.RS 8n +.rt +Number of interrupts requested. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_intr_set_nreq()\fR function changes the number of interrupts +requested by a device driver instance. +.sp +.LP +The \fInreq\fR parameter is the total number of interrupt resources that this +instance of the device driver would like to have available. The \fInreq\fR +parameter includes any interrupt resources already allocated by the driver. For +example, if the driver instance already has two MSI-X vectors and it wants two +more, it should call this function with an \fInreq\fR parameter set to four. +.sp +.LP +The \fInreq\fR parameter can be any value between one and the maximum number of +interrupts supported by the device hardware, as reported by a call to the +\fBddi_intr_get_nintrs\fR(9F) function. The driver receives a callback +notifying it in cases when it must release any previously allocated interrupts, +or when it is allowed to allocate more interrupts as a result of its new +\fInreq\fR parameter. +.sp +.LP +The \fBddi_intr_set_nreq()\fRfunction is not supported unless a driver is +already consuming interrupts, and if it has a registered callback handler that +can process actions related to changes in interrupt availability. See +\fBddi_cb_register\fR(9F) for an explanation on how to enable this +functionality. +.SH RETURN VALUES +.sp +.LP +The \fBddi_intr_set_nreq()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +on success +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EINVAL\fR\fR +.ad +.RS 15n +.rt +The operation is invalid because the \fInreq\fR parameter is not a legal value +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_ENOTSUP\fR\fR +.ad +.RS 15n +.rt +The operation is not supported. The driver must have a registered callback, and +the system must have interrupt pools implemented. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Implementation specific failure +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from kernel, non-interrupt context. +.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 StabilityPrivate +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBattach\fR(9E), \fBddi_cb_register\fR(9F), +\fBddi_intr_alloc\fR(9F), \fBddi_intr_get_nintrs\fR(9F) +.SH NOTES +.sp +.LP +The Interrupt Resource Management feature is limited to device driver instances +that are using MSI-X interrupts (interrupt type \fBDDI_INTR_TYPE_MSIX\fR). +Attempts to use this function for any other type of interrupts fails with +\fBDDI_ENOTSUP\fR. +.sp +.LP +The total number of interrupts requested by the driver is initially defined by +the \fIcount\fR parameter provided by the driver's first call to the +\fBddi_intr_alloc\fR(9F) function, specifically during the driver instance's +\fBattach\fR(9E) routine. The \fBddi_intr_set_nreq()\fR function is only used +if the driver instance experiences changes in its I/O load. In response to +increased I/O load, the driver may want to request additional interrupt +resources. In response to diminished I/O load. the driver may volunteer to +return extra interrupt resources back to the system. diff --git a/usr/src/man/man9f/ddi_io_get8.9f b/usr/src/man/man9f/ddi_io_get8.9f new file mode 100644 index 0000000000..7e5f2c12b6 --- /dev/null +++ b/usr/src/man/man9f/ddi_io_get8.9f @@ -0,0 +1,107 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_io_get8 9F "1 Nov 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_io_get8, ddi_io_get16, ddi_io_get32, ddi_io_getb, ddi_io_getl, ddi_io_getw +\- read data from the mapped device register in I/O space +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBuint8_t\fR \fBddi_io_get8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint8_t *\fR\fIdev_addr\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBddi_io_get16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint16_t *\fR\fIdev_addr\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBddi_io_get32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint32_t *\fR\fIdev_addr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_io_get8()\fR, +\fBddi_io_get16()\fR, \fBddi_io_get32()\fR, \fBddi_io_getb()\fR, +\fBddi_io_getl()\fR, and \fBddi_io_getw()\fR functions are obsolete. The +\fBddi_get8\fR(9F) function replaces \fBddi_io_get8()\fR. The +\fBddi_get16\fR(9F) function replaces \fBddi_io_get16()\fR. The +\fBddi_get32\fR(9F) function replaces \fBddi_io_get32()\fR. The +\fBddi_get8\fR(9F) function replaces \fBddi_io_getb()\fR. The +\fBddi_get32\fR(9F) function replaces \fBddi_io_getl()\fR. The +\fBddi_get16\fR(9F) function replaces \fBddi_io_getw()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 12n +.rt +Data access handle returned from setup calls, such as +\fBddi_regs_map_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_addr\fR\fR +.ad +.RS 12n +.rt +Device address. +.RE + +.SH DESCRIPTION +.sp +.LP +These routines generate a read of various sizes from the device address, +\fIdev_addr\fR, in I/O space. The \fBddi_io_get8()\fR, \fBddi_io_get16()\fR, +and \fBddi_io_get32()\fR functions read 8 bits, 16 bits, and 32 bits of data, +respectively, from the device address, \fIdev_addr\fR. +.sp +.LP +Each individual datum will automatically be translated to maintain a consistent +view between the host and the device based on the encoded information in the +data access handle. The translation may involve byte-swapping if the host and +the device have incompatible endian characteristics. +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel, or interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBisa\fR(4), \fBddi_get8\fR(9F), \fBddi_get16\fR(9F), \fBddi_get32\fR(9F), +\fBddi_io_put8\fR(9F), \fBddi_io_rep_get8\fR(9F), \fBddi_io_rep_put8\fR(9F), +\fBddi_regs_map_free\fR(9F), \fBddi_regs_map_setup\fR(9F), +\fBddi_device_acc_attr\fR(9S) diff --git a/usr/src/man/man9f/ddi_io_put8.9f b/usr/src/man/man9f/ddi_io_put8.9f new file mode 100644 index 0000000000..ba6351c507 --- /dev/null +++ b/usr/src/man/man9f/ddi_io_put8.9f @@ -0,0 +1,121 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_io_put8 9F "1 Nov 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_io_put8, ddi_io_put16, ddi_io_put32, ddi_io_putb, ddi_io_putl, ddi_io_putw +\- write data to the mapped device register in I/O space +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_io_put8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint8_t *\fR\fIdev_addr\fR, + uint8_t \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_io_put16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint16_t *\fR\fIdev_addr\fR, + uint16_t \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_io_put32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint32_t *\fR\fIdev_addr\fR, + uint32_t \fIvalue\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_io_put8()\fR, +\fBddi_io_put16()\fR, \fBddi_io_put32()\fR, \fBddi_io_putb()\fR, +\fBddi_io_putl()\fR, and \fBddi_io_putw()\fR functions are obsolete. The +\fBddi_put8\fR(9F) function replaces \fBddi_io_put8()\fR. The +\fBddi_put16\fR(9F) function replaces \fBddi_io_put16()\fR. The +\fBddi_put32\fR(9F) function replaces \fBddi_io_put32()\fR. The +\fBddi_put8\fR(9F) function replaces \fBddi_io_putb()\fR. The +\fBddi_put32\fR(9F) function replaces \fBddi_io_putl()\fR. The +\fBddi_put16\fR(9F) function replaces \fBddi_io_putw()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 12n +.rt +Data access handle returned from setup calls, such as +\fBddi_regs_map_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_addr\fR\fR +.ad +.RS 12n +.rt +Base device address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvalue\fR\fR +.ad +.RS 12n +.rt +Data to be written to the device. +.RE + +.SH DESCRIPTION +.sp +.LP +These routines generate a write of various sizes to the device address, +\fIdev_addr\fR, in I/O space. The \fBddi_io_put8()\fR, \fBddi_io_put16()\fR, +and \fBddi_io_put32()\fR functions write 8 bits, 16 bits, and 32 bits of data, +respectively, to the device address, \fIdev_addr\fR. +.sp +.LP +Each individual datum will automatically be translated to maintain a consistent +view between the host and the device based on the encoded information in the +data access handle. The translation may involve byte-swapping if the host and +the device have incompatible endian characteristics. +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel, or interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBisa\fR(4), \fBddi_io_get8\fR(9F), \fBddi_io_rep_get8\fR(9F), +\fBddi_io_rep_put8\fR(9F), \fBddi_put8\fR(9F), \fBddi_put16\fR(9F), +\fBddi_put32\fR(9F), \fBddi_regs_map_setup\fR(9F), +\fBddi_device_acc_attr\fR(9S) diff --git a/usr/src/man/man9f/ddi_io_rep_get8.9f b/usr/src/man/man9f/ddi_io_rep_get8.9f new file mode 100644 index 0000000000..8ebebafc75 --- /dev/null +++ b/usr/src/man/man9f/ddi_io_rep_get8.9f @@ -0,0 +1,136 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_io_rep_get8 9F "1 Nov 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_io_rep_get8, ddi_io_rep_get16, ddi_io_rep_get32, ddi_io_rep_getb, +ddi_io_rep_getl, ddi_io_rep_getw \- read multiple data from the mapped device +register in I/O space +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_io_rep_get8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint8_t *\fR\fIhost_addr\fR, + \fBuint8_t *\fR\fIdev_addr\fR, \fBsize_t\fR \fIrepcount\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_io_rep_get16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint16_t *\fR\fIhost_addr\fR, + \fBuint16_t *\fR\fIdev_addr\fR,, \fBsize_t\fR \fIrepcount\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_io_rep_get32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint32_t *\fR\fIhost_addr\fR, + \fBuint32_t *\fR\fIdev_addr\fR,, \fBsize_t\fR \fIrepcount\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_io_rep_get8()\fR, +\fBddi_io_rep_get16()\fR, \fBddi_io_rep_get32()\fR, \fBddi_io_rep_getb()\fR, +\fBddi_io_rep_getl()\fR, and \fBddi_io_rep_getw()\fR functions are obsolete. +The \fBddi_rep_get8\fR(9F) function replaces \fBddi_io_rep_get8()\fR. The +\fBddi_rep_get16\fR(9F) function replaces \fBddi_io_rep_get16()\fR. The +\fBddi_rep_get32\fR(9F) function replaces \fBddi_io_rep_get32()\fR. The +\fBddi_rep_get8\fR(9F) function replaces \fBddi_io_rep_getb()\fR. The +\fBddi_rep_get32\fR(9F) function replaces \fBddi_io_rep_getl()\fR. The +\fBddi_rep_get16\fR(9F) function replaces \fBddi_io_rep_getw()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 13n +.rt +The data access handle returned from setup calls, such as +\fBddi_regs_map_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhost_addr\fR\fR +.ad +.RS 13n +.rt +Base host address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_addr\fR\fR +.ad +.RS 13n +.rt +Base device address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrepcount\fR\fR +.ad +.RS 13n +.rt +Number of data accesses to perform. +.RE + +.SH DESCRIPTION +.sp +.LP +These routines generate multiple reads from the device address, \fIdev_addr\fR, +in I/O space. \fIrepcount\fR data is copied from the device address, +\fIdev_addr\fR, to the host address, \fIhost_addr\fR. For each input datum, the +\fBddi_io_rep_get8()\fR, \fBddi_io_rep_get16()\fR, and \fBddi_io_rep_get32()\fR +functions read 8 bits, 16 bits, and 32 bits of data, respectively, from the +device address. \fIhost_addr\fR must be aligned to the datum boundary described +by the function. +.sp +.LP +Each individual datum will automatically be translated to maintain a consistent +view between the host and the device based on the encoded information in the +data access handle. The translation may involve byte-swapping if the host and +the device have incompatible endian characteristics. +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel, or interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBisa\fR(4), \fBddi_io_get8\fR(9F), \fBddi_io_put8\fR(9F), +\fBddi_io_rep_put8\fR(9F), \fBddi_regs_map_free\fR(9F), +\fBddi_regs_map_setup\fR(9F), \fBddi_rep_get8\fR(9F), \fBddi_rep_get16\fR(9F), +\fBddi_rep_get32\fR(9F), \fBddi_device_acc_attr\fR(9S) diff --git a/usr/src/man/man9f/ddi_io_rep_put8.9f b/usr/src/man/man9f/ddi_io_rep_put8.9f new file mode 100644 index 0000000000..bacdea9981 --- /dev/null +++ b/usr/src/man/man9f/ddi_io_rep_put8.9f @@ -0,0 +1,136 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_io_rep_put8 9F "1 Nov 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_io_rep_put8, ddi_io_rep_put16, ddi_io_rep_put32, ddi_io_rep_putb, +ddi_io_rep_putl, ddi_io_rep_putw \- write multiple data to the mapped device +register in I/O space +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_io_rep_put8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint8_t *\fR\fIhost_addr\fR, + \fBuin8_t *\fR\fIdev_addr\fR, \fBsize_t\fR \fIrepcount\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_io_rep_put16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint16_t *\fR\fIhost_addr\fR, + \fBuin16_t *\fR\fIdev_addr\fR, \fBsize_t\fR \fIrepcount\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_io_rep_put32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint32_t *\fR\fIhost_addr\fR, + \fBuin32_t *\fR\fIdev_addr\fR, \fBsize_t\fR \fIrepcount\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_io_rep_put8()\fR, +\fBddi_io_rep_put16()\fR, \fBddi_io_rep_put32()\fR, \fBddi_io_rep_putb()\fR, +\fBddi_io_rep_putl()\fR, and \fBddi_io_rep_putw()\fR functions are obsolete. +The \fBddi_rep_put8\fR(9F) function replaces \fBddi_io_rep_put8()\fR. The +\fBddi_rep_put16\fR(9F) function replaces \fBddi_io_rep_put16()\fR. The +\fBddi_rep_put32\fR(9F) function replaces \fBddi_io_rep_put32()\fR. The +\fBddi_rep_put8\fR(9F) function replaces \fBddi_io_rep_putb()\fR. The +\fBddi_rep_put32\fR(9F) function replaces \fBddi_io_rep_putl()\fR. The +\fBddi_rep_put16\fR(9F) function replaces \fBddi_io_rep_putw()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 13n +.rt +Data access handle returned from setup calls, such as +\fBddi_regs_map_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhost_addr\fR\fR +.ad +.RS 13n +.rt +Base host address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_addr\fR\fR +.ad +.RS 13n +.rt +Base device address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrepcount\fR\fR +.ad +.RS 13n +.rt +Number of data accesses to perform. +.RE + +.SH DESCRIPTION +.sp +.LP +These routines generate multiple writes to the device address, +\fIdev_address\fR, in I/O space. \fIrepcount\fR data is copied from the host +address, \fIhost_addr\fR, to the device address, \fIdev_addr\fR. For each input +datum, the \fBddi_io_rep_put8()\fR, \fBddi_io_rep_put16()\fR, and +\fBddi_io_rep_put32()\fR functions write 8 bits, 16 bits, and 32 bits of data, +respectively, to the device address. \fIhost_addr\fR must be aligned to the +datum boundary described by the function. +.sp +.LP +Each individual datum will automatically be translated to maintain a consistent +view between the host and the device based on the encoded information in the +data access handle. The translation may involve byte-swapping if the host and +the device have incompatible endian characteristics. +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel, or interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBisa\fR(4), \fBddi_io_get8\fR(9F), \fBddi_io_put8\fR(9F), +\fBddi_io_rep_get8\fR(9F), \fBddi_regs_map_setup\fR(9F), +\fBddi_rep_put8\fR(9F), \fBddi_rep_put16\fR(9F), \fBddi_rep_put32\fR(9F), +\fBddi_device_acc_attr\fR(9S) diff --git a/usr/src/man/man9f/ddi_iomin.9f b/usr/src/man/man9f/ddi_iomin.9f new file mode 100644 index 0000000000..791ff31d81 --- /dev/null +++ b/usr/src/man/man9f/ddi_iomin.9f @@ -0,0 +1,106 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_iomin 9F "04 Apr 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_iomin \- find minimum alignment and transfer size for DMA +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_iomin\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIinitial\fR, \fBint\fR \fIstreaming\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). This interface is obsolete. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 13n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinitial\fR\fR +.ad +.RS 13n +.rt +The initial minimum \fBDMA\fRtransfer size in bytes. This may be zero or an +appropriate \fBdlim_minxfer\fR value for device's \fBddi_dma_lim\fR structure +(see \fBddi_dma_lim_sparc\fR(9S) or \fBddi_dma_lim_x86\fR(9S)). This value must +be a power of two. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstreaming\fR\fR +.ad +.RS 13n +.rt +This argument, if non-zero, indicates that the returned value should be +modified to account for \fIstreaming\fR mode accesses (see +\fBddi_dma_req\fR(9S) for a discussion of streaming versus non-streaming access +mode). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_iomin()\fR function, finds out the minimum \fBDMA\fRtransfer size +for the device pointed to by \fIdip\fR. This provides a mechanism by which a +driver can determine the effects of underlying caches as well as intervening +bus adapters on the granularity of a DMA transfer. +.SH RETURN VALUES +.sp +.LP +The \fBddi_iomin()\fR function returns the minimum \fBDMA\fRtransfer size for +the calling device, or it returns zero, which means that you cannot get there +from here. +.SH CONTEXT +.sp +.LP +This function can be called from user, interrupt, or kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_dma_devalign\fR(9F), \fBddi_dma_setup\fR(9F), \fBddi_dma_sync\fR(9F), +\fBddi_dma_lim_sparc\fR(9S), \fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_iopb_alloc.9f b/usr/src/man/man9f/ddi_iopb_alloc.9f new file mode 100644 index 0000000000..c6a86c8eda --- /dev/null +++ b/usr/src/man/man9f/ddi_iopb_alloc.9f @@ -0,0 +1,178 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_iopb_alloc 9F "04 Apr 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_iopb_alloc, ddi_iopb_free \- allocate and free non-sequentially accessed +memory +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_iopb_alloc\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_lim_t *\fR\fIlimits\fR, + \fBuint_t\fR \fIlength\fR, \fBcaddr_t *\fR\fIiopbp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_iopb_free\fR(\fBcaddr_t\fR \fIiopb\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +These interfaces are obsolete. Use \fBddi_dma_mem_alloc\fR(9F) instead of +\fBddi_iopb_alloc()\fR. Use \fBddi_dma_mem_free\fR(9F) instead of +\fBddi_iopb_free()\fR. +.SH PARAMETERS +.SS "\fBddi_iopb_alloc()\fR" +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 10n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlimits\fR\fR +.ad +.RS 10n +.rt +A pointer to a \fBDMA \fRlimits structure for this device (see +\fBddi_dma_lim_sparc\fR(9S) or \fBddi_dma_lim_x86\fR(9S)). If this pointer is +\fINULL\fR, a default set of \fBDMA \fRlimits is assumed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlength\fR\fR +.ad +.RS 10n +.rt +The length in bytes of the desired allocation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIiopbp\fR\fR +.ad +.RS 10n +.rt +A pointer to a \fBcaddr_t\fR. On a successful return, \fI*iopbp\fR points to +the allocated storage. +.RE + +.SS "\fBddi_iopb_free()\fR" +.sp +.ne 2 +.mk +.na +\fB\fIiopb\fR\fR +.ad +.RS 8n +.rt +The \fIiopb\fR returned from a successful call to \fBddi_iopb_alloc()\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_iopb_alloc()\fR function allocates memory for \fBDMA\fR transfers +and should be used if the device accesses memory in a non-sequential fashion, +or if synchronization steps using \fBddi_dma_sync\fR(9F) should be as +lightweight as possible, due to frequent use on small objects. This type of +access is commonly known as \fIconsistent\fR access. The allocation will obey +the alignment and padding constraints as specified in the \fIlimits\fR argument +and other limits imposed by the system. +.sp +.LP +Note that you still must use \fBDMA\fR resource allocation functions (see +\fBddi_dma_setup\fR(9F)) to establish \fBDMA\fR resources for the memory +allocated using \fBddi_iopb_alloc()\fR. +.sp +.LP +In order to make the view of a memory object shared between a \fBCPU\fR and a +\fBDMA\fR device consistent, explicit synchronization steps using +\fBddi_dma_sync\fR(9F) or \fBddi_dma_free\fR(9F) are still required. The +\fBDMA\fR resources will be allocated so that these synchronization steps are +as efficient as possible. +.sp +.LP +The \fBddi_iopb_free()\fR function frees up memory allocated by +\fBddi_iopb_alloc()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_iopb_alloc()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Memory successfully allocated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Allocation failed. +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.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 +_ +Stability LevelObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_dma_free\fR(9F), \fBddi_dma_mem_alloc\fR(9F), +\fBddi_dma_mem_free\fR(9F), \fBddi_dma_setup\fR(9F), \fBddi_dma_sync\fR(9F), +\fBddi_mem_alloc\fR(9F), \fBddi_dma_lim_sparc\fR(9S), +\fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +This function uses scarce system resources. Use it selectively. diff --git a/usr/src/man/man9f/ddi_log_sysevent.9f b/usr/src/man/man9f/ddi_log_sysevent.9f new file mode 100644 index 0000000000..11b3d7e71d --- /dev/null +++ b/usr/src/man/man9f/ddi_log_sysevent.9f @@ -0,0 +1,372 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_log_sysevent 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_log_sysevent \- log system event for drivers +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_log_sysevent\fR(\fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIvendor\fR, + \fBchar *\fR\fIclass\fR, \fBchar *\fR\fIsubclass\fR, \fBnvlist_t *\fR\fIattr_list\fR, + \fBsysevent_id_t *\fR\fIeidp\fR, \fBint\fR \fIsleep_flag\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 14n +.rt +A pointer to the \fBdev_info\fR node for this driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvendor\fR\fR +.ad +.RS 14n +.rt +A pointer to a string defining the vendor. Third-party drivers should use their +company's stock symbol (or similarly enduring identifier). Sun-supplied drivers +should use \fBDDI_VENDOR_SUNW\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIclass\fR\fR +.ad +.RS 14n +.rt +A pointer to a string defining the event class. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsubclass\fR\fR +.ad +.RS 14n +.rt +A pointer to a string defining the event subclass. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIattr_list\fR\fR +.ad +.RS 14n +.rt +A pointer to an \fBnvlist_t\fR, listing the name-value attributes associated +with the event or NULL if there are no such attributes for this event. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIeidp\fR\fR +.ad +.RS 14n +.rt +The address of a \fBsysevent_id_t\fR structure in which the event's sequence +number and timestamp are returned if the event is successfully queued. May be +NULL if this information is not of interest. See below for the definition of +\fBsysevent_id_t\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsleep_flag\fR\fR +.ad +.RS 14n +.rt +Indicates how a caller wants to handle the possibility of resources not being +available. If \fIsleep_flag\fR is \fBDDI_NOSLEEP\fR, the caller does not care +if the allocation fails or the queue is full and can handle a failure +appropriately. If \fBsleep_flag\fR is \fBDDI_SLEEP\fR, the caller wishes to +have the allocation and queuing routines wait for resources to become +available. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_log_sysevent()\fR function causes a system event, of the specified +class and subclass, to be generated on behalf of the driver and queued for +delivery to \fBsyseventd\fR, the user-land \fBsysevent\fR daemon. +.sp +.LP +The publisher string for the event is constructed using the vendor name and +driver name, with the format: +.sp +.in +2 +.nf +"\fI<vendor>\fR:kern:\fI<driver-name>\fR" +.fi +.in -2 +.sp + +.sp +.LP +The two fields of \fBeidp\fR, \fBeid_seq\fR and \fBeid_ts\fR, are sufficient to +uniquely identify an event. +.SH STRUCTURE MEMBERS +.sp +.LP +The structure members of \fBsysevent_id_t\fR are: +.sp +.in +2 +.nf + uint64_t eid_seq; /* sysevent sequence number */ + hrtime_t eid_ts; /* sysevent timestamp */ +.fi +.in -2 + +.SH RETURN VALUES +.sp +.LP +The \fBddi_log_sysevent()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 18n +.rt +The event has been queued for delivery successfully. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_ENOMEM\fR\fR +.ad +.RS 18n +.rt +There is not enough memory to queue the system event at this time. +\fBDDI_ENOMEM\fR cannot be returned when \fIsleep_flag\fR is \fBDDI_SLEEP\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_EBUSY\fR\fR +.ad +.RS 18n +.rt +The system event queue is full at this time. \fBDDI_EBUSY\fR cannot be returned +when \fIsleep_flag\fR is \fBDDI_SLEEP\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_ETRANSPORT\fR\fR +.ad +.RS 18n +.rt +The \fBsyseventd\fR daemon is not responding and events cannot be queued or +delivered at this time. \fBDDI_ETRANSPORT\fR can be returned even when +\fIsleep_flag\fR is \fBDDI_SLEEP\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_ECONTEXT\fR\fR +.ad +.RS 18n +.rt +\fIsleep_flag\fR is DDI_SLEEP and the driver is running in interrupt context. +.RE + +.sp +.LP +\fBddi_log_sysevent\fR supports the following data types: +.br +.in +2 +DATA_TYPE_BYTE +.in -2 +.br +.in +2 +DATA_TYPE_INT16 +.in -2 +.br +.in +2 +DATA_TYPE_UINT16 +.in -2 +.br +.in +2 +DATA_TYPE_INT32 +.in -2 +.br +.in +2 +DATA_TYPE_UINT32 +.in -2 +.br +.in +2 +DATA_TYPE_INT64 +.in -2 +.br +.in +2 +DATA_TYPE_UINT64 +.in -2 +.br +.in +2 +DATA_TYPE_STRING +.in -2 +.br +.in +2 +DATA_TYPE_BYTE_ARRAY +.in -2 +.br +.in +2 +DATA_TYPE_INT16_ARRAY +.in -2 +.br +.in +2 +DATA_TYPE_UINT16_ARRAY +.in -2 +.br +.in +2 +DATA_TYPE_INT32_ARRAY +.in -2 +.br +.in +2 +DATA_TYPE_UINT32_ARRAY +.in -2 +.br +.in +2 +DATA_TYPE_INT64_ARRAY +.in -2 +.br +.in +2 +DATA_TYPE_UINT64_ARRAY +.in -2 +.SH CONTEXT +.sp +.LP +The \fBddi_log_sysevent()\fR function can be called from user, interrupt, or +kernel context, except when \fIsleep_flag\fR is \fBDDI_SLEEP\fR, in which case +it cannot be called from interrupt context. +.SH EXAMPLES +.LP +\fBExample 1 \fRLogging System Event with No Attributes +.sp +.in +2 +.nf + if (ddi_log_sysevent(dip, DDI_VENDOR_SUNW, "class", "subclass", + NULL, NULL, DDI_SLEEP) != DDI_SUCCESS) { + cmn_err(CE_WARN, "error logging system event\en"); + } +.fi +.in -2 + +.LP +\fBExample 2 \fRLogging System Event with Two Name/Value Attributes, an Integer +and a String +.sp +.in +2 +.nf +nvlist_t *attr_list; +sysevent_id_t eid; + +if (nvlist_alloc(&attr_list, NV_UNIQUE_NAME_TYPE, KM_SLEEP) == 0) +{ + err = nvlist_add_uint32(attr_list, int_name, int_value); + if (err == 0) + err = nvlist_add_string(attr_list, str_name, str_value); + if (err == 0) + err = ddi_log_sysevent(dip, DDI_VENDOR_SUNW, + "class", "subclass", attr_list, &eid, DDI_SLEEP); + if (err != DDI_SUCCESS) + cmn_err(CE_WARN, "error logging system event\en"); + nvlist_free(attr_list); + } +.fi +.in -2 + +.LP +\fBExample 3 \fRUse Timeout to Handle \fBnvlist\fR and System Event Resource +Allocation Failures +.sp +.LP +Since no blocking calls are made, this example would be useable from a driver +needing to generate an event from interrupt context. + +.sp +.in +2 +.nf +static int + xx_se_timeout_handler(xx_state_t *xx) + { + xx->xx_timeoutid = (xx_generate_event(xx) ? + timeout(xx_se_timeout_handler, xx, 4) : 0); + } + + static int + xx_generate_event(xx_state_t *xx) + { + int err; + + err = nvlist_alloc(&xx->xx_ev_attrlist, NV_UNIQUE_NAME_TYPE, 0); + if (err != 0) + return (1); + err = nvlist_add_uint32(&xx->xx_ev_attrlist, + xx->xx_ev_name, xx->xx_ev_value); + if (err != 0) { + nvlist_free(xx->xx_ev_attrlist); + return(1); + } + + err = ddi_log_sysevent(xx->xx_dip, DDI_VENDOR_SUNW, + xx->xx_ev_class, xx->xx_ev_sbclass, + xx->xx_ev_attrlist, NULL, DDI_NOSLEEP); + nvlist_free(xx->xx_ev_attrlist); + if (err == DDI_SUCCESS || err == DDI_ETRANSPORT) { + if (err == DDI_ETRANSPORT) + cmn_err(CE_WARN, "cannot log system event\en"); + return (0); + } + return (1); + } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBsyseventd\fR(1M), \fBattributes\fR(5), \fBnvlist_add_boolean\fR(9F), +\fBnvlist_alloc\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_map_regs.9f b/usr/src/man/man9f/ddi_map_regs.9f new file mode 100644 index 0000000000..ab109a1ead --- /dev/null +++ b/usr/src/man/man9f/ddi_map_regs.9f @@ -0,0 +1,215 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_map_regs 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_map_regs, ddi_unmap_regs \- map or unmap registers +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_map_regs\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIrnumber\fR, \fBcaddr_t *\fR\fIkaddrp\fR, + \fBoff_t\fR \fIoffset\fR, \fBoff_t\fR \fIlen\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_unmap_regs\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIrnumber\fR, \fBcaddr_t *\fR\fIkaddrp\fR, + \fBoff_t\fR \fIoffset\fR, \fBoff_t\fR \fIlen\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +These interfaces are obsolete. Use \fBddi_regs_map_setup\fR(9F) instead of +\fBddi_map_regs()\fR. Use \fBddi_regs_map_free\fR(9F) instead of +\fBddi_unmap_regs()\fR. +.SH PARAMETERS +.SS "\fBddi_map_regs()\fR" +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 11n +.rt +Pointer to the device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrnumber\fR\fR +.ad +.RS 11n +.rt +Register set number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIkaddrp\fR\fR +.ad +.RS 11n +.rt +Pointer to the base kernel address of the mapped region (set on return). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR\fR +.ad +.RS 11n +.rt +Offset into register space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 11n +.rt +Length to be mapped. +.RE + +.SS "\fBddi_unmap_regs()\fR" +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 11n +.rt +Pointer to the device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrnumber\fR\fR +.ad +.RS 11n +.rt +Register set number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIkaddrp\fR\fR +.ad +.RS 11n +.rt +Pointer to the base kernel address of the region to be unmapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR\fR +.ad +.RS 11n +.rt +Offset into register space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 11n +.rt +Length to be unmapped. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_map_regs()\fR function maps in the register set given by +\fIrnumber\fR. The register number determines which register set will be mapped +if more than one exists. The base kernel virtual address of the mapped register +set is returned in \fIkaddrp\fR. \fIoffset\fR specifies an offset into the +register space to start from and \fIlen\fR indicates the size of the area to be +mapped. If \fIlen\fR is non-zero, it overrides the length given in the register +set description. See the discussion of the \fBreg\fR property in \fBsbus\fR(4) +and for more information on register set descriptions. If \fIlen\fR and +\fIoffset\fR are 0, the entire space is mapped. +.sp +.LP +The \fBddi_unmap_regs()\fR function undoes mappings set up by +\fBddi_map_regs()\fR. This is provided for drivers preparing to detach +themselves from the system, allowing them to release allocated mappings. +Mappings must be released in the same way they were mapped (a call to +\fBddi_unmap_regs()\fR must correspond to a previous call to +\fBddi_map_regs()\fR). Releasing portions of previous mappings is not allowed. +\fIrnumber\fR determines which register set will be unmapped if more than one +exists. The \fIkaddrp\fR, \fIoffset\fR and \fIlen\fR specify the area to be +unmapped. \fIkaddrp\fR is a pointer to the address returned from +\fBddi_map_regs()\fR; \fIoffset\fR and \fIlen\fR should match what +\fBddi_map_regs()\fR was called with. +.SH RETURN VALUES +.sp +.LP +The \fBddi_map_regs()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +on success. +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.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 +_ +Interface Stability Obsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBsbus\fR(4), \fBddi_regs_map_free\fR(9F), +\fBddi_regs_map_setup\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_mem_alloc.9f b/usr/src/man/man9f/ddi_mem_alloc.9f new file mode 100644 index 0000000000..3c3770a5b3 --- /dev/null +++ b/usr/src/man/man9f/ddi_mem_alloc.9f @@ -0,0 +1,199 @@ +'\" te +.\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_mem_alloc 9F "04 Apr 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_mem_alloc, ddi_mem_free \- allocate and free sequentially accessed memory +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_mem_alloc\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_lim_t *\fR\fIlimits\fR, + \fBuint_t\fR \fIlength\fR, \fBuint_t\fR \fIflags\fR, \fBcaddr_t *\fR\fIkaddrp\fR, + \fBuint_t *\fR\fIreal_length\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_mem_free\fR(\fBcaddr_t\fR \fIkaddr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +These interfaces are obsolete. \fBddi_dma_mem_alloc\fR(9F) and +\fBddi_dma_mem_free\fR(9F) should be used instead. +.SH PARAMETERS +.SS "\fBddi_mem_alloc()\fR" +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 15n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlimits\fR\fR +.ad +.RS 15n +.rt +A pointer to a \fBDMA\fR limits structure for this device (see +\fBddi_dma_lim_sparc\fR(9S) or \fBddi_dma_lim_x86\fR(9S)). If this pointer is +\fINULL\fR, a default set of \fBDMA\fR limits is assumed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlength\fR\fR +.ad +.RS 15n +.rt +The length in bytes of the desired allocation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 15n +.rt +The possible flags \fB1\fR and \fB0\fR are taken to mean, respectively, wait +until memory is available, or do not wait. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIkaddrp\fR\fR +.ad +.RS 15n +.rt +On a successful return, *\fIkaddrp\fR points to the allocated memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreal_length\fR\fR +.ad +.RS 15n +.rt +The length in bytes that was allocated. Alignment and padding requirements may +cause \fBddi_mem_alloc()\fR to allocate more memory than requested in +\fIlength\fR. +.RE + +.SS "\fBddi_mem_free()\fR" +.sp +.ne 2 +.mk +.na +\fB\fIkaddr\fR\fR +.ad +.RS 9n +.rt +The memory returned from a successful call to \fBddi_mem_alloc()\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_mem_alloc()\fR function allocates memory for \fBDMA\fR transfers and +should be used if the device is performing sequential, unidirectional, +block-sized and block-aligned transfers to or from memory. This type of access +is commonly known as \fBstreaming\fR access. The allocation will obey the +alignment and padding constraints as specified by the \fIlimits\fR argument and +other limits imposed by the system. +.sp +.LP +Note that you must still use \fBDMA\fR resource allocation functions (see +\fBddi_dma_setup\fR(9F)) to establish \fBDMA\fR resources for the memory +allocated using \fBddi_mem_alloc()\fR. \fBddi_mem_alloc()\fR returns the actual +size of the allocated memory object. Because of padding and alignment +requirements, the actual size might be larger than the requested size. +\fBddi_dma_setup\fR(9F) requires the actual length. +.sp +.LP +In order to make the view of a memory object shared between a \fBCPU\fR and a +\fBDMA\fR device consistent, explicit synchronization steps using +\fBddi_dma_sync\fR(9F) or \fBddi_dma_free\fR(9F) are required. +.sp +.LP +The \fBddi_mem_free()\fR function frees up memory allocated by +\fBddi_mem_alloc()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_mem_alloc()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Memory successfully allocated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Allocation failed. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_mem_alloc()\fR function can be called from user, interrupt, or +kernel context, except when \fIflags\fR is set to \fB1\fR, in which case it +cannot be called from interrupt context. +.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 +_ +Stability LevelObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_dma_free\fR(9F), \fBddi_dma_mem_alloc\fR(9F), +\fBddi_dma_mem_free\fR(9F), \fBddi_dma_setup\fR(9F), \fBddi_dma_sync\fR(9F), +\fBddi_iopb_alloc\fR(9F), \fBddi_dma_lim_sparc\fR(9S), +\fBddi_dma_lim_x86\fR(9S), \fBddi_dma_req\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_mem_get8.9f b/usr/src/man/man9f/ddi_mem_get8.9f new file mode 100644 index 0000000000..b994f93a2c --- /dev/null +++ b/usr/src/man/man9f/ddi_mem_get8.9f @@ -0,0 +1,117 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_mem_get8 9F "1 Nov 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_mem_get8, ddi_mem_get16, ddi_mem_get32, ddi_mem_get64, ddi_mem_getb, +ddi_mem_getl, ddi_mem_getll, ddi_mem_getw \- read data from mapped device in +the memory space or allocated DMA memory +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBuint8_t\fR \fBddi_mem_get8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint8_t *\fR\fIdev_addr\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBddi_mem_get16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint16_t *\fR \fIdev_addr\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBddi_mem_get32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint32_t *\fR\fIdev_addr\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBddi_mem_get64\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint64_t *\fR\fIdev_addr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_mem_get8()\fR, +\fBddi_mem_get16()\fR, \fBddi_mem_get32()\fR, \fBddi_mem_get64()\fR, +\fBddi_mem_getb()\fR, \fBddi_mem_getl()\fR, \fBddi_mem_getll()\fR, and +\fBddi_mem_getw()\fR functions are obsolete. The \fBddi_get8\fR(9F) function +replaces \fBddi_mem_get8()\fR. The \fBddi_get16\fR(9F) function replaces +\fBddi_mem_get16()\fR. The \fBddi_get32\fR(9F) function replaces +\fBddi_mem_get32()\fR. The \fBddi_get64\fR(9F) function replaces +\fBddi_mem_get64()\fR. The \fBddi_get8\fR(9F) function replaces +\fBddi_mem_getb()\fR. The \fBddi_get32\fR(9F) function replaces +\fBddi_mem_getl()\fR. The \fBddi_get64\fR(9F) function replaces +\fBddi_mem_getll()\fR. The \fBddi_get16\fR(9F) function replaces +\fBddi_mem_getw()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 12n +.rt +The data access handle returned from setup calls, such as +\fBddi_regs_map_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_addr\fR\fR +.ad +.RS 12n +.rt +Base device address. +.RE + +.SH DESCRIPTION +.sp +.LP +These routines generate a read of various sizes from memory space or allocated +\fBDMA \fRmemory. The \fBddi_mem_get8()\fR, \fBddi_mem_get16()\fR, +\fBddi_mem_get32()\fR, and \fBddi_mem_get64()\fR functions read 8 bits, 16 +bits, 32 bits and 64 bits of data, respectively, from the device address, +\fIdev_addr\fR, in memory space. +.sp +.LP +Each individual datum will automatically be translated to maintain a consistent +view between the host and the device based on the encoded information in the +data access handle. The translation may involve byte-swapping if the host and +the device have incompatible endian characteristics. +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel, or interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_get8\fR(9F), \fBddi_get16\fR(9F), \fBddi_get32\fR(9F), +\fBddi_get64\fR(9F), \fBddi_mem_put8\fR(9F), \fBddi_mem_rep_get8\fR(9F), +\fBddi_mem_rep_put8\fR(9F), \fBddi_regs_map_setup\fR(9F), +\fBddi_device_acc_attr\fR(9S) diff --git a/usr/src/man/man9f/ddi_mem_put8.9f b/usr/src/man/man9f/ddi_mem_put8.9f new file mode 100644 index 0000000000..367d3ba940 --- /dev/null +++ b/usr/src/man/man9f/ddi_mem_put8.9f @@ -0,0 +1,132 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_mem_put8 9F "1 Nov 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_mem_put8, ddi_mem_put16, ddi_mem_put32, ddi_mem_put64, ddi_mem_putb, +ddi_mem_putw, ddi_mem_putl, ddi_mem_putll \- write data to mapped device in the +memory space or allocated DMA memory +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_mem_put8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint8_t *\fR\fIdev_addr\fR, + \fBuint8_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_mem_put16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint16_t *\fR\fIdev_addr\fR, + \fBuint16_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_mem_put32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint32_t *\fR\fIdev_addr\fR, + \fBuint32_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_mem_put64\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint64_t *\fR\fIdev_addr\fR, + \fBuint64_t\fR \fIvalue\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 12n +.rt +The data access handle returned from setup calls, such as +\fBddi_regs_map_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_addr\fR\fR +.ad +.RS 12n +.rt +Base device address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvalue\fR\fR +.ad +.RS 12n +.rt +The data to be written to the device. +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_mem_put8()\fR, +\fBddi_mem_put16()\fR, \fBddi_mem_put32()\fR, \fBddi_mem_put64()\fR, +\fBddi_mem_putb()\fR, \fBddi_mem_putl()\fR, \fBddi_mem_putll()\fR, and +\fBddi_mem_putw()\fR functions are obsolete. The \fBddi_put8\fR(9F) function +replaces \fBddi_mem_put8()\fR. The \fBddi_put16\fR(9F) function replaces +\fBddi_mem_put16()\fR. The \fBddi_put32\fR(9F) function replaces +\fBddi_mem_put32()\fR. The \fBddi_put64\fR(9F) function replaces +\fBddi_mem_put64()\fR. The \fBddi_put8\fR(9F) function replaces +\fBddi_mem_putb()\fR. The \fBddi_put32\fR(9F) function replaces +\fBddi_mem_putl()\fR. The \fBddi_put64\fR(9F) function replaces +\fBddi_mem_putll()\fR. The \fBddi_put16\fR(9F) function replaces +\fBddi_mem_putw()\fR. +.SH DESCRIPTION +.sp +.LP +These routines generate a write of various sizes to memory space or allocated +\fBDMA \fRmemory. The \fBddi_mem_put8()\fR, \fBddi_mem_put16()\fR, +\fBddi_mem_put32()\fR, and \fBddi_mem_put64()\fR functions write 8 bits, 16 +bits, 32 bits and 64 bits of data, respectively, to the device address, +\fIdev_addr\fR, in memory space. +.sp +.LP +Each individual datum will automatically be translated to maintain a consistent +view between the host and the device based on the encoded information in the +data access handle. The translation may involve byte-swapping if the host and +the device have incompatible endian characteristics. +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel, or interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_mem_get8\fR(9F), \fBddi_mem_rep_get8\fR(9F), \fBddi_put8\fR(9F), +\fBddi_put16\fR(9F), \fBddi_put32\fR(9F), \fBddi_put64\fR(9F), +\fBddi_mem_get8\fR(9F), \fBddi_regs_map_setup\fR(9F), +\fBddi_device_acc_attr\fR(9S) diff --git a/usr/src/man/man9f/ddi_mem_rep_get8.9f b/usr/src/man/man9f/ddi_mem_rep_get8.9f new file mode 100644 index 0000000000..7696a0f4b2 --- /dev/null +++ b/usr/src/man/man9f/ddi_mem_rep_get8.9f @@ -0,0 +1,191 @@ +'\" te +.\" Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_mem_rep_get8 9F "1 Nov 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_mem_rep_get8, ddi_mem_rep_get16, ddi_mem_rep_get32, ddi_mem_rep_get64, +ddi_mem_rep_getb, ddi_mem_rep_getl, ddi_mem_rep_getll, ddi_mem_rep_getw \- read +multiple data from mapped device in the memory space or allocated DMA memory +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_mem_rep_get8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, + \fBuint8_t *\fR\fIhost_addr\fR, \fBuint8_t *\fR\fIdev_addr\fR, \fBsize_t\fR \fIrepcount\fR, + \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_mem_rep_get16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, + \fBuint16_t *\fR\fIhost_addr\fR, \fBuint16_t *\fR\fIdev_addr\fR, \fBsize_t\fR \fIrepcount\fR, + \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_mem_rep_get32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, + \fBuint32_t *\fR\fIhost_addr\fR, \fBuint32_t *\fR\fIdev_addr\fR, \fBsize_t\fR \fIrepcount\fR, + \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_mem_rep_get64\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, + \fBuint64_t *\fR\fIhost_addr\fR, \fBuint64_t *\fR\fIdev_addr\fR, \fBsize_t\fR \fIrepcount\fR, + \fBuint_t\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_mem_rep_get8()\fR, +\fBddi_mem_rep_get16()\fR, \fBddi_mem_rep_get32()\fR, +\fBddi_mem_rep_get64()\fR, \fBddi_mem_rep_getb()\fR, \fBddi_mem_rep_getl()\fR, +\fBddi_mem_rep_getll()\fR, and \fBddi_mem_rep_getw()\fR functions are obsolete. +The \fBddi_rep_get8\fR(9F) function replaces \fBddi_mem_rep_get8()\fR. The +\fBddi_rep_get16\fR(9F) function replaces \fBddi_mem_rep_get16()\fR. The +\fBddi_rep_get32\fR(9F) function replaces \fBddi_mem_rep_get32()\fR. The +\fBddi_rep_get64\fR(9F) function replaces \fBddi_mem_rep_get64()\fR. The +\fBddi_rep_get8\fR(9F) function replaces \fBddi_mem_rep_getb()\fR. The +\fBddi_rep_get32\fR(9F) function replaces \fBddi_mem_rep_getl()\fR. The +\fBddi_rep_get64\fR(9F) function replaces \fBddi_mem_rep_getll()\fR. The +\fBddi_rep_get16\fR(9F) function replaces \fBddi_mem_rep_getw()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 13n +.rt +The data access handle returned from setup calls, such as +\fBddi_regs_map_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhost_addr\fR\fR +.ad +.RS 13n +.rt +Base host address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_addr\fR\fR +.ad +.RS 13n +.rt +Base device address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrepcount\fR\fR +.ad +.RS 13n +.rt +Number of data accesses to perform. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 13n +.rt +Device address flags: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEV_AUTOINCR\fR\fR +.ad +.RS 23n +.rt +Automatically increment the device address, \fIdev_addr\fR, during data +accesses. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEV_NO_AUTOINCR\fR\fR +.ad +.RS 23n +.rt +Do not advance the device address, \fIdev_addr\fR, during data accesses. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +These routines generate multiple reads from memory space or allocated \fBDMA +\fRmemory. \fIrepcount\fR data is copied from the device address, +\fIdev_addr\fR, in memory space to the host address, \fIhost_addr\fR. For each +input datum, the \fBddi_mem_rep_get8()\fR, \fBddi_mem_rep_get16()\fR, +\fBddi_mem_rep_get32()\fR, and \fBddi_mem_rep_get64()\fR functions read 8 bits, +16 bits, 32 bits and 64 bits of data, respectively, from the device address, +\fIdev_addr\fR. \fIdev_addr\fR and \fIhost_addr\fR must be aligned to the datum +boundary described by the function. +.sp +.LP +Each individual datum will automatically be translated to maintain a consistent +view between the host and the device based on the encoded information in the +data access handle. The translation may involve byte-swapping if the host and +the device have incompatible endian characteristics. +.sp +.LP +When the \fIflags\fR argument is set to \fBDDI_DEV_AUTOINCR\fR, these +functions will treat the device address, \fIdev_addr\fR, as a memory buffer +location on the device and increments its address on the next input datum. +However, when the \fIflags\fR argument is set to \fBDDI_DEV_NO_AUTOINCR\fR, +the same device address will be used for every datum access. For example, this +flag may be useful when reading from a data register. +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel, or interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_mem_get8\fR(9F), \fBddi_mem_put8\fR(9F), \fBddi_mem_rep_put8\fR(9F), +\fBddi_regs_map_setup\fR(9F), \fBddi_rep_get8\fR(9F), \fBddi_rep_get16\fR(9F), +\fBddi_rep_get32\fR(9F), \fBddi_rep_get64\fR(9F), \fBddi_device_acc_attr\fR(9S) diff --git a/usr/src/man/man9f/ddi_mem_rep_put8.9f b/usr/src/man/man9f/ddi_mem_rep_put8.9f new file mode 100644 index 0000000000..44a71a8e27 --- /dev/null +++ b/usr/src/man/man9f/ddi_mem_rep_put8.9f @@ -0,0 +1,188 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_mem_rep_put8 9F "1 Nov 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_mem_rep_put8, ddi_mem_rep_put16, ddi_mem_rep_put32, ddi_mem_rep_put64, +ddi_mem_rep_putb, ddi_mem_rep_putl, ddi_mem_rep_putll, ddi_mem_rep_putw \- +write multiple data to mapped device in the memory space or allocated DMA +memory +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_mem_rep_put8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint8_t *\fR\fIhost_addr\fR, + \fBuint8_t *\fR\fIdev_addr\fR, \fBsize_t\fR \fIrepcount\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_mem_rep_put16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint16_t *\fR\fIhost_addr\fR, + \fBuint16_t *\fR\fIdev_addr\fR, \fBsize_t\fR \fIrepcount\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_mem_rep_put32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint32_t *\fR\fIhost_addr\fR, + \fBuint32_t *\fR\fIdev_addr\fR, \fBsize_t\fR \fIrepcount\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_mem_rep_put64\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint64_t *\fR\fIhost_addr\fR, + \fBuint64_t *\fR\fIdev_addr\fR, \fBsize_t\fR \fIrepcount\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_mem_rep_put8()\fR, +\fBddi_mem_rep_put16()\fR, \fBddi_mem_rep_put32()\fR, +\fBddi_mem_rep_put64()\fR, \fBddi_mem_rep_putb()\fR, \fBddi_mem_rep_putl()\fR, +\fBddi_mem_rep_putll()\fR, and \fBddi_mem_rep_putw()\fR functions are obsolete. +The \fBddi_rep_put8\fR(9F) function replaces \fBddi_mem_rep_put8()\fR. The +\fBddi_rep_put16\fR(9F) function replaces \fBddi_mem_rep_put16()\fR. The +\fBddi_rep_put32\fR(9F) function replaces \fBddi_mem_rep_put32()\fR. The +\fBddi_rep_put64\fR(9F) function replaces \fBddi_mem_rep_put64()\fR. The +\fBddi_rep_put8\fR(9F) function replaces \fBddi_mem_rep_putb()\fR. The +\fBddi_rep_put32\fR(9F) function replaces \fBddi_mem_rep_putl()\fR. The +\fBddi_rep_put64\fR(9F) function replaces \fBddi_mem_rep_putll()\fR. The +\fBddi_rep_put16\fR(9F) function replaces \fBddi_mem_rep_putw()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 13n +.rt +The data access handle returned from setup calls, such as +\fBddi_regs_map_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhost_addr\fR\fR +.ad +.RS 13n +.rt +Base host address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_addr\fR\fR +.ad +.RS 13n +.rt +Base device address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrepcount\fR\fR +.ad +.RS 13n +.rt +Number of data accesses to perform. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 13n +.rt +Device address flags: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEV_AUTOINCR\fR\fR +.ad +.RS 23n +.rt +Automatically increment the device address, \fIdev_addr\fR, during data +accesses. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEV_NO_AUTOINCR\fR\fR +.ad +.RS 23n +.rt +Do not advance the device address, \fIdev_addr\fR, during data accesses. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +These routines generate multiple writes to memory space or allocated \fBDMA +\fRmemory. \fIrepcount\fR data is copied from the host address, +\fIhost_addr\fR, to the device address, \fIdev_addr\fR, in memory space. For +each input datum, the \fBddi_mem_rep_put8()\fR, \fBddi_mem_rep_put16()\fR, +\fBddi_mem_rep_put32()\fR, and \fBddi_mem_rep_put64()\fR functions write 8 +bits, 16 bits, 32 bits and 64 bits of data, respectively, to the device +address. \fIdev_addr\fR and \fIhost_addr\fR must be aligned to the datum +boundary described by the function. +.sp +.LP +Each individual datum will automatically be translated to maintain a consistent +view between the host and the device based on the encoded information in the +data access handle. The translation may involve byte-swapping if the host and +the device have incompatible endian characteristics. +.sp +.LP +When the \fIflags\fR argument is set to \fBDDI_DEV_AUTOINCR\fR, these functions +will treat the device address, \fIdev_addr\fR, as a memory buffer location on +the device and increments its address on the next input datum. However, when +the \fIflags\fR argument is set to \fBDDI_DEV_NO_AUTOINCR\fR, the same device +address will be used for every datum access. For example, this flag may be +useful when writing from a data register. +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel, or interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_mem_get8\fR(9F), \fBddi_mem_put8\fR(9F), \fBddi_mem_rep_get8\fR(9F), +\fBddi_regs_map_setup\fR(9F), \fBddi_rep_put8\fR(9F), \fBddi_rep_put16\fR(9F), +\fBddi_rep_put32\fR(9F), \fBddi_rep_put64\fR(9F), \fBddi_device_acc_attr\fR(9S) diff --git a/usr/src/man/man9f/ddi_mmap_get_model.9f b/usr/src/man/man9f/ddi_mmap_get_model.9f new file mode 100644 index 0000000000..0d4b6abdc5 --- /dev/null +++ b/usr/src/man/man9f/ddi_mmap_get_model.9f @@ -0,0 +1,125 @@ +'\" 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 ddi_mmap_get_model 9F "8 Feb 2001" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_mmap_get_model \- return data model type of current thread +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBuint_t\fR \fBddi_mmap_get_model\fR(\fBvoid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +\fBddi_mmap_get_model()\fR returns the \fIC\fR Language Type Model which the +current thread expects. \fBddi_mmap_get_model()\fR is used in combination with +\fBddi_model_convert_from\fR(9F) in the \fBmmap\fR(9E) driver entry point 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. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_MODEL_ILP32\fR \fR +.ad +.RS 20n +.rt +Current thread expects 32-bit \fI(ILP32)\fR semantics. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_MODEL_LP64\fR \fR +.ad +.RS 20n +.rt +Current thread expects 64-bit \fI(LP64)\fR semantics. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR \fR +.ad +.RS 20n +.rt +The \fBddi_mmap_get_model()\fR function was not called from the \fBmmap\fR(9E) +entry point. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_mmap_get_model()\fR function can only be called from the +\fBmmap\fR(9E) driver entry point. +.SH EXAMPLES +.LP +\fBExample 1 \fR: Using \fBddi_mmap_get_model()\fR +.sp +.LP +The following is an example of the \fBmmap\fR(9E) entry point and how to +support 32-bit and 64-bit applications with the same device driver. + +.sp +.in +2 +.nf +struct data32 { + int len; + caddr32_t addr; +}; + +struct data { + int len; + caddr_t addr; +}; +xxmmap(dev_t dev, off_t off, int prot) { + struct data dtc; /* a local copy for clash resolution */ + struct data *dp = (struct data *)shared_area; + + switch (ddi_model_convert_from(ddi_mmap_get_model())) { + case DDI_MODEL_ILP32: + { + struct data32 *da32p; + + da32p = (struct data32 *)shared_area; + dp = &dtc; + dp->len = da32p->len; + dp->address = da32->address; + break; + } + case DDI_MODEL_NONE: + break; + } + /* continues along using dp */ + \&.\|.\|. +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBmmap\fR(9E), \fBddi_model_convert_from\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_model_convert_from.9f b/usr/src/man/man9f/ddi_model_convert_from.9f new file mode 100644 index 0000000000..73406d00ff --- /dev/null +++ b/usr/src/man/man9f/ddi_model_convert_from.9f @@ -0,0 +1,131 @@ +'\" 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 ddi_model_convert_from 9F "8 Feb 2001" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_model_convert_from \- determine data model type mismatch +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fB uint_t\fR\fBddi_model_convert_from\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\fImodel\fR \fR +.ad +.RS 10n +.rt +The data model type of the current thread. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_model_convert_from()\fR is used to determine if the current thread uses +a different \fBC\fR Language Type Model than the device driver. The 64-bit +version of Solaris will require a 64-bit kernel to support both 64-bit and +32-bit user mode programs. The difference between a 32-bit program and a 64-bit +program is in its \fBC\fR Language Type Model: a 32-bit program is \fBILP32\fR +(integer, longs, and pointers are 32-bit) and a 64-bit program is \fBLP64\fR +(longs and pointers are 64-bit). There are a number of driver entry points such +as \fBioctl\fR(9E) and \fBmmap\fR(9E) where it is necessary to identify the +\fBC\fR Language Type Model of the user-mode originator of an kernel event. For +example any data which flows between programs and the device driver or vice +versa need to be identical in format. A 64-bit device driver may need to modify +the format of the data before sending it to a 32-bit application. +\fBddi_model_convert_from()\fR is used to determine if data that is passed +between the device driver and the application requires reformatting to any +non-native data model. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_MODEL_ILP32\fR \fR +.ad +.RS 20n +.rt +A conversion to/from \fBILP32\fR is necessary. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_MODEL_NONE\fR \fR +.ad +.RS 20n +.rt +No conversion is necessary. Current thread and driver use the same data model. +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_model_convert_from()\fR can be called from any context. +.SH EXAMPLES +.LP +\fBExample 1 \fR: Using \fBddi_model_convert_from()\fR in the \fBioctl()\fR +entry point to support both 32-bit and 64-bit applications. +.sp +.LP +The following is an example how to use \fBddi_model_convert_from()\fR in the +\fBioctl()\fR entry point to support both 32-bit and 64-bit applications. + +.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; + + switch (ddi_model_convert_from(mode & FMODELS)) { + case DDI_MODEL_ILP32: + { + struct passargs32 pa32; + + ddi_copyin(arg, &pa32, sizeof (struct passargs32), mode); + pa.len = pa32.len; + pa.address = pa32.address; + break; + } + case DDI_MODEL_NONE: + ddi_copyin(arg, &pa, sizeof (struct passargs), mode); + break; + } + + do_ioctl(&pa); + .\|.\|.\|. +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBioctl\fR(9E), \fBmmap\fR(9E), \fBddi_mmap_get_model\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_modopen.9f b/usr/src/man/man9f/ddi_modopen.9f new file mode 100644 index 0000000000..37e174b070 --- /dev/null +++ b/usr/src/man/man9f/ddi_modopen.9f @@ -0,0 +1,325 @@ +'\" 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 ddi_modopen 9F "17 March 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_modopen, ddi_modsym, ddi_modclose \- dynamically-loaded kernel module +functions +.SH SYNOPSIS +.LP +.nf +#include <sys/modctl.h> + +\fBddi_modhandle_t\fR \fBddi_modopen\fR(\fBconst char\fR\fI*modname\fR, \fBint\fR \fImode\fR, + \fBint\fR \fI*errnop\fR); +.fi + +.LP +.nf +\fBvoid\fR \fB*ddi_modsym\fR(\fBddi_modhandle_t\fR \fIhandle\fR, \fBconst char\fR \fI*symname\fR, + \fBint\fR \fI*errnop\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_modclose\fR(\fBddi_modhandle_t\fR \fIhandle\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImodname\fR\fR +.ad +.RS 11n +.rt +The name of the dynamically-loaded kernel module (file) to be opened. The +\fImodname\fR string is of the form: +.sp +.in +2 +.nf +"[\fInamespace\fR/[\fIdirspace\fR/]]\fImodulename\fR" +.fi +.in -2 +.sp + +Each "\fInamespace\fR/" directory along the standard kernel +moddir/\fImodule-path\fR path (\fBsystem\fR(4)) is searched to locate the +module. If "\fInamespace\fR/" is not specified, "misc/" is assumed. If +"\fIdirspace\fR" is specified, then "\fInamespace\fR/" must be explicitly +provided. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImode\fR\fR +.ad +.RS 11n +.rt +Currently, \fBKRTLD_MODE_FIRST\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerrnop\fR\fR +.ad +.RS 11n +.rt +Pointer to \fBerrno\fR returned on error, if \fBNULL\fR then no additional +error information is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 11n +.rt +Opaque handle returned from \fBddi_modopen()\fR, invalidated by +\fBddi_modclose()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsymname\fR\fR +.ad +.RS 11n +.rt +Symbol's name as a character string. +.RE + +.SH DESCRIPTION +.sp +.LP +The function prototypes for \fBddi_modopen()\fR, \fBddi_modsym()\fR, and +\fBddi_modclose()\fR are modeled after the userland \fBlibdl\fR(3LIB), +\fBdlopen\fR(3C), \fBdlsym\fR(3C) , and\fBdlclose\fR(3C) interfaces, however +not all userland features are available and the kernel symbol resolution is +different. The \fBdlerror\fR(3C) interface is not appropriate for the kernel +environment, so the new \fIerrnop\fR return argument was added for +\fBddi_modopen()\fR and \fBddi_modsym()\fR. +.sp +.LP +The \fBddi_modopen()\fRfunction makes a dynamically-loaded kernel module named +by "modname" available to a running kernel. \fBddi_modopen()\fR returns a +handle that the caller can use on subsequent calls to \fBddi_modsym()\fR and +\fBddi_modclose()\fR. The value of this handle should not be interpreted in any +way by the caller. +.sp +.LP +The \fBddi_modopen()\fR interface works best as a dynamic component/object +plug-in mechanism when targeting kernel "misc" modules that contain a single +"struct modlmisc" module linkage, however non-"misc" modules and modules with +multiple linkage structures can also be targeted. +.sp +.LP +There are two different symbol resolution search orders associated with the +\fBddi_modopen()\fR function: one search order to resolve symbols during the +load of the targeted module, another search order o resolve \fBddi_modsym()\fR +calls against the handle returned by \fBddi_modopen()\fR. To resolve symbols +during module load, the standard kernel module load search order is used; to +resolve symbols during module "A" load, the order is as follows: +.sp +.in +2 +.nf +A -> A's _depends_on -> unix -> unix's _depends_on +.fi +.in -2 +.sp + +.sp +.LP +A single-level, left-to-right search in \fB_depends_on\fR (or the "ld -N" +alternative) modules occurs. For \fBUNIX\fR on \fBSparc\fR, \fB_depends_on\fR +is similar to "genunix misc/platmod cpu/SUNW,UltraSPARC-III+ dtracestubs" for +\fBIntel\fR, it is "genunix dtracestubs". The \fBddi_modsym()\fR search is +limited to the module directly associated with the handle. +.sp +.LP +The \fBddi_modopen()\fR function increments the reference count on the named +kernel module. Upon the first load of a module, the\fB_init\fR(9E) +initialization code in the module is called; \fBddi_modopen()\fR does not +return until \fB_init\fR completes. +.sp +.LP +The \fBddi_modsym()\fR function allows a caller to obtain the address of a +symbol that is defined within a module. The \fIhandle\fR argument is a valid +\fBddi_modhandle_t\fR as returned by \fBddi_modopen()\fR, the \fIsymname\fR +argument is the symbol's name as a character string. The special handle values +supported by ddi_modsym(3C) are not supported. +.sp +.LP +The \fBddi_modclose()\fR function decrements the reference count of the kernel +module associated with the specified handle. After the \fBddi_modclose()\fR +function is called, all \fBddi_modsym()\fR resolutions obtained (either +directly or indirectly) using the now closed \fIhandle\fR are invalid; further +use of these resolutions can cause undefined behavior (that is, may lead to a +panic). When the last \fBddi_modclose()\fR of a module occurs, and there are no +further references to the module, the module \fB_fini\fR(9E)entry point may be +called. If \fB_fini\fR returns success then the module may be unloaded. +.SH RETURN VALUES +.sp +.LP +The \fBddi_modopen()\fR function returns a handle to the dynamically-loaded +kernel module. The \fBddi_modopen()\fR function returns \fBNULL\fR if the +module cannot be found, the object cannot be relocated, or an error occurs +during the process of resolving and relocating its symbolic references. +.sp +.LP +The \fBddi_modsym()\fR function returns \fBNULL\fR if the \fIsymname\fR symbol +cannot be found directly within the module associated with the \fIhandle\fR. +.sp +.LP +If the \fIhandle\fR was not referenced, \fBddi_modclose()\fR returns 0. If the +\fIhandle\fR is invalid, \fBddi_modclose()\fR may return a non-zero value. +.sp +.LP +When either \fBddi_modopen()\fR or \fBddi_modsym()\fR return \fBNULL\fR, +additional \fIerrno\fR information related to the failure is returned in +\fI*errnop\fR if it is not \fBNULL\fR. +.SH CONTEXT +.sp +.LP +\fBddi_modopen()\fR can be called from user context only. +.SH EXAMPLES +.LP +\fBExample 1 \fRCoding a Dynamically Loaded Kernel Module +.sp +.LP +The following example shows code to dynamically load and call a "\fBtest\fR" +interface in a module called "\fBdltest\fR". The "\fBtest\fR" interface then +adds one to its integer argument. + +.sp +.in +2 +.nf +ddi_modhandle_t modh; +int (*test)(int); +int i = 0; +int errno; +---%<--- +/* dynamically load "dltest" kernel 'misc' module */ +modh = ddi_modopen("dltest", KRTLD_MODE_FIRST, &errno); +if (modh == NULL) + goto fail; /* failed to open dltest module */ + +test = (int (*)())ddi_modsym(modh, "test", &errno); +if (test == NULL) { + (void) ddi_modclose(modh); + goto fail; /* failed to find "test" interface */ +} + +/* invoke test interface and verify result */ +i = (*test)(0); +ASSERT(i == 1); + +(void) ddi_modclose(modh); +---%<--- +.fi +.in -2 + +.sp +.LP +The implementation of the "dltest" "misc" module is as follows: + +.sp +.in +2 +.nf +#include <sys/modctl.h> +static dltest_add = 0; + +/* define the module linkage */ +static struct modlmisc modlmisc = {&mod_miscops, "dltest"}; +static struct modlinkage modlinkage = { + MODREV_1, (void *)&modmisc, NULL +}; +int +_init(void) +{ + int i; + + dltest_add = 1; /* initialization */ + if ((i = mod_install(&modlinkage)) != 0) + dltest_add = -1; /* un-initialization */ + return (i); +} +int +_fini() +{ + int i; + + if ((i = mod_remove(&modlinkage)) == 0) + dltest_add = -1; /* un-initialization */ + return (i); +} +int +_info(struct modinfo *modinfop) +{ + return (mod_info(&modlinkage, modinfop)); +} + +/* "test" interface */ +int +test(int i) +{ + return (i + dltest_add); +} +.fi +.in -2 + +.LP +\fBExample 2 \fRDynamically Accessing a Kernel Module within a Drive +.sp +.LP +The following example shows driver code to dynamically load into the kernel a +module constructed via the \fBelfwrap\fR(1) utility and containing firmware +intended for download to a device. The "\fBstart\fR" and "\fBend\fR" pointers +provide the addresses of the beginning of the data and first byte beyond the +data. + +.sp +.in +2 +.nf +ddi_modhandle_t modp; +char *data_startp, *data_endp; +size_t nbytes; +int rv; + +modp = ddi_modopen("firmware-rev1.2a", KRTLD_MODE_FIRST, &rv); +data_startp = (char *)ddi_modsym(modp, "fw-rev1.2a_start", &rv); +data_endp = (char *)ddi_modsym(modp, "fw-rev1.2a_end", &rv); +nbytes = data_endp - data_startp; +rv = ddi_modclose(modp); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBdlclose\fR(3C), \fBdlopen\fR(3C), \fBdlsym\fR(3C), \fBlibdl\fR(3LIB), +\fBboot\fR(1M), \fBelfwrap\fR(1), \fBmodload\fR(1M), \fBsystem\fR(4), +\fB_fini\fR(9E), \fB_info\fR(9E), \fB_init\fR(9E) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +A \fBsystem\fR(4)forceload must be established for modules targeted by +\fBddi_modopen()\fR by code involved in the mount of root on "bootdev" during +machine \fBboot\fR(1M). diff --git a/usr/src/man/man9f/ddi_no_info.9f b/usr/src/man/man9f/ddi_no_info.9f new file mode 100644 index 0000000000..bd254250b8 --- /dev/null +++ b/usr/src/man/man9f/ddi_no_info.9f @@ -0,0 +1,86 @@ +'\" 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 ddi_no_info 9F "9 Jul 2002" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_no_info \- stub for getinfo(9E) +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_no_info\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_info_cmd_t\fR \fIinfocmd\fR, \fBvoid *\fR\fIarg\fR, + \fBvoid **\fR\fIresult\fR +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fBdev_info_t *\fIdip\fR\fR +.ad +.RS 26n +.rt +Pointer to \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fBddi_info_cmd_t \fIinfocmd\fR\fR +.ad +.RS 26n +.rt +Command argument. Valid command values are: \fBDDI_INFO_DEVT2DEVINFO\fR and +\fBDDI_INFO_DEVT2INSTANCE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBvoid *\fIarg\fR\fR +.ad +.RS 26n +.rt +Command-specific argument. +.RE + +.sp +.ne 2 +.mk +.na +\fBvoid **\fIresult\fR\fR +.ad +.RS 26n +.rt +Pointer to where the requested information is stored. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_no_info()\fR function always returns \fBDDI_FAILURE\fR. It is +provided as a convenience routine for drivers not providing a \fBcb_ops\fR(9S) +or for network drivers only providing DLPI-2 services. Such drivers can use +\fBddi_no_info()\fR in the \fBdevo_getinfo\fR entry point (see +\fBgetinfo\fR(9E)) of the \fBdev_ops\fR(9S) structure. +.SH RETURN VALUES +.sp +.LP +The \fBddi_no_info()\fR function always returns \fBDDI_FAILURE\fR. +.SH SEE ALSO +.sp +.LP +\fBgetinfo\fR(9E), \fBqassociate\fR(9F), \fBcb_ops\fR(9S), \fBdev_ops\fR(9S) diff --git a/usr/src/man/man9f/ddi_node_name.9f b/usr/src/man/man9f/ddi_node_name.9f new file mode 100644 index 0000000000..4857a1df77 --- /dev/null +++ b/usr/src/man/man9f/ddi_node_name.9f @@ -0,0 +1,58 @@ +'\" te +.\" All Rights Reserved Copyright (c) 2006, Sun +.\" Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_node_name 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_node_name \- return the devinfo node name +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBchar *\fR\fBddi_node_name\fR(\fBdev_info_t *\fR\fIdip\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 the device's \fBdev_info\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_node_name()\fR function returns the device node name contained in +the \fBdev_info\fR node pointed to by \fIdip\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_node_name()\fR function returns the device node name contained in +the \fBdev_info\fR structure. +.SH CONTEXT +.sp +.LP +The \fBddi_node_name()\fR function can be called from user, interrupt, or +kernel context. +.SH SEE ALSO +.sp +.LP +\fBddi_binding_name\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_peek.9f b/usr/src/man/man9f/ddi_peek.9f new file mode 100644 index 0000000000..8024ca266b --- /dev/null +++ b/usr/src/man/man9f/ddi_peek.9f @@ -0,0 +1,197 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_peek 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_peek, ddi_peek8, ddi_peek16, ddi_peek32, ddi_peek64, ddi_peekc, ddi_peeks, +ddi_peekl, ddi_peekd \- read a value from a location +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_peek8\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint8_t\fR \fI*addr\fR, \fBint8_t\fR \fI*valuep\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_peek16\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint16_t\fR \fI*addr\fR, \fBint16_t\fR \fI*valuep\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_peek32\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint32_t\fR \fI*addr\fR, \fBint32_t\fR \fI*valuep\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_peek64\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint64_t\fR \fI*addr\fR, \fBint64_t\fR \fI*valuep\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_peekc()\fR, \fBddi_peeks()\fR, +\fBddi_peekl()\fR, and \fBddi_peekd()\fR functions are obsolete. Use, +respectively, \fBddi_peek8()\fR, \fBddi_peek16()\fR, \fBddi_peek32()\fR, and +\fBddi_peek64()\fR, instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 10n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR\fR +.ad +.RS 10n +.rt +Virtual address of the location to be examined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvaluep\fR\fR +.ad +.RS 10n +.rt +Pointer to a location to hold the result. If a null pointer is specified, then +the value read from the location will simply be discarded. +.RE + +.SH DESCRIPTION +.sp +.LP +These routines cautiously attempt to read a value from a specified virtual +address, and return the value to the caller, using the parent nexus driver to +assist in the process where necessary. +.sp +.LP +If the address is not valid, or the value cannot be read without an error +occurring, an error code is returned. +.sp +.LP +The routines are most useful when first trying to establish the presence of a +device on the system in a driver's \fBprobe\fR(9E) or \fBattach\fR(9E) +routines. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +The value at the given virtual address was successfully read, and if +\fIvaluep\fR is non-null, \fI*valuep\fR will have been updated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +An error occurred while trying to read the location. \fI*valuep\fR is +unchanged. +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRChecking to see that the status register of a device is mapped +into the kernel address space: +.sp +.in +2 +.nf +if (ddi_peek8(dip, csr, (int8_t *)0) != DDI_SUCCESS) { + cmn_err(CE_WARN, "Status register not mapped"); + return (DDI_FAILURE); +} +.fi +.in -2 + +.LP +\fBExample 2 \fRReading and logging the device type of a particular device: +.sp +.in +2 +.nf +int +xx_attach(dev_info_t *dip, ddi_attach_cmd_t cmd) +{ + \&.\|.\|. + /* map device registers */ + \&.\|.\|. + + if (ddi_peek32(dip, id_addr, &id_value) != DDI_SUCCESS) { + cmn_err(CE_WARN, "%s%d: cannot read device identifier", + ddi_get_name(dip), ddi_get_instance(dip)); + goto failure; + } else + cmn_err(CE_CONT, "!%s%d: device type 0x%x\en", + ddi_get_name(dip), ddi_get_instance(dip), id_value); + \&.\|.\|. + \&.\|.\|. + + ddi_report_dev(dip); + return (DDI_SUCCESS); + +failure: + /* free any resources allocated */ + \&.\|.\|. + return (DDI_FAILURE); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBprobe\fR(9E), \fBddi_poke\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The functions described in this manual page previously used symbolic names +which specified their data access size; the function names have been changed so +they now specify a fixed-width data size. See the following table for the new +name equivalents: +.sp + +.sp +.TS +tab() box; +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPrevious Name\fR\fBNew Name\fR +\fBddi_peekc\fR\fBddi_peek8\fR +\fBddi_peeks\fR\fBddi_peek16\fR +\fBddi_peekl\fR\fBddi_peek32\fR +\fBddi_peekd\fR\fBddi_peek64\fR +.TE + diff --git a/usr/src/man/man9f/ddi_periodic_add.9f b/usr/src/man/man9f/ddi_periodic_add.9f new file mode 100644 index 0000000000..58cd6c13da --- /dev/null +++ b/usr/src/man/man9f/ddi_periodic_add.9f @@ -0,0 +1,190 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_periodic_add 9F "13 Apr 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_periodic_add \- issue nanosecond periodic timeout requests +.SH SYNOPSIS +.LP +.nf +#include <sys/dditypes.h> +#include <sys/sunddi.h> + +\fBddi_periodic_t\fR \fBddi_periodic_add\fR(\fBvoid (*\fR\fIfunc\fR)(\fBvoid *)\fR, \fBvoid\fR \fIarg\fR, + \fBhrtime_t\fR \fIinterval\fR, \fBint\fR \fIlevel\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIfunc\fR\fR +.ad +.RS 12n +.rt +The callback function is invoked periodically in the specified interval. If the +argument level is zero, the function is invoked in kernel context. Otherwise, +it's invoked in interrupt context at the specified level. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 12n +.rt +The argument passed to the callback function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinterval\fR\fR +.ad +.RS 12n +.rt +Interval time in nanoseconds. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlevel\fR\fR +.ad +.RS 12n +.rt +Callback interrupt level. If the value is zero, the callback function is +invoked in kernel context. If the value is more than zero, but less than or +equal to ten, the callback function is invoked in interrupt context at the +specified interrupt level, which may be used for real time applications. +.sp +This value must be in range of 0-10, which can be either a numeric number, a +pre-defined macro (\fBDDI_IPL_0\fR, ... , \fBDDI_IPL_10\fR), or the +\fBDDI_INTR_PRI\fR macro with the interrupt priority. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_periodic_add()\fR function schedules the specified function to be +periodically invoked in the nanosecond interval time. +.sp +.LP +As with \fBtimeout\fR(9F), the exact time interval over which the function +takes effect cannot be guaranteed, but the value given is a close +approximation. +.SH RETURN VALUES +.sp +.LP +\fBddi_periodic_add()\fRreturns the non-zero opaque value +(\fBddi_periodic_t\fR), which might be used for \fBddi_periodic_delete\fR(9F) +to specify the request. +.SH CONTEXT +.sp +.LP +The \fBddi_periodic_add()\fR function may be called from user or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBddi_periodic_add()\fR for a periodic callback function +.sp +.LP +In the following example, the device driver registers a periodic callback +function invoked in kernel context. + +.sp +.in +2 +.nf +static void +my_periodic_func(void *arg) +{ + /* + * This handler is invoked periodically. + */ + struct my_state *statep = (struct my_state *)arg; + + mutex_enter(&statep->lock); + if (load_unbalanced(statep)) { + balance_tasks(statep); + } + mutex_exit(&statep->lock); +} + +static void +start_periodic_timer(struct my_state *statep) +{ + hrtime_t interval = CHECK_INTERVAL; + + mutex_init(&statep->lock, NULL, MUTEX_DRIVER, + (void *)DDI_IPL_0); + + /* + * Register my_callback which is invoked periodically + * in CHECK_INTERVAL in kernel context. + */ + statep->periodic_id = ddi_periodic_add(my_periodic_func, + statep, interval, DDI_IPL_0); +.fi +.in -2 + +.sp +.LP +In the following example, the device driver registers a callback function +invoked in interrupt context at level 7. +.sp +.in +2 +.nf +/* + * This handler is invoked periodically in interrupt context. + */ + static void + my_periodic_int7_func(void *arg) + { + struct my_state *statep = (struct my_state *)arg; + mutex_enter(&statep->lock); + monitor_device(statep); + mutex_exit(&statep->lock); + } + + static void + start_monitor_device(struct my_state *statep) + { + hrtime_t interval = MONITOR_INTERVAL; + + mutex_init(&statep->lock, NULL, MUTEX_DRIVER, + (void *)DDI_IPL_7); + + /* + * Register the callback function invoked periodically + * at interrupt level 7. + */ + statep->periodic_id = ddi_periodic_add(my_periodic_int7_func, + statep, interval, DDI_IPL_7); + } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBcv_timedwait\fR(9F), \fBddi_intr_get_pri\fR(9F), +\fBddi_periodic_delete\fR(9F), \fBddi_intr_get_softint_pri\fR(9F), +\fBdelay\fR(9F), \fBdrv_usectohz\fR(9F), \fBqtimeout\fR(9F), +\fBquntimeout\fR(9F), \fBtimeout\fR(9F), \fBuntimeout\fR(9F) +.SH NOTES +.sp +.LP +A caller can only specify an interval in an integral multiple of 10ms. No other +values are supported at this time. The interval specified is a lower bound on +the interval on which the callback occurs. diff --git a/usr/src/man/man9f/ddi_periodic_delete.9f b/usr/src/man/man9f/ddi_periodic_delete.9f new file mode 100644 index 0000000000..67e9824b8d --- /dev/null +++ b/usr/src/man/man9f/ddi_periodic_delete.9f @@ -0,0 +1,119 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_periodic_delete 9F "6 May 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_periodic_delete \- cancel nanosecond periodic timeout requests +.SH SYNOPSIS +.LP +.nf +#include <sys/dditypes.h> +#include <sys/sunddi.h> + +\fBvoid\fR \fBddi_periodic_delete\fR(\fBddi_periodic_t\fR \fIreq\fR\fB);\fR +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIreq\fR\fR +.ad +.RS 7n +.rt +\fBddi_periodic_t\fR opaque value returned by \fBddi_periodic_add\fR(9F) +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_periodic_delete()\fR function cancels the \fBddi_periodic_add\fR(9F) +request that was previously issued. +.sp +.LP +As with \fBuntimeout\fR(9F), calling \fBddi_periodic_delete()\fR against a +periodic \fItimeout\fR request which is either running on another CPU, or has +already been canceled causes no problems. Unlike \fBuntimeout\fR(9F), there are +no restrictions on the lock which might be held across the call to +\fBddi_periodic_delete()\fR. +.SH CONTEXT +.sp +.LP +The \fBddi_periodic_delete()\fR function may be called from user or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRCancelling a timeout request +.sp +.LP +In the following example, the device driver cancels the \fItimeout\fR request +by calling \fBddi_periodic_delete()\fR against the request that was previously +issued. + +.sp +.in +2 +.nf +/* +* Stop the periodic timer +*/ +static void +stop_periodic_timer(struct my_state *statep) +{ + ddi_periodic_delete(statep->periodic_id); + delay(1); /* wait for one tick */ + mutex_destory(&statep->lock); +} + +static void +start_periodic_timer(struct my_state *statep) +{ + hrtime_t interval = CHECK_INTERVAL; + + mutex_init(&statep->lock, NULL, MUTEX_DRIVER, + (void *)DDI_IPL_0); + + /* + * Register my_callback which is invoked periodically + * in CHECK_INTERVAL in kernel context. + */ + statep->periodic_id = ddi_periodic_add(my_periodic_func, + statep, interval, DDI_IPL_0); +} + +static void +my_periodic_func(void *arg) +{ + /* + * This handler is invoked periodically. + */ + struct my_state *statep = (struct my_state *)arg; + + mutex_enter(&statep->lock); + if (load_unbalanced(statep)) { + balance_tasks(statep); + } + mutex_exit(&statep->lock); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBcv_timedwait\fR(9F), \fBddi_intr_get_pri\fR(9F), \fBddi_periodic_add\fR(9F), +\fBdelay\fR(9F), \fBdrv_usectohz\fR(9F), \fBqtimeout\fR(9F), +\fBquntimeout\fR(9F), \fBtimeout\fR(9F), \fBuntimeout\fR(9F) +.SH NOTES +.sp +.LP +There might be a race between a callback invocation and +\fBddi_periodic_delete()\fR. A device driver should take a responsibility for +this avoidance if needed by using the kernel synchronization such as a mutex +lock or calling \fBdelay\fR(9F) as in the example above. diff --git a/usr/src/man/man9f/ddi_poke.9f b/usr/src/man/man9f/ddi_poke.9f new file mode 100644 index 0000000000..fa6b6de81e --- /dev/null +++ b/usr/src/man/man9f/ddi_poke.9f @@ -0,0 +1,151 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_poke 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_poke, ddi_poke8, ddi_poke16, ddi_poke32, ddi_poke64, ddi_pokec, ddi_pokes, +ddi_pokel, ddi_poked \- write a value to a location +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_poke8\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint8_t\fR \fI*addr\fR, \fBint8_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_poke16\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint16_t\fR \fI*addr\fR, \fBint16_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_poke32\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint32_t\fR \fI*addr\fR, \fBint32_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_poke64\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint64_t\fR \fI*addr\fR, \fBint64_t\fR \fIvalue\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_pokec()\fR, \fBddi_pokes()\fR, +\fBddi_pokel()\fR, and \fBddi_poked()\fR functions are obsolete. Use, +respectively, \fBddi_poke8()\fR, \fBddi_poke16()\fR, \fBddi_poke32()\fR, and +\fBddi_poke64()\fR, instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 9n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR\fR +.ad +.RS 9n +.rt +Virtual address of the location to be written to. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvalue\fR\fR +.ad +.RS 9n +.rt +Value to be written to the location. +.RE + +.SH DESCRIPTION +.sp +.LP +These routines cautiously attempt to write a value to a specified virtual +address, using the parent nexus driver to assist in the process where +necessary. +.sp +.LP +If the address is not valid, or the value cannot be written without an error +occurring, an error code is returned. +.sp +.LP +These routines are most useful when first trying to establish the presence of a +given device on the system in a driver's \fBprobe\fR(9E) or \fBattach\fR(9E) +routines. +.sp +.LP +On multiprocessing machines these routines can be extremely heavy-weight, so +use the \fBddi_peek\fR(9F) routines instead if possible. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +The value was successfully written to the given virtual address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +An error occurred while trying to write to the location. +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBprobe\fR(9E), \fBddi_peek\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The functions described in this manual page previously used symbolic names +which specified their data access size; the function names have been changed so +they now specify a fixed-width data size. See the following table for the new +name equivalents: +.sp + +.sp +.TS +tab() box; +lw(2.75i) lw(2.75i) +lw(2.75i) lw(2.75i) +. +\fBPrevious Name\fR\fBNew Name\fR +\fBddi_pokec\fR\fBddi_poke8\fR +\fBddi_pokes\fR\fBddi_poke16\fR +\fBddi_pokel\fR\fBddi_poke32\fR +\fBddi_poked\fR\fBddi_poke64\fR +.TE + diff --git a/usr/src/man/man9f/ddi_prop_create.9f b/usr/src/man/man9f/ddi_prop_create.9f new file mode 100644 index 0000000000..edbdb108c5 --- /dev/null +++ b/usr/src/man/man9f/ddi_prop_create.9f @@ -0,0 +1,620 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_prop_create 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_prop_create, ddi_prop_modify, ddi_prop_remove, ddi_prop_remove_all, +ddi_prop_undefine \- create, remove, or modify properties for leaf device +drivers +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_prop_create\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, + \fBchar *\fR\fIname\fR, \fBcaddr_t\fR \fIvaluep\fR, \fBint\fR \fIlength\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_prop_undefine\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, + \fBchar *\fR\fIname\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_prop_modify\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, + \fBchar *\fR\fIname\fR, \fBcaddr_t\fR \fIvaluep\fR, \fBint\fR \fIlength\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_prop_remove\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_prop_remove_all\fR(\fBdev_info_t *\fR\fIdip\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_prop_create()\fR and +\fBddi_prop_modify()\fR functions are obsolete. Use \fBddi_prop_update\fR(9F) +instead of these functions. +.SH PARAMETERS +.sp +.LP +\fBddi_prop_create()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 10n +.rt +\fBdev_t\fR of the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 10n +.rt +\fBdev_info_t\fR pointer of the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 10n +.rt +\fIflag\fR modifiers. The only possible flag value is \fBDDI_PROP_CANSLEEP\fR: +Memory allocation may sleep. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 10n +.rt +name of property. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvaluep\fR\fR +.ad +.RS 10n +.rt +pointer to property value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlength\fR\fR +.ad +.RS 10n +.rt +property length. +.RE + +.sp +.LP +\fBddi_prop_undefine()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 9n +.rt +\fBdev_t\fR of the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 9n +.rt +\fBdev_info_t\fR pointer of the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 9n +.rt +flag modifiers. The only possible flag value is \fBDDI_PROP_CANSLEEP\fR: Memory +allocation may sleep. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 9n +.rt +name of property. +.RE + +.sp +.LP +\fBddi_prop_modify()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 10n +.rt +\fBdev_t\fR of the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 10n +.rt +\fBdev_info_t\fR pointer of the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 10n +.rt +flag modifiers. The only possible flag value is \fBDDI_PROP_CANSLEEP\fR: Memory +allocation may sleep. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 10n +.rt +name of property. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvaluep\fR\fR +.ad +.RS 10n +.rt +pointer to property value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlength\fR\fR +.ad +.RS 10n +.rt +property length. +.RE + +.sp +.LP +\fBddi_prop_remove()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 8n +.rt +\fBdev_t\fR of the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 8n +.rt +\fBdev_info_t\fR pointer of the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 8n +.rt +name of property. +.RE + +.sp +.LP +\fBddi_prop_remove_all()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 7n +.rt +\fBdev_info_t\fR pointer of the device. +.RE + +.SH DESCRIPTION +.sp +.LP +Device drivers have the ability to create and manage their own properties as +well as gain access to properties that the system creates on behalf of the +driver. A driver uses \fBddi_getproplen\fR(9F) to query whether or not a +specific property exists. +.sp +.LP +Property creation is done by creating a new property definition in the driver's +property list associated with \fIdip\fR. +.sp +.LP +Property definitions are stacked; they are added to the beginning of the +driver's property list when created. Thus, when searched for, the most recent +matching property definition will be found and its value will be return to the +caller. +.sp +.LP +The individual functions are described as follows: +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_create()\fR\fR +.ad +.RS 25n +.rt +\fBddi_prop_create()\fR adds a property to the device's property list. If the +property is not associated with any particular \fIdev\fR but is associated with +the physical device itself, then the argument \fIdev\fR should be the special +device \fBDDI_DEV_T_NONE\fR. If you do not have a \fIdev\fR for your device +(for example during \fBattach\fR(9E) time), you can create one using +\fBmakedevice\fR(9F) with a major number of \fBDDI_MAJOR_T_UNKNOWN.\fR +\fBddi_prop_create()\fR will then make the correct \fIdev\fR for your device. +.sp +For boolean properties, you must set \fIlength\fR to \fB0\fR. For all other +properties, the \fIlength\fR argument must be set to the number of bytes used +by the data structure representing the property being created. +.sp +Note that creating a property involves allocating memory for the property list, +the property name and the property value. If \fIflags\fR does not contain +\fBDDI_PROP_CANSLEEP\fR, \fBddi_prop_create()\fR returns +\fBDDI_PROP_NO_MEMORY\fR on memory allocation failure or \fBDDI_PROP_SUCCESS\fR +if the allocation succeeded. If \fBDDI_PROP_CANSLEEP\fR was set, the caller may +sleep until memory becomes available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_undefine()\fR\fR +.ad +.RS 25n +.rt +\fBddi_prop_undefine()\fR is a special case of property creation where the +value of the property is set to undefined. This property has the effect of +terminating a property search at the current devinfo node, rather than allowing +the search to proceed up to ancestor devinfo nodes. However, +\fBddi_prop_undefine()\fR will not terminate a search when the +\fBddi_prop_get_int\fR(9F) or \fBddi_prop_lookup\fR(9F) routines are used for +lookup of 64-bit property value. See \fBddi_prop_op\fR(9F). +.sp +Note that undefining properties does involve memory allocation, and therefore, +is subject to the same memory allocation constraints as +\fBddi_prop_create()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_modify()\fR\fR +.ad +.RS 25n +.rt +\fBddi_prop_modify()\fR modifies the length and the value of a property. If +\fBddi_prop_modify()\fR finds the property in the driver's property list, +allocates memory for the property value and returns \fBDDI_PROP_SUCCESS\fR. If +the property was not found, the function returns \fBDDI_PROP_NOT_FOUND\fR. +.sp +Note that modifying properties does involve memory allocation, and therefore, +is subject to the same memory allocation constraints as +\fBddi_prop_create()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_remove()\fR\fR +.ad +.RS 25n +.rt +\fBddi_prop_remove()\fR unlinks a property from the device's property list. If +\fBddi_prop_remove()\fR finds the property (an exact match of both +\fIname\fRand \fIdev\fR), it unlinks the property, frees its memory, and +returns \fBDDI_PROP_SUCCESS,\fR otherwise, it returns \fBDDI_PROP_NOT_FOUND\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_remove_all()\fR\fR +.ad +.RS 25n +.rt +\fBddi_prop_remove_all()\fR removes the properties of all the \fBdev_t\fR's +associated with the \fIdip\fR. It is called before unloading a driver. +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBddi_prop_create()\fR function returns the following values: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_SUCCESS\fR\fR +.ad +.RS 22n +.rt +On success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NO_MEMORY\fR\fR +.ad +.RS 22n +.rt +On memory allocation failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_INVAL_ARG\fR\fR +.ad +.RS 22n +.rt +If an attempt is made to create a property with \fIdev\fR equal to +\fBDDI_DEV_T_ANY\fR or if \fIname\fR is \fINULL\fR or \fIname\fR is the +\fINULL\fR string. +.RE + +.sp +.LP +The \fBddi_prop_ undefine()\fR function returns the following values: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_SUCCESS\fR\fR +.ad +.RS 22n +.rt +On success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NO_MEMORY\fR\fR +.ad +.RS 22n +.rt +On memory allocation failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_INVAL_ARG\fR\fR +.ad +.RS 22n +.rt +If an attempt is made to create a property with \fIdev\fR \fBDDI_DEV_T_ANY\fR +or if \fIname\fR is \fINULL\fR or \fIname\fR is the \fINULL\fR string. +.RE + +.sp +.LP +The \fBddi_prop_modify()\fR function returns the following values: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_SUCCESS\fR\fR +.ad +.RS 22n +.rt +On success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NO_MEMORY\fR\fR +.ad +.RS 22n +.rt +On memory allocation failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_INVAL_ARG\fR\fR +.ad +.RS 22n +.rt +If an attempt is made to create a property with \fIdev\fR equal to +\fBDDI_DEV_T_ANY\fR or if \fIname\fR is \fINULL\fR or \fIname\fR is the +\fINULL\fR string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NOT_FOUND\fR\fR +.ad +.RS 22n +.rt +On property search failure. +.RE + +.sp +.LP +The \fBddi_prop_remove()\fR function returns the following values: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_SUCCESS\fR\fR +.ad +.RS 22n +.rt +On success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_INVAL_ARG\fR\fR +.ad +.RS 22n +.rt +If an attempt is made to create a property with \fIdev\fR equal to +\fBDDI_DEV_T_ANY\fR or if \fIname\fR is \fINULL\fR or \fIname\fR is the +\fINULL\fR string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NOT_FOUND\fR\fR +.ad +.RS 22n +.rt +On property search failure. +.RE + +.SH CONTEXT +.sp +.LP +If \fBDDI_PROP_CANSLEEP\fR is set, these functions can cannot be called from +interrupt context. Otherwise, they can be called from user, interrupt, or +kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRCreating a Property +.sp +.LP +The following example creates a property called \fInblocks\fR for each +partition on a disk. + +.sp +.in +2 +.nf +int propval = 8192; + +for (minor = 0; minor < 8; minor ++) { + (void) ddi_prop_create(makedevice(DDI_MAJOR_T_UNKNOWN, minor), + dev, DDI_PROP_CANSLEEP, "nblocks", (caddr_t) &propval, + sizeof (int)); + \&.\|.\|. +} +.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.66i) |cw(2.84i) +lw(2.66i) |lw(2.84i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Stability LevelT{ +\fBddi_prop_create()\fR and \fBddi_prop_modify()\fR are Obsolete +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBdriver.conf\fR(4), \fBattributes\fR(5), \fBattach\fR(9E), +\fBddi_getproplen\fR(9F), \fBddi_prop_op\fR(9F), \fBddi_prop_update\fR(9F), +\fBmakedevice\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_prop_exists.9f b/usr/src/man/man9f/ddi_prop_exists.9f new file mode 100644 index 0000000000..f590dd92ac --- /dev/null +++ b/usr/src/man/man9f/ddi_prop_exists.9f @@ -0,0 +1,189 @@ +'\" te +.\" Copyright (c) 1995, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_prop_exists 9F "22 May 1995" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_prop_exists \- check for the existence of a property +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_prop_exists\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIflags\fR, + \fBchar *\fR\fIname\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImatch_dev\fR \fR +.ad +.RS 14n +.rt +Device number associated with property or \fBDDI_DEV_T_ANY.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR \fR +.ad +.RS 14n +.rt +Pointer to the device info node of device whose property list should be +searched. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR \fR +.ad +.RS 14n +.rt +Possible flag values are some combination of: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_DONTPASS\fR \fR +.ad +.RS 22n +.rt +Do not pass request to parent device information node if the property is not +found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NOTPROM\fR \fR +.ad +.RS 22n +.rt +Do not look at \fBPROM \fRproperties (ignored on platforms that do not support +\fBPROM \fRproperties). +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR \fR +.ad +.RS 14n +.rt +String containing the name of the property. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_prop_exists()\fR checks for the existence of a property regardless of +the property value data type. +.sp +.LP +Properties are searched for based on the \fIdip\fR, \fIname\fR, and +\fImatch_dev\fR. The property search order is as follows: +.RS +4 +.TP +1. +Search software properties created by the driver. +.RE +.RS +4 +.TP +2. +Search the software properties created by the system (or nexus nodes in the +device info tree). +.RE +.RS +4 +.TP +3. +Search the driver global properties list. +.RE +.RS +4 +.TP +4. +If \fBDDI_PROP_NOTPROM\fR is not set, search the \fBPROM \fRproperties (if +they exist). +.RE +.RS +4 +.TP +5. +If \fBDDI_PROP_DONTPASS\fR is not set, pass this request to the parent +device information node. +.RE +.RS +4 +.TP +6. +Return \fB0\fR if not found and \fB1\fR if found. +.RE +.sp +.LP +Usually, the \fImatch_dev\fR argument should be set to the actual device number +that this property is associated with. However, if the \fImatch_dev\fR +argument is \fBDDI_DEV_T_ANY,\fR then \fBddi_prop_exists()\fR will match the +request regardless of the \fImatch_dev\fR the property was created with. +That is the first property whose name matches \fIname\fR will be returned. If +a property was created with \fImatch_dev\fR set to \fBDDI_DEV_T_NONE\fR then +the only way to look up this property is with a \fImatch_dev\fR set to +\fBDDI_DEV_T_ANY.\fR \fBPROM \fRproperties are always created with +\fImatch_dev\fR set to \fBDDI_DEV_T_NONE.\fR +.sp +.LP +\fIname\fR must always be set to the name of the property being looked up. +.SH RETURN VALUES +.sp +.LP +\fBddi_prop_exists()\fR returns \fB1\fR if the property exists and \fB0\fR +otherwise. +.SH CONTEXT +.sp +.LP +These functions can be called from user or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fR: Using \fBddi_prop_exists()\fR +.sp +.LP +The following example demonstrates the use of \fBddi_prop_exists()\fR. + +.sp +.in +2 +.nf +/* + * Enable "whizzy" mode if the "whizzy-mode" property exists + */ + if (ddi_prop_exists(xx_dev, xx_dip, DDI_PROP_NOTPROM, + "whizzy-mode") == 1) { + xx_enable_whizzy_mode(xx_dip); + } else { + xx_disable_whizzy_mode(xx_dip); + } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBddi_prop_get_int\fR(9F), \fBddi_prop_lookup\fR(9F), +\fBddi_prop_remove\fR(9F), \fBddi_prop_update\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_prop_get_int.9f b/usr/src/man/man9f/ddi_prop_get_int.9f new file mode 100644 index 0000000000..ced2df9a80 --- /dev/null +++ b/usr/src/man/man9f/ddi_prop_get_int.9f @@ -0,0 +1,215 @@ +'\" te +.\" Copyright (c) 2001, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_prop_get_int 9F "25 Aug 2001" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_prop_get_int, ddi_prop_get_int64 \- lookup integer property +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_prop_get_int\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIflags\fR, + \fBchar *\fR\fIname\fR, \fBint\fR \fIdefvalue\fR); +.fi + +.LP +.nf +\fBint64_t\fR \fBddi_prop_get_int64\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIflags\fR, + \fBchar *\fR\fIname\fR, \fBint64_t\fR \fIdefvalue\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImatch_dev\fR\fR +.ad +.RS 13n +.rt +Device number associated with property or \fBDDI_DEV_T_ANY.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 13n +.rt +Pointer to the device info node of device whose property list should be +searched. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 13n +.rt +Possible flag values are some combination of: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_DONTPASS\fR\fR +.ad +.RS 21n +.rt +Do not pass request to parent device information node if property not found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NOTPROM\fR\fR +.ad +.RS 21n +.rt +Do not look at \fBPROM \fRproperties (ignored on platforms that do not support +\fBPROM \fRproperties). +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 13n +.rt +String containing the name of the property. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdefvalue\fR\fR +.ad +.RS 13n +.rt +An integer value that is returned if the property cannot be found. +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBddi_prop_get_int()\fR and \fBddi_prop_get_int64()\fR functions search +for an integer property and, if found, returns the value of the property. +.sp +.LP +Properties are searched for based on the \fIdip\fR, \fIname\fR, +\fImatch_dev\fR, and the type of the data (integer). The property search order +is as follows: +.RS +4 +.TP +1. +Search software properties created by the driver. +.RE +.RS +4 +.TP +2. +Search the software properties created by the system (or nexus nodes in the +device info tree). +.RE +.RS +4 +.TP +3. +Search the driver global properties list. +.RE +.RS +4 +.TP +4. +If \fBDDI_PROP_NOTPROM\fR is not set, search the \fBPROM \fRproperties (if +they exist). +.RE +.RS +4 +.TP +5. +If \fBDDI_PROP_DONTPASS\fR is not set, pass this request to the parent +device information node. +.RE +.RS +4 +.TP +6. +Return \fIdefvalue\fR. +.RE +.sp +.LP +Usually, the \fImatch_dev\fR argument should be set to the actual device number +that this property is associated with. However, if the \fImatch_dev\fR argument +is \fBDDI_DEV_T_ANY,\fR then \fBddi_prop_get_int()\fR and +\fBddi_prop_get_int()\fR will match the request regardless of the +\fImatch_dev\fR the property was created with. If a property was created with +\fImatch_dev\fR set to \fBDDI_DEV_T_NONE,\fR then the only way to look up this +property is with a \fImatch_dev\fR set to \fBDDI_DEV_T_ANY.\fR \fBPROM +\fRproperties are always created with \fImatch_dev\fR set to +\fBDDI_DEV_T_NONE.\fR +.sp +.LP +\fIname\fR must always be set to the name of the property being looked up. +.sp +.LP +The return value of the routine is the value of the property. If the property +is not found, the argument \fIdefvalue\fR is returned as the value of the +property. +.sp +.LP +\fBddi_prop_get_int64()\fR will not search the PROM for 64-bit property values. +.SH RETURN VALUES +.sp +.LP +\fBddi_prop_get_int()\fR and \fBddi_prop_get_int64()\fR return the value of the +property. If the property is not found, the argument \fBdefvalue\fR is +returned. If the property is found, but cannot be decoded into an \fBint\fR or +an \fBint64\fR, then \fBDDI_PROP_NOT_FOUND\fR is returned. +.SH CONTEXT +.sp +.LP +\fBddi_prop_get_int()\fR and \fBddi_prop_get_int64()\fR can be called from user +or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBddi_prop_get_int()\fR +.sp +.LP +The following example demonstrates the use of \fBddi_prop_get_int()\fR. + +.sp +.in +2 +.nf +\fB +/* + * Get the value of the integer "width" property, using + * our own default if no such property exists + */ + width = ddi_prop_get_int(xx_dev, xx_dip, 0, "width", + XX_DEFAULT_WIDTH);\fR +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBddi_prop_exists\fR(9F), \fBddi_prop_lookup\fR(9F), +\fBddi_prop_remove\fR(9F), \fBddi_prop_update\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_prop_lookup.9f b/usr/src/man/man9f/ddi_prop_lookup.9f new file mode 100644 index 0000000000..2b72c336bc --- /dev/null +++ b/usr/src/man/man9f/ddi_prop_lookup.9f @@ -0,0 +1,488 @@ +'\" 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 ddi_prop_lookup 9F "11 Apr 2001" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_prop_lookup, ddi_prop_lookup_int_array, ddi_prop_lookup_int64_array, +ddi_prop_lookup_string_array, ddi_prop_lookup_string, +ddi_prop_lookup_byte_array, ddi_prop_free \- look up property information +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_prop_lookup_int_array\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR, + \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBint **\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_prop_lookup_int64_array\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR, + \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBint64_t **\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_prop_lookup_string_array\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR, + \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBchar ***\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_prop_lookup_string\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIflags\fR, + \fBchar *\fR\fIname\fR, \fBchar **\fR\fIdatap\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_prop_lookup_byte_array\fR(\fBdev_t\fR \fImatch_dev\fR, \fBdev_info_t *\fR\fIdip\fR, + \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBuchar_t **\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_prop_free\fR(\fBvoid *\fR\fIdata\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImatch_dev\fR\fR +.ad +.RS 14n +.rt +Device number associated with property or \fBDDI_DEV_T_ANY.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 14n +.rt +Pointer to the device info node of device whose property list should be +searched. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 14n +.rt +Possible flag values are some combination of: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_DONTPASS\fR\fR +.ad +.RS 21n +.rt +Do not pass request to parent device information node if the property is not +found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NOTPROM\fR\fR +.ad +.RS 21n +.rt +Do not look at \fBPROM \fRproperties (ignored on platforms that do not support +\fBPROM \fRproperties). +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 14n +.rt +String containing the name of the property. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInelementsp\fR\fR +.ad +.RS 14n +.rt +The address of an unsigned integer which, upon successful return, will contain +the number of elements accounted for in the memory pointed at by \fIdatap\fR. +The elements are either integers, strings or bytes depending on the interface +used. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdatap\fR\fR +.ad +.RS 14n +.rt +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_lookup_int_array()\fR\fR +.ad +.sp .6 +.RS 4n +The address of a pointer to an array of integers which, upon successful return, +will point to memory containing the integer array property value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_lookup_int64_array()\fR\fR +.ad +.sp .6 +.RS 4n +The address of a pointer to an array of 64-bit integers which, upon successful +return, will point to memory containing the integer array property value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_lookup_string_array()\fR\fR +.ad +.sp .6 +.RS 4n +The address of a pointer to an array of strings which, upon successful return, +will point to memory containing the array of strings. The array of strings is +formatted as an array of pointers to \fBNULL \fRterminated strings, much like +the \fIargv\fR argument to \fBexecve\fR(2). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_lookup_string()\fR\fR +.ad +.sp .6 +.RS 4n +The address of a pointer to a string which, upon successful return, will point +to memory containing the \fBNULL \fRterminated string value of the property. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_lookup_byte_array()\fR\fR +.ad +.sp .6 +.RS 4n +The address of pointer to an array of bytes which, upon successful return, will +point to memory containing the byte array value of the property. +.RE + +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The property look up routines search for and, if found, return the value of a +given property. Properties are searched for based on the \fIdip\fR, \fIname\fR, +\fImatch_dev\fR, and the type of the data (integer, string, or byte). The +property search order is as follows: +.RS +4 +.TP +1. +Search software properties created by the driver. +.RE +.RS +4 +.TP +2. +Search the software properties created by the system (or nexus nodes in the +device info tree). +.RE +.RS +4 +.TP +3. +Search the driver global properties list. +.RE +.RS +4 +.TP +4. +If \fBDDI_PROP_NOTPROM\fR is not set, search the \fBPROM \fRproperties (if +they exist). +.RE +.RS +4 +.TP +5. +If \fBDDI_PROP_DONTPASS\fR is not set, pass this request to the parent +device information node. +.RE +.RS +4 +.TP +6. +Return \fBDDI_PROP_NOT_FOUND\fR. +.RE +.sp +.LP +Usually, the \fImatch_dev\fR argument should be set to the actual device number +that this property is associated with. However, if the \fImatch_dev\fR argument +is \fBDDI_DEV_T_ANY\fR, the property look up routines will match the request +regardless of the actual \fImatch_dev\fR the property was created with. If a +property was created with \fImatch_dev\fR set to \fBDDI_DEV_T_NONE\fR, then the +only way to look up this property is with a \fImatch_dev\fR set to +\fBDDI_DEV_T_ANY\fR. \fBPROM \fRproperties are always created with +\fImatch_dev\fR set to \fBDDI_DEV_T_NONE\fR. +.sp +.LP +\fIname\fR must always be set to the name of the property being looked up. +.sp +.LP +For the routines \fBddi_prop_lookup_int_array()\fR, +\fBddi_prop_lookup_int64_array()\fR, \fBddi_prop_lookup_string_array()\fR, +\fBddi_prop_lookup_string()\fR, and \fBddi_prop_lookup_byte_array()\fR, +\fIdatap\fR is the address of a pointer which, upon successful return, will +point to memory containing the value of the property. In each case \fI*datap\fR +points to a different type of property value. See the individual descriptions +of the routines below for details on the different return values. +\fInelementsp\fR is the address of an unsigned integer which, upon successful +return, will contain the number of integer, string or byte elements accounted +for in the memory pointed at by \fI*datap\fR. +.sp +.LP +All of the property look up routines may block to allocate memory needed to +hold the value of the property. +.sp +.LP +When a driver has obtained a property with any look up routine and is finished +with that property, it must be freed by calling \fBddi_prop_free()\fR. +\fBddi_prop_free()\fR must be called with the address of the allocated +property. For instance, if one called \fBddi_prop_lookup_int_array()\fR with +\fIdatap\fR set to the address of a pointer to an integer, \fI&my_int_ptr\fR, +then the companion free call would be +\fBddi_prop_free(\fR\fImy_int_ptr\fR\fB)\fR. +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_lookup_int_array()\fR\fR +.ad +.sp .6 +.RS 4n +This routine searches for and returns an array of integer property values. An +array of integers is defined to \fI*nelementsp\fR number of 4 byte long integer +elements. \fIdatap\fR should be set to the address of a pointer to an array of +integers which, upon successful return, will point to memory containing the +integer array value of the property. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_lookup_int64_array()\fR\fR +.ad +.sp .6 +.RS 4n +This routine searches for and returns an array of 64-bit integer property +values. The array is defined to be *\fInelementsp\fR number of \fBint64_t\fR +elements. \fIdatap\fR should be set to the address of a pointer to an array of +\fBint64_t\fR's which, upon successful return, will point to memory containing +the integer array value of the property. This routine will not search the PROM +for 64-bit property values. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_lookup_string_array()\fR\fR +.ad +.sp .6 +.RS 4n +This routine searches for and returns a property that is an array of strings. +\fIdatap\fR should be set to address of a pointer to an array of strings which, +upon successful return, will point to memory containing the array of strings. +The array of strings is formatted as an array of pointers to null-terminated +strings, much like the \fIargv\fR argument to \fBexecve\fR(2). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_lookup_string()\fR\fR +.ad +.sp .6 +.RS 4n +This routine searches for and returns a property that is a null-terminated +string. \fIdatap\fR should be set to the address of a pointer to string which, +upon successful return, will point to memory containing the string value of the +property. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_lookup_byte_array()\fR\fR +.ad +.sp .6 +.RS 4n +This routine searches for and returns a property that is an array of bytes. +\fIdatap\fR should be set to the address of a pointer to an array of bytes +which, upon successful return, will point to memory containing the byte array +value of the property. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_free()\fR\fR +.ad +.sp .6 +.RS 4n +Frees the resources associated with a property previously allocated using +\fBddi_prop_lookup_int_array()\fR, \fBddi_prop_lookup_int64_array()\fR, +\fBddi_prop_lookup_string_array()\fR, \fBddi_prop_lookup_string()\fR, or +\fBddi_prop_lookup_byte_array()\fR. +.RE + +.SH RETURN VALUES +.sp +.LP +The functions \fBddi_prop_lookup_int_array()\fR, +\fBddi_prop_lookup_int64_array()\fR, \fBddi_prop_lookup_string_array()\fR, +\fBddi_prop_lookup_string()\fR, and \fBddi_prop_lookup_byte_array()\fR return +the following values: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_SUCCESS\fR\fR +.ad +.RS 26n +.rt +Upon success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_INVAL_ARG\fR\fR +.ad +.RS 26n +.rt +If an attempt is made to look up a property with \fImatch_dev\fR equal to +\fBDDI_DEV_T_NONE\fR, \fIname\fR is \fBNULL \fRor \fIname\fR is the null +string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NOT_FOUND\fR\fR +.ad +.RS 26n +.rt +Property not found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_UNDEFINED\fR\fR +.ad +.RS 26n +.rt +Property explicitly not defined (see \fBddi_prop_undefine\fR(9F)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_CANNOT_DECODE\fR\fR +.ad +.RS 26n +.rt +The value of the property cannot be decoded. +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from user or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBddi_prop_lookup_int_array()\fR +.sp +.LP +The following example demonstrates the use of +\fBddi_prop_lookup_int_array()\fR. + +.sp +.in +2 +.nf + +int *options; +int noptions; + +/* + * Get the data associated with the integer "options" property + * array, along with the number of option integers + */ + if (ddi_prop_lookup_int_array(DDI_DEV_T_ANY, xx_dip, 0, + "options", &options, &noptions) == DDI_PROP_SUCCESS) { + /* + * Do "our thing" with the options data from the property + */ + xx_process_options(options, noptions); + + /* + * Free the memory allocated for the property data + */ + ddi_prop_free(options); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBexecve\fR(2), \fBddi_prop_exists\fR(9F), \fBddi_prop_get_int\fR(9F), +\fBddi_prop_remove\fR(9F), \fBddi_prop_undefine\fR(9F), +\fBddi_prop_update\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_prop_op.9f b/usr/src/man/man9f/ddi_prop_op.9f new file mode 100644 index 0000000000..ab0be87745 --- /dev/null +++ b/usr/src/man/man9f/ddi_prop_op.9f @@ -0,0 +1,368 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_prop_op 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_prop_op, ddi_getprop, ddi_getlongprop, ddi_getlongprop_buf, ddi_getproplen +\- get property information for leaf device drivers +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_prop_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 + +.LP +.nf +\fBint\fR \fBddi_getprop\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, + \fBint\fR \fIdefvalue\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_getlongprop\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, + \fBcaddr_t\fR \fIvaluep\fR, \fBint *\fR\fIlengthp\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_getlongprop_buf\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, + \fBcaddr_t\fR \fIvaluep\fR, \fBint *\fR\fIlengthp\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_getproplen\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, + \fBint *\fR\fIlengthp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_getlongprop()\fR, +\fBddi_getlongprop_buf()\fR, \fBddi_getprop()\fR, and \fBddi_getproplen()\fR +functions are obsolete. Use \fBddi_prop_lookup\fR(9F) instead of +\fBddi_getlongprop()\fR, \fBddi_getlongprop_buf()\fR, and +\fBddi_getproplen()\fR. Use \fBddi_prop_get_int\fR(9F) instead of +\fBddi_getprop()\fR +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 12n +.rt +Device number associated with property or \fBDDI_DEV_T_ANY\fR as the +\fIwildcard\fR device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 12n +.rt +Pointer to a device info node. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprop_op\fR\fR +.ad +.RS 12n +.rt +Property operator. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 12n +.rt +Possible flag values are some combination of: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_DONTPASS\fR\fR +.ad +.RS 21n +.rt +do not pass request to parent device information node if property not found +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_CANSLEEP\fR\fR +.ad +.RS 21n +.rt +the routine may sleep while allocating memory +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NOTPROM\fR\fR +.ad +.RS 21n +.rt +do not look at PROM properties (ignored on architectures that do not support +PROM properties) +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 12n +.rt +String containing the name of the property. +.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 +users 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, \fI*lengthp\fR will contain the property length. If \fIprop_op\fR is +\fBPROP_LEN_AND_VAL_BUF\fR then before calling \fBddi_prop_op()\fR, +\fIlengthp\fR should point to an \fBint\fR that contains the length of callers +buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdefvalue\fR\fR +.ad +.RS 12n +.rt +The value that \fBddi_getprop()\fR returns if the property is not found. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_prop_op()\fR function gets arbitrary-size properties for leaf +devices. The routine searches the device's property list. If it does not find +the property at the device level, it examines the \fIflags\fR argument, and if +\fBDDI_PROP_DONTPASS\fR is set, then \fBddi_prop_op()\fR returns +\fBDDI_PROP_NOT_FOUND.\fR Otherwise, it passes the request to the next level of +the device info tree. If it does find the property, but the property has been +explicitly undefined, it returns \fBDDI_PROP_UNDEFINED.\fR Otherwise it returns +either the property length, or both the length and value of the property to the +caller via the \fIvaluep\fR and \fIlengthp\fR pointers, depending on the value +of \fIprop_op\fR, as described below, and returns \fBDDI_PROP_SUCCESS.\fR If a +property cannot be found at all, \fBDDI_PROP_NOT_FOUND\fR is returned. +.sp +.LP +Usually, the \fIdev\fR argument should be set to the actual device number that +this property applies to. However, if the \fIdev\fR argument is +\fBDDI_DEV_T_ANY,\fR the \fIwildcard dev\fR, then \fBddi_prop_op()\fR will +match the request based on \fIname\fR only (regardless of the actual \fIdev\fR +the property was created with). This property/dev match is done according to +the property search order which is to first search software properties created +by the driver in \fIlast-in, first-out\fR (LIFO) order, next search software +properties created by the \fIsystem\fR in LIFO order, then search PROM +properties if they exist in the system architecture. +.sp +.LP +Property operations are specified by the \fIprop_op\fR argument. If +\fIprop_op\fR is \fBPROP_LEN,\fR then \fBddi_prop_op()\fR just sets the callers +length, \fI*lengthp,\fR to the property length and returns the value +\fBDDI_PROP_SUCCESS\fR to the caller. The \fIvaluep\fR argument is not used in +this case. Property lengths are \fB0\fR for boolean properties, +\fBsizeof\|(int)\fR for integer properties, and size in bytes for long +(variable size) properties. +.sp +.LP +If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_BUF,\fR then \fIvaluep\fR should be a +pointer to a user-supplied buffer whose length should be given in +\fI*lengthp\fR by the caller. If the requested property exists, +\fBddi_prop_op()\fR first sets \fI*lengthp\fR to the property length. It then +examines the size of the buffer supplied by the caller, and if it is large +enough, copies the property value into that buffer, and returns +\fBDDI_PROP_SUCCESS.\fR If the named property exists but the buffer supplied is +too small to hold it, it returns \fBDDI_PROP_BUF_TOO_SMALL.\fR +.sp +.LP +If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_ALLOC,\fR and the property is found, +\fBddi_prop_op()\fR sets \fI*lengthp\fR to the property length. It then +attempts to allocate a buffer to return to the caller using the +\fBkmem_alloc\fR(9F) routine, so that memory can be later recycled using +\fBkmem_free\fR(9F). The driver is expected to call \fBkmem_free()\fR with the +returned address and size when it is done using the allocated buffer. If the +allocation is successful, it sets \fI*valuep\fR to point to the allocated +buffer, copies the property value into the buffer and returns +\fBDDI_PROP_SUCCESS.\fR Otherwise, it returns \fBDDI_PROP_NO_MEMORY.\fR Note +that the \fIflags\fR argument may affect the behavior of memory allocation in +\fBddi_prop_op()\fR. In particular, if \fBDDI_PROP_CANSLEEP\fR is set, then the +routine will wait until memory is available to copy the requested property. +.sp +.LP +The \fBddi_getprop()\fR function returns boolean and integer-size properties. +It is a convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to +\fBPROP_LEN_AND_VAL_BUF\fR, and the buffer is provided by the wrapper. By +convention, this function returns a \fB1\fR for boolean (zero-length) +properties. +.sp +.LP +The \fBddi_getlongprop()\fR function returns arbitrary-size properties. It is a +convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to +\fBPROP_LEN_AND_VAL_ALLOC,\fR so that the routine will allocate space to hold +the buffer that will be returned to the caller via \fI*valuep\fR. +.sp +.LP +The \fBddi_getlongprop_buf()\fR function returns arbitrary-size properties. It +is a convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to +\fBPROP_LEN_AND_VAL_BUF\fR so the user must supply a buffer. +.sp +.LP +The \fBddi_getproplen()\fR function returns the length of a given property. It +is a convenience wrapper for \fBddi_prop_op()\fR with \fIprop_op\fR set to +\fBPROP_LEN\fR. +.SH RETURN VALUES +.sp +.LP +The \fBddi_prop_op()\fR, \fBddi_getlongprop()\fR, \fBddi_getlongprop_buf()\fR, +and \fBddi_getproplen()\fR functions return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_SUCCESS\fR\fR +.ad +.RS 26n +.rt +Property found and returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NOT_FOUND\fR\fR +.ad +.RS 26n +.rt +Property not found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_UNDEFINED\fR\fR +.ad +.RS 26n +.rt +Property already explicitly undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_NO_MEMORY\fR\fR +.ad +.RS 26n +.rt +Property found, but unable to allocate memory. \fIlengthp\fR points to the +correct property length. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_BUF_TOO_SMALL\fR\fR +.ad +.RS 26n +.rt +Property found, but the supplied buffer is too small. \fIlengthp\fR points to +the correct property length. +.RE + +.sp +.LP +The \fBddi_getprop()\fR function returns: +.sp +.LP +The value of the property or the value passed into the routine as +\fIdefvalue\fR if the property is not found. By convention, the value of zero +length properties (boolean properties) are returned as the integer value 1. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context, provided +\fBDDI_PROP_CANSLEEP\fR is not set; if it is set, they cannot be called from +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.51i) |cw(2.99i) +lw(2.51i) |lw(2.99i) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Stability LevelT{ +\fBddi_getlongprop()\fR, \fBddi_getlongprop_buf()\fR, \fBddi_getprop()\fR, and \fBddi_getproplen()\fR functions are Obsolete +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_prop_create\fR(9F), \fBddi_prop_get_int\fR(9F), +\fBddi_prop_lookup\fR(9F), \fBkmem_alloc\fR(9F), \fBkmem_free\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_prop_update.9f b/usr/src/man/man9f/ddi_prop_update.9f new file mode 100644 index 0000000000..7f5cd9433a --- /dev/null +++ b/usr/src/man/man9f/ddi_prop_update.9f @@ -0,0 +1,396 @@ +'\" 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 ddi_prop_update 9F "28 Aug 2001" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_prop_update, ddi_prop_update_int_array, ddi_prop_update_int, +ddi_prop_update_string_array, ddi_prop_update_int64, +ddi_prop_update_int64_array, ddi_prop_update_string, ddi_prop_update_byte_array +\- update properties +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_prop_update_int_array\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, + \fBchar *\fR\fIname\fR, \fBint *\fR\fIdata\fR, \fBuint_t\fR \fInelements\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_prop_update_int\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR, + \fBint\fR \fIdata\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_prop_update_int64_array\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR, + \fBint64_t *\fR\fIdata\fR, \fBuint_t\fR \fInelements\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_prop_update_int64\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR, + \fBint64_t\fR \fIdata\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_prop_update_string_array\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR, + \fBchar **\fR\fIdata\fR, \fBuint_t\fR \fInelements\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_prop_update_string\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR, + \fBchar *\fR\fIdata\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_prop_update_byte_array\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR, + \fBuchar_t *\fR\fIdata\fR, \fBuint_t\fR \fInelements\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR \fR +.ad +.RS 14n +.rt +Device number associated with the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR \fR +.ad +.RS 14n +.rt +Pointer to the device info node of device whose property list should be +updated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR \fR +.ad +.RS 14n +.rt +String containing the name of the property to be updated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInelements\fR \fR +.ad +.RS 14n +.rt +The number of elements contained in the memory pointed at by \fIdata\fR. +.RE + +.sp +.LP +\fBddi_prop_update_int_array()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdata\fR \fR +.ad +.RS 9n +.rt +A pointer an integer array with which to update the property. +.RE + +.sp +.LP +\fBddi_prop_update_int()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdata\fR \fR +.ad +.RS 9n +.rt +An integer value with which to update the property. +.RE + +.sp +.LP +\fBddi_prop_update_int64_array()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdata\fR \fR +.ad +.RS 9n +.rt +An pointer to a 64-bit integer array with which to update the property. +.RE + +.sp +.LP +\fBddi_prop_update_int64()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdata\fR \fR +.ad +.RS 9n +.rt +A 64-bit integer value with which to update the property. +.RE + +.sp +.LP +\fBddi_prop_update_string_array()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdata\fR \fR +.ad +.RS 9n +.rt +A pointer to a string array with which to update the property. The array of +strings is formatted as an array of pointers to \fBNULL \fRterminated strings, +much like the \fIargv\fR argument to \fBexecve\fR(2). +.RE + +.sp +.LP +\fBddi_prop_update_string()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdata\fR \fR +.ad +.RS 9n +.rt +A pointer to a string value with which to update the property. +.RE + +.sp +.LP +\fBddi_prop_update_byte_array()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdata\fR \fR +.ad +.RS 9n +.rt +A pointer to a byte array with which to update the property. +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The property update routines search for and, if found, modify the value of a +given property. Properties are searched for based on the \fIdip\fR, \fIname\fR, +\fIdev\fR, and the type of the data (integer, string, or byte). The driver +software properties list is searched. If the property is found, it is updated +with the supplied value. If the property is not found on this list, a new +property is created with the value supplied. For example, if a driver attempts +to update the "foo" property, a property named "foo" is searched for on the +driver's software property list. If "foo" is found, the value is updated. If +"foo" is not found, a new property named "foo" is created on the driver's +software property list with the supplied value even if a "foo" property exists +on another property list (such as a \fBPROM \fRproperty list). +.sp +.LP +Every property value has a data type associated with it: byte, integer, or +string. A property should be updated using a function with the same +corresponding data type as the property value. For example, an integer property +must be updated using either \fBddi_prop_update_int_array()\fR or +\fBddi_prop_update_int()\fR. For a 64-bit integer, you must use +\fBddi_prop_update_int64_array()\fR or \fBddi_prop_update_int64()\fR. Attempts +to update a property with a function that does not correspond to the property +data type that was used to create it results in an undefined state. +.sp +.LP +Usually, the \fIdev\fR argument should be set to the actual device number that +this property is associated with. If the property is not associated with any +particular \fIdev\fR, then the argument \fIdev\fR should be set to +\fBDDI_DEV_T_NONE.\fR This property will then match a look up request (see +\fBddi_prop_lookup\fR(9F)) with the \fImatch_dev\fR argument set to +\fBDDI_DEV_T_ANY.\fR If no \fIdev\fR is available for the device (for example +during \fBattach\fR(9E) time), one can be created using \fBmakedevice\fR(9F) +with a major number of \fBDDI_MAJOR_T_UNKNOWN.\fR The update routines will then +generate the correct \fIdev\fR when creating or updating the property. +.sp +.LP +\fIname\fR must always be set to the name of the property being updated. +.sp +.LP +For the routines \fBddi_prop_update_int_array\fR(\|), +\fBddi_prop_lookup_int64_array()\fR, \fBddi_prop_update_string_array\fR(\|), +\fBddi_prop_update_string\fR(\|), and \fBddi_prop_update_byte_array\fR(\|), +\fIdata\fR is a pointer which points to memory containing the value of the +property. In each case \fI*data\fR points to a different type of property +value. See the individual descriptions of the routines below for details +concerning the different values. \fInelements\fR is an unsigned integer which +contains the number of integer, string, or byte elements accounted for in the +memory pointed at by \fI*data\fR. +.sp +.LP +For the routines \fBddi_prop_update_int()\fR and \fBddi_prop_update_int64()\fR, +\fIdata\fR is the new value of the property. +.sp +.LP +\fBddi_prop_update_int_array()\fR +.sp +.LP +Updates or creates an array of integer property values. An array of integers is +defined to be \fInelements\fR of 4 byte long integer elements. \fIdata\fR must +be a pointer to an integer array with which to update the property. +.sp +.LP +\fBddi_prop_update_int()\fR +.sp +.LP +Update or creates a single integer value of a property. \fIdata\fR must be an +integer value with which to update the property. +.sp +.LP +\fBddi_prop_update_int64_array()\fR +.sp +.LP +Updates or creates an array of 64-bit integer property values. An array of +integers is defined to be \fBnelements\fR of \fBint64_t\fR integer elements. +\fIdata\fR must be a pointer to a 64-bit integer array with which to update the +property. +.sp +.LP +\fBddi_prop_update_int64()\fR +.sp +.LP +Updates or creates a single 64-bit integer value of a property. \fIdata\fR must +be an \fBint64_t\fR value with which to update the property. +.sp +.LP +\fBddi_prop_update_string_array()\fR +.sp +.LP +Updates or creates a property that is an array of strings. \fIdata\fR must be a +pointer to a string array with which to update the property. The array of +strings is formatted as an array of pointers to \fBNULL\fRterminated strings, +much like the \fIargv\fR argument to \fBexecve\fR(2). +.sp +.LP +\fBddi_prop_update_string()\fR +.sp +.LP +Updates or creates a property that is a single string value. \fIdata\fR must be +a pointer to a string with which to update the property. +.sp +.LP +\fBddi_prop_update_byte_array()\fR +.sp +.LP +Updates or creates a property that is an array of bytes. \fIdata\fR should be a +pointer to a byte array with which to update the property. +.sp +.LP +The property update routines may block to allocate memory needed to hold the +value of the property. +.SH RETURN VALUES +.sp +.LP +All of the property update routines return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_SUCCESS\fR \fR +.ad +.RS 27n +.rt +On success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_INVAL_ARG\fR \fR +.ad +.RS 27n +.rt +If an attempt is made to update a property with \fIname\fR set to \fINULL\fR or +\fIname\fR set to the null string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_PROP_CANNOT_ENCODE\fR \fR +.ad +.RS 27n +.rt +If the bytes of the property cannot be encoded. +.RE + +.SH CONTEXT +.sp +.LP +These functions can only be called from user or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUpdating Properties +.sp +.LP +The following example demonstrates the use of +\fBddi_prop_update_int_array()\fR. + +.sp +.in +2 +.nf +int options[4]; + + /* + * Create the "options" integer array with + * our default values for these parameters + */ + options[0] = XX_OPTIONS0; + options[1] = XX_OPTIONS1; + options[2] = XX_OPTIONS2; + options[3] = XX_OPTIONS3; + i = ddi_prop_update_int_array(xx_dev, xx_dip, "options", + &options, sizeof (options) / sizeof (int)); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBexecve\fR(2), \fBattach\fR(9E), \fBddi_prop_lookup\fR(9F), +\fBddi_prop_remove\fR(9F), \fBmakedevice\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_put8.9f b/usr/src/man/man9f/ddi_put8.9f new file mode 100644 index 0000000000..57a6750170 --- /dev/null +++ b/usr/src/man/man9f/ddi_put8.9f @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_put8 9F "1 Nov 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_put8, ddi_put16, ddi_put32, ddi_put64, ddi_putb, ddi_putl, ddi_putll, +ddi_putw \- write data to the mapped memory address, device register or +allocated DMA memory address +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_put8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint8_t\fR \fI*dev_addr\fR, + \fBuint8_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_put16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint16_t\fR \fI*dev_addr\fR, + \fBuint16_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_put32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint32_t\fR \fI*dev_addr\fR, + \fBuint32_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_put64\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint64_t\fR \fI*dev_addr\fR, + \fBuint64_t\fR \fIvalue\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_putb()\fR, \fBddi_putl()\fR, +\fBddi_putll()\fR, and \fBddi_putw()\fR functions are obsolete. The +\fBddi_put8()\fR function replaces \fBddi_putb()\fR. The \fBddi_put32()\fR +function replaces \fBddi_putl()\fR. The \fBddi_put64()\fR function replaces +\fBddi_putll()\fR. The \fBddi_put16()\fR function replaces \fBddi_putw()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 12n +.rt +The data access handle returned from setup calls, such as +\fBddi_regs_map_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvalue\fR\fR +.ad +.RS 12n +.rt +The data to be written to the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_addr\fR\fR +.ad +.RS 12n +.rt +Base device address. +.RE + +.SH DESCRIPTION +.sp +.LP +These routines generate a write of various sizes to the mapped memory or device +register. The \fBddi_put8()\fR, \fBddi_put16()\fR, \fBddi_put32()\fR, and +\fBddi_put64()\fR functions write 8 bits, 16 bits, 32 bits and 64 bits of data, +respectively, to the device address, \fIdev_addr\fR. +.sp +.LP +Each individual datum will automatically be translated to maintain a consistent +view between the host and the device based on the encoded information in the +data access handle. The translation may involve byte-swapping if the host and +the device have incompatible endian characteristics. +.sp +.LP +For certain bus types, you can call these \fBDDI\fR functions from a +high-interrupt context. These types include \fBISA\fR and SBus buses. See +\fBsysbus\fR(4), \fBisa\fR(4), and \fBsbus\fR(4) for details. For the PCI bus, +you can, under certain conditions, call these \fBDDI\fR functions from a +high-interrupt context. See \fBpci\fR(4). +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel, or interrupt context. +.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 StabilityT{ +\fBddi_putb()\fR, \fBddi_putl()\fR, \fBddi_putll()\fR, and \fBddi_putw()\fR are Obsolete \fBddi_put8()\fR, \fBddi_put16()\fR, \fBddi_put32()\fR, \fBddi_put64()\fR are Committed +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_get8\fR(9F), \fBddi_regs_map_free\fR(9F), \fBddi_regs_map_setup\fR(9F), +\fBddi_rep_get8\fR(9F), \fBddi_rep_put8\fR(9F), \fBddi_device_acc_attr\fR(9S) diff --git a/usr/src/man/man9f/ddi_regs_map_free.9f b/usr/src/man/man9f/ddi_regs_map_free.9f new file mode 100644 index 0000000000..e2b8379617 --- /dev/null +++ b/usr/src/man/man9f/ddi_regs_map_free.9f @@ -0,0 +1,71 @@ +'\" 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 ddi_regs_map_free 9F "18 Nov 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_regs_map_free \- free a previously mapped register address space +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_regs_map_free\fR(\fBddi_acc_handle_t\fR \fI*handle\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR specific (Solaris \fBDDI\fR). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 11n +.rt +Pointer to a data access handle previously allocated by a call to a setup +routine such as \fBddi_regs_map_setup\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_regs_map_free()\fR frees the mapping represented by the data access +handle \fIhandle\fR. This function is provided for drivers preparing to detach +themselves from the system, allowing them to release allocated system resources +represented in the handle. +.SH CONTEXT +.sp +.LP +\fBddi_regs_map_free()\fR must be called from user or kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI Local Bus, SBus, ISA +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_regs_map_setup\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_regs_map_setup.9f b/usr/src/man/man9f/ddi_regs_map_setup.9f new file mode 100644 index 0000000000..aef3e1eb9d --- /dev/null +++ b/usr/src/man/man9f/ddi_regs_map_setup.9f @@ -0,0 +1,214 @@ +'\" 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 ddi_regs_map_setup 9F "18 Nov 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_regs_map_setup \- set up a mapping for a register address space +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_regs_map_setup\fR(\fBdev_info_t\fR \fI*dip\fR, \fBuint_t\fR \fIrnumber\fR, \fBcaddr_t\fR \fI*addrp\fR, + \fBoffset_t\fR \fIoffset\fR, \fBoffset_t\fR \fIlen\fR, \fBddi_device_acc_attr_t\fR \fI*accattrp\fR, + \fBddi_acc_handle_t\fR \fI*handlep\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR specific (Solaris \fBDDI\fR). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 12n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrnumber\fR\fR +.ad +.RS 12n +.rt +Index number to the register address space set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddrp\fR\fR +.ad +.RS 12n +.rt +A platform-dependent value that, when added to an offset that is less than or +equal to the \fIlen\fR parameter (see below), is used for the \fBdev_addr\fR +argument to the \fBddi_get\fR, \fBddi_mem_get\fR, and +\fBddi_io_get\fR/\fBput\fR routines. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR\fR +.ad +.RS 12n +.rt +Offset into the register address space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 12n +.rt +Length to be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaccattrp\fR\fR +.ad +.RS 12n +.rt +Pointer to a device access attribute structure of this mapping (see +\fBddi_device_acc_attr\fR(9S)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandlep\fR\fR +.ad +.RS 12n +.rt +Pointer to a data access handle. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_regs_map_setup()\fR maps in the register set given by \fIrnumber\fR. The +register number determines which register set is mapped if more than one +exists. +.sp +.LP +\fIoffset\fR specifies the starting location within the register space and +\fIlen\fR indicates the size of the area to be mapped. If \fIlen\fR is +non-zero, it overrides the length given in the register set description. If +both \fIlen\fR and \fIoffset\fR are \fB0\fR, the entire space is mapped. The +base of the mapped register space is returned in \fIaddrp\fR. +.sp +.LP +The device access attributes are specified in the location pointed by the +\fIaccattrp\fR argument (see \fBddi_device_acc_attr\fR(9S) for details). +.sp +.LP +The data access handle is returned in \fIhandlep\fR. \fIhandlep\fR is opaque; +drivers should not attempt to interpret its value. The handle is used by the +system to encode information for subsequent data access function calls to +maintain a consistent view between the host and the device. +.SH RETURN VALUES +.sp +.LP +\fBddi_regs_map_setup()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 25n +.rt +Successfully set up the mapping for data access. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 25n +.rt +Invalid register number \fIrnumber\fR, offset \fIoffset\fR, or length +\fIlen\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_ME_RNUMBER_RANGE\fR\fR +.ad +.RS 25n +.rt +Invalid register number \fIrnumber\fR or unable to find \fIreg\fR property. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_REGS_ACC_CONFLICT\fR\fR +.ad +.RS 25n +.rt +Cannot enable the register mapping due to access conflicts with other enabled +mappings. +.RE + +.sp +.LP +Note that the return value \fBDDI_ME_RNUMBER_RANGE\fR is not supported on all +platforms. Also, there is potential overlap between \fBDDI_ME_RNUMBER_RANGE\fR +and \fBDDI_FAILURE\fR. Drivers should check for \fB!=DDI_SUCCESS\fR rather than +checking for a specific failure value. +.SH CONTEXT +.sp +.LP +\fBddi_regs_map_setup()\fR must be called from user or kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI Local Bus, SBus, ISA +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_regs_map_free\fR(9F), \fBddi_device_acc_attr\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_remove_event_handler.9f b/usr/src/man/man9f/ddi_remove_event_handler.9f new file mode 100644 index 0000000000..b934079999 --- /dev/null +++ b/usr/src/man/man9f/ddi_remove_event_handler.9f @@ -0,0 +1,99 @@ +'\" 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 ddi_remove_event_handler 9F "2 May 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_remove_event_handler \- remove an NDI event service callback handler +.SH SYNOPSIS +.LP +.nf +#include <sys/dditypes.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_remove_event_handler\fR(\fBddi_registration_id_t\fR \fIid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fBddi_registration_id_t \fR\fIid\fR\fR +.ad +.RS 28n +.rt +Unique system wide registration ID return by \fBddi_add_event_handler\fR(9F) +upon successful registration. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_remove_event_handler()\fR function removes the callback handler +specified by the registration \fIid\fR (\fBddi_registration_id_t\fR). Upon +successful removal, the callback handler is removed from the system and will +not be invoked in the face of the event. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Callback handler removed successfully. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Failed to remove callback handler. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_remove_event_handler()\fR function can be called from user and +kernel contexts only. +.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 LevelCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBddi_add_event_handler\fR(9F), +\fBddi_get_eventcookie\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Device drivers must remove all registered callback handlers before +\fBdetach\fR(9E) processing for that device instance is complete. diff --git a/usr/src/man/man9f/ddi_remove_minor_node.9f b/usr/src/man/man9f/ddi_remove_minor_node.9f new file mode 100644 index 0000000000..4ce29cb642 --- /dev/null +++ b/usr/src/man/man9f/ddi_remove_minor_node.9f @@ -0,0 +1,70 @@ +'\" 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 ddi_remove_minor_node 9F "10 Mar 1992" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_remove_minor_node \- remove a minor node for this dev_info +.SH SYNOPSIS +.LP +.nf +\fBvoid\fR \fBddi_remove_minor_node\fR(\fBdev_info_t\fR \fI*dip\fR, \fBchar\fR \fI*name\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR specific (Solaris \fBDDI\fR). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR \fR +.ad +.RS 9n +.rt +A pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR \fR +.ad +.RS 9n +.rt +The name of this minor device. If \fIname\fR is \fINULL\fR, then remove all +minor data structures from this \fBdev_info\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_remove_minor_node()\fR removes a data structure from the linked list of +minor data structures that is pointed to by the \fBdev_info\fR structure for +this driver. +.SH EXAMPLES +.LP +\fBExample 1 \fRRemoving a minor node +.sp +.LP +This will remove a data structure describing a minor device called \fBdev1\fR +which is linked into the \fBdev_info\fR structure pointed to by \fBdip\fR: + +.sp +.in +2 +.nf + ddi_remove_minor_node(dip, "dev1"); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBdetach\fR(9E), \fBddi_create_minor_node\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_removing_power.9f b/usr/src/man/man9f/ddi_removing_power.9f new file mode 100644 index 0000000000..0f79021b7f --- /dev/null +++ b/usr/src/man/man9f/ddi_removing_power.9f @@ -0,0 +1,130 @@ +'\" 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 ddi_removing_power 9F "14 March 2001" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_removing_power \- check whether \fBDDI_SUSPEND\fR might result in power +being removed from a device +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_removing_power\fR(\fBdev_info_t\fR \fI*dip\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBddi_removing_power()\fR function indicates whether a currently pending +call into a driver's \fBdetach\fR(9E) entry point with a command of +\fBDDI_SUSPEND\fR is likely to result in power being removed from the device. +.sp +.LP +\fBddi_removing_power()\fR can return true and power still not be removed from +the device due to a failure to suspend and power off the system. +.SH PARAMETERS +.sp +.LP +The \fBddi_removing_power()\fR function supports the following parameter: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 7n +.rt +pointer to the device's \fBdev_info\fR structure +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBddi_removing_power()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 5n +.rt +Power might be removed by the framework as a result of the pending +\fBDDI_SUSPEND\fR call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +Power will not be removed by the framework as a result of the pending +\fBDDI_SUSPEND\fR call. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRProtecting a Tape from Abrupt Power Removal +.sp +.LP +A tape driver that has hardware that would damage the tape if power is removed +might include this code in its \fBdetach\fR(9E) code: + +.sp +.in +2 +.nf +int + xxdetach(dev_info_t *dip, ddi_detach_cmd_t cmd) + { + + ... + case DDI_SUSPEND: + /* + * We do not allow DDI_SUSPEND if power will be removed and + * we have a device that damages tape when power is removed + * We do support DDI_SUSPEND for Device Reconfiguration, + * however. + */ + if (ddi_removing_power(dip) && xxdamages_tape(dip)) + return (DDI_FAILURE); + ... +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBcpr\fR(7), \fBattach\fR(9E), \fBdetach\fR(9E) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_rep_get8.9f b/usr/src/man/man9f/ddi_rep_get8.9f new file mode 100644 index 0000000000..bfa7bb0a68 --- /dev/null +++ b/usr/src/man/man9f/ddi_rep_get8.9f @@ -0,0 +1,186 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_rep_get8 9F "1 Nov 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_rep_get8, ddi_rep_get16, ddi_rep_get32, ddi_rep_get64, ddi_rep_getw, +ddi_rep_getl, ddi_rep_getll, ddi_rep_getb \- read data from the mapped memory +address, device register or allocated DMA memory address +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_rep_get8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint8_t\fR \fI*host_addr\fR, + \fBuint8_t\fR \fI*dev_addr\fR, \fBsize_t\fR \fIrepcount\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_rep_get16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint16_t\fR \fI*host_addr\fR, + \fBuint16_t\fR \fI*dev_addr\fR, \fBsize_t\fR \fIrepcount\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_rep_get32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint32_t\fR \fI*host_addr\fR, + \fBuint32_t\fR \fI*dev_addr\fR, \fBsize_t\fR \fIrepcount\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_rep_get64\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint64_t\fR \fI*host_addr\fR, + \fBuint64_t\fR \fI*dev_addr\fR, \fBsize_t\fR \fIrepcount\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_rep_getb()\fR, +\fBddi_rep_getl()\fR, \fBddi_rep_getll()\fR, and \fBddi_rep_getw()\fR functions +are obsolete. The \fBddi_rep_get8()\fR function replaces \fBddi_rep_getb()\fR. +The \fBddi_rep_get32()\fR function replaces \fBddi_rep_getl()\fR. The +\fBddi_rep_get64()\fR function replaces \fBddi_rep_getll()\fR. The +\fBddi_rep_get16()\fR function replaces \fBddi_rep_getw()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 13n +.rt +The data access handle returned from setup calls, such as +\fBddi_regs_map_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhost_addr\fR\fR +.ad +.RS 13n +.rt +Base host address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_addr\fR\fR +.ad +.RS 13n +.rt +Base device address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrepcount\fR\fR +.ad +.RS 13n +.rt +Number of data accesses to perform. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 13n +.rt +Device address flags: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEV_AUTOINCR\fR\fR +.ad +.RS 23n +.rt +Automatically increment the device address, \fIdev_addr\fR, during data +accesses. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEV_NO_AUTOINCR\fR\fR +.ad +.RS 23n +.rt +Do not advance the device address, \fIdev_addr\fR, during data accesses. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +These routines generate multiple reads from the mapped memory or device +register. \fIrepcount\fR data is copied from the device address, +\fIdev_addr\fR, to the host address, \fIhost_addr\fR. For each input datum, the +\fBddi_rep_get8()\fR, \fBddi_rep_get16()\fR, \fBddi_rep_get32()\fR, and +\fBddi_rep_get64()\fR functions read 8 bits, 16 bits, 32 bits, and 64 bits of +data, respectively, from the device address, \fIdev_addr\fR. \fIdev_addr\fR and +\fIhost_addr\fR must be aligned to the datum boundary described by the +function. +.sp +.LP +Each individual datum will automatically be translated to maintain a consistent +view between the host and the device based on the encoded information in the +data access handle. The translation may involve byte-swapping if the host and +the device have incompatible endian characteristics. +.sp +.LP +When the \fIflags\fR argument is set to \fBDDI_DEV_AUTOINCR\fR, these function +treat the device address, \fIdev_addr\fR, as a memory buffer location on the +device and increment its address on the next input datum. However, when the +\fIflags\fR argument is to \fBDDI_DEV_NO_AUTOINCR\fR, the same device address +will be used for every datum access. For example, this flag may be useful when +reading from a data register. +.SH RETURN VALUES +.sp +.LP +These functions return the value read from the mapped address. +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel, or interrupt context. +.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 StabilityT{ +\fBddi_rep_getb()\fR, \fBddi_rep_getl()\fR, \fBddi_rep_getll()\fR, and \fBddi_rep_getw()\fR are Obsolete \fBddi_rep_get8()\fR, \fBddi_rep_get16()\fR, \fBddi_rep_get32()\fR, \fBddi_rep_get64()\fR are Committed +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_get8\fR(9F), \fBddi_put8\fR(9F), \fBddi_regs_map_free\fR(9F), +\fBddi_regs_map_setup\fR(9F), \fBddi_rep_put8\fR(9F) diff --git a/usr/src/man/man9f/ddi_rep_put8.9f b/usr/src/man/man9f/ddi_rep_put8.9f new file mode 100644 index 0000000000..2a320f60f6 --- /dev/null +++ b/usr/src/man/man9f/ddi_rep_put8.9f @@ -0,0 +1,183 @@ +'\" 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 ddi_rep_put8 9F "1 Nov 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_rep_put8, ddi_rep_put16, ddi_rep_put32, ddi_rep_put64, ddi_rep_putb, +ddi_rep_putw, ddi_rep_putl, ddi_rep_putll \- write data to the mapped memory +address, device register or allocated DMA memory address +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_rep_put8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint8_t\fR \fI*host_addr\fR, + \fBuint8_t\fR \fI*dev_addr\fR, \fBsize_t\fR \fIrepcount\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_rep_put16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint16_t\fR \fI*host_addr\fR, + \fBuint16_t\fR \fI*dev_addr\fR, \fBsize_t\fR \fIrepcount\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_rep_put32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint32_t\fR \fI*host_addr\fR, + \fBuint32_t\fR \fI*dev_addr\fR, \fBsize_t\fR \fIrepcount\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_rep_put64\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBuint64_t\fR \fI*host_addr\fR, + \fBuint64_t\fR \fI*dev_addr\fR,\fBsize_t\fR \fIrepcount\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBddi_rep_putb()\fR, +\fBddi_rep_putl()\fR, \fBddi_rep_putll()\fR, and \fBddi_rep_putw()\fR functions +are obsolete. The \fBddi_rep_put8()\fR function replaces \fBddi_rep_putb()\fR. +The \fBddi_rep_put32()\fR function replaces \fBddi_rep_putl()\fR. The +\fBddi_rep_put64()\fR function replaces \fBddi_rep_putll()\fR. The +\fBddi_rep_put16()\fR function replaces \fBddi_rep_putw()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 13n +.rt +The data access handle returned from setup calls, such as +\fBddi_regs_map_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhost_addr\fR\fR +.ad +.RS 13n +.rt +Base host address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_addr\fR\fR +.ad +.RS 13n +.rt +Base device address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrepcount\fR\fR +.ad +.RS 13n +.rt +Number of data accesses to perform. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 13n +.rt +Device address flags: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEV_AUTOINCR\fR\fR +.ad +.RS 23n +.rt +Automatically increment the device address, \fIdev_addr\fR, during data +accesses. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_DEV_NO_AUTOINCR\fR\fR +.ad +.RS 23n +.rt +Do not advance the device address, \fIdev_addr\fR, during data accesses. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +These routines generate multiple writes to the mapped memory or device +register. \fIrepcount\fR data is copied from the host address, \fIhost_addr\fR, +to the device address, \fIdev_addr\fR. For each input datum, the +\fBddi_rep_put8()\fR, \fBddi_rep_put16()\fR, \fBddi_rep_put32()\fR, and +\fBddi_rep_put64()\fR functions write 8 bits, 16 bits, 32 bits, and 64 bits of +data, respectively, to the device address, \fIdev_addr\fR. \fIdev_addr\fR and +\fIhost_addr\fR must be aligned to the datum boundary described by the +function. +.sp +.LP +Each individual datum will automatically be translated to maintain a consistent +view between the host and the device based on the encoded information in the +data access handle. The translation may involve byte-swapping if the host and +the device have incompatible endian characteristics. +.sp +.LP +When the \fIflags\fR argument is set to \fBDDI_DEV_AUTOINCR\fR, these functions +treat the device address, \fIdev_addr\fR, as a memory buffer location on the +device and increment its address on the next input datum. However, when the +\fIflags\fR argument is set to \fBDDI_DEV_NO_AUTOINCR\fR, the same device +address will be used for every datum access. For example, this flag may be +useful when writing to a data register. +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel, or interrupt context. +.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 StabilityT{ +\fBddi_rep_putb()\fR, \fBddi_rep_putl()\fR, \fBddi_rep_putll()\fR, and \fBddi_rep_putw()\fR are Obsolete \fBddi_rep_put8()\fR, \fBddi_rep_put16()\fR, \fBddi_rep_put32()\fR, \fBddi_rep_put64()\fR are Committed +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBddi_get8\fR(9F), \fBddi_put8\fR(9F), \fBddi_regs_map_free\fR(9F), +\fBddi_regs_map_setup\fR(9F), \fBddi_rep_get8\fR(9F), +\fBddi_device_acc_attr\fR(9S) diff --git a/usr/src/man/man9f/ddi_report_dev.9f b/usr/src/man/man9f/ddi_report_dev.9f new file mode 100644 index 0000000000..2ef7f773ed --- /dev/null +++ b/usr/src/man/man9f/ddi_report_dev.9f @@ -0,0 +1,54 @@ +'\" 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 ddi_report_dev 9F "7 Jun 1993" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_report_dev \- announce a device +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBddi_report_dev\fR(\fBdev_info_t *\fR\fIdip\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 8n +.rt +a pointer the device's \fBdev_info\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_report_dev()\fR prints a banner at boot time, announcing the device +pointed to by \fIdip\fR. The banner is always placed in the system logfile +(displayed by \fBdmesg\fR(1M)), but is only displayed on the console if the +system was booted with the verbose (\fB-v\fR) argument. +.SH CONTEXT +.sp +.LP +\fBddi_report_dev()\fR can be called from user context. +.SH SEE ALSO +.sp +.LP +\fBdmesg\fR(1M), \fBkernel\fR(1M) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_root_node.9f b/usr/src/man/man9f/ddi_root_node.9f new file mode 100644 index 0000000000..a932db3f50 --- /dev/null +++ b/usr/src/man/man9f/ddi_root_node.9f @@ -0,0 +1,43 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_root_node 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_root_node \- get the root of the dev_info tree +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBdev_info_t *\fR\fBddi_root_node\fR(\fBvoid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The \fBddi_root_node()\fR function returns a pointer to the root node of the +device information tree. +.SH RETURN VALUES +.sp +.LP +The \fBddi_root_node()\fR function returns a pointer to a device information +structure. +.SH CONTEXT +.sp +.LP +The \fBddi_root_node()\fR function can be called from user, interrupt, or +kernel context. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_segmap.9f b/usr/src/man/man9f/ddi_segmap.9f new file mode 100644 index 0000000000..81481f6769 --- /dev/null +++ b/usr/src/man/man9f/ddi_segmap.9f @@ -0,0 +1,348 @@ +'\" 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 ddi_segmap 9F "17 Nov 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_segmap, ddi_segmap_setup \- set up a user mapping using seg_dev +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_segmap\fR(\fBdev_t\fR \fIdev\fR, \fBoff_t\fR \fIoffset\fR, \fBstruct as *\fR\fIasp\fR, + \fBcaddr_t *\fR\fIaddrp\fR, \fBoff_t\fR \fIlen\fR, \fBuint_t\fR \fIprot\fR, + \fBuint_t\fR \fImaxprot\fR, \fBuint_t\fR \fIflags\fR, \fBcred_t\fR \fI*credp\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_segmap_setup\fR(\fBdev_t\fR \fIdev\fR, \fBoff_t\fR \fIoffset\fR, \fBstruct as *\fR\fIasp\fR, + \fBcaddr_t *\fR\fIaddrp\fR, \fBoff_t\fR \fIlen\fR, \fBuint_t\fR \fIprot\fR, + \fBuint_t\fR \fImaxprot\fR, \fBuint_t\fR \fIflags\fR, \fBcred_t\fR \fI*credp\fR, + \fBddi_device_acc_attr_t\fR \fI*accattrp\fR, \fBuint_t\fR \fIrnumber\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +These interfaces are obsolete. See \fBdevmap\fR(9E) for an alternative to +\fBddi_segmap()\fR. Use \fBdevmap_setup\fR(9F) instead of +\fBddi_segmap_setup()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR \fR +.ad +.RS 12n +.rt +The device whose memory is to be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR \fR +.ad +.RS 12n +.rt +The offset within device memory at which the mapping begins. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIasp\fR \fR +.ad +.RS 12n +.rt +An opaque pointer to the user 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 starting address within the user 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. Some combinations of 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). If +\fB(maxprot & prot) != prot\fR then there is an access violation. +.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_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 + +.sp +.ne 2 +.mk +.na +\fB\fBMAP_FIXED\fR \fR +.ad +.RS 16n +.rt +The user specified an address in \fI*addrp\fR rather than letting the system +pick and address. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcredp\fR \fR +.ad +.RS 12n +.rt +Pointer to user credential structure. +.RE + +.SS "ddi_segmap_setup(\|)" +.sp +.ne 2 +.mk +.na +\fB\fIdev_acc_attr\fR \fR +.ad +.RS 17n +.rt +Pointer to a \fBddi_device_acc_attr\fR(9S) structure which contains the device +access attributes to apply to this mapping. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrnumber\fR \fR +.ad +.RS 17n +.rt +Index number to the register address space set. +.RE + +.SH DESCRIPTION +.sp +.LP +Future releases of Solaris will provide this function for binary and source +compatibility. However, for increased functionality, use +\fBddi_devmap_segmap\fR(9F) instead. See \fBddi_devmap_segmap\fR(9F) for +details. +.sp +.LP +\fBddi_segmap\fR(\|) and \fBddi_segmap_setup()\fR set up user mappings to +device space. When setting up the mapping, the \fBddi_segmap\fR(\|) and +\fBddi_segmap_setup()\fR routines call the \fBmmap\fR(9E) entry point to +validate the range to be mapped. When a user process accesses the mapping, the +drivers \fBmmap\fR(9E) entry point is again called to retrieve the page frame +number that needs to be loaded. The mapping translations for that page are +then loaded on behalf of the driver by the DDI framework. +.sp +.LP +\fBddi_segmap()\fR is typically used as the \fBsegmap\fR(9E) entry in the +\fBcb_ops\fR(9S) structure for those devices that do not choose to provide +their own \fBsegmap\fR(9E) entry point. However, some drivers may have their +own \fBsegmap\fR(9E) entry point to do some initial processing on the +parameters and then call \fBddi_segmap()\fR to establish the default memory +mapping. +.sp +.LP +\fBddi_segmap_setup()\fR is used in the drivers \fBsegmap\fR(9E) entry point to +set up the mapping and assign device access attributes to that mapping. +\fIrnumber\fR specifies the register set representing the range of device +memory being mapped. See \fBddi_device_acc_attr\fR(9S) for details regarding +what device access attributes are available. +.sp +.LP +\fBddi_segmap_setup()\fR cannot be used directly in the \fBcb_ops\fR(9S) +structure and requires a driver to have a \fBsegmap\fR(9E) entry point. +.SH RETURN VALUES +.sp +.LP +\fBddi_segmap()\fR and \fBddi_segmap_setup()\fR return the following values: +.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. In particular, they return \fBENXIO\fR if the range to be +mapped is invalid. +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_segmap()\fR and \fBddi_segmap_setup()\fR can be called from user or +kernel context only. +.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), \fBdevmap\fR(9E), \fBmmap\fR(9E), +\fBsegmap\fR(9E), \fBdevmap_setup\fR(9F), \fBcb_ops\fR(9S), +\fBddi_device_acc_attr\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_slaveonly.9f b/usr/src/man/man9f/ddi_slaveonly.9f new file mode 100644 index 0000000000..16680ed72d --- /dev/null +++ b/usr/src/man/man9f/ddi_slaveonly.9f @@ -0,0 +1,75 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_slaveonly 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_slaveonly \- tell if a device is installed in a slave access only location +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBddi_slaveonly\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 \fBddi_slaveonly()\fR function tells the caller if the bus, or part of the +bus that the device is installed on, does not permit the device to become a DMA +master, that is, whether the device has been installed in a slave access only +slot. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +The device has been installed in a slave access only location. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +The device has not been installed in a slave access only location. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_slaveonly()\fR function can be called from user, interrupt, or +kernel context. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_soft_state.9f b/usr/src/man/man9f/ddi_soft_state.9f new file mode 100644 index 0000000000..7f8ed5e45c --- /dev/null +++ b/usr/src/man/man9f/ddi_soft_state.9f @@ -0,0 +1,411 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_soft_state 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_soft_state, ddi_get_soft_state, ddi_soft_state_fini, ddi_soft_state_free, +ddi_soft_state_init, ddi_soft_state_zalloc \- driver soft state utility +routines +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid *\fR\fBddi_get_soft_state\fR(\fBvoid\fR \fI*state\fR, \fBint\fR \fIitem\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_soft_state_fini\fR(\fBvoid\fR \fI**state_p\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_soft_state_free\fR(\fBvoid\fR \fI*state\fR, \fBint\fR \fIitem\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_soft_state_init\fR(\fBvoid\fR \fI**state_p\fR, \fBsize_t\fR \fIsize\fR, \fBsize_t\fR \fIn_items\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_soft_state_zalloc\fR(\fBvoid\fR \fI*state\fR, \fBint\fR \fIitem\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIstate_p\fR\fR +.ad +.RS 11n +.rt +Address of the opaque state pointer which will be initialized by +\fBddi_soft_state_init()\fR to point to implementation dependent data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 11n +.rt +Size of the item which will be allocated by subsequent calls to +\fBddi_soft_state_zalloc()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIn_items\fR\fR +.ad +.RS 11n +.rt +A hint of the number of items which will be preallocated; zero is allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstate\fR\fR +.ad +.RS 11n +.rt +An opaque pointer to implementation-dependent data that describes the soft +state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIitem\fR\fR +.ad +.RS 11n +.rt +The item number for the state structure; usually the instance number of the +associated devinfo node. +.RE + +.SH DESCRIPTION +.sp +.LP +Most device drivers maintain state information with each instance of the device +they control; for example, a soft copy of a device control register, a mutex +that must be held while accessing a piece of hardware, a partition table, or a +unit structure. These utility routines are intended to help device drivers +manage the space used by the driver to hold such state information. +.sp +.LP +For example, if the driver holds the state of each instance in a single state +structure, these routines can be used to dynamically allocate and deallocate a +separate structure for each instance of the driver as the instance is attached +and detached. +.sp +.LP +To use the routines, the driver writer needs to declare a state pointer, +\fIstate_p\fR, which the implementation uses as a place to hang a set of +per-driver structures; everything else is managed by these routines. +.sp +.LP +The routine \fBddi_soft_state_init()\fR is usually called in the driver's +\fB_init\fR(9E) routine to initialize the state pointer, set the size of the +soft state structure, and to allow the driver to pre-allocate a given number of +such structures if required. +.sp +.LP +The routine \fBddi_soft_state_zalloc()\fR is usually called in the driver's +\fBattach\fR(9E) routine. The routine is passed an item number which is used +to refer to the structure in subsequent calls to \fBddi_get_soft_state()\fR and +\fBddi_soft_state_free()\fR. The item number is usually just the instance +number of the \fBdevinfo\fR node, obtained with \fBddi_get_instance\fR(9F). The +routine attempts to allocate space for the new structure, and if the space +allocation was successful, \fBDDI_SUCCESS\fR is returned to the caller. +Returned memory is zeroed. +.sp +.LP +A pointer to the space previously allocated for a soft state structure can be +obtained by calling \fBddi_get_soft_state()\fR with the appropriate item +number. +.sp +.LP +The space used by a given soft state structure can be returned to the system +using \fBddi_soft_state_free()\fR. This routine is usually called from the +driver's \fBdetach\fR(9E) entry point. +.sp +.LP +The space used by all the soft state structures allocated on a given state +pointer, together with the housekeeping information used by the implementation +can be returned to the system using \fBddi_soft_state_fini()\fR. This routine +can be called from the driver's \fB_fini\fR(9E) routine. +.sp +.LP +The \fBddi_soft_state_zalloc()\fR, \fBddi_soft_state_free()\fR and +\fBddi_get_soft_state()\fR routines coordinate access to the underlying data +structures in an MT-safe fashion, thus no additional locks should be necessary. +.SH RETURN VALUES +.sp +.LP +\fBddi_get_soft_state()\fR +.sp +.ne 2 +.mk +.na +\fB\fINULL\fR\fR +.ad +.RS 11n +.rt +The requested state structure was not allocated at the time of the call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpointer\fR\fR +.ad +.RS 11n +.rt +The pointer to the state structure. +.RE + +.sp +.LP +\fBddi_soft_state_init()\fR +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 10n +.rt +The allocation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Either the \fBsize\fR parameter was zero, or the \fIstate_p\fR parameter was +invalid. +.RE + +.sp +.LP +\fBddi_soft_state_zalloc()\fR +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +The allocation was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +The routine failed to allocate the storage required; either the \fIstate\fR +parameter was invalid, the item number was negative, or an attempt was made to +allocate an item number that was already allocated. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_soft_state_init()\fR and \fBddi_soft_state_alloc()\fR functions can +be called from user or kernel context only, since they may internally call +\fBkmem_zalloc\fR(9F) with the \fBKM_SLEEP\fR flag. +.sp +.LP +The \fBddi_soft_state_fini()\fR, \fBddi_soft_state_free()\fR and +\fBddi_get_soft_state()\fR routines can be called from any driver context. +.SH EXAMPLES +.LP +\fBExample 1 \fRCreating and Removing Data Structures +.sp +.LP +The following example shows how the routines described above can be used in +terms of the driver entry points of a character-only driver. The example +concentrates on the portions of the code that deal with creating and removing +the driver's data structures. + +.sp +.in +2 +.nf +typedef struct { + volatile caddr_t *csr; /* device registers */ + kmutex_t csr_mutex; /* protects 'csr' field */ + unsigned int state; + dev_info_t *dip; /* back pointer to devinfo */ +} devstate_t; +static void *statep; + +int +_init(void) +{ + int error; + + error = ddi_soft_state_init(&statep, sizeof (devstate_t), 0); + if (error != 0) + return (error); + if ((error = mod_install(&modlinkage)) != 0) + ddi_soft_state_fini(&statep); + return (error); +} + +int +_fini(void) +{ + int error; + + if ((error = mod_remove(&modlinkage)) != 0) + return (error); + ddi_soft_state_fini(&statep); + return (0); +} + +static int +xxattach(dev_info_t *dip, ddi_attach_cmd_t cmd) +{ + int instance; + devstate_t *softc; + + switch (cmd) { + case DDI_ATTACH: + instance = ddi_get_instance(dip); + if (ddi_soft_state_zalloc(statep, instance) != DDI_SUCCESS) + return (DDI_FAILURE); + softc = ddi_get_soft_state(statep, instance); + softc->dip = dip; + ... + return (DDI_SUCCESS); + default: + return (DDI_FAILURE); + } +} + +static int +xxdetach(dev_info_t *dip, ddi_detach_cmd_t cmd) +{ + int instance; + + switch (cmd) { + + case DDI_DETACH: + instance = ddi_get_instance(dip); + ... + ddi_soft_state_free(statep, instance); + return (DDI_SUCCESS); + + default: + return (DDI_FAILURE); + } +} + +static int +xxopen(dev_t *devp, int flag, int otyp, cred_t *cred_p) +{ + devstate_t *softc; + int instance; + + instance = getminor(*devp); + if ((softc = ddi_get_soft_state(statep, instance)) == NULL) + return (ENXIO); + ... + softc->state |= XX_IN_USE; + ... + return (0); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fB_fini\fR(9E), \fB_init\fR(9E), \fBattach\fR(9E), \fBdetach\fR(9E), +\fBddi_get_instance\fR(9F), \fBgetminor\fR(9F), \fBkmem_zalloc\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +There is no attempt to validate the \fBitem\fR parameter given to +\fBddi_soft_state_zalloc()\fR other than it must be a positive signed integer. +Therefore very large item numbers may cause the driver to hang forever waiting +for virtual memory resources that can never be satisfied. +.SH NOTES +.sp +.LP +If necessary, a hierarchy of state structures can be constructed by embedding +state pointers in higher order state structures. +.SH DIAGNOSTICS +.sp +.LP +All of the messages described below usually indicate bugs in the driver and +should not appear in normal operation of the system. +.sp +.in +2 +.nf +WARNING: ddi_soft_state_zalloc: bad handle +WARNING: ddi_soft_state_free: bad handle +WARNING: ddi_soft_state_fini: bad handle +.fi +.in -2 + +.sp +.LP +The implementation-dependent information kept in the state variable is corrupt. +.sp +.in +2 +.nf +WARNING: ddi_soft_state_free: null handle +WARNING: ddi_soft_state_fini: null handle +.fi +.in -2 + +.sp +.LP +The routine has been passed a null or corrupt state pointer. Check that +\fBddi_soft_state_init()\fR has been called. +.sp +.in +2 +.nf +WARNING: ddi_soft_state_free: item %d not in range [0..%d] +.fi +.in -2 + +.sp +.LP +The routine has been asked to free an item which was never allocated. The +message prints out the invalid item number and the acceptable range. diff --git a/usr/src/man/man9f/ddi_strtol.9f b/usr/src/man/man9f/ddi_strtol.9f new file mode 100644 index 0000000000..0df523607c --- /dev/null +++ b/usr/src/man/man9f/ddi_strtol.9f @@ -0,0 +1,162 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_strtol 9F "13 May 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_strtol \- String conversion routines +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_strtol\fR(\fBconst char *\fR\fIstr\fR, \fBchar **\fR\fIendptr\fR, \fBint\fR \fIbase\fR, + \fBlong *\fR\fIresult\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIstr\fR \fR +.ad +.RS 11n +.rt +Pointer to a character string to be converted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIendptr\fR \fR +.ad +.RS 11n +.rt +Post-conversion final string of unrecognized characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbase\fR\fR +.ad +.RS 11n +.rt +Radix used for conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIresult\fR \fR +.ad +.RS 11n +.rt +Pointer to variable which contains the converted value. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_strtol()\fR function converts the initial portion of the string +pointed to by \fIstr\fR to a type \fBlong\fR int representation and stores the +converted value in result. +.sp +.LP +The function first decomposes the input string into three parts: +.RS +4 +.TP +1. +An initial (possibly empty) sequence of white-space characters +(' ', '\et', '\en', '\er', '\ef') +.RE +.RS +4 +.TP +2. +A subject sequence interpreted as an integer represented in some radix +determined by the value of \fIbase\fR +.RE +.RS +4 +.TP +3. +A final string of one or more unrecognized characters, including the +terminating null byte of the input string. +.RE +.sp +.LP +The \fBddi_strtol()\fR function then attempts to convert the subject sequence +to an integer and returns the result. +.sp +.LP +If the value of \fIbase\fR is 0, the expected form of the subject sequence is a +decimal constant, octal constant or hexadecimal constant, any of which may be +preceded by a plus ("+") or minus ("-") sign. A decimal constant begins with a +non-zero digit, and consists of a sequence of decimal digits. An octal +constant consists of the prefix 0 optionally followed by a sequence of the +digits 0 to 7 only. A hexadecimal constant consists of the prefix 0x or 0X +followed by a sequence of the decimal digits and letters a (or A) to f (or F) +with values 10 to 15 respectively. +.sp +.LP +If the value of \fIbase\fR is between 2 and 36, the expected form of the +subject sequence is a sequence of letters and digits representing an integer +with the radix specified by \fIbase\fR, optionally preceded by a plus or minus +sign. The letters from a (or A) to z (or Z) inclusive are ascribed the values +10 to 35 and only letters whose ascribed values are less than that of +\fIbase\fR are permitted. If the value of \fIbase\fR is 16, the characters 0x +or 0X may optionally precede the sequence of letters and digits following the +sign, if present. +.sp +.LP +The subject sequence is defined as the longest initial subsequence of the input +string, starting with the first non-white-space character that is of the +expected form. The subject sequence contains no characters if the input string +is empty or consists entirely of white-space characters or if the first +non-white-space character is other than a sign or a permissible letter or +digit. +.sp +.LP +If the subject sequence has the expected form and the value of \fIbase\fR is 0, +the sequence of characters starting with the first digit is interpreted as an +integer constant. If the subject sequence has the expected form and the value +of \fIbase\fR is between 2 and 36, it is used as the \fIbase\fR for +conversion, ascribing to each letter its value as given above. If the subject +sequence begins with a minus sign, the value resulting from the conversion is +negated. A pointer to the final string is stored in the object pointed to by +\fIendptr\fR, provided that \fIendptr\fR is not a null pointer. +.sp +.LP +If the subject sequence is empty or does not have the expected form, no +conversion is performed and the value of \fIstr\fR is stored in the object +pointed to by \fIendptr\fR, provided that \fIendptr\fR is not a null pointer. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBddi_strtol()\fR returns \fB0\fR and stores the +converted value in \fIresult\fR. If no conversion is performed due to invalid +\fIbase\fR, \fBddi_strtol()\fR returns \fBEINVAL\fR and the variable pointed by +\fIresult\fR is not changed. +.sp +.LP +If the correct value is outside the range of representable values, +\fBddi_strtol()\fR returns \fBERANGE\fR and the value pointed to by +\fIresult\fR is not changed. +.SH CONTEXT +.sp +.LP +The \fBddi_strtol()\fR function may be called from user, kernel or interrupt +context. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_strtoll.9f b/usr/src/man/man9f/ddi_strtoll.9f new file mode 100644 index 0000000000..507615d137 --- /dev/null +++ b/usr/src/man/man9f/ddi_strtoll.9f @@ -0,0 +1,191 @@ +'\" te +.\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved. +.\" Portions Copyright (c) 2009, Sun Microsystems Inc. All Rights Reserved. +.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at http://www.opengroup.org/bookstore/. +.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text +.\" are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical +.\" and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html. +.\" This notice shall appear on any product containing this material. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. +.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with +.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_strtoll 9F "25 Feb 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_strtoll, ddi_strtoull \- string conversion functions +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_strtoll\fR(\fBconst char *\fR\fIstr\fR, \fBchar **\fR\fIendptr\fR, \fBint\fR \fIbase\fR, + \fBlonglong_t *\fR\fIresult\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_strtoull\fR(\fBconst char *\fR\fIstr\fR, \fBchar **\fR\fIendptr\fR, \fBint\fR \fIbase\fR, + \fBu_longlong_t *\fR\fIresult\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIstr\fR\fR +.ad +.RS 10n +.rt +pointer to a character string to be converted +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIendptr\fR\fR +.ad +.RS 10n +.rt +post-conversion final string of unrecognized characters +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbase\fR\fR +.ad +.RS 10n +.rt +radix used for conversion +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIresult\fR\fR +.ad +.RS 10n +.rt +pointer to variable which contains the converted value +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBddi_strtoll()\fR function converts the initial portion of the string +pointed to by \fIstr\fR to a type \fBlonglong_t\fR representation and stores +the converted value in \fIresult\fR. +.sp +.LP +The \fBddi_strtoull()\fR function converts the initial portion of the string +pointed to by \fIstr\fR to a type \fBu_longlong_t\fR representation and stores +the converted value in \fIresult\fR. +.sp +.LP +These functions first decomposes the input string into three parts: +.RS +4 +.TP +1. +An initial (possibly empty) sequence of white-space characters (" ", "\et", +"\en", "\er", "\ef") +.RE +.RS +4 +.TP +2. +A subject sequence interpreted as an integer represented in some radix +determined by the value of base +.RE +.RS +4 +.TP +3. +A final string of one or more unrecognized characters, including the +terminating null byte of the input string. +.RE +.sp +.LP +The \fBddi_strtoll()\fR function then attempts to convert the subject sequence +to an integer and returns the result. The \fBddi_strtoull()\fR function +attempts to convert the subject sequence to an unsigned integer and returns the +result. +.sp +.LP +If the value of base is 0, the expected form of the subject sequence is that of +a decimal constant, octal constant or hexadecimal constant, any of which may be +preceded by a plus ("+") or minus ("-") sign. A decimal constant begins with a +non-zero digit, and consists of a sequence of decimal digits. An octal constant +consists of the prefix 0 optionally followed by a sequence of the digits 0 to 7 +only. A hexadecimal constant consists of the prefix 0x or 0X followed by a +sequence of the decimal digits and letters a (or A) to f (or F) with values 10 +to 15 respectively. +.sp +.LP +If the value of base is between 2 and 36, the expected form of the subject +sequence is a sequence of letters and digits representing an integer with the +radix specified by base, optionally preceded by a plus or minus sign. The +letters from a (or A) to z (or Z) inclusive are ascribed the values 10 to 35 +and only letters whose ascribed values are less than that of base are +permitted. If the value of base is 16, the characters 0x or 0X may optionally +precede the sequence of letters and digits, following the sign if present. +.sp +.LP +The subject sequence is defined as the longest initial subsequence of the input +string, starting with the first non-white-space character that is of the +expected form. The subject sequence contains no characters if the input string +is empty or consists entirely of white-space characters, or if the first +non-white-space character is other than a sign or a permissible letter or +digit. +.sp +.LP +If the subject sequence has the expected form and the value of base is 0, the +sequence of characters starting with the first digit is interpreted as an +integer constant. If the subject sequence has the expected form and the value +of base is between 2 and 36, it is used as the base for conversion, ascribing +to each letter its value as given above. If the subject sequence begins with a +minus sign, the value resulting from the conversion is negated. A pointer to +the final string is stored in the object pointed to by \fIendptr\fR, provided +that \fIendptr\fR is not a null pointer. +.sp +.LP +If the subject sequence is empty or does not have the expected form, no +conversion is performed and the value of \fIstr\fR is stored in the object +pointed to by \fIendptr\fR, provided that \fIendptr\fR is not a null pointer. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, these functions return 0 and store the converted +value in \fIresult\fR. If no conversion is performed due to an invalid base, +these functions return \fBEINVAL\fR and the variable pointed by \fIresult\fR is +not changed. +.SH CONTEXT +.sp +.LP +These functions may be called from user, kernel or interrupt context. +.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 +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_strtoul.9f b/usr/src/man/man9f/ddi_strtoul.9f new file mode 100644 index 0000000000..248018f6c6 --- /dev/null +++ b/usr/src/man/man9f/ddi_strtoul.9f @@ -0,0 +1,162 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_strtoul 9F "13 May 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_strtoul \- String conversion functions +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_strtoul\fR(\fBconst char *\fR\fIstr\fR, \fBchar **\fR\fIendptr\fR, \fBint\fR \fIbase\fR, + \fBunsigned long *\fR\fIresult\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIstr\fR \fR +.ad +.RS 11n +.rt +Pointer to a character string to be converted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIendptr\fR \fR +.ad +.RS 11n +.rt +Post-conversion final string of unrecognized characters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbase\fR\fR +.ad +.RS 11n +.rt +Radix used for conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIresult\fR \fR +.ad +.RS 11n +.rt +Pointer to variable which contains the converted value. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_strtoul()\fR function converts the initial portion of the string +pointed to by \fIstr\fR to a type \fBunsigned long\fR int representation and +stores the converted value in \fIresult\fR. +.sp +.LP +The function first decomposes the input string into three parts: +.RS +4 +.TP +1. +An initial (possibly empty) sequence of white-space characters +(' ', '\et', '\en', '\er', '\ef') +.RE +.RS +4 +.TP +2. +A subject sequence interpreted as an integer represented in some radix +determined by the value of \fIbase\fR +.RE +.RS +4 +.TP +3. +A final string of one or more unrecognized characters, including the +terminating null byte of the input string. +.RE +.sp +.LP +The \fBddi_strtoul()\fR function then attempts to convert the subject sequence +to an \fBunsigned\fR integer and returns the result. +.sp +.LP +If the value of \fIbase\fR is 0, the expected form of the subject sequence is +that of a decimal constant, octal constant or hexadecimal constant, any of +which may be preceded by a plus ("+") or minus ("-") sign. A decimal constant +begins with a non-zero digit, and consists of a sequence of decimal digits. An +octal constant consists of the prefix 0 optionally followed by a sequence of +the digits 0 to 7 only. A hexadecimal constant consists of the prefix 0x or 0X +followed by a sequence of the decimal digits and letters a (or A) to f (or F) +with values 10 to 15 respectively. +.sp +.LP +If the value of \fIbase\fR is between 2 and 36, the expected form of the +subject sequence is a sequence of letters and digits representing an integer +with the radix specified by \fIbase\fR, optionally preceded by a plus or minus +sign. The letters from a (or A) to z (or Z) inclusive are ascribed the values +10 to 35 and only letters whose ascribed values are less than that of +\fIbase\fR are permitted. If the value of \fIbase\fR is 16, the characters 0x +or 0X may optionally precede the sequence of letters and digits, following the +sign if present. +.sp +.LP +The subject sequence is defined as the longest initial subsequence of the +input string, starting with the first non-white-space character that is of the +expected form. The subject sequence contains no characters if the input string +is empty or consists entirely of white-space characters, or if the first +non-white-space character is other than a sign or a permissible letter or +digit. +.sp +.LP +If the subject sequence has the expected form and the value of \fIbase\fR is +0, the sequence of characters starting with the first digit is interpreted as +an integer constant. If the subject sequence has the expected form and the +value of \fIbase\fR is between 2 and 36, it is used as the \fIbase\fR for +conversion, ascribing to each letter its value as given above. If the subject +sequence begins with a minus sign, the value resulting from the conversion is +negated. A pointer to the final string is stored in the object pointed to by +\fIendptr\fR, provided that \fIendptr\fR is not a null pointer. +.sp +.LP +If the subject sequence is empty or does not have the expected form, no +conversion is performed and the value of \fIstr\fR is stored in the object +pointed to by \fIendptr\fR, provided that \fIendptr\fR is not a null pointer. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBddi_strtoul()\fR returns \fB0\fR and stores the +converted value in \fIresult\fR. If no conversion is performed due to invalid +\fIbase\fR, \fBddi_strtoul()\fR returns \fBEINVAL\fR and the variable pointed +by \fIresult\fR is not changed. +.sp +.LP +If the correct value is outside the range of representable values, +\fBddi_strtoul()\fR returns \fBERANGE\fR and the value pointed to by +\fIresult\fR is not changed. +.SH CONTEXT +.sp +.LP +The \fBddi_strtoul()\fR function may be called from user, kernel or interrupt +context. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ddi_umem_alloc.9f b/usr/src/man/man9f/ddi_umem_alloc.9f new file mode 100644 index 0000000000..1e45c68967 --- /dev/null +++ b/usr/src/man/man9f/ddi_umem_alloc.9f @@ -0,0 +1,196 @@ +'\" 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 ddi_umem_alloc 9F "19 Mar 2002" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_umem_alloc, ddi_umem_free \- allocate and free page-aligned kernel memory +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/sunddi.h> + +\fBvoid *\fR\fBddi_umem_alloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflag\fR, + \fBddi_umem_cookie_t *\fR\fIcookiep\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_umem_free\fR(\fBddi_umem_cookie_t\fR \fIcookie\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.SS "ddi_umem_alloc()" +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 11n +.rt +Number of bytes to allocate. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 11n +.rt +Used to determine the sleep and pageable conditions. +.sp +Possible sleep flags are \fBDDI_UMEM_SLEEP\fR, which allows sleeping until +memory is available, and \fBDDI_UMEM_NOSLEEP\fR, which returns \fBNULL\fR +immediately if memory is not available. +.sp +The default condition is to allocate locked memory; this can be changed to +allocate pageable memory using the \fBDDI_UMEM_PAGEABLE\fR flag. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookiep\fR\fR +.ad +.RS 11n +.rt +Pointer to a kernel memory cookie. +.RE + +.SS "ddi_umem_free()" +.sp +.ne 2 +.mk +.na +\fB\fIcookie\fR\fR +.ad +.RS 10n +.rt +A kernel memory cookie allocated in \fBddi_umem_alloc()\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBddi_umem_alloc()\fR allocates page-aligned kernel memory and returns a +pointer to the allocated memory. The number of bytes allocated is a multiple of +the system page size (roundup of \fIsize\fR). The allocated memory can be used +in the kernel and can be exported to user space. See \fBdevmap\fR(9E) and +\fBdevmap_umem_setup\fR(9F) for further information. +.sp +.LP +\fIflag\fR determines whether the caller can sleep for memory and whether the +allocated memory is locked or not. \fBDDI_UMEM_SLEEP\fR allocations may sleep +but are guaranteed to succeed. \fBDDI_UMEM_NOSLEEP\fR allocations do not sleep +but may fail (return \fINULL\fR) if memory is currently unavailable. If +\fBDDI_UMEM_PAGEABLE\fR is set, pageable memory will be allocated. These pages +can be swapped out to secondary memory devices. The initial contents of memory +allocated using \fBddi_umem_alloc()\fR is zero-filled. +.sp +.LP +\fI*cookiep\fR is a pointer to the kernel memory cookie that describes the +kernel memory being allocated. A typical use of \fIcookiep\fR is in +\fBdevmap_umem_setup\fR(9F) when the drivers want to export the kernel memory +to a user application. +.sp +.LP +To free the allocated memory, a driver calls \fBddi_umem_free()\fR with the +cookie obtained from \fBddi_umem_alloc()\fR. \fBddi_umem_free()\fR releases the +entire buffer. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBNon-null\fR\fR +.ad +.RS 12n +.rt +Successful completion. \fBddi_umem_alloc()\fR returns a pointer to the +allocated memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNULL\fR\fR +.ad +.RS 12n +.rt +Memory cannot be allocated by \fBddi_umem_alloc()\fR because +\fBDDI_UMEM_NOSLEEP\fR is set and the system is out of resources. +.RE + +.SH CONTEXT +.sp +.LP +\fBddi_umem_alloc()\fR can be called from any context if \fIflag\fR is set to +\fBDDI_UMEM_NOSLEEP.\fR If \fBDDI_UMEM_SLEEP\fR is set, \fBddi_umem_alloc()\fR +can be called from user and kernel context only. \fBddi_umem_free()\fR can be +called from any context. +.SH SEE ALSO +.sp +.LP +\fBdevmap\fR(9E), \fBcondvar\fR(9F), \fBdevmap_umem_setup\fR(9F), +\fBkmem_alloc\fR(9F), \fBmutex\fR(9F), \fBrwlock\fR(9F), \fBsemaphore\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +Setting the \fBDDI_UMEM_PAGEABLE\fR flag in \fBddi_umem_alloc()\fR will result +in an allocation of pageable memory. Because these pages can be swapped out to +secondary memory devices, drivers should use this flag with care. This memory +must not be used for the following purposes: +.RS +4 +.TP +.ie t \(bu +.el o +For synchronization objects such as locks and condition variables. See +\fBmutex\fR(9F), \fBsemaphore\fR(9F), \fBrwlock\fR(9F), and \fBcondvar\fR(9F). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +For driver interrupt routines. +.RE +.sp +.LP +Memory allocated using \fBddi_umem_alloc()\fR without setting +\fBDDI_UMEM_PAGEABLE\fR flag cannot be paged. Available memory is therefore +limited by the total physical memory on the system. It is also limited by the +available kernel virtual address space, which is often the more restrictive +constraint on large-memory configurations. +.sp +.LP +Excessive use of kernel memory is likely to effect overall system performance. +Over-commitment of kernel memory may cause unpredictable consequences. +.sp +.LP +Misuse of the kernel memory allocator, such as writing past the end of a +buffer, using a buffer after freeing it, freeing a buffer twice, or freeing an +invalid pointer, will cause the system to corrupt data or panic. +.sp +.LP +Do not call \fBddi_umem_alloc()\fR within \fBDDI_SUSPEND\fR and +\fBDDI_RESUME\fR operations. Memory acquired at these times is not reliable. In +some cases, such a call can cause a system to hang. +.SH NOTES +.sp +.LP +\fBddi_umem_alloc(0,\fR \fIflag\fR, \fIcookiep\fR\fB)\fR always returns +\fBNULL.\fR \fBddi_umem_free(NULL)\fR has no effects on system. diff --git a/usr/src/man/man9f/ddi_umem_iosetup.9f b/usr/src/man/man9f/ddi_umem_iosetup.9f new file mode 100644 index 0000000000..68ec98ca93 --- /dev/null +++ b/usr/src/man/man9f/ddi_umem_iosetup.9f @@ -0,0 +1,176 @@ +'\" 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 ddi_umem_iosetup 9F "4 Feb 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_umem_iosetup \- Setup I/O requests to application memory +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBstruct buf *\fR\fBddi_umem_iosetup\fR(\fBddi_umem_cookie_t\fR \fIcookie,\fRoff_t off, + size_t \fIlen\fR, int \fIdirection\fR, dev_t \fIdev\fR, daddr_t \fIblkno\fR, + int (*iodone) (struct buf *), int \fIsleepflag\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcookie\fR \fR +.ad +.RS 14n +.rt +The kernel memory cookie allocated by \fBddi_umem_lock\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoff\fR \fR +.ad +.RS 14n +.rt +Offset from the start of the cookie. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR \fR +.ad +.RS 14n +.rt +Length of the I/O request in bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdirection\fR \fR +.ad +.RS 14n +.rt +Must be set to \fBB_READ\fR for reads from the device or \fBB_WRITE\fR for +writes to the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR \fR +.ad +.RS 14n +.rt +Device number +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIblkno\fR \fR +.ad +.RS 14n +.rt +Block number on device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIiodone\fR \fR +.ad +.RS 14n +.rt +Specific \fBbiodone\fR(9F) routine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsleepflag\fR \fR +.ad +.RS 14n +.rt +Determines whether caller can sleep for memory. Possible flags are +\fBDDI_UMEM_SLEEP\fR to allow sleeping until memory is available, or +\fBDDI_UMEM_NOSLEEP\fR to return \fBNULL\fR immediately if memory is not +available. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_umem_iosetup\fR(9F) function is used by drivers to setup I/O +requests to application memory which has been locked down using +\fBddi_umem_lock\fR(9F). +.sp +.LP +The \fBddi_umem_iosetup\fR(9F) function returns a pointer to a \fBbuf\fR(9S) +structure corresponding to the memory cookie \fBcookie\fR. Drivers can setup +multiple buffer structures simultaneously active using the same memory cookie. +The \fBbuf\fR(9S) structures can span all or part of the region represented by +the cookie and can overlap each other. The \fBbuf\fR(9S) structure can be +passed to \fBddi_dma_buf_bind_handle\fR(9F) to initiate DMA transfers to or +from the locked down memory. +.sp +.LP +The \fIoff \fR parameter specifies the offset from the start of the cookie. The +\fIlen\fR parameter represents the length of region to be mapped by the buffer. +The \fIdirection\fR parameter must be set to either \fBB_READ\fR or +\fBB_WRITE\fR, to indicate the action that will be performed by the device. +(Note that this direction is in the opposite sense of the VM system's direction +of \fBDDI_UMEMLOCK_READ\fR and \fBDDI_UMEMLOCK_WRITE\fR.) The direction must be +compatible with the flags used to create the memory cookie in +\fBddi_umem_lock\fR(9F). For example, if \fBddi_umem_lock()\fR is called with +the \fIflags\fR parameter set to DDI_UMEMLOCK_READ, the \fIdirection\fR +parameter in \fBddi_umem_iosetup()\fR should be set to \fBB_WRITE\fR. +.sp +.LP +The \fIdev\fR parameter specifies the device to which the buffer is to perform +I/O.The \fIblkno\fR parameter represents the block number on the device. It +will be assigned to the \fBb_blkno\fR field of the returned buffer structure. +The \fIiodone\fR parameter enables the driver to identify a specific +\fBbiodone\fR(9F) routine to be called by the driver when the I/O is complete. +The \fIsleepflag \fR parameter determines if the caller can sleep for memory. +\fBDDI_UMEM_SLEEP\fR allocations may sleep but are guaranteed to succeed. +\fBDDI_UMEM_NOSLEEP\fR allocations do not sleep but may fail (return +\fBNULL\fR) if memory is currently not available. +.sp +.LP +After the I/O has completed and the buffer structure is no longer needed, the +driver calls \fBfreerbuf\fR(9F) to free the buffer structure. +.SH RETURN VALUES +.sp +.LP +The \fBddi_umem_iosetup\fR(9F) function returns a pointer to the initialized +buffer header, or \fBNULL\fR if no space is available. +.SH CONTEXT +.sp +.LP +The \fBddi_umem_iosetup\fR(9F) function can be called from any context only if +flag is set to \fBDDI_UMEM_NOSLEEP\fR. If \fBDDI_UMEM_SLEEP\fR is set, +\fBddi_umem_iosetup\fR(9F) can be called from user and kernel context only. +.SH SEE ALSO +.sp +.LP +\fBddi_umem_lock\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), \fBfreerbuf\fR(9F), +\fBphysio\fR(9F), \fBbuf\fR(9S) diff --git a/usr/src/man/man9f/ddi_umem_lock.9f b/usr/src/man/man9f/ddi_umem_lock.9f new file mode 100644 index 0000000000..02157909ae --- /dev/null +++ b/usr/src/man/man9f/ddi_umem_lock.9f @@ -0,0 +1,221 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ddi_umem_lock 9F "10 Apr 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ddi_umem_lock, ddi_umem_unlock \- lock and unlock memory pages +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBddi_umem_lock\fR(\fBcaddr_t\fR \fIaddr\fR, \fBsize_t\fR \fIlen\fR, \fBint\fR \fIflags\fR, + \fBddi_umem_cookie_t\fR *\fIcookiep\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_umem_unlock\fR(\fBddi_umem_cookie_t\fR \fIcookie\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.SS "ddi_umem_lock" +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR\fR +.ad +.RS 11n +.rt +Virtual address of memory object +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 11n +.rt +Length of memory object in bytes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 11n +.rt +Valid flags include: +.sp +.ne 2 +.mk +.na +\fBDDI_UMEMLOCK_READ\fR +.ad +.RS 21n +.rt +Memory pages are locked to be read from. (Disk write or a network send.) +.RE + +.sp +.ne 2 +.mk +.na +\fBDDI_UMEMLOCK_WRITE\fR +.ad +.RS 22n +.rt +Memory pages are locked to be written to. (Disk read or a network receive.) +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookiep\fR\fR +.ad +.RS 11n +.rt +Pointer to a kernel memory cookie. +.RE + +.SS "ddi_umem_unlock" +.sp +.ne 2 +.mk +.na +\fBcookie\fR +.ad +.RS 10n +.rt +Kernel memory cookie allocated by \fBddi_umem_lock()\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBddi_umem_lock()\fR function locks down the physical pages (including I/O +pages) that correspond to the current process' virtual address range +[\fIaddr\fR, \fIaddr\fR + \fIsize\fR) and fills in a cookie representing the +locked pages. This cookie can be used to create a \fBbuf\fR(9S) structure that +can be used to perform I/O (see \fBddi_umem_iosetup\fR(9F) and +\fBddi_dma_buf_bind_handle\fR(9F), or it can be used with +\fBdevmap_umem_setup\fR(9F) to export the memory to an application. +.sp +.LP +The virtual address and length specified must be at a page boundary and the +mapping performed in terms of the system page size. See \fBpagesize\fR(1). +.sp +.LP +The flags argument indicates the intended use of the locked memory. Set flags +to \fBDDI_UMEMLOCK_READ\fR if the memory pages will be read (for example, in a +disk write or a network send.) Set flags to \fBDDI_UMEMLOCK_WRITE\fR if the +memory pages will be written (for example, in a disk read or a network +receive). You must choose one (and only one) of these values. +.sp +.LP +To unlock the locked pages, the drivers call \fBddi_umem_unlock(9F)\fR with the +cookie obtained from \fBddi_umem_lock()\fR. +.sp +.LP +The process is not allowed to \fBexec\fR(2) or \fBfork\fR(2) while its physical +pages are locked down by the device driver. +.sp +.LP +The device driver must ensure that the physical pages have been unlocked after +the application has called \fBclose\fR(2). +.SH RETURN VALUES +.sp +.LP +On success, a \fB0\fR is returned. Otherwise, one of the following \fBerrno\fR +values is returned. +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 10n +.rt +User process has no mapping at that address range or does not support locking +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +.rt +User process does not have the required permission. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +The system does not have sufficient resources to lock memory, or locking +\fIlen\fR memory would exceed a limit or resource control on locked memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +Could not allocate system resources required to lock the pages. The +\fBddi_umem_lock()\fR could succeed at a later time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Requested memory is not aligned on a system page boundary. +.RE + +.SH CONTEXT +.sp +.LP +The \fBddi_umem_lock()\fR function can only be called from user context; +\fBddi_umem_unlock()\fR from user, kernel, and interrupt contexts. +.SH SEE ALSO +.sp +.LP +\fBddi_umem_iosetup\fR(9F), \fBddi_dma_buf_bind_handle\fR(9F), +\fBdevmap_umem_setup\fR(9F), \fBddi_umem_alloc\fR(9F) +.SH NOTES +.sp +.LP +The \fBddi_umem_unlock()\fR function consumes physical memory. The driver is +responsible for a speedy unlock to free up the resources. +.sp +.LP +The \fBddi_umem_unlock()\fR function can defer unlocking of the pages to a +later time depending on the implementation. diff --git a/usr/src/man/man9f/delay.9f b/usr/src/man/man9f/delay.9f new file mode 100644 index 0000000000..4ccd413a47 --- /dev/null +++ b/usr/src/man/man9f/delay.9f @@ -0,0 +1,102 @@ +'\" 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 delay 9F "15 Oct 2001" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +delay \- delay execution for a specified number of clock ticks +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> + + + +\fBvoid\fR \fBdelay\fR(\fBclock_t\fR \fIticks\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIticks\fR \fR +.ad +.RS 10n +.rt +The number of clock cycles to delay. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBdelay()\fR provides a mechanism for a driver to delay its execution for a +given period of time. Since the speed of the clock varies among systems, +drivers should base their time values on microseconds and use +\fBdrv_usectohz\fR(9F) to convert microseconds into clock ticks. +.sp +.LP +\fBdelay()\fR uses \fBtimeout\fR(9F) to schedule an internal function to be +called after the specified amount of time has elapsed. \fBdelay()\fR then waits +until the function is called. Because \fBtimeout()\fR is subject to priority +inversion, drivers waiting on behalf of processes with real-time constraints +should use \fBcv_timedwait\fR(9F) rather than \fBdelay()\fR. +.sp +.LP +\fBdelay()\fR does not busy-wait. If busy-waiting is required, use +\fBdrv_usecwait\fR(9F). +.SH CONTEXT +.sp +.LP +\fBdelay()\fR can be called from user and kernel contexts. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBdelay()\fR Example +.sp +.LP +Before a driver I/O routine allocates buffers and stores any user data in them, +it checks the status of the device (line 12). If the device needs manual +intervention (such as, needing to be refilled with paper), a message is +displayed on the system console (line 14). The driver waits an allotted time +(line 17) before repeating the procedure. + +.sp +.in +2 +.nf + 1 struct device { /* layout of physical device registers */ + 2 int control; /* physical device control word */ + 3 int status; /* physical device status word */ + 4 short xmit_char; /* transmit character to device */ + 5 }; + 6 + 7 + . . . + 9 /* get device registers */ +10 register struct device *rp = ... +11 +12 while (rp->status & NOPAPER) { /* while printer is out of paper */ +13 /* display message and ring bell */ + /* on system console */ +14 cmn_err(CE_WARN, "^\e007", +15 (getminor(dev) & 0xf)); +16 /* wait one minute and try again */ +17 delay(60 * drv_usectohz(1000000)); +18 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBbiodone\fR(9F), \fBbiowait\fR(9F), \fBcv_timedwait\fR(9F), +\fBddi_in_panic\fR(9F), \fBdrv_hztousec\fR(9F), \fBdrv_usectohz\fR(9F), +\fBdrv_usecwait\fR(9F), \fBtimeout\fR(9F), \fBuntimeout\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/devmap_default_access.9f b/usr/src/man/man9f/devmap_default_access.9f new file mode 100644 index 0000000000..2f3c99d7cf --- /dev/null +++ b/usr/src/man/man9f/devmap_default_access.9f @@ -0,0 +1,211 @@ +'\" 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_default_access 9F "14 Jan 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +devmap_default_access \- default driver memory access function +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + +\fBint\fR \fBdevmap_default_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 PARAMETERS +.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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrw\fR \fR +.ad +.RS 9n +.rt +Type of access. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBdevmap_default_access()\fR is a function providing the semantics of +\fBdevmap_access\fR(9E). The drivers call \fBdevmap_default_access()\fR to +handle the mappings that do not support context switching. The drivers should +call \fBdevmap_do_ctxmgt\fR(9F) for the mappings that support context +management. +.sp +.LP +\fBdevmap_default_access()\fR can either be called from \fBdevmap_access\fR(9E) +or be used as the \fBdevmap_access\fR(9E) entry point. The arguments \fIdhp\fR, +\fIpvtp\fR, \fIoff\fR, \fIlen\fR, \fItype\fR, and \fIrw\fR are provided by +the \fBdevmap_access\fR(9E) entry point and must not be modified. +.SH RETURN VALUES +.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 CONTEXT +.sp +.LP +\fBdevmap_default_access()\fR must be called from the driver's +\fBdevmap_access\fR(9E) entry point. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing devmap_default_access in devmap_access. +.sp +.LP +The following shows an example of using \fBdevmap_default_access()\fR in the +\fBdevmap_access\fR(9E) entry point. + +.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 off 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 off is 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_access\fR(9E), \fBdevmap_do_ctxmgt\fR(9F), +\fBdevmap_callback_ctl\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/devmap_devmem_setup.9f b/usr/src/man/man9f/devmap_devmem_setup.9f new file mode 100644 index 0000000000..b7e67131ea --- /dev/null +++ b/usr/src/man/man9f/devmap_devmem_setup.9f @@ -0,0 +1,546 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH devmap_devmem_setup 9F "05 Jun 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +devmap_devmem_setup, devmap_umem_setup \- set driver memory mapping parameters +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBdevmap_devmem_setup\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBdev_info_t *\fR\fIdip\fR, + \fBstruct devmap_callback_ctl *\fR\fIcallbackops\fR, \fBuint_t\fR \fIrnumber\fR, + \fBoffset_t\fR \fIroff\fR, \fBsize_t\fR \fIlen\fR, \fBuint_t\fR \fImaxprot\fR, + \fBuint_t\fR \fIflags\fR, \fBddi_device_acc_attr_t *\fR\fIaccattrp\fR); +.fi + +.LP +.nf +\fBint\fR \fBdevmap_umem_setup\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBdev_info_t *\fR\fIdip\fR, + \fBstruct devmap_callback_ctl *\fR\fIcallbackops\fR, \fBddi_umem_cookie_t\fR \fIcookie\fR, + \fBoffset_t\fR \fIkoff\fR, \fBsize_t\fR \fIlen\fR, \fBuint_t\fR \fImaxprot\fR, \fBuint_t\fR \fIflags\fR, + \fBddi_device_acc_attr_t *\fR\fIaccattrp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +\fBdevmap_devmem_setup()\fR parameters: +.sp +.ne 2 +.mk +.na +\fB\fIdhp\fR\fR +.ad +.RS 15n +.rt +An opaque mapping handle that the system uses to describe the mapping. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 15n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallbackops\fR\fR +.ad +.RS 15n +.rt +Pointer to a \fBdevmap_callback_ctl\fR(9S) structure. The structure contains +pointers to device driver-supplied functions that manage events on the device +mapping. The framework will copy the structure to the system private memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrnumber\fR\fR +.ad +.RS 15n +.rt +Index number to the register address space set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIroff\fR\fR +.ad +.RS 15n +.rt +Offset into the register address space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 15n +.rt +Length (in bytes) of the mapping to be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImaxprot\fR\fR +.ad +.RS 15n +.rt +Maximum protection flag possible for attempted mapping. Some combinations of +possible settings are: +.sp +.ne 2 +.mk +.na +\fB\fBPROT_READ\fR\fR +.ad +.RS 14n +.rt +Read access is allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_WRITE\fR\fR +.ad +.RS 14n +.rt +Write access is allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_EXEC\fR\fR +.ad +.RS 14n +.rt +Execute access is allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_USER\fR\fR +.ad +.RS 14n +.rt +User-level access is allowed. The mapping is done as a result of a +\fBmmap\fR(2) system call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_ALL\fR\fR +.ad +.RS 14n +.rt +All access is allowed. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 15n +.rt +Used to determine the cache attribute. +.sp +Possible values of the cache attribute are: +.sp +.ne 2 +.mk +.na +\fB\fBIOMEM_DATA_CACHED\fR\fR +.ad +.RS 28n +.rt +The CPU can cache the data it fetches and push it to memory at a later time. +This is the default attribute that is used if no cache attributes are +specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBIOMEM_DATA_UC_WR_COMBINE\fR\fR +.ad +.RS 28n +.rt +The CPU never caches the data, but writes can occur out of order or can be +combined. Reordering is implied. +.sp +If \fBIOMEM_DATA_UC_WR_COMBINE\fR is specified but not supported, +\fBIOMEM_DATA_UNCACHED\fR is used instead. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBIOMEM_DATA_UNCACHED\fR\fR +.ad +.RS 28n +.rt +The CPU never caches data, but has uncacheable access to memory. Strict +ordering is implied. +.RE + +The cache attributes are mutually exclusive. Any combination of the values +leads to a failure. On the SPARC architecture, only \fBIOMEM_DATA_CACHED\fR is +meaningful. Others lead to a failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaccattrp\fR\fR +.ad +.RS 15n +.rt +Pointer to a \fBddi_device_acc_attr()\fR structure of the device. See +\fBddi_device_acc_attr\fR(9S). The value in \fBdevacc_attr_dataorder\fR is +ignored in the current release. The value in \fBdevacc_attr_endian_flags\fR is +meaningful on the SPARC architecture only. +.RE + +.sp +.LP +\fBdevmap_umem_setup()\fR parameters: +.sp +.ne 2 +.mk +.na +\fB\fIdhp\fR\fR +.ad +.RS 15n +.rt +An opaque data structure that the system uses to describe the mapping. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 15n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallbackops\fR\fR +.ad +.RS 15n +.rt +Pointer to a \fBdevmap_callback_ctl\fR(9S) structure. The structure contains +pointers to device driver-supplied functions that manage events on the device +mapping. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcookie\fR\fR +.ad +.RS 15n +.rt +A kernel memory \fIcookie\fR (see \fBddi_umem_alloc\fR(9F)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIkoff\fR\fR +.ad +.RS 15n +.rt +Offset into the kernel memory defined by \fIcookie\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 15n +.rt +Length (in bytes) of the mapping to be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImaxprot\fR\fR +.ad +.RS 15n +.rt +Maximum protection flag possible for attempted mapping. Some combinations of +possible settings are: +.sp +.ne 2 +.mk +.na +\fB\fBPROT_READ\fR\fR +.ad +.RS 14n +.rt +Read access is allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_WRITE\fR\fR +.ad +.RS 14n +.rt +Write access is allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_EXEC\fR\fR +.ad +.RS 14n +.rt +Execute access is allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPROT_USER\fR\fR +.ad +.RS 14n +.rt +User-level access is allowed (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 14n +.rt +All access is allowed. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 15n +.rt +Must be set to \fB0\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaccattrp\fR\fR +.ad +.RS 15n +.rt +Pointer to a \fBddi_device_acc_attr\fR(9S) structure. Ignored in the current +release. Reserved for future use. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdevmap_devmem_setup()\fR and \fBdevmap_umem_setup()\fR functions are +used in the \fBdevmap\fR(9E) entry point to pass mapping parameters from the +driver to the system. +.sp +.LP +The \fIdhp\fR argument specifies a device mapping handle that the system uses +to store all mapping parameters of a physical contiguous memory. The system +copies the data pointed to by \fIcallbackops\fR to a system private memory. +This allows the driver to free the data after returning from either +\fBdevmap_devmem_setup()\fR or \fBdevmap_umem_setup()\fR. The driver is +notified of user events on the mappings via the entry points defined by +\fBdevmap_callback_ctl\fR(9S). The driver is notified of the following user +events: +.sp +.ne 2 +.mk +.na +\fBMapping Setup\fR +.ad +.RS 17n +.rt +User has called \fBmmap\fR(2) to create a mapping to the device memory. +.RE + +.sp +.ne 2 +.mk +.na +\fBAccess\fR +.ad +.RS 17n +.rt +User has accessed an address in the mapping that has no translations. +.RE + +.sp +.ne 2 +.mk +.na +\fBDuplication\fR +.ad +.RS 17n +.rt +User has duplicated the mapping. Mappings are duplicated when the process calls +\fBfork\fR(2). +.RE + +.sp +.ne 2 +.mk +.na +\fBUnmapping\fR +.ad +.RS 17n +.rt +User has called \fBmunmap\fR(2) on the mapping or is exiting, \fBexit\fR(2). +.RE + +.sp +.LP +See \fBdevmap_map\fR(9E), \fBdevmap_access\fR(9E), \fBdevmap_dup\fR(9E), and +\fBdevmap_unmap\fR(9E) for details on these entry points. +.sp +.LP +By specifying a valid \fIcallbackops\fR to the system, device drivers can +manage events on a device mapping. For example, the \fBdevmap_access\fR(9E) +entry point allows the drivers to perform context switching by unloading the +mappings of other processes and to load the mapping of the calling process. +Device drivers may specify \fINULL\fR to \fIcallbackops\fR which means the +drivers do not want to be notified by the system. +.sp +.LP +The maximum protection allowed for the mapping is specified in \fImaxprot\fR. +\fIaccattrp\fR defines the device access attributes. See +\fBddi_device_acc_attr\fR(9S) for more details. +.sp +.LP +\fBdevmap_devmem_setup()\fR is used for device memory to map in the register +set given by \fIrnumber\fR and the offset into the register address space given +by \fIroff\fR. The system uses \fIrnumber\fR and \fIroff\fR to go up the device +tree to get the physical address that corresponds to \fIroff\fR. The range to +be affected is defined by \fIlen\fR and \fIroff\fR. The range from \fIroff\fR +to \fIroff\fR \fI+\fR \fIlen\fR must be a physical contiguous memory and page +aligned. +.sp +.LP +Drivers use \fBdevmap_umem_setup()\fR for kernel memory to map in the kernel +memory described by \fIcookie\fR and the offset into the kernel memory space +given by \fIkoff\fR. \fIcookie\fR is a kernel memory pointer obtained from +\fBddi_umem_alloc\fR(9F). If \fIcookie\fR is \fINULL,\fR +\fBdevmap_umem_setup()\fR returns \fB-1.\fR The range to be affected is defined +by \fIlen\fR and \fIkoff\fR. The range from \fIkoff\fR to \fIkoff\fR \fI+\fR +\fIlen\fR must be within the limits of the kernel memory described by +\fIkoff\fR \fI+\fR \fIlen\fR and must be page aligned. +.sp +.LP +Drivers use \fBdevmap_umem_setup()\fR to export the kernel memory allocated by +\fBddi_umem_alloc\fR(9F) to user space. The system selects a user virtual +address that is aligned with the kernel virtual address being mapped to avoid +cache incoherence if the mapping is not \fBMAP_FIXED.\fR +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 6n +.rt +Successful completion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB-1\fR\fR +.ad +.RS 6n +.rt +An error occurred. +.RE + +.SH CONTEXT +.sp +.LP +\fBdevmap_devmem_setup()\fR and \fBdevmap_umem_setup()\fR can be called from +user, kernel, and interrupt context. +.SH SEE ALSO +.sp +.LP +\fBexit\fR(2), \fBfork\fR(2), \fBmmap\fR(2), \fBmunmap\fR(2), \fBdevmap\fR(9E), +\fBddi_umem_alloc\fR(9F), \fBddi_device_acc_attr\fR(9S), +\fBdevmap_callback_ctl\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/devmap_do_ctxmgt.9f b/usr/src/man/man9f/devmap_do_ctxmgt.9f new file mode 100644 index 0000000000..f4759c2538 --- /dev/null +++ b/usr/src/man/man9f/devmap_do_ctxmgt.9f @@ -0,0 +1,239 @@ +'\" te +.\" Copyright (c) 2000, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH devmap_do_ctxmgt 9F "22 Jan 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +devmap_do_ctxmgt \- perform device context switching on a mapping +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBdevmap_do_ctxmgt\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBvoid\fR \fI*pvtp\fR, \fBoffset_t\fR \fIoff\fR, + \fBsize_t\fR \fIlen\fR, \fBuint_t\fR \fItype\fR, + \fBuint_t\fR \fIrw\fR, \fBint (*\fR\fIdevmap_contextmgt\fR)devmap_cookie_t, + void *, offset_t, size_t, uint_t, uint_t); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdhp\fR \fR +.ad +.RS 22n +.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 22n +.rt +Driver private mapping data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoff\fR \fR +.ad +.RS 22n +.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 22n +.rt +Length (in bytes) of the memory being accessed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdevmap_contextmgt\fR \fR +.ad +.RS 22n +.rt +The address of driver function that the system will call to perform context +switching on a mapping. See \fBdevmap_contextmgt\fR(9E) for details. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR \fR +.ad +.RS 22n +.rt +Type of access operation. Provided by \fBdevmap_access\fR(9E). Should not be +modified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrw\fR \fR +.ad +.RS 22n +.rt +Direction of access. Provided by \fBdevmap_access\fR(9E). Should not be +modified. +.RE + +.SH DESCRIPTION +.sp +.LP +Device drivers call \fBdevmap_do_ctxmgt()\fR in the \fBdevmap_access\fR(9E) +entry point to perform device context switching on a mapping. +\fBdevmap_do_ctxmgt()\fR passes a pointer to a driver supplied callback +function, \fBdevmap_contextmgt\fR(9E), to the system that will perform the +actual device context switching. If \fBdevmap_contextmgt\fR(9E) is not a valid +driver callback function, the system will fail the memory access operation +which will result in a \fBSIGSEGV\fR or \fBSIGBUS\fR signal being delivered to +the process. +.sp +.LP +\fBdevmap_do_ctxmgt()\fR performs context switching on the mapping object +identified by \fIdhp\fR and \fIpvtp\fR in the range specified by \fIoff\fR and +\fIlen\fR. The arguments \fIdhp\fR, \fIpvtp\fR, \fItype\fR, and \fIrw\fR are +provided by the \fBdevmap_access\fR(9E) entry point and must not be modified. +The range from \fIoff\fR to \fIoff+len\fR must support context switching. +.sp +.LP +The system will pass through \fIdhp\fR,\fI pvtp\fR,\fI off\fR, \fI len\fR,\fI +type\fR, and \fIrw\fR to \fBdevmap_contextmgt\fR(9E) in order to perform the +actual device context switching. The return value from +\fBdevmap_contextmgt\fR(9E) will be returned directly to +\fBdevmap_do_ctxmgt()\fR. +.SH RETURN VALUES +.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 CONTEXT +.sp +.LP +\fBdevmap_do_ctxmgt()\fR must be called from the driver's +\fBdevmap_access\fR(9E) entry point. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing devmap_do_ctxmgt in the devmap_access entry point. +.sp +.LP +The following shows an example of using \fBdevmap_do_ctxmgt()\fR in the +\fBdevmap_access\fR(9E) entry point. + +.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 off 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 off is 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_access\fR(9E), \fBdevmap_contextmgt\fR(9E), +\fBdevmap_default_access\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/devmap_set_ctx_timeout.9f b/usr/src/man/man9f/devmap_set_ctx_timeout.9f new file mode 100644 index 0000000000..a2755149b5 --- /dev/null +++ b/usr/src/man/man9f/devmap_set_ctx_timeout.9f @@ -0,0 +1,70 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH devmap_set_ctx_timeout 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +devmap_set_ctx_timeout \- set the timeout value for the context management +callback +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBdevmap_set_ctx_timeout\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBclock_t\fR \fIticks\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.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\fIticks\fR\fR +.ad +.RS 9n +.rt +Number of clock ticks to wait between successive calls to the context +management callback function. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdevmap_set_ctx_timeout()\fR function specifies the time interval for the +system to wait between successive calls to the driver's context management +callback function, \fBdevmap_contextmgt\fR(9E). +.sp +.LP +Device drivers typically call \fBdevmap_set_ctx_timeout()\fR in the +\fBdevmap_map\fR(9E) routine. If the drivers do not call +\fBdevmap_set_ctx_timeout()\fR to set the timeout value, the default timeout +value of \fB0\fR will result in no delay between successive calls to the +driver's \fBdevmap_contextmgt\fR(9E) callback function. +.SH CONTEXT +.sp +.LP +The \fBdevmap_set_ctx_timeout()\fR function can be called from user, interrupt, +or kernel context. +.SH SEE ALSO +.sp +.LP +\fBdevmap_contextmgt\fR(9E), \fBdevmap_map\fR(9E), \fBtimeout\fR(9F) diff --git a/usr/src/man/man9f/devmap_setup.9f b/usr/src/man/man9f/devmap_setup.9f new file mode 100644 index 0000000000..9a50067c9f --- /dev/null +++ b/usr/src/man/man9f/devmap_setup.9f @@ -0,0 +1,332 @@ +'\" 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_setup 9F "22 Jan 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +devmap_setup, ddi_devmap_segmap \- set up a user mapping to device memory using +the devmap framework +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBdevmap_setup\fR(\fBdev_t\fR \fIdev\fR, \fBoffset_t\fR \fIoff\fR, \fBddi_as_handle_t\fR \fIas\fR, + \fBcaddr_t *\fR\fIaddrp\fR, \fBsize_t\fR\fIlen\fR, \fBuint_t\fR \fIprot\fR, \fBuint_t\fR \fImaxprot\fR, + \fBuint_t\fR \fIflags\fR, \fBcred_t *\fR\fIcred\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_devmap_segmap\fR(\fBdev_t\fR \fIdev\fR, \fBoff_t\fR \fIoff\fR, \fBddi_as_handle_t\fR \fIas\fR, + \fBcaddr_t *\fR\fIaddrp\fR, \fBoff_t\fR\fIlen\fR, \fBuint_t\fR \fIprot\fR, \fBuint_t\fR \fImaxprot\fR, + \fBuint_t\fR \fIflags\fR, \fBcred_t *\fR\fIcred\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 12n +.rt +Device whose memory is to be mapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoff\fR \fR +.ad +.RS 12n +.rt +User offset within the logical device memory at which the mapping begins. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIas\fR \fR +.ad +.RS 12n +.rt +An opaque data structure that describes 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 starting address in the address space into 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. Some possible settings combinations +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. The following flags can be specified: +.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 + +.sp +.ne 2 +.mk +.na +\fB\fBMAP_FIXED\fR \fR +.ad +.RS 16n +.rt +The user specified an address in \fI*addrp\fR rather than letting the system +choose an address. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcred\fR \fR +.ad +.RS 12n +.rt +Pointer to the user credential structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBdevmap_setup()\fR and \fBddi_devmap_segmap()\fR allow device drivers to use +the devmap framework to set up user mappings to device memory. The devmap +framework provides several advantages over the default device mapping framework +that is used by \fBddi_segmap\fR(9F) or \fBddi_segmap_setup\fR(9F). Device +drivers should use the devmap framework, if the driver wants to: +.RS +4 +.TP +.ie t \(bu +.el o +use an optimal MMU pagesize to minimize address translations, +.RE +.RS +4 +.TP +.ie t \(bu +.el o +conserve kernel resources, +.RE +.RS +4 +.TP +.ie t \(bu +.el o +receive callbacks to manage events on the mapping, +.RE +.RS +4 +.TP +.ie t \(bu +.el o +export kernel memory to applications, +.RE +.RS +4 +.TP +.ie t \(bu +.el o +set up device contexts for the user mapping if the device requires context +switching, +.RE +.RS +4 +.TP +.ie t \(bu +.el o +assign device access attributes to the user mapping, or +.RE +.RS +4 +.TP +.ie t \(bu +.el o +change the maximum protection for the mapping. +.RE +.sp +.LP +\fBdevmap_setup()\fR must be called in the \fBsegmap\fR(9E) entry point to +establish the mapping for the application. \fBddi_devmap_segmap()\fR can be +called in, or be used as, the \fBsegmap\fR(9E) entry point. The differences +between \fBdevmap_setup()\fR and \fBddi_devmap_segmap()\fR are in the data +type used for \fIoff\fR and \fIlen\fR. +.sp +.LP +When setting up the mapping, \fBdevmap_setup()\fR and +\fBddi_devmap_segmap()\fR call the \fBdevmap\fR(9E) entry point to validate the +range to be mapped. The \fBdevmap\fR(9E) entry point also translates the +logical offset (as seen by the application) to the corresponding physical +offset within the device address space. If the driver does not provide its own +\fBdevmap\fR(9E) entry point, \fBEINVAL\fR will be returned to the +\fBmmap\fR(2) system call. +.SH RETURN VALUES +.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. The return value of \fBdevmap_setup()\fR and +\fBddi_devmap_segmap()\fR should be used directly in the \fBsegmap\fR(9E) +entry point. +.RE + +.SH CONTEXT +.sp +.LP +\fBdevmap_setup()\fR and \fBddi_devmap_segmap()\fR can be called from user or +kernel context only. +.SH SEE ALSO +.sp +.LP +\fBmmap\fR(2), \fBdevmap\fR(9E), \fBsegmap\fR(9E), \fBddi_segmap\fR(9F), +\fBddi_segmap_setup\fR(9F), \fBcb_ops\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/devmap_unload.9f b/usr/src/man/man9f/devmap_unload.9f new file mode 100644 index 0000000000..f44768ac19 --- /dev/null +++ b/usr/src/man/man9f/devmap_unload.9f @@ -0,0 +1,205 @@ +'\" te +.\" Copyright (c) 1999, 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_unload 9F "22 Jan 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +devmap_unload, devmap_load \- control validation of memory address translations +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBdevmap_load\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBoffset_t\fR \fIoff\fR, \fBsize_t\fR \fIlen\fR, + \fBuint_t\fR \fItype\fR, \fBuint_t\fR \fIrw\fR); +.fi + +.LP +.nf +\fBint\fR \fBdevmap_unload\fR(\fBdevmap_cookie_t\fR \fIdhp\fR, \fBoffset_t\fR \fIoff\fR, \fBsize_t\fR \fIlen\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdhp\fR \fR +.ad +.RS 8n +.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 8n +.rt +User offset within the logical device memory at which the loading or unloading +of the address translations begins. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR \fR +.ad +.RS 8n +.rt +Length (in bytes) of the range being affected. +.RE + +.SS "devmap_load() only" +.sp +.ne 2 +.mk +.na +\fB\fItype\fR \fR +.ad +.RS 9n +.rt +Type of access operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrw\fR \fR +.ad +.RS 9n +.rt +Direction of access. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBdevmap_unload()\fR and \fBdevmap_load()\fR are used to control the +validation of the memory mapping described by \fIdhp\fR in the specified range. +\fBdevmap_unload()\fR invalidates the mapping translations and will generate +calls to the \fBdevmap_access\fR(9E) entry point next time the mapping is +accessed. The drivers use \fBdevmap_load()\fR to validate the mapping +translations during memory access. +.sp +.LP +A typical use of \fBdevmap_unload()\fR and \fBdevmap_load()\fR is in the +driver's context management callback function, \fBdevmap_contextmgt\fR(9E). To +manage a device context, a device driver calls \fBdevmap_unload()\fR on the +context about to be switched out. It switches contexts, and then calls +\fBdevmap_load()\fR on the context switched in. \fBdevmap_unload()\fR can be +used to unload the mappings of other processes as well as the mappings of the +calling process, but \fBdevmap_load()\fR can only be used to load the mappings +of the calling process. Attempting to load another process's mappings with +\fBdevmap_load()\fR will result in a system panic. +.sp +.LP +For both routines, the range to be affected is defined by the \fIoff\fR and +\fIlen\fR arguments. Requests affect the entire page containing the \fIoff\fR +and all pages up to and including the page containing the last byte as +indicated by \fIoff + len\fR. The arguments \fItype\fR and \fIrw\fR are +provided by the system to the calling function (for example, +\fBdevmap_contextmgt\fR(9E)) and should not be modified. +.sp +.LP +Supplying a value of \fB0\fR for the \fIlen\fR argument affects all addresses +from the \fIoff\fR to the end of the mapping. Supplying a value of \fB0\fR for +the \fIoff\fR argument and a value of \fB0\fR for \fIlen\fR argument affect all +addresses in the mapping. +.sp +.LP +A non-zero return value from either \fBdevmap_unload()\fR or +\fBdevmap_load()\fR 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 +\fB\fBNon-zero\fR\fR +.ad +.RS 12n +.rt +An error occurred. +.RE + +.SH CONTEXT +.sp +.LP +These routines can be called from user or kernel context only. +.SH EXAMPLES +.LP +\fBExample 1 \fRManaging a One-Page Device Context +.sp +.LP +The following shows an example of managing a device context that is one page in +length. + +.sp +.in +2 +.nf +struct xx_context cur_ctx; + +static int +xxdevmap_contextmgt(devmap_cookie_t dhp, void *pvtp, offset_t off, + size_t len, uint_t type, uint_t rw) +{ + int err; + devmap_cookie_t cur_dhp; + struct xx_pvt *p; + struct xx_pvt *pvp = (struct xx_pvt *)pvtp; + /* enable access callbacks for the current mapping */ + if (cur_ctx != NULL && cur_ctx != pvp->ctx) { + p = cur_ctx->pvt; + /* + * unload the region from off to the end of the mapping. + */ + 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; + /* + * Disable callbacks and complete the access for the + * mapping that generated this callback. + */ + return (devmap_load(pvp->dhp, off, len, type, rw)); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBdevmap_access\fR(9E), \fBdevmap_contextmgt\fR(9E) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/disksort.9f b/usr/src/man/man9f/disksort.9f new file mode 100644 index 0000000000..03c13d4c5a --- /dev/null +++ b/usr/src/man/man9f/disksort.9f @@ -0,0 +1,94 @@ +'\" te +.\" Copyright (c) 2006, 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 disksort 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +disksort \- single direction elevator seek sort for buffers +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> +void + +\fB\fR\fBdisksort\fR(\fBstruct diskhd\fR \fI*dp\fR, \fBstruct buf\fR \fI*bp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdp\fR\fR +.ad +.RS 6n +.rt +A pointer to a \fBdiskhd\fR structure. A \fBdiskhd\fR structure is essentially +identical to head of a buffer structure (see \fBbuf\fR(9S)). The only defined +items of interest for this structure are the \fBav_forw\fR and \fBav_back\fR +structure elements which are used to maintain the front and tail pointers of +the forward linked \fBI/O\fR request queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +A pointer to a buffer structure. Typically this is the \fBI/O\fR request that +the driver receives in its strategy routine (see \fBstrategy\fR(9E)). The +driver is responsible for initializing the \fBb_resid\fR structure element to a +meaningful sort key value prior to calling \fBdisksort()\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The function \fBdisksort()\fR sorts a pointer to a buffer into a single forward +linked list headed by the \fBav_forw\fR element of the argument \fI*dp\fR. +.sp +.LP +It uses a one-way elevator algorithm that sorts buffers into the queue in +ascending order based upon a key value held in the argument buffer structure +element \fBb_resid\fR. +.sp +.LP +This value can either be the driver calculated cylinder number for the +\fBI/O\fR request described by the buffer argument, or simply the absolute +logical block for the \fBI/O\fR request, depending on how fine grained the sort +is desired to be or how applicable either quantity is to the device in +question. +.sp +.LP +The head of the linked list is found by use of the \fBav_forw\fR structure +element of the argument \fI*dp\fR. The tail of the linked list is found by use +of the \fBav_back\fR structure element of the argument \fI*dp\fR. The +\fBav_forw\fR element of the \fI*bp\fR argument is used by \fBdisksort()\fR to +maintain the forward linkage. The value at the head of the list presumably +indicates the currently active disk area. +.SH CONTEXT +.sp +.LP +This function can be called from user, interrupt, or kernel context. +.SH SEE ALSO +.sp +.LP +\fBstrategy\fR(9E), \fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +The \fBdisksort()\fR function does no locking. Therefore, any locking is +completely the responsibility of the caller. diff --git a/usr/src/man/man9f/dlbindack.9f b/usr/src/man/man9f/dlbindack.9f new file mode 100644 index 0000000000..f6c42cc042 --- /dev/null +++ b/usr/src/man/man9f/dlbindack.9f @@ -0,0 +1,230 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH dlbindack 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +dlbindack, dlphysaddrack, dlokack, dlerrorack, dluderrorind \- DLPI device +driver helper functions +.SH SYNOPSIS +.LP +.nf +#include <sys/dlpi.h> + + + +\fBvoid\fR \fBdlokack\fR(\fBqueue_t *\fR\fIwq\fR, \fBmblk_t *\fR\fImp\fR, \fBt_uscalar_t\fR \fIcorrect_primitive\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBdlerrorack\fR(\fBqueue_t *\fR\fIwq\fR, \fBmblk_t *\fR\fImp\fR, \fBt_uscalar_t\fR \fIerror_primitive\fR, + \fBt_uscalar_t\fR \fIerror\fR, \fBt_uscalar_t\fR \fIunix_errno\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBdlbindack\fR(\fBqueue_t *\fR\fIwq\fR, \fBmblk_t *\fR\fImp\fR, \fBt_scalar_t\fR \fIsap\fR, \fBconst void *\fR\fIaddrp\fR, + \fBt_uscalar_t\fR \fIaddrlen\fR, \fBt_uscalar_t\fR \fImaxconind\fR, \fB t_uscalar_t\fR \fIxidtest\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBdlphysaddrack\fR(\fBqueue_t *\fR\fIwq\fR, \fBmblk_t *\fR\fImp\fR, \fBconst void *\fR\fIaddrp\fR, + \fBt_uscalar_t\fR \fIaddrlen\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBdluderrorind\fR(\fBqueue_t *\fR\fIwq\fR, \fBmblk_t *\fR\fImp\fR, \fBconst void *\fR\fIaddrp\fR, + \fBt_uscalar_t\fR \fIaddrlen\fR, \fBt_uscalar_t\fR \fIerror\fR, \fBt_uscalar_t\fR \fIunix_errno\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIwq\fR\fR +.ad +.RS 21n +.rt +Streams write queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 21n +.rt +Pointer to the bind request message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsap\fR\fR +.ad +.RS 21n +.rt +Service access point being requested. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddrp\fR\fR +.ad +.RS 21n +.rt +Pointer to the dlpi layer source address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddrlen\fR\fR +.ad +.RS 21n +.rt +Size of the \fBdlpi\fR layer address pointed to by \fIaddr\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImaxconind\fR\fR +.ad +.RS 21n +.rt +Maximum number of \fBDL_CONNECT_IND\fR messages allowed to be outstanding per +stream. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIxidtest\fR\fR +.ad +.RS 21n +.rt +The \fBXID\fR and \fBTEST\fR responses supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcorrect_primitive\fR\fR +.ad +.RS 21n +.rt +Identifies the \fBDL\fR primitive completing successfully. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerror_primitive\fR\fR +.ad +.RS 21n +.rt +Identifies the \fBDL\fR primitive in error. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerror\fR\fR +.ad +.RS 21n +.rt +\fBDLPI\fR error associated with the failure in the \fBDLPI\fR request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIunix_errno\fR\fR +.ad +.RS 21n +.rt +Corresponding \fBUNIX\fR system error that can be associated with the failure +in the \fBDLPI\fR request. +.RE + +.SH DESCRIPTION +.sp +.LP +All functions described in this manpage take a pointer to the message passed to +the \fBDLPI\fR provider (\fBmblk_t\fR) and attempt to reuse it in formulating +the \fBM_PROTO\fR reply. If the message block is too small to be reused, it is +freed and a new one is allocated. +.sp +.LP +All functions reply upstream using \fBqreply\fR(9F). The write-side queue +pointer must be provided. +.sp +.LP +The \fBdlokack()\fR function provides the successfull acknowledgement +\fBDL_OK_ACK\fR message reply to the \fBDLPI\fR provider and is used to +complete many of the \fBDLPI\fR requests in the \fBDLPI\fR consumer. +.sp +.LP +The \fBdlerrorack()\fR function provides the unsuccessfull acknowledgement +\fBDL_ERROR_ACK\fR message reply to the \fBDLPI\fR() provider and is used for +error completions were required for \fBDLPI\fR requests in the \fBDLPI\fR +consumer. +.sp +.LP +The \fBdlbindack()\fR function provides the \fBDL_BIND_ACK\fR message reply to +the \fBDLPI\fR provider and is used to complete the \fBDL_BIND_REQ\fR +processing in the \fBDLPI\fR consumer. +.sp +.LP +The \fBdlphysaddrack()\fR function provides the \fB\fR()\fBDL_PHYS_ADDR_ACK\fR +message reply used to complete the \fBDL_PHYS_ADDR_ACK\fR processing. +.sp +.LP +The \fBdluderrorind()\fR function provides the \fBDL_UDERROR_IND\fR message +reply used to complete an unsuccessful \fBDL_UNITDATA_REQ\fR. +.SH RETURN VALUES +.sp +.LP +None. +.SH NOTES +.sp +.LP +These functions are not required if you are are writing a \fBDLPI\fR device +driver using \fBgld\fR(7D). +.SH CONTEXT +.sp +.LP +All \fBDLPI\fR helper functions can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBgld\fR(7D), \fBdlpi\fR(7P), \fBqreply\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/drv_getparm.9f b/usr/src/man/man9f/drv_getparm.9f new file mode 100644 index 0000000000..e2f66377f9 --- /dev/null +++ b/usr/src/man/man9f/drv_getparm.9f @@ -0,0 +1,179 @@ +'\" te +.\" opyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH drv_getparm 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +drv_getparm \- retrieve kernel state information +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> + + + +\fBint\fR \fBdrv_getparm\fR(\fBunsigned int\fR \fIparm\fR, \fBvoid *\fR\fIvalue_p\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIparm\fR\fR +.ad +.RS 8n +.rt +The kernel parameter to be obtained. Possible values are: +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLBOLT\fR\fR +.ad +.RS 10n +.rt +Read the value of \fBlbolt\fR. \fBlbolt\fR is a \fBclock_t\fR that is +unconditionally incremented by one at each clock tick. No special treatment is +applied when this value overflows the maximum value of the signed integral type +\fBclock_t\fR. When this occurs, its value will be negative, and its magnitude +will be decreasing until it again passes zero. It can therefore not be relied +upon to provide an indication of the amount of time that passes since the last +system reboot, nor should it be used to mark an absolute time in the system. +Only the difference between two measurements of \fBlbolt\fR is significant. It +is used in this way inside the system kernel for timing purposes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPPGRP\fR\fR +.ad +.RS 10n +.rt +Read the process group identification number. This number determines which +processes should receive a \fBHANGUP\fR or \fBBREAK\fR signal when detected by +a driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUPROCP\fR\fR +.ad +.RS 10n +.rt +Read the process table token value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPPID\fR\fR +.ad +.RS 10n +.rt +Read process identification number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPSID\fR\fR +.ad +.RS 10n +.rt +Read process session identification number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTIME\fR\fR +.ad +.RS 10n +.rt +Read time in seconds. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCRED\fR\fR +.ad +.RS 10n +.rt +Return a pointer to the caller's credential structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvalue_p\fR\fR +.ad +.RS 11n +.rt +A pointer to the data space in which the value of the parameter is to be +copied. +.RE + +.SH DESCRIPTION +.sp +.LP +Since the release of the Solaris 2.6 operating environment, the +\fBdrv_getparm()\fR function has been replaced by \fBddi_get_lbolt\fR(9F), +\fBddi_get_time\fR(9F), and \fBddi_get_pid\fR(9F). +.sp +.LP +The \fBdrv_getparm()\fR function verifies that \fIparm\fR corresponds to a +kernel parameter that may be read. If the value of \fIparm\fR does not +correspond to a parameter or corresponds to a parameter that may not be read, +\fB-1\fR is returned. Otherwise, the value of the parameter is stored in the +data space pointed to by \fIvalue_p\fR. +.sp +.LP +The \fBdrv_getparm()\fR function does not explicitly check to see whether the +device has the appropriate context when the function is called and the function +does not check for correct alignment in the data space pointed to by +\fIvalue_p\fR. It is the responsibility of the driver writer to use this +function only when it is appropriate to do so and to correctly declare the data +space needed by the driver. +.SH RETURN VALUES +.sp +.LP +The \fBdrv_getparm()\fR function returns \fB0\fR to indicate success, \fB-1\fR +to indicate failure. The value stored in the space pointed to by \fIvalue_p\fR +is the value of the parameter if \fB0\fR is returned, or undefined if \fB-1\fR +is returned. \fB-1\fR is returned if you specify a value other than +\fBLBOLT\fR, \fBPPGRP\fR, \fBPPID\fR, \fBPSID\fR, \fBTIME\fR, \fBUCRED\fR, or +\fBUPROCP\fR. Always check the return code when using this function. +.SH CONTEXT +.sp +.LP +The \fBdrv_getparm()\fR function can be called from user context only when +using \fBPPGRP\fR, \fBPPID\fR, \fBPSID\fR, \fBUCRED\fR, or \fBUPROCP\fR. It can +be called from user, interrupt, or kernel context when using the \fBLBOLT\fR or +\fBTIME\fR argument. +.SH SEE ALSO +.sp +.LP +\fBddi_get_lbolt\fR(9F), \fBddi_get_pid\fR(9F), \fBddi_get_time\fR(9F), +\fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/drv_hztousec.9f b/usr/src/man/man9f/drv_hztousec.9f new file mode 100644 index 0000000000..1e05500ac5 --- /dev/null +++ b/usr/src/man/man9f/drv_hztousec.9f @@ -0,0 +1,69 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH drv_hztousec 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +drv_hztousec \- convert clock ticks to microseconds +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> + + + +\fBclock_t\fR \fBdrv_hztousec\fR(\fBclock_t\fR \fIhertz\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhertz\fR\fR +.ad +.RS 9n +.rt +The number of clock ticks to convert. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdrv_hztousec()\fR function converts into microseconds the time expressed +by \fIhertz\fR, which is in system clock ticks. +.sp +.LP +The kernel variable \fBlbolt\fR, whose value should be retrieved by calling +\fBddi_get_lbolt\fR(9F), is the length of time the system has been up since +boot and is expressed in clock ticks. Drivers often use the value of +\fBlbolt\fR before and after an \fBI/O\fR request to measure the amount of time +it took the device to process the request. The \fBdrv_hztousec()\fR function +can be used by the driver to convert the reading from clock ticks to a known +unit of time. +.SH RETURN VALUES +.sp +.LP +The number of microseconds equivalent to the \fIhertz\fR parameter. No error +value is returned. If the microsecond equivalent to \fIhertz\fR is too large to +be represented as a \fBclock_t\fR, then the maximum \fBclock_t\fR value will be +returned. +.SH CONTEXT +.sp +.LP +The \fBdrv_hztousec()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBddi_get_lbolt\fR(9F), \fBdrv_usectohz\fR(9F), \fBdrv_usecwait\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/drv_priv.9f b/usr/src/man/man9f/drv_priv.9f new file mode 100644 index 0000000000..6bbd33a2d0 --- /dev/null +++ b/usr/src/man/man9f/drv_priv.9f @@ -0,0 +1,65 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH drv_priv 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +drv_priv \- determine driver privilege +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/cred.h> +#include <sys/ddi.h> + + + +\fBint\fR \fBdrv_priv\fR(\fBcred_t *\fR\fIcr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcr\fR\fR +.ad +.RS 6n +.rt +Pointer to the user credential structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdrv_priv()\fR function provides a general interface to the system +privilege policy. It determines whether the credentials supplied by the user +credential structure pointed to by \fIcr\fR identify a process that has the +\fB{PRIV_SYS_DEVICES}\fR privilege asserted in its effective set. This function +should be used only when file access modes, special minor device numbers, and +the device policy (see \fBprivileges\fR(5), \fBadd_drv\fR(1M)) are insufficient +to provide protection for the requested driver function. It is intended to +replace all calls to \fBsuser()\fR and any explicit checks for effective user +ID = 0 in driver code. +.SH RETURN VALUES +.sp +.LP +This routine returns \fB0\fR if it succeeds, \fBEPERM\fR if it fails. +.SH CONTEXT +.sp +.LP +The \fBdrv_priv()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBadd_drv\fR(1M), \fBupdate_drv\fR(1M), \fBprivileges\fR(5) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/drv_usectohz.9f b/usr/src/man/man9f/drv_usectohz.9f new file mode 100644 index 0000000000..f82f9ee5e8 --- /dev/null +++ b/usr/src/man/man9f/drv_usectohz.9f @@ -0,0 +1,78 @@ +'\" 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 drv_usectohz 9F "24 Apr 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +drv_usectohz \- convert microseconds to clock ticks +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> + + + +\fBclock_t\fR \fBdrv_usectohz\fR(\fBclock_t\fR \fImicrosecs\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImicrosecs\fR\fR +.ad +.RS 13n +.rt +The number of microseconds to convert. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdrv_usectohz()\fR function converts a length of time expressed in +microseconds to a number of system clock ticks. The time arguments to +\fBtimeout\fR(9F) and \fBdelay\fR(9F) are expressed in clock ticks. +.sp +.LP +The \fBdrv_usectohz()\fR function is a portable interface for drivers to make +calls to \fBtimeout\fR(9F) and \fBdelay\fR(9F) and remain binary compatible +should the driver object file be used on a system with a different clock speed +(a different number of ticks in a second). +.SH RETURN VALUES +.sp +.LP +The value returned is the number of system clock ticks equivalent to the +\fImicrosecs\fR argument. No error value is returned. If the clock tick +equivalent to \fImicrosecs\fR is too large to be represented as a +\fBclock_t\fR, then the maximum \fBclock_t\fR value will be returned. +.SH CONTEXT +.sp +.LP +The \fBdrv_usectohz()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBdelay\fR(9F), \fBdrv_hztousec\fR(9F), \fBtimeout\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +If the \fImicrosecs\fR argument to \fBdrv_usectohz()\fR is less than +\fBdrv_hztousec\fR(9F), \fBdrv_usectohz()\fR returns one tick. This, coupled +with multiplication, can result in significantly longer durations than +expected. For example, on a machine where \fBhz\fR is 100, calling +\fBdrv_usectohz()\fR with a \fImicrosecs\fR value less than 10000 returns a +result equivalent to 10000 (1 tick). This type of mistake causes code such +as"5000 * drv_usectohz(1000)" to compute a duration of 50 seconds instead of +the intended 5 seconds. diff --git a/usr/src/man/man9f/drv_usecwait.9f b/usr/src/man/man9f/drv_usecwait.9f new file mode 100644 index 0000000000..da786dffc9 --- /dev/null +++ b/usr/src/man/man9f/drv_usecwait.9f @@ -0,0 +1,74 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH drv_usecwait 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +drv_usecwait \- busy-wait for specified interval +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBdrv_usecwait\fR(\fBclock_t\fR \fImicrosecs\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImicrosecs\fR\fR +.ad +.RS 13n +.rt +The number of microseconds to busy-wait. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBdrv_usecwait()\fR function gives drivers a means of busy-waiting for a +specified microsecond count. The amount of time spent busy-waiting may be +greater than the microsecond count but will minimally be the number of +microseconds specified. +.sp +.LP +\fBdelay\fR(9F) can be used by a driver to delay for a specified number of +system ticks, but it has two limitations. First, the granularity of the wait +time is limited to one clock tick, which may be more time than is needed for +the delay. Second, \fBdelay\fR(9F) can be invoked from user or kernel context +and hence cannot be used at interrupt time or system initialization. +.sp +.LP +Often, drivers need to delay for only a few microseconds, waiting for a write +to a device register to be picked up by the device. In this case, even in user +context, \fBdelay\fR(9F) produces too long a wait period. +.SH CONTEXT +.sp +.LP +The \fBdrv_usecwait()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBdelay\fR(9F), \fBtimeout\fR(9F), \fBuntimeout\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The driver wastes processor time by making this call since \fBdrv_usecwait()\fR +does not block but simply busy-waits. The driver should only make calls to +\fBdrv_usecwait()\fR as needed, and only for as much time as needed. The +\fBdrv_usecwait()\fR function does not mask out interrupts. diff --git a/usr/src/man/man9f/dupb.9f b/usr/src/man/man9f/dupb.9f new file mode 100644 index 0000000000..d6d46fea72 --- /dev/null +++ b/usr/src/man/man9f/dupb.9f @@ -0,0 +1,182 @@ +'\" 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 dupb 9F "22 Mar 2002" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +dupb \- duplicate a message block descriptor +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBmblk_t *\fR\fBdupb\fR(\fBmblk_t *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH DESCRIPTION +.sp +.LP +\fBdupb()\fR creates a new \fBmblk_t\fR structure (see \fBmsgb\fR(9S)) to +reference the message block pointed to by \fIbp\fR. +.sp +.LP +Unlike \fBcopyb\fR(9F), \fBdupb()\fR does not copy the information in the +\fBdblk_t\fR structure (see \fBdatab\fR(9S)), but creates a new \fBmblk_t\fR +structure to point to it. The reference count in the \fBdblk_t\fR structure +(\fBdb_ref\fR) is incremented. The new \fBmblk_t\fR structure contains the +same information as the original. Note that \fBb_rptr\fRand \fBb_wptr\fR are +copied from the \fIbp\fR. +.sp +Printed copy or docs.sun.com shows a figure that shows a new mblk_t structure +created, with the original and new bp both pointing to the dblk_t structure, +and db_ref incremented by one +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR \fR +.ad +.RS 7n +.rt +Pointer to the message block to be duplicated. \fBmblk_t\fR is an instance of +the \fBmsgb\fR(9S) structure. +.RE + +.SH RETURN VALUES +.sp +.LP +If successful, \fBdupb()\fR returns a pointer to the new message block. A +\fINULL\fR pointer is returned if \fBdupb()\fR cannot allocate a new message +block descriptor or if the \fBdb_ref\fR field of the data block structure (see +\fBdatab\fR(9S)) has reached a maximum value (\fB255\fR). +.SH CONTEXT +.sp +.LP +\fBdupb()\fR can be called from user, kernel, or interrupt context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBdupb()\fR +.sp +.LP +This \fBsrv\fR(9E) (service) routine adds a header to all \fBM_DATA\fR +messages before passing them along. \fBdupb\fR is used instead of +\fBcopyb\fR(9F) because the contents of the header block are not changed. + +.sp +.LP +For each message on the queue, if it is a priority message, pass it along +immediately (lines 10-11). Otherwise, if it is anything other than an +\fBM_DATA\fR message (line 12), and if it can be sent along (line 13), then do +so (line 14). Otherwise, put the message back on the queue and return (lines +16-17). For all \fBM_DATA\fR messages, first check to see if the stream is +flow-controlled (line 20). If it is, put the message back on the queue and +return (lines 37-38). If it is not, the header block is duplicated (line 21). + +.sp +.LP +\fBdupb()\fR can fail either due to lack of resources or because the message +block has already been duplicated 255 times. In order to handle the latter +case, the example calls \fBcopyb\fR(9F) (line 22). If \fBcopyb\fR(9F) fails, +it is due to buffer allocation failure. In this case, \fBqbufcall\fR(9F) is +used to initiate a callback (lines 30-31) if one is not already pending (lines +26-27). + +.sp +.LP +The callback function, \fBxxxcallback()\fR, clears the recorded +\fBqbufcall\fR(9F) callback id and schedules the service procedure (lines +49-50). Note that the close routine, \fBxxxclose()\fR, must cancel any +outstanding \fBqbufcall\fR(9F) callback requests (lines 58-59). + +.sp +.LP +If \fBdupb()\fR or \fBcopyb\fR(9F) succeed, link the \fBM_DATA\fR message to +the new message block (line 34) and pass it along (line 35). + +.sp +.in +2 +.nf + 1 xxxsrv(q) + 2 queue_t *q; + 3 { + 4 struct xx *xx = (struct xx *)q->q_ptr; + 5 mblk_t *mp; + 6 mblk_t *bp; + 7 extern mblk_t *hdr; + 8 + 9 while ((mp = getq(q)) != NULL) { + 10 if (mp->b_datap->db_type >= QPCTL) { + 11 putnext(q, mp); + 12 } else if (mp->b_datap->db_type != M_DATA) { + 13 if (canputnext(q)) + 14 putnext(q, mp); + 15 else { + 16 putbq(q, mp); + 17 return; + 18 } + 19 } else { /* M_DATA */ + 20 if (canputnext(q)) { + 21 if ((bp = dupb(hdr)) == NULL) + 22 bp = copyb(hdr); + 23 if (bp == NULL) { + 24 size_t size = msgdsize(mp); + 25 putbq(q, mp); + 26 if (xx->xx_qbufcall_id) { + 27 /* qbufcall pending */ + 28 return; + 29 } + 30 xx->xx_qbufcall_id = qbufcall(q, size, + 31 BPRI_MED, xxxcallback, (intptr_t)q); + 32 return; + 33 } + 34 linkb(bp, mp); + 35 putnext(q, bp); + 36 } else { + 37 putbq(q, mp); + 38 return; + 39 } + 40 } + 41 } + 42 } + 43 void + 44 xxxcallback(q) + 45 queue_t *q; + 46 { + 47 struct xx *xx = (struct xx *)q->q_ptr; + 48 + 49 xx->xx_qbufcall_id = 0; + 50 qenable(q); + 51 } + + 52 xxxclose(q, cflag, crp) + 53 queue_t *q; + 54 int cflag; + 55 cred_t *crp; + 56 { + 57 struct xx *xx = (struct xx *)q->q_ptr; + ... + 58 if (xx->xx_qbufcall_id) + 59 qunbufcall(q, xx->xx_qbufcall_id); + ... + 60 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBsrv\fR(9E), \fBcopyb\fR(9F), \fBqbufcall\fR(9F), \fBdatab\fR(9S), +\fBmsgb\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR \fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/dupmsg.9f b/usr/src/man/man9f/dupmsg.9f new file mode 100644 index 0000000000..543ccf3c5a --- /dev/null +++ b/usr/src/man/man9f/dupmsg.9f @@ -0,0 +1,69 @@ +'\" te +.\" 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 dupmsg 9F "11 Apr 1991" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +dupmsg \- duplicate a message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBmblk_t *\fR\fBdupmsg\fR(\fBmblk_t *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR \fR +.ad +.RS 7n +.rt +Pointer to the message. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBdupmsg()\fR forms a new message by copying the message block descriptors +pointed to by \fImp\fR and linking them. \fBdupb\fR(9F) is called for each +message block. The data blocks themselves are not duplicated. +.SH RETURN VALUES +.sp +.LP +If successful, \fBdupmsg()\fR returns a pointer to the new message block. +Otherwise, it returns a \fINULL\fR pointer. A return value of \fINULL\fR +indicates either memory depletion or the data block reference count, +\fBdb_ref\fR (see \fBdatab\fR(9S)), has reached a limit (\fB255\fR). See +\fBdupb\fR(9F). +.SH CONTEXT +.sp +.LP +\fBdupmsg()\fR can be called from user, kernel, or interrupt context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBdupmsg()\fR +.sp +.LP +See \fBcopyb\fR(9F) for an example using \fBdupmsg()\fR. + +.SH SEE ALSO +.sp +.LP +\fBcopyb\fR(9F), \fBcopymsg\fR(9F), \fBdupb\fR(9F), \fBdatab\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/enableok.9f b/usr/src/man/man9f/enableok.9f new file mode 100644 index 0000000000..b2e6f3d508 --- /dev/null +++ b/usr/src/man/man9f/enableok.9f @@ -0,0 +1,81 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH enableok 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +enableok \- reschedule a queue for service +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBenableok\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 5n +.rt +A pointer to the queue to be rescheduled. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBenableok()\fR function enables queue \fIq\fR to be rescheduled for +service. It reverses the effect of a previous call to \fBnoenable\fR(9F) on +\fIq\fR by turning off the \fBQNOENB\fR flag in the queue. +.SH CONTEXT +.sp +.LP +The \fBenableok()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBemableok()\fR +.sp +.LP +The \fBqrestart()\fR routine uses two STREAMS functions to restart a queue that +has been disabled. The \fBenableok()\fR function turns off the \fBQNOENB\fR +flag, allowing the \fBqenable\fR(9F) to schedule the queue for immediate +processing. + +.sp +.in +2 +.nf +1 void +2 qrestart(rdwr_q) +3 register queue_t *rdwr_q; +4 { +5 enableok(rdwr_q); +6 /* re-enable a queue that has been disabled */ +7 (void) qenable(rdwr_q); +8 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBnoenable\fR(9F), \fBqenable\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/esballoc.9f b/usr/src/man/man9f/esballoc.9f new file mode 100644 index 0000000000..f12a1c3813 --- /dev/null +++ b/usr/src/man/man9f/esballoc.9f @@ -0,0 +1,167 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH esballoc 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +esballoc, desballoc \- allocate a message block using a caller-supplied buffer +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBmblk_t *\fR\fBesballoc\fR(\fBuchar_t *\fR\fIbase\fR, \fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR, + \fBfrtn_t *\fR\fIfr_rtnp\fR); +.fi + +.LP +.nf +\fBmblk_t *\fR\fBdesballoc\fR(\fBuchar_t *\fR\fIbase\fR, \fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR, + \fBfrtn_t *\fR\fIfr_rtnp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +\fBesballoc()\fR: Architecture independent level 1 (DDI/DKI) +.sp +.LP +\fBdesballoc()\fR: Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbase\fR\fR +.ad +.RS 11n +.rt +Address of caller-supplied data buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 11n +.rt +Number of bytes in data buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpri\fR\fR +.ad +.RS 11n +.rt +Priority of the request (no longer used). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfr_rtnp\fR\fR +.ad +.RS 11n +.rt +Free routine data structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBesballoc()\fR and \fBdesballoc()\fR functions operate identically to +\fBallocb\fR(9F), except that the data buffer to associate with the message is +specified by the caller. The allocated message will have both the \fBb_wptr\fR +and \fBb_rptr\fR set to the supplied data buffer starting at \fIbase\fR. Only +the buffer itself can be specified by the caller. The message block and data +block header are allocated as if by \fBallocb\fR(9F). +.sp +.LP +When \fBfreeb\fR(9F) is called to free the message, the driver's +message-freeing routine, referenced through the \fBfree_rtn\fR(9S) structure, +is called with appropriate arguments to free the data buffer. +.sp +.LP +The \fBfree_rtn\fR(9S) structure includes the following members: +.sp +.in +2 +.nf +void (*free_func)(); /* caller's freeing routine */ +caddr_t free_arg; /* argument to free_func() */ +.fi +.in -2 + +.sp +.LP +Instead of requiring a specific number of arguments, the \fBfree_arg\fR field +is defined of type \fBcaddr_t\fR. This way, the driver can pass a pointer to a +structure if more than one argument is needed. +.sp +.LP +If \fBesballoc()\fR was used, then \fBfree_func\fR will be called +asynchronously at some point after the message is no longer referenced. If +\fBdesballoc()\fR was used, then \fBfree_func\fR will be called synchronously +by the thread releasing the final reference. See \fBfreeb\fR(9F). +.sp +.LP +The \fBfree_func\fR routine must not sleep, and must not access any dynamically +allocated data structures that could be freed before or during its execution. +In addition, because messages allocated with \fBdesballoc()\fR are freed in the +context of the caller, \fBfree_func\fR must not call another module's \fBput\fR +procedure, or attempt to acquire a private module lock which might be held by +another thread across a call to a STREAMS utility routine that could free a +message block. Finally, \fBfree_func\fR routines specified using +\fBdesballoc\fR may run in interrupt context and thus must only use +synchronization primitives that include an interrupt priority returned from +\fBddi_intr_get_pri\fR(9F) or \fBddi_intr_get_softint_pri\fR(9F). If any of +these restrictions are not followed, the possibility of lock recursion or +deadlock exists. +.SH RETURN VALUES +.sp +.LP +On success, a pointer to the newly allocated message block is returned. On +failure, \fBNULL\fR is returned. +.SH CONTEXT +.sp +.LP +The \fBesballoc()\fR and \fBdesballoc()\fR functions can be called from user, +interrupt, or kernel context. +.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 +\fBallocb\fR(9F), \fBddi_intr_get_pri\fR(9F), +\fBddi_intr_get_softint_pri\fR(9F), \fBfreeb\fR(9F), \fBdatab\fR(9S), +\fBfree_rtn\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/esbbcall.9f b/usr/src/man/man9f/esbbcall.9f new file mode 100644 index 0000000000..4251af1e22 --- /dev/null +++ b/usr/src/man/man9f/esbbcall.9f @@ -0,0 +1,89 @@ +'\" te +.\" Copyright 1989 AT&T Copyright (c) 2006, +.\" 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 esbbcall 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +esbbcall \- call function when buffer is available +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBbufcall_id_t\fR \fBesbbcall\fR(\fBuint_t\fR \fIpri\fR, \fBvoid\fR (\fI*func\fR)(\fIvoid *arg\fR), + \fBvoid\fR(\fIarg\fR)); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpri\fR\fR +.ad +.RS 8n +.rt +Priority of allocation request (to be used by \fBallocb\fR(9F) function, called +by \fBesbbcall()\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfunc\fR\fR +.ad +.RS 8n +.rt +Function to be called when buffer becomes available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 8n +.rt +Argument to \fIfunc\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBesbbcall()\fR function, like \fBbufcall\fR(9F), serves as a +\fBtimeout\fR(9F) call of indeterminate length. If \fBesballoc\fR(9F) is unable +to allocate a message and data block header to go with its externally supplied +data buffer, \fBesbbcall()\fR can be used to schedule the routine \fIfunc\fR, +to be called with the argument \fIarg\fR when a buffer becomes available. The +\fIfunc\fR argument can be a routine that calls \fBesballoc\fR(9F) or it may be +another kernel function. +.SH RETURN VALUES +.sp +.LP +On success, a \fBbufcall\fR \fBID\fRis returned. On failure, \fB0\fR is +returned. The value returned from a successful call should be saved for +possible future use with \fBunbufcall()\fR should it become necessary to cancel +the \fBesbbcall()\fR request (as at driver close time). +.SH CONTEXT +.sp +.LP +The \fBesbbcall()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBallocb\fR(9F), \fBbufcall\fR(9F), \fBesballoc\fR(9F), \fBtimeout\fR(9F), +\fBdatab\fR(9S), \fBunbufcall\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR \fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/flushband.9f b/usr/src/man/man9f/flushband.9f new file mode 100644 index 0000000000..84c1b37f77 --- /dev/null +++ b/usr/src/man/man9f/flushband.9f @@ -0,0 +1,99 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH flushband 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +flushband \- flush messages for a specified priority band +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBvoid\fR \fBflushband\fR(\fBqueue_t\fR \fI*q\fR, \fBunsigned char\fR \fIpri\fR, \fBint\fR \fIflag\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 8n +.rt +Pointer to the queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpri\fR\fR +.ad +.RS 8n +.rt +Priority of messages to be flushed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 8n +.rt +Valid \fIflag\fR values are: +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFLUSHDATA\fR\fR +.ad +.RS 13n +.rt +Flush only data messages (types \fBM_DATA,\fR \fBM_DELAY,\fR \fBM_PROTO,\fR and +\fBM_PCPROTO\fR \fB\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFLUSHALL\fR\fR +.ad +.RS 13n +.rt +Flush all messages. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBflushband()\fR function flushes messages associated with the priority +band specified by \fIpri\fR. If \fIpri\fR is \fB0\fR, only normal and high +priority messages are flushed. Otherwise, messages are flushed from the band +\fIpri\fR according to the value of \fIflag\fR. +.SH CONTEXT +.sp +.LP +The \fBflushband()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBflushq\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR \fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/flushq.9f b/usr/src/man/man9f/flushq.9f new file mode 100644 index 0000000000..021a1c44f6 --- /dev/null +++ b/usr/src/man/man9f/flushq.9f @@ -0,0 +1,126 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH flushq 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +flushq \- remove messages from a queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBvoid\fR \fBflushq\fR(\fBqueue_t *\fR\fIq\fR, \fBint\fR \fIflag\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 8n +.rt +Pointer to the queue to be flushed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 8n +.rt +Valid \fIflag\fR values are: +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFLUSHDATA\fR\fR +.ad +.RS 13n +.rt +Flush only data messages (types \fBM_DATA\fR \fBM_DELAY\fR \fBM_PROTO\fR and +\fBM_PCPROTO\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBFLUSHALL\fR\fR +.ad +.RS 13n +.rt +Flush all messages. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBflushq()\fR function frees messages and their associated data structures +by calling \fBfreemsg\fR(9F). If the queue's count falls below the low water +mark and the queue was blocking an upstream service procedure, the nearest +upstream service procedure is enabled. +.SH CONTEXT +.sp +.LP +The \fBflushq()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBflushq()\fR +.sp +.LP +This example depicts the canonical flushing code for STREAMS modules. The +module has a write service procedure and potentially has messages on the queue. +If it receives an \fBM_FLUSH\fR message, and if the \fBFLUSHR\fR bit is on in +the first byte of the message (line 10), then the read queue is flushed (line +11). If the \fBFLUSHW\fR bit is on (line 12), then the write queue is flushed +(line 13). Then the message is passed along to the next entity in the stream +(line 14). See the example for \fBqreply\fR(9F) for the canonical flushing code +for drivers. + +.sp +.in +2 +.nf + 1 /* + 2 * Module write-side put procedure. + 3 */ + 4 xxxwput(q, mp) + 5 queue_t *q; + 6 mblk_t *mp; + 7 { + 8 switch(mp->b_datap->db_type) { + 9 case M_FLUSH: + 10 if (*mp->b_rptr & FLUSHR) + 11 flushq(RD(q), FLUSHALL); + 12 if (*mp->b_rptr & FLUSHW) + 13 flushq(q, FLUSHALL); + 14 putnext(q, mp); + 15 break; + . . . + 16 } + 17 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBflushband\fR(9F), \fBfreemsg\fR(9F), \fBputq\fR(9F), \fBqreply\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR \fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/freeb.9f b/usr/src/man/man9f/freeb.9f new file mode 100644 index 0000000000..7e5c052bbe --- /dev/null +++ b/usr/src/man/man9f/freeb.9f @@ -0,0 +1,76 @@ +'\" te +.\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH freeb 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +freeb \- free a message block +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBvoid\fR \fBfreeb\fR(\fBmblk_t *\fR\fIbp\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +Pointer to the message block to be deallocated. \fBmblk_t\fR is an instance of +the \fBmsgb\fR(9S) structure. +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH DESCRIPTION +.sp +.LP +The \fBfreeb()\fR function deallocates a message block. If the reference count +of the \fBdb_ref\fR member of the \fBdatab\fR(9S) structure is greater than +\fB1\fR, \fBfreeb()\fR decrements the count. If \fBdb_ref\fR equals \fB1\fR, it +deallocates the message block and the corresponding data block and buffer. +.sp +.LP +If the data buffer to be freed was allocated with the \fBesballoc\fR(9F), the +buffer may be a non-STREAMS resource. In that case, the driver must be notified +that the attached data buffer needs to be freed, and run its own freeing +routine. To make this process independent of the driver used in the stream, +\fBfreeb()\fR finds the \fBfree_rtn\fR(9S) structure associated with the +buffer. The \fBfree_rtn\fR structure contains a pointer to the driver-dependent +routine, which releases the buffer. Once this is accomplished, \fBfreeb()\fR +releases the \fBSTREAMS\fR resources associated with the buffer. +.SH CONTEXT +.sp +.LP +The \fBfreeb()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBfreeb()\fR +.sp +.LP +See \fBcopyb\fR(9F) for an example of using \fBfreeb()\fR. + +.SH SEE ALSO +.sp +.LP +\fBallocb\fR(9F), \fBcopyb\fR(9F), \fBdupb\fR(9F), \fBesballoc\fR(9F), +\fBfree_rtn\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/freemsg.9f b/usr/src/man/man9f/freemsg.9f new file mode 100644 index 0000000000..28ed64ff70 --- /dev/null +++ b/usr/src/man/man9f/freemsg.9f @@ -0,0 +1,69 @@ +'\" te +.\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH freemsg 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +freemsg \- free all message blocks in a message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBvoid\fR \fBfreemsg\fR(\fBmblk_t *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 6n +.rt +Pointer to the message blocks to be deallocated. \fBmblk_t\fR is an instance of +the \fBmsgb\fR(9S) structure. If \fImp\fR is \fINULL\fR, \fBfreemsg()\fR +immediately returns. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBfreemsg()\fR function calls \fBfreeb\fR(9F) to free all message and data +blocks associated with the message pointed to by \fImp\fR. +.SH CONTEXT +.sp +.LP +The \fBfreemsg()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBfreemsg()\fR +.sp +.LP +See \fBcopymsg\fR(9F). + +.SH SEE ALSO +.sp +.LP +\fBcopymsg\fR(9F), \fBfreeb\fR(9F), \fBmsgb\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH NOTES +.sp +.LP +The behavior of \fBfreemsg()\fR when passed a \fINULL\fR pointer is +Solaris-specific. diff --git a/usr/src/man/man9f/freerbuf.9f b/usr/src/man/man9f/freerbuf.9f new file mode 100644 index 0000000000..d11008b736 --- /dev/null +++ b/usr/src/man/man9f/freerbuf.9f @@ -0,0 +1,52 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH freerbuf 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +freerbuf \- free a raw buffer header +.SH SYNOPSIS +.LP +.nf +#include <sys/buf.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBfreerbuf\fR(\fBstruct buf *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +Pointer to a previously allocated buffer header structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBfreerbuf()\fR function frees a raw buffer header previously allocated by +\fBgetrbuf\fR(9F). This function does not sleep and so may be called from an +interrupt routine. +.SH CONTEXT +.sp +.LP +The \fBfreerbuf()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBgetrbuf\fR(9F), \fBkmem_alloc\fR(9F), \fBkmem_free\fR(9F), +\fBkmem_zalloc\fR(9F) diff --git a/usr/src/man/man9f/freezestr.9f b/usr/src/man/man9f/freezestr.9f new file mode 100644 index 0000000000..30b295895b --- /dev/null +++ b/usr/src/man/man9f/freezestr.9f @@ -0,0 +1,88 @@ +'\" te +.\" Copyright (c) 2001, 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 freezestr 9F "17 Oct 2000" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +freezestr, unfreezestr \- freeze, thaw the state of a stream +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBfreezestr\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBunfreezestr\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR \fR +.ad +.RS 6n +.rt +Pointer to the message queue to freeze/unfreeze. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBfreezestr()\fR freezes the state of the entire stream containing the queue +pair \fIq\fR. A frozen stream blocks any thread attempting to enter any open, +close, put or service routine belonging to any queue instance in the stream, +and blocks any thread currently within the stream if it attempts to put +messages onto or take messages off of any queue within the stream (with the +sole exception of the caller). Threads blocked by this mechanism remain so +until the stream is thawed by a call to \fBunfreezestr()\fR. +.sp +.LP +Drivers and modules must freeze the stream before manipulating the queues +directly (as opposed to manipulating them through programmatic interfaces such +as \fBgetq\fR(9F), \fBputq\fR(9F), \fBputbq\fR(9F), etc.) +.SH CONTEXT +.sp +.LP +These routines may be called from any stream open, close, put or service +routine as well as interrupt handlers, callouts and call-backs. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH NOTES +.sp +.LP +The \fBfreezestr()\fR and \fBunfreezestr()\fR functions can have a serious +impact on system performance. Their use should be very limited. In most cases, +there is no need to use \fBfreezestr()\fR and there are usually better ways to +accomplish what you need to do than by freezing the stream. +.sp +.LP +Calling \fBfreezestr()\fR to freeze a stream that is already frozen by the +caller will result in a single-party deadlock. +.sp +.LP +The caller of \fBunfreezestr()\fR must be the thread who called +\fBfreezestr()\fR. +.sp +.LP +STREAMS utility functions such as \fBgetq\fR(9F), \fBputq\fR(9F), +\fBputbq\fR(9F), and so forth, should not be called by the caller of +\fBfreezestr()\fR while the stream is still frozen, as they indirectly freeze +the stream to ensure atomicity of queue manipulation. diff --git a/usr/src/man/man9f/get_pktiopb.9f b/usr/src/man/man9f/get_pktiopb.9f new file mode 100644 index 0000000000..d65ed84283 --- /dev/null +++ b/usr/src/man/man9f/get_pktiopb.9f @@ -0,0 +1,228 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH get_pktiopb 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +get_pktiopb, free_pktiopb \- allocate/free a SCSI packet in the iopb map +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBstruct scsi_pkt *\fR\fBget_pktiopb\fR(\fBstruct scsi_address *\fR\fIap\fR, + \fBcaddr_t *\fR\fIdatap\fR, \fBint\fR \fIcdblen\fR, \fBint\fR \fIstatuslen\fR, \fBint\fR \fIdatalen\fR, + \fBint\fR \fIreadflag\fR, \fBint (*\fR\fIcallback\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBfree_pktiopb\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR, \fBcaddr_t\fR \fIdatap\fR, \fBint\fR \fIdatalen\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +These interfaces are obsolete. Use \fBscsi_alloc_consistent_buf\fR(9F) instead +of \fBget_pktiopb()\fR. Use \fBscsi_free_consistent_buf\fR(9F) instead of +\fBfree_pktiopb()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR\fR +.ad +.RS 13n +.rt +Pointer to the target's \fBscsi_address\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdatap\fR\fR +.ad +.RS 13n +.rt +Pointer to the address of the packet, set by this function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcdblen\fR\fR +.ad +.RS 13n +.rt +Number of bytes required for the \fBSCSI \fRcommand descriptor block (CDB). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstatuslen\fR\fR +.ad +.RS 13n +.rt +Number of bytes required for the \fBSCSI \fRstatus area. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdatalen\fR\fR +.ad +.RS 13n +.rt +Number of bytes required for the data area of the \fBSCSI \fRcommand. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreadflag\fR\fR +.ad +.RS 13n +.rt +If non-zero, data will be transferred from the \fBSCSI \fRtarget. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 13n +.rt +Pointer to a callback function, or \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR\fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBget_pktiopb()\fR function allocates a \fBscsi_pkt\fR structure that has +a small data area allocated. It is used by some \fBSCSI \fRcommands such as +\fBREQUEST_SENSE\fR, which involve a small amount of data and require +cache-consistent memory for proper operation. It uses \fBddi_iopb_alloc\fR(9F) +for allocating the data area and \fBscsi_resalloc\fR(9F) to allocate the packet +and \fBDMA\fR resources. +.sp +.LP +\fIcallback\fR indicates what \fBget_pktiopb()\fR should do when resources are +not available: +.sp +.ne 2 +.mk +.na +\fB\fBNULL_FUNC\fR\fR +.ad +.RS 16n +.rt +Do not wait for resources. Return a \fINULL\fR pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSLEEP_FUNC\fR\fR +.ad +.RS 16n +.rt +Wait indefinitely for resources. +.RE + +.sp +.ne 2 +.mk +.na +\fBOther Values\fR +.ad +.RS 16n +.rt +\fIcallback\fR points to a function which is called when resources may have +become available. \fIcallback\fR \fBmust\fR return either \fB0\fR (indicating +that it attempted to allocate resources but failed to do so again), in which +case it is put back on a list to be called again later, or \fB1\fR indicating +either success in allocating resources or indicating that it no longer cares +for a retry. +.RE + +.sp +.LP +The \fBfree_pktiopb()\fR function is used for freeing the packet and its +associated resources. +.SH RETURN VALUES +.sp +.LP +The \fBget_pktiopb()\fR function returns a pointer to the newly allocated +\fBscsi_pkt\fR or a \fINULL\fR pointer. +.SH CONTEXT +.sp +.LP +If \fIcallback\fR is \fBSLEEP_FUNC\fR, then this routine can be called only +from user or kernel context. Otherwise, it can be called from user, interrupt, +or kernel context. The \fIcallback\fR function should not block or call +routines that block. +.sp +.LP +The \fBfree_pktiopb()\fR function can be called from user, interrupt, or kernel +context. +.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 +\fBattributes\fR(5), \fBddi_iopb_alloc\fR(9F), +\fBscsi_alloc_consistent_buf\fR(9F), \fBscsi_free_consistent_buf\fR(9F), +\fBscsi_pktalloc\fR(9F), \fBscsi_resalloc\fR(9F), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The \fBget_pktiopb()\fR and \fBfree_pktiopb()\fR functions are obsolete and +will be discontinued in a future release. These functions have been replaced +by, respectively, \fBscsi_alloc_consistent_buf\fR(9F) and +\fBscsi_free_consistent_buf\fR(9F). +.sp +.LP +The \fBget_pktiopb()\fR function uses scarce resources. For this reason and its +obsolescence (see above), its use is discouraged. diff --git a/usr/src/man/man9f/geterror.9f b/usr/src/man/man9f/geterror.9f new file mode 100644 index 0000000000..fc9eeb6bf4 --- /dev/null +++ b/usr/src/man/man9f/geterror.9f @@ -0,0 +1,59 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH geterror 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +geterror \- return \fBI/O\fR error +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/buf.h> +#include <sys/ddi.h> + + + +\fBint\fR \fBgeterror\fR(\fBstruct buf *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBbuf\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBgeterror()\fR function returns the error number from the error field of +the buffer header structure. +.SH RETURN VALUES +.sp +.LP +An error number indicating the error condition of the \fBI/O\fR request is +returned. If the \fBI/O\fR request completes successfully, \fB0\fR is returned. +.SH CONTEXT +.sp +.LP +The \fBgeterror()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/gethrtime.9f b/usr/src/man/man9f/gethrtime.9f new file mode 100644 index 0000000000..e452396812 --- /dev/null +++ b/usr/src/man/man9f/gethrtime.9f @@ -0,0 +1,56 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH gethrtime 9F " 2 Oct 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +gethrtime \- get high resolution time +.SH SYNOPSIS +.LP +.nf +#include <sys/time.h> + + + +\fBhrtime_t\fR \fBgethrtime\fR(\fB\fR\fIvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBgethrtime()\fR function returns the current high-resolution real time. +Time is expressed as nanoseconds since some arbitrary time in the past; it is +not correlated in any way to the time of day, and thus is not subject to +resetting or drifting by way of \fBadjtime\fR(2) or \fBsettimeofday\fR(3C). The +hi-res timer is ideally suited to performance measurement tasks, where cheap, +accurate interval timing is required. +.SH RETURN VALUES +.sp +.LP +\fBgethrtime()\fR always returns the current high-resolution real time. There +are no error conditions. +.SH CONTEXT +.sp +.LP +There are no restrictions on the context from which \fBgethrtime()\fR can be +called. +.SH SEE ALSO +.sp +.LP +\fBproc\fR(1), \fBgettimeofday\fR(3C), \fBsettimeofday\fR(3C), +\fBattributes\fR(5) +.SH NOTES +.sp +.LP +Although the units of hi-res time are always the same (nanoseconds), the actual +resolution is hardware dependent. Hi-res time is guaranteed to be monotonic (it +does not go backward, it does not periodically wrap) and linear (it does not +occasionally speed up or slow down for adjustment, as the time of day can), but +not necessarily unique: two sufficiently proximate calls might return the same +value. +.sp +.LP +The time base used for this function is the same as that for +\fBgethrtime\fR(3C). Values returned by both of these functions can be +interleaved for comparison purposes. diff --git a/usr/src/man/man9f/getmajor.9f b/usr/src/man/man9f/getmajor.9f new file mode 100644 index 0000000000..ad24241026 --- /dev/null +++ b/usr/src/man/man9f/getmajor.9f @@ -0,0 +1,83 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getmajor 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +getmajor \- get major device number +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/mkdev.h> +#include <sys/ddi.h> + + + +\fBmajor_t\fR \fBgetmajor\fR(\fBdev_t\fR \fIdev\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 7n +.rt +Device number. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBgetmajor()\fR function extracts the major number from a device number. +.SH RETURN VALUES +.sp +.LP +The major number. +.SH CONTEXT +.sp +.LP +The \fBgetmajor()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBgetmajor()\fR +.sp +.LP +The following example shows both the \fBgetmajor()\fR and \fBgetminor\fR(9F) +functions used in a debug \fBcmn_err\fR(9F) statement to return the major and +minor numbers for the device supported by the driver. + +.sp +.in +2 +.nf +dev_t dev; + +#ifdef DEBUG +cmn_err(CE_NOTE,"Driver Started. Major# = %d, + Minor# = %d", getmajor(dev), getminor(dev)); +#endif +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBcmn_err\fR(9F), \fBgetminor\fR(9F), \fBmakedevice\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +No validity checking is performed. If \fIdev\fR is invalid, an invalid number +is returned. diff --git a/usr/src/man/man9f/getminor.9f b/usr/src/man/man9f/getminor.9f new file mode 100644 index 0000000000..f8c2db85b6 --- /dev/null +++ b/usr/src/man/man9f/getminor.9f @@ -0,0 +1,67 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getminor 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +getminor \- get minor device number +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/mkdev.h> +#include <sys/ddi.h> + + + +\fBminor_t\fR \fBgetminor\fR(\fBdev_t\fR \fIdev\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 7n +.rt +Device number. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBgetminor()\fR function extracts the minor number from a device number. +.SH RETURN VALUES +.sp +.LP +The minor number. +.SH CONTEXT +.sp +.LP +The \fBgetminor()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +See the \fBgetmajor\fR(9F) manual page for an example of how to use +\fBgetminor()\fR. +.SH SEE ALSO +.sp +.LP +\fBgetmajor\fR(9F), \fBmakedevice\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +No validity checking is performed. If \fIdev\fR is invalid, an invalid number +is returned. diff --git a/usr/src/man/man9f/getq.9f b/usr/src/man/man9f/getq.9f new file mode 100644 index 0000000000..2bba39cd89 --- /dev/null +++ b/usr/src/man/man9f/getq.9f @@ -0,0 +1,78 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getq 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +getq \- get the next message from a queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBmblk_t *\fR\fBgetq\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 5n +.rt +Pointer to the queue from which the message is to be retrieved. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBgetq()\fR function is used by a service ( \fBsrv\fR(9E)) routine to +retrieve its enqueued messages. +.sp +.LP +A module or driver may include a service routine to process enqueued messages. +Once the \fBSTREAMS \fRscheduler calls \fBsrv()\fR it must process all enqueued +messages, unless prevented by flow control. \fBgetq()\fR obtains the next +available message from the top of the queue pointed to by \fIq\fR. It should be +called in a \fBwhile\fR loop that is exited only when there are no more +messages or flow control prevents further processing. +.sp +.LP +If an attempt was made to write to the queue while it was blocked by flow +control, \fBgetq()\fR back-enables (restarts) the service routine once it falls +below the low water mark. +.SH RETURN VALUES +.sp +.LP +If there is a message to retrieve, \fBgetq()\fR returns a pointer to it. If no +message is queued, \fBgetq()\fR returns a \fBNULL\fR pointer. +.SH CONTEXT +.sp +.LP +The \fBgetq()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +See \fBdupb\fR(9F). +.SH SEE ALSO +.sp +.LP +\fBsrv\fR(9E), \fBbcanput\fR(9F), \fBcanput\fR(9F), \fBdupb\fR(9F), +\fBputbq\fR(9F), \fBputq\fR(9F), \fBqenable\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/getrbuf.9f b/usr/src/man/man9f/getrbuf.9f new file mode 100644 index 0000000000..08d85246e9 --- /dev/null +++ b/usr/src/man/man9f/getrbuf.9f @@ -0,0 +1,72 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH getrbuf 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +getrbuf \- get a raw buffer header +.SH SYNOPSIS +.LP +.nf +#include <sys/buf.h> +#include <sys/kmem.h> +#include <sys/ddi.h> + + + +\fBstruct buf *\fR\fBgetrbuf\fR(\fBint\fR \fIsleepflag\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsleepflag\fR\fR +.ad +.RS 13n +.rt +Indicates whether driver should sleep for free space. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBgetrbuf()\fR function allocates the space for a buffer header to the +caller. It is used in cases where a block driver is performing raw (character +interface) I/O and needs to set up a buffer header that is not associated with +the buffer cache. +.sp +.LP +The \fBgetrbuf()\fR function calls \fBkmem_alloc\fR(9F) to perform the memory +allocation. \fBkmem_alloc()\fRrequires the information included in the +\fIsleepflag\fR argument. If \fIsleepflag\fR is set to \fBKM_SLEEP\fR, the +driver may sleep until the space is freed up. If \fIsleepflag\fR is set to +\fBKM_NOSLEEP\fR, the driver will not sleep. In either case, a pointer to the +allocated space is returned or \fBNULL\fR to indicate that no space was +available. +.SH RETURN VALUES +.sp +.LP +The \fBgetrbuf()\fR function returns a pointer to the allocated buffer header, +or \fBNULL\fR if no space is available. +.SH CONTEXT +.sp +.LP +The \fBgetrbuf()\fR function can be called from user, interrupt, or kernel +context. (Drivers must not allow \fBgetrbuf()\fR to sleep if called from an +interrupt routine.) +.SH SEE ALSO +.sp +.LP +\fBbioinit\fR(9F), \fBfreerbuf\fR(9F), \fBkmem_alloc\fR(9F), +\fBkmem_free\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/gld.9f b/usr/src/man/man9f/gld.9f new file mode 100644 index 0000000000..3023269eca --- /dev/null +++ b/usr/src/man/man9f/gld.9f @@ -0,0 +1,324 @@ +'\" 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 gld 9F "28 Aug 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +gld, gld_mac_alloc, gld_mac_free, gld_register, gld_unregister, gld_recv, +gld_sched, gld_intr \- Generic LAN Driver service routines +.SH SYNOPSIS +.LP +.nf +#include <sys/gld.h> + +\fBgld_mac_info_t *\fR\fBgld_mac_alloc\fR(\fBdev_info_t *\fR\fIdip\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBgld_mac_free\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR); +.fi + +.LP +.nf +\fBint\fR \fBgld_register\fR(\fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR, \fBgld_mac_info_t *\fR\fImacinfo\fR); +.fi + +.LP +.nf +\fBint\fR \fBgld_unregister\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBgld_recv\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR, \fBmblk_t *\fR\fImp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBgld_sched\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBgld_intr\fR(\fBcaddr_t);\fR +.fi + +.LP +.nf +\fBvoid\fR \fBgld_linkstate\fR(\fBgld_mac_info_t *\fR\fImacinfo\fR, \fBint32_t\fR \fInewstate\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 13n +.rt +Pointer to a \fBgld_mac_info\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR \fR +.ad +.RS 13n +.rt +Pointer to \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR \fR +.ad +.RS 13n +.rt +Device interface name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR \fR +.ad +.RS 13n +.rt +Pointer to a message block containing a received packet. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInewstate\fR \fR +.ad +.RS 13n +.rt +Media link state. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBgld_mac_alloc\fR(\|) allocates a new \fBgld_mac_info\fR(9S) structure and +returns a pointer to it. Some of the GLD-private elements of the structure may +be initialized before \fBgld_mac_alloc\fR(\|) returns; all other elements are +initialized to zero. The device driver must initialize some structure members, +as described in \fBgld_mac_info\fR(9S), before passing the mac_info pointer to +\fBgld_register\fR(\|). +.sp +.LP +\fBgld_mac_free\fR(\|) frees a \fBgld_mac_info\fR(9S) structure previously +allocated by \fBgld_mac_alloc\fR(\|). +.sp +.LP +\fBgld_register\fR(\|) is called from the device driver's \fBattach\fR(9E) +routine, and is used to link the GLD-based device driver with the GLD +framework. Before calling \fBgld_register\fR(\|) the device driver's +\fBattach\fR(9E) routine must first use \fBgld_mac_alloc\fR(\|) to allocate a +\fBgld_mac_info\fR(9S) structure, and initialize several of its structure +elements. See \fBgld_mac_info\fR(9S) for more information. A successful call to +\fBgld_register\fR(\|) performs the following actions: +.RS +4 +.TP +.ie t \(bu +.el o +links the device-specific driver with the GLD system; +.RE +.RS +4 +.TP +.ie t \(bu +.el o +sets the device-specific driver's private data pointer (using +\fBddi_set_driver_private\fR(9F)) to point to the \fBmacinfo\fR structure; +.RE +.RS +4 +.TP +.ie t \(bu +.el o +creates the minor device node. +.RE +.sp +.LP +The device interface name passed to \fBgld_register\fR(\|) must exactly match +the name of the driver module as it exists in the filesystem. +.sp +.LP +The driver's \fBattach\fR(9E) routine should return \fBDDI_SUCCESS\fR if +\fBgld_register\fR(\|) succeeds. If \fBgld_register\fR(\|) returns +\fBDDI_FAILURE\fR, the \fBattach\fR(9E) routine should deallocate any resources +it allocated before calling \fBgld_register\fR(\|) and then also return +\fBDDI_FAILURE\fR. +.sp +.LP +\fBgld_unregister\fR(\|) is called by the device driver's \fBdetach\fR(9E) +function, and if successful, performs the following tasks: +.RS +4 +.TP +.ie t \(bu +.el o +ensures the device's interrupts are stopped, calling the driver's +\fBgldm_stop\fR(\|) routine if necessary; +.RE +.RS +4 +.TP +.ie t \(bu +.el o +removes the minor device node; +.RE +.RS +4 +.TP +.ie t \(bu +.el o +unlinks the device-specific driver from the GLD system. +.RE +.sp +.LP +If \fBgld_unregister\fR(\|) returns \fBDDI_SUCCESS\fR, the \fBdetach\fR(9E) +routine should deallocate any data structures allocated in the \fBattach\fR(9E) +routine, using \fBgld_mac_free\fR(\|) to deallocate the \fBmacinfo\fR +structure, and return \fBDDI_SUCCESS\fR. If \fBgld_unregister\fR(\|) returns +\fBDDI_FAILURE\fR, the driver's \fBdetach\fR(9E) routine must leave the device +operational and return \fBDDI_FAILURE\fR. +.sp +.LP +\fBgld_recv\fR(\|) is called by the driver's interrupt handler to pass a +received packet upstream. The driver must construct and pass a STREAMS +\fBM_DATA\fR message containing the raw packet. \fBgld_recv\fR(\|) determines +which STREAMS queues, if any, should receive a copy of the packet, duplicating +it if necessary. It then formats a \fBDL_UNITDATA_IND\fR message, if required, +and passes the data up all appropriate streams. +.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 +\fBgld_sched\fR(\|) is called by the device driver to reschedule stalled +outbound packets. Whenever the driver's \fBgldm_send\fR(\|) routine has +returned \fBGLD_NORESOURCES\fR, the driver must later call \fBgld_sched\fR(\|) +to inform the GLD framework that it should retry the packets that previously +could not be sent. \fBgld_sched\fR(\|) should be called as soon as possible +after resources are again available, to ensure that GLD resumes passing +outbound packets to the driver's \fBgldm_send\fR(\|) routine in a timely way. +(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 +\fBgld_intr\fR(\|) is GLD's main interrupt handler. Normally it is specified as +the interrupt routine in the device driver's call to \fBddi_add_intr\fR(9F). +The argument to the interrupt handler (specified as \fIint_handler_arg\fR in +the call to \fBddi_add_intr\fR(9F)) must be a pointer to the +\fBgld_mac_info\fR(9S) structure. \fBgld_intr\fR(\|) will, when appropriate, +call the device driver's \fBgldm_intr\fR(\|) function, passing that pointer to +the \fBgld_mac_info\fR(9S) structure. However, if the driver uses a high-level +interrupt, it must provide its own high-level interrupt handler, and trigger a +soft interrupt from within that. In this case, \fBgld_intr\fR(\|) may be +specified as the soft interrupt handler in the call to +\fBddi_add_softintr\fR(\|). +.sp +.LP +\fBgld_linkstate()\fR is called by the device driver to notify GLD of changes +in the media link state. The newstate argument should be set to one of the +following: +.sp +.ne 2 +.mk +.na +\fB\fBGLD_LINKSTATE_DOWN\fR \fR +.ad +.RS 26n +.rt +The media link is unavailable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLD_LINKSTATE_UP\fR \fR +.ad +.RS 26n +.rt +The media link is unavailable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBGLD_LINKSTATE_UNKNOWN\fR \fR +.ad +.RS 26n +.rt +The status of the media link is unknown. +.RE + +.sp +.LP +If a driver calls \fBgld_linkstate()\fR, it must also set the GLD_CAP_LINKSTATE +bit in the gldm_capabilties field of the \fBgld_mac_info\fR(9S) structure. +.SH RETURN VALUES +.sp +.LP +\fBgld_mac_alloc\fR(\|) returns a pointer to a new \fBgld_mac_info\fR(9S) +structure. +.sp +.LP +\fBgld_register\fR(\|) and \fBgld_unregister\fR(\|) return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR \fR +.ad +.RS 16n +.rt +on success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR \fR +.ad +.RS 16n +.rt +on failure. +.RE + +.sp +.LP +\fBgld_intr\fR(\|) returns a value appropriate for an interrupt handler. +.SH SEE ALSO +.sp +.LP +\fBgld\fR(7D), \fBgld\fR(9E), \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/man9f/hook_alloc.9f b/usr/src/man/man9f/hook_alloc.9f new file mode 100644 index 0000000000..e410a16237 --- /dev/null +++ b/usr/src/man/man9f/hook_alloc.9f @@ -0,0 +1,68 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH hook_alloc 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +hook_alloc \- allocate a hook_t data structure +.SH SYNOPSIS +.LP +.nf +#include <sys/hook.h> + +\fBhook_t *\fR\fBhook_alloc\fR(\fBconst\fR \fBint\fR \fIversion\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIversion\fR\fR +.ad +.RS 11n +.rt +must always be the symbol \fBHOOK_VERSION\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBhook_alloc()\fR function allocates a \fBhook_t\fR structure, returning a +pointer for the caller to use. +.SH RETURN VALUES +.sp +.LP +Upon success, \fBhook_alloc()\fR returns a pointer to the allocated +\fIhook_t\fR structure. On failure, \fBhook_alloc()\fR returns a \fINULL\fR +pointer. +.SH CONTEXT +.sp +.LP +The \fBhook_alloc()\fR function may be called from user or kernel context. +.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 +\fBhook_free\fR(9F), \fBhook_t\fR(9S) diff --git a/usr/src/man/man9f/hook_free.9f b/usr/src/man/man9f/hook_free.9f new file mode 100644 index 0000000000..7c44b0654d --- /dev/null +++ b/usr/src/man/man9f/hook_free.9f @@ -0,0 +1,63 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH hook_free 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +hook_free \- free a hook_t data structure +.SH SYNOPSIS +.LP +.nf +#include <sys/hook.h> + +\fBvoid\fR \fBhook_free\fR(\fBhook_t *\fR \fIhook\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhook\fR\fR +.ad +.RS 8n +.rt +pointer returned by \fBhook_alloc\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBhook_free()\fR function frees a \fBhook_t\fR structure that was +originally allocated by \fBhook_alloc\fR(9F). +.SH CONTEXT +.sp +.LP +The \fBhook_free()\fR function may be called from user, kernel, or interrupt +context. +.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 +\fBhook_alloc\fR(9F), \fBhook_t\fR(9S) diff --git a/usr/src/man/man9f/id32_alloc.9f b/usr/src/man/man9f/id32_alloc.9f new file mode 100644 index 0000000000..0d58181fc6 --- /dev/null +++ b/usr/src/man/man9f/id32_alloc.9f @@ -0,0 +1,106 @@ +'\" 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 id32_alloc 9F "12 Dec 2001" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +id32_alloc, id32_free, id32_lookup \- 32-bit driver ID management routines +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/id32.h> + + + +\fBuint32_t\fR \fBid32_alloc\fR(\fBvoid *\fR\fIptr\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBid32_free\fR(\fBuint32_t\fR \fItoken\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBid32_lookup\fR(\fBuint32_t\fR \fItoken\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIptr\fR\fR +.ad +.RS 9n +.rt +any valid 32- or 64-bit pointer +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR \fR +.ad +.RS 9n +.rt +determines whether caller can sleep for memory (see \fBkmem_alloc\fR(9F) for a +description) +.RE + +.SH DESCRIPTION +.sp +.LP +These routines were originally developed so that device drivers could manage +64-bit pointers on devices that save space only for 32-bit pointers. +.sp +.LP +Many device drivers need to pass a 32-bit value to the hardware when attempting +I/O. Later, when that I/O completes, the only way the driver has to identify +the request that generated that I/O is via a "token". When the I/O is +initiated, the driver passes this token to the hardware. When the I/O completes +the hardware passes back this 32-bit token. +.sp +.LP +Before Solaris supported 64-bit pointers, device drivers just passed a raw +32-bit pointer to the hardware. When pointers grew to be 64 bits this was no +longer possible. The \fBid32_*()\fR routines were created to help drivers +translate between 64-bit pointers and a 32-bit token. +.sp +.LP +Given a 32- or 64-bit pointer, the routine \fBid32_alloc()\fR allocates a +32-bit token, returning 0 if \fBKM_NOSLEEP\fR was specified and memory could +not be allocated. The allocated token is passed back to \fBid32_lookup()\fR to +obtain the original 32- or 64-bit pointer. +.sp +.LP +The routine \fBid32_free()\fR is used to free an allocated token. Once +\fBid32_free()\fR is called, the supplied token is no longer valid. +.sp +.LP +Note that these routines have some degree of error checking. This is done so +that an invalid token passed to \fBid32_lookup()\fR will not be accepted as +valid. When \fBid32_lookup()\fR detects an invalid token it returns NULL. +Calling routines should check for this return value so that they do not try to +dereference a NULL pointer. +.SH CONTEXT +.sp +.LP +These functions can be called from user or interrupt context. The routine +\fBid32_alloc()\fR should not be called from interrupt context when the +\fBKM_SLEEP\fR flag is passed in. All other routines can be called from +interrupt or kernel context. +.SH SEE ALSO +.sp +.LP +\fBkmem_alloc\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/inb.9f b/usr/src/man/man9f/inb.9f new file mode 100644 index 0000000000..348a3a3e36 --- /dev/null +++ b/usr/src/man/man9f/inb.9f @@ -0,0 +1,141 @@ +'\" te +.\" Copyright (c) 2006, 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 inb 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +inb, inw, inl, repinsb, repinsw, repinsd \- read from an I/O port +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBunsigned char\fR \fBinb\fR(\fBint\fR \fIport\fR); +.fi + +.LP +.nf +\fBunsigned short\fR \fBinw\fR(\fBint\fR +\fIport\fR); +.fi + +.LP +.nf +\fBunsigned long\fR \fBinl\fR(\fBint\fR \fIport\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrepinsb\fR(\fBint\fR \fIport\fR, \fBunsigned char *\fR\fIaddr\fR, \fBint\fR +\fIcount\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrepinsw\fR(\fBint\fR \fIport\fR, \fBunsigned short *\fR\fIaddr\fR, \fBint\fR +\fIcount\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrepinsd\fR(\fBint\fR \fIport\fR, \fBunsigned long *\fR\fIaddr\fR, \fBint\fR +\fIcount\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +The functions described here are obsolete. For the \fBinb()\fR, \fBinw()\fR, +and \fBinl()\fR functions, use, respectively, \fBddi_get8\fR(9F), +\fBddi_get8\fR(9F), and \fBddi_get8\fR(9F) instead. For \fBrepinsb()\fR, +\fBrepinsw()\fR, and\fBrepinsl()\fR, use, respectively, \fBddi_rep_get8\fR(9F), +\fBddi_rep_get8\fR(9F), and \fBddi_rep_get8\fR(9F) instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIport\fR\fR +.ad +.RS 9n +.rt +A valid I/O port address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR\fR +.ad +.RS 9n +.rt +The address of a buffer where the values will be stored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcount\fR\fR +.ad +.RS 9n +.rt +The number of values to be read from the I/O port. +.RE + +.SH DESCRIPTION +.sp +.LP +These routines read data of various sizes from the I/O port with the address +specified by \fIport\fR. +.sp +.LP +The \fBinb()\fR, \fBinw()\fR, and \fBinl()\fR functions read 8 bits, 16 bits, +and 32 bits of data respectively, returning the resulting values. +.sp +.LP +The \fBrepinsb()\fR, \fBrepinsw()\fR, and \fBrepinsd()\fR functions read +multiple 8-bit, 16-bit, and 32-bit values, respectively. \fIcount\fR specifies +the number of values to be read. A pointer to a buffer will receive the input +data; the buffer must be long enough to hold count values of the requested +size. +.SH RETURN VALUES +.sp +.LP +The \fBinb()\fR, \fBinw()\fR, and \fBinl()\fR functions return the value that +was read from the I/O port. +.SH CONTEXT +.sp +.LP +These functions may be called from user, interrupt, or kernel context. +.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) +. +\fBATTRIBUTE TYPE\fR\fBATTRIBUTE VALUE\fR +_ +Architecturex86 +_ +Stability Level Obsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBisa\fR(4), \fBattributes\fR(5), \fBddi_get8\fR(9F), \fBddi_get8\fR(9F), +\fBddi_get8\fR(9F), \fBddi_rep_get8\fR(9F), \fBddi_rep_get8\fR(9F), +\fBddi_rep_get8\fR(9F), \fBoutb\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/insq.9f b/usr/src/man/man9f/insq.9f new file mode 100644 index 0000000000..cc40dae72e --- /dev/null +++ b/usr/src/man/man9f/insq.9f @@ -0,0 +1,147 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH insq 9F "23 Mar 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +insq \- insert a message into a queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBinsq\fR(\fBqueue_t *\fR\fIq\fR, \fBmblk_t *\fR\fIemp\fR, \fBmblk_t *\fR\fInmp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 7n +.rt +Pointer to the queue containing message \fIemp\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIemp\fR\fR +.ad +.RS 7n +.rt +Enqueued message before which the new message is to be inserted. \fBmblk_t\fR +is an instance of the \fBmsgb\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInmp\fR\fR +.ad +.RS 7n +.rt +Message to be inserted. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBinsq()\fR function inserts a message into a queue. The message to be +inserted, \fInmp\fR, is placed in \fIq\fR immediately before the message +\fIemp\fR. If \fIemp\fR is \fINULL\fR, the new message is placed at the end of +the queue. The queue class of the new message is ignored. All flow control +parameters are updated. The service procedure is enabled unless \fBQNOENB\fR is +set. +.SH RETURN VALUES +.sp +.LP +The \fBinsq()\fR function returns \fB1\fR on success, and \fB0\fR on failure. +.SH CONTEXT +.sp +.LP +The \fBinsq()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +This routine illustrates the steps a transport provider may take to place +expedited data ahead of normal data on a queue (assume all \fBM_DATA\fR +messages are converted into \fBM_PROTO T_DATA_REQ\fR messages). Normal +\fBT_DATA_REQ\fR messages are just placed on the end of the queue (line 16). +However, expedited \fBT_EXDATA_REQ\fR messages are inserted before any normal +messages already on the queue (line 25). If there are no normal messages on the +queue, \fBbp\fR will be \fINULL\fR and we fall out of the \fBfor\fR loop (line +21). \fBinsq\fR acts like \fBputq\fR(9F) in this case. +.sp +.in +2 +.nf + 1 #include <sys/stream.h> + 2 #include <sys/tihdr.h> + 3 + 4 static int + 5 xxxwput(queue_t *q, mblk_t *mp) + 6 { + 7 union T_primitives *tp; + 8 mblk_t *bp; + 9 union T_primitives *ntp; +10 +11 switch (mp->b_datap->db_type) { +12 case M_PROTO: +13 tp = (union T_primitives *)mp->b_rptr; +14 switch (tp->type) { +15 case T_DATA_REQ: +16 putq(q, mp); +17 break; +18 +19 case T_EXDATA_REQ: +20 /* Insert code here to protect queue and message block */ +21 for (bp = q->q_first; bp; bp = bp->b_next) { +22 if (bp->b_datap->db_type == M_PROTO) { +23 ntp = (union T_primitives *)bp->b_rptr; +24 if (ntp->type != T_EXDATA_REQ) +25 break; +26 } +27 } +28 (void)insq(q, bp, mp); +29 /* End of region that must be protected */ +30 break; + . . . +31 } +32 } +33 } +.fi +.in -2 + +.sp +.LP +When using \fBinsq()\fR, you must ensure that the queue and the message block +is not modified by another thread at the same time. You can achieve this either +by using STREAMS functions or by implementing your own locking. +.SH SEE ALSO +.sp +.LP +\fBputq\fR(9F), \fBrmvq\fR(9F), \fBmsgb\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH WARNINGS +.sp +.LP +If \fIemp\fR is non-\fINULL\fR, it must point to a message on \fIq\fR or a +system panic could result. diff --git a/usr/src/man/man9f/kiconv.9f b/usr/src/man/man9f/kiconv.9f new file mode 100644 index 0000000000..6994277726 --- /dev/null +++ b/usr/src/man/man9f/kiconv.9f @@ -0,0 +1,326 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kiconv 9F "16 Oct 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +kiconv \- buffer-based code conversion function +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> + + + +\fBsize_t\fR \fBkiconv\fR(\fBkiconv_t\fR \fIcd\fR, \fBchar **\fR\fIinbuf\fR, \fBsize_t *\fR\fIinbytesleft\fR, + \fBchar **\fR\fIoutbuf\fR, \fBsize_t *\fR\fIoutbytesleft\fR, \fBint *\fR\fIerrno\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +The parameters for the \fBkiconv\fR function are as follows: +.sp +.ne 2 +.mk +.na +\fB\fIcd\fR\fR +.ad +.RS 16n +.rt +Code conversion descriptor indicating the code conversion and conversion state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinbuf\fR\fR +.ad +.RS 16n +.rt +Points to an address of a buffer containing a sequence of character bytes in +\fBfromcode\fR codeset to be converted. After the conversion, the variable is +updated to point to the byte following the last byte that was successfully used +in the conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinbytesleft\fR\fR +.ad +.RS 16n +.rt +As an input parameter, the number of bytes to be converted in \fIinbuf\fR. As +an output parameter, the number of bytes in \fIinbuf\fR still not converted +after the conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoutbuf\fR\fR +.ad +.RS 16n +.rt +Points to an address of a buffer where converted character bytes in +\fBtocode\fR codeset can be saved. After the conversion, the variable is +updated to point to the byte following the last byte of converted output data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoutbytesleft\fR\fR +.ad +.RS 16n +.rt +As an input parameter, the number of available bytes at \fIoutbuf\fR where +converted character bytes can be saved. As an output parameter, the number of +bytes still available at \fIoutbuf\fR after the conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerrno\fR\fR +.ad +.RS 16n +.rt +Indicates the error when conversion is not completed or failed. The following +are possible values: +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 13n +.rt +The input conversion was stopped due to an input byte that does not belong to +the input codeset. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBE2BIG\fR\fR +.ad +.RS 13n +.rt +The input conversion was stopped due to lack of space in the output buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +The input conversion was stopped due to an incomplete character or shift +sequence at the end of the input buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 13n +.rt +The \fIcd\fR input parameter is not a valid open code conversion descriptor. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBkiconv()\fR function converts the sequence of characters from one +\fBcodeset\fR, in the array specified by \fIinbuf\fR, into a sequence of +corresponding characters in another \fBcodeset\fR, in the array specified by +\fIoutbuf\fR. The \fBcodesets\fR are those specified in the \fBkiconv_open()\fR +call that returned the code conversion descriptor, \fIcd\fR. The \fIinbuf\fR +parameter points to a variable that points to the first character in the input +buffer and \fIinbytesleft\fR indicates the number of bytes to the end of the +buffer to be converted. The \fIoutbuf\fR parameter points to a variable that +points to the first available byte in the output buffer and \fIoutbytesleft\fR +indicates the number of the available bytes to the end of the buffer. +.sp +.LP +For state-dependent encodings, the conversion descriptor \fIcd\fR is placed +into its initial shift state by a call for which \fIinbuf\fR is a null pointer, +or for which \fIinbuf\fR points to a null pointer. When \fBkiconv()\fR is +called in this way, and if \fIoutbuf\fR is not a null pointer or a pointer to a +null pointer, and \fIoutbytesleft\fR points to a positive value, \fBkiconv()\fR +places, if any, into the output buffer, the byte sequence to change the output +buffer to its initial shift state. If the output buffer is not large enough to +hold the entire reset sequence, \fBkiconv()\fR fails and sets \fIerrno\fR to +\fBE2BIG\fR. Subsequent calls with \fIinbuf\fR as other than a null pointer or +a pointer to a null pointer cause the conversion to take place from the current +state of the conversion descriptor. +.sp +.LP +If a sequence of input bytes does not form a valid character in the specified +\fBcodeset\fR, conversion stops after the previous successfully converted +character. If the input buffer ends with an incomplete character or shift +sequence, conversion stops after the previous successfully converted bytes. If +the output buffer is not large enough to hold the entire converted input, +conversion stops just prior to the input bytes that would cause the output +buffer to overflow. The variable pointed to by \fIinbuf\fR is updated to point +to the byte following the last byte that was successfully used in the +conversion. The value pointed to by \fIinbytesleft\fR is decremented to reflect +the number of bytes still not converted in the input buffer. The variable +pointed to by \fIoutbuf\fR is updated to point to the byte following the last +byte of converted output data. The value pointed to by \fIoutbytesleft\fR is +decremented to reflect the number of bytes still available in the output +buffer. For state-dependent encodings, the conversion descriptor is updated to +reflect the shift state in effect at the end of the last successfully converted +byte sequence. +.sp +.LP +If \fBkiconv()\fR encounters a character in the input buffer that is legal, but +for which an identical character does not exist in the target \fBcodeset\fR, +\fBkiconv()\fR performs an implementation-defined conversion (that is, a +non-identical conversion) on this character. +.SH RETURN VALUES +.sp +.LP +The \fBkiconv()\fR function updates the variables pointed to by the parameters +to reflect the extent of the conversion and returns the number of non-identical +conversions performed. If the entire string in the input buffer is converted, +the value pointed to by \fIinbytesleft\fR is 0. If the input conversion is +stopped due to any conditions mentioned above, the value pointed to by +\fIinbytesleft\fR is non-zero and \fIerrno\fR is set to indicate the condition. +If such and other error occurs, \fBkiconv()\fR returns (\fBsize_t\fR)-1 and +sets \fIerrno\fR to indicate the error. +.SH CONTEXT +.sp +.LP +\fBkiconv()\fR can be called from user or interrupt context. +.SH EXAMPLES +.LP +\fBExample 1 \fRPerforming a Simple Conversion +.sp +.LP +The following example shows how to perform a simple conversion using +\fBkiconv()\fR with a limited size of output buffer: + +.sp +.in +2 +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> + +int +doconversion(char *fromcode, char *tocode, char *inbuf, char *outbuf, + size_t inlen, size_t *outlen) +{ + kiconv_t cd; + size_t ileft, ret; + int err; + + cd = kiconv_open((const char *)tocode, (const char *)fromcode); + if (cd == (kiconv_t)-1) { + /* Cannot open conversion. */ + return (-1); + } + + ret = kiconv(cd, &inbuf, &inlen, &outbuf, outlen, &err); + if (ret == (size_t)-1) + goto doconv_error_return; + + /* + * Reset the conversion descriptor. This will also + * make sure to write to output buffer any saved bytes + * in the conversion descriptor state. + */ + ileft = 0; + ret = kiconv(cd, (char *)NULL, &ileft, &outbuf, outlen, &err); + if (ret == (size_t)-1) + goto doconv_error_return; + + (void) kiconv_close(cd); + + return (0); + +doconv_error_return: + (void) kiconv_close(cd); + + /* Need more output buffer. */ + if (err == E2BIG) + return (-2); + + /* Illegal sequence? */ + if (err == EILSEQ) + return (-3); + + /* Incomplete character? */ + if (err == EINVAL) + return (-4); + + /* + * Bad code conversion descriptor or any other unknown error. + */ + return (-5); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBiconv\fR(3C), \fBiconv_close\fR(3C), \fBiconv_open\fR(3C), +\fBu8_strcmp\fR(3C), \fBu8_textprep_str\fR(3C), \fBu8_validate\fR(3C), +\fBuconv_u16tou32\fR(3C), \fBuconv_u16tou8\fR(3C), \fBuconv_u32tou16\fR(3C), +\fBuconv_u32tou8\fR(3C), \fBuconv_u8tou16\fR(3C), \fBuconv_u8tou32\fR(3C), +\fBattributes\fR(5), \fBkiconvstr\fR(9F), \fBkiconv_close\fR(9F), +\fBkiconv_open\fR(9F), \fBu8_strcmp\fR(9F), \fBu8_textprep_str\fR(9F), +\fBu8_validate\fR(9F), \fBuconv_u16tou32\fR(9F), \fBuconv_u16tou8\fR(9F), +\fBuconv_u32tou16\fR(9F), \fBuconv_u32tou8\fR(9F), \fBuconv_u8tou16\fR(9F), +\fBuconv_u8tou32\fR(9F) +.sp +.LP +The Unicode Standard: +.sp +.LP +http://www.unicode.org/standard/standard.html +.SH NOTES +.sp +.LP +The \fBiconv\fR(3C) man page also has a good example code that can be +referenced. diff --git a/usr/src/man/man9f/kiconv_close.9f b/usr/src/man/man9f/kiconv_close.9f new file mode 100644 index 0000000000..20e315911c --- /dev/null +++ b/usr/src/man/man9f/kiconv_close.9f @@ -0,0 +1,126 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kiconv_close 9F "16 Oct 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +kiconv_close \- code conversion descriptor deallocation function +.SH SYNOPSIS +.LP +.nf +#include <sys/errno.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBkiconv_close\fR(\fBkiconv_t\fR \fIcd\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcd\fR\fR +.ad +.RS 6n +.rt +Code conversion descriptor to be deallocated. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBkiconv_close()\fR function deallocates the conversion descriptor +\fIcd\fR and all other associated resources allocated by the +\fBkiconv_open()\fR function. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBkiconv_close()\fR returns 0; otherwise, it +returns the following \fIerrno\fR value to indicate the error: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 9n +.rt +The code conversion descriptor is invalid. +.RE + +.SH CONTEXT +.sp +.LP +\fBkiconv_close()\fR can be called from user or interrupt context. +.SH EXAMPLES +.LP +\fBExample 1 \fRClosing the Code Conversion +.sp +.LP +The following example shows how to close the code conversion descriptor with +error checking: + +.sp +.in +2 +.nf +if (kiconv_close(cd) == EBADF) { + /* Code conversion descriptor is invalid. */ + return (-1); +} +.fi +.in -2 + +.sp +.LP +The following example shows how to close the code conversion descriptor without +error checking: + +.sp +.in +2 +.nf +(void) kiconv_close(cd); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBiconv\fR(3C), \fBiconv_close\fR(3C), \fBiconv_open\fR(3C), +\fBu8_strcmp\fR(3C), \fBu8_textprep_str\fR(3C), \fBu8_validate\fR(3C), +\fBuconv_u16tou32\fR(3C), \fBuconv_u16tou8\fR(3C), \fBuconv_u32tou16\fR(3C), +\fBuconv_u32tou8\fR(3C), \fBuconv_u8tou16\fR(3C), \fBuconv_u8tou32\fR(3C), +\fBattributes\fR(5), \fBkiconv\fR(9F), \fBkiconvstr\fR(9F), +\fBkiconv_open\fR(9F), \fBu8_strcmp\fR(9F), \fBu8_textprep_str\fR(9F), +\fBu8_validate\fR(9F), \fBuconv_u16tou32\fR(9F), \fBuconv_u16tou8\fR(9F), +\fBuconv_u32tou16\fR(9F), \fBuconv_u32tou8\fR(9F), \fBuconv_u8tou16\fR(9F), +\fBuconv_u8tou32\fR(9F) +.sp +.LP +The Unicode Standard +.sp +.LP +http://www.unicode.org/standard/standard.html diff --git a/usr/src/man/man9f/kiconv_open.9f b/usr/src/man/man9f/kiconv_open.9f new file mode 100644 index 0000000000..c7210325d8 --- /dev/null +++ b/usr/src/man/man9f/kiconv_open.9f @@ -0,0 +1,238 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kiconv_open 9F "16 Oct 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +kiconv_open \- code conversion descriptor allocation function +.SH SYNOPSIS +.LP +.nf +#include <sys/sunddi.h> + + + +\fBkiconv_t\fR \fBkiconv_open\fR(\fBconst\fR \fBchar *\fR\fItocode\fR, \fBconst\fR \fBchar *\fR\fIfromcode\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fItocode\fR\fR +.ad +.RS 12n +.rt +Points to a target codeset name string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfromcode\fR\fR +.ad +.RS 12n +.rt +Points to a source codeset name string. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBkiconv_open()\fR function returns a code conversion descriptor that +describes a conversion from the codeset specified by \fIfromcode\fR to the +codeset specified by \fItocode\fR. For state-dependent encodings, the +conversion descriptor is in a codeset-dependent initial state (ready for +immediate use with the \fBkiconv()\fR function). +.sp +.LP +Supported code conversions are between \fBUTF-8\fR and the following: +.sp +.in +2 +.nf +Name Description + + Big5 Traditional Chinese Big5 + Big5-HKSCS Traditional Chinese Big5-Hong Kong + Supplementary Character Set + CP720 DOS Arabic + CP737 DOS Greek + CP850 DOS Latin-1 (Western European) + CP852 DOS Latin-2 (Eastern European) + CP857 DOS Latin-5 (Turkish) + CP862 DOS Hebrew + CP866 DOS Cyrillic Russian + CP932 Japanese Shift JIS (Windows) + CP950-HKSCS Traditional Chinese HKSCS-2001 (Windows) + CP1250 Central Europe + CP1251 Cyrillic + CP1252 Western Europe + CP1253 Greek + CP1254 Turkish + CP1255 Hebrew + CP1256 Arabic + CP1257 Baltic + EUC-CN Simplified Chinese EUC + EUC-JP Japanese EUC + EUC-JP-MS Japanese EUC MS + EUC-KR Korean EUC + EUC-TW Traditional Chinese EUC + GB18030 Simplified Chinese GB18030 + GBK Simplified Chinese GBK + ISO-8859-1 Latin-1 (Western European) + ISO-8859-2 Latin-2 (Eastern European) + ISO-8859-3 Latin-3 (Southern European) + ISO-8859-4 Latin-4 (Northern European) + ISO-8859-5 Cyrillic + ISO-8859-6 Arabic + ISO-8859-7 Greek + ISO-8859-8 Hebrew + ISO-8859-9 Latin-5 (Turkish) + ISO-8859-10 Latin-6 (Nordic) + ISO-8859-13 Latin-7 (Baltic) + ISO-8859-15 Latin-9 (Western European with euro sign) + KOI8-R Cyrillic + Shift_JIS Japanese Shift JIS (JIS) + TIS_620 Thai (a.k.a. ISO 8859-11) + Unified-Hangul Korean Unified Hangul + +.fi +.in -2 +.sp + +.sp +.LP +\fBUTF-8\fR and the above names can be used at \fItocode\fR and \fIfromcode\fR +to specify the desired code conversion. The following aliases are also +supported as alternative names to be used: +.sp +.in +2 +.nf +Aliases Original Name + 720 CP720 + 737 CP737 + 850 CP850 + 852 CP852 + 857 CP857 + 862 CP862 + 866 CP866 + 932 CP932 + 936, CP936 GBK + 949, CP949 Unified-Hangul + 950, CP950 Big5 + 1250 CP1250 + 1251 CP1251 + 1252 CP1252 + 1253 CP1253 + 1254 CP1254 + 1255 CP1255 + 1256 CP1256 + 1257 CP1257 + ISO-8859-11 TIS_620 + PCK, SJIS Shift_JIS +.fi +.in -2 +.sp + +.sp +.LP +A conversion descriptor remains valid until it is closed by using +\fBkiconv_close()\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBkiconv_open()\fR returns a code conversion +descriptor for use on subsequent calls to \fBkiconv()\fR. Otherwise, if the +conversion specified by \fIfromcode\fR and \fItocode\fR is not supported or for +any other reasons the code conversion descriptor cannot be allocated, +\fBkiconv_open()\fR returns (\fBkiconv_t\fR)-1 to indicate the error. +.SH CONTEXT +.sp +.LP +\fBkiconv_close()\fR can be called from user context only. +.SH EXAMPLES +.LP +\fBExample 1 \fROpening a Code Conversion +.sp +.LP +The following example shows how to open a code conversion from \fBISO\fR +8859-15 to \fBUTF-8\fR + +.sp +.in +2 +.nf +#include <sys/sunddi.h> + +kiconv_t cd; + +cd = kiconv_open("UTF-8", "ISO-8859-15"); +if (cd == (kiconv_t)-1) { + /* Cannot open up the code conversion. */ + return (-1); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBiconv\fR(3C), \fBiconv_close\fR(3C), \fBiconv_open\fR(3C), +\fBu8_strcmp\fR(3C), \fBu8_textprep_str\fR(3C), \fBu8_validate\fR(3C), +\fBuconv_u16tou32\fR(3C), \fBuconv_u16tou8\fR(3C), \fBuconv_u32tou16\fR(3C), +\fBuconv_u32tou8\fR(3C), \fBuconv_u8tou16\fR(3C), \fBuconv_u8tou32\fR(3C), +\fBattributes\fR(5), \fBkiconv\fR(9F), \fBkiconvstr\fR(9F), +\fBkiconv_close\fR(9F), \fBu8_strcmp\fR(9F), \fBu8_textprep_str\fR(9F), +\fBu8_validate\fR(9F), \fBuconv_u16tou32\fR(9F), \fBuconv_u16tou8\fR(9F), +\fBuconv_u32tou16\fR(9F), \fBuconv_u32tou8\fR(9F), \fBuconv_u8tou16\fR(9F), +\fBuconv_u8tou32\fR(9F) +.sp +.LP +The Unicode Standard +.sp +.LP +http://www.unicode.org/standard/standard.html +.SH NOTES +.sp +.LP +The code conversions are available between \fBUTF-8\fR and the above noted +\fIcodesets\fR. For example, to convert from \fBEUC-JP \fRto \fBShift_JIS\fR, +first convert \fBEUC-JP\fR to \fBUTF-8\fR and then convert \fBUTF-8\fR to +\fBShift_JIS\fR. +.sp +.LP +The code conversions supported are based on simple one-to-one mappings. There +is no special treatment or processing done during code conversions such as case +conversion, Unicode Normalization, or mapping between combining or conjoining +sequences of \fBUTF-\fR8 and pre-composed characters in non-\fBUTF-8\fR +codesets. +.sp +.LP +All supported non-\fBUTF-8\fR codesets use pre-composed characters only. +However, \fBUTF-8\fR allows combining or conjoining characters too. For this +reason, using a form of Unicode Normalizations on \fBUTF-8\fR text with +\fBu8_textprep_str()\fR before or after doing code conversions might be +necessary. diff --git a/usr/src/man/man9f/kiconvstr.9f b/usr/src/man/man9f/kiconvstr.9f new file mode 100644 index 0000000000..141e43cf92 --- /dev/null +++ b/usr/src/man/man9f/kiconvstr.9f @@ -0,0 +1,355 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kiconvstr 9F "16 Oct 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +kiconvstr \- string-based code conversion function +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> + + + +\fBsize_t\fR \fBkiconvstr\fR(\fBconst char *\fR\fItocode\fR, \fBconst char *\fR\fIfromcode\fR, \fBchar *\fR\fIinarray\fR, + \fBsize_t *\fR\fIinlen\fR, \fBchar *\fR\fIoutarray\fR, \fBsize_t *\fR\fIoutlen\fR, \fBint\fR \fIflag\fR, \fBint *\fR\fIerrno\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +The parameters for the \fBkiconvstr\fR function are as follows: +.sp +.ne 2 +.mk +.na +\fB\fItocode\fR\fR +.ad +.RS 12n +.rt +Points to a target codeset name string. Supported names are specified at +\fBkiconv_open()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfromcode\fR\fR +.ad +.RS 12n +.rt +Points to a source codeset name string. Supported names are specified at +\fBkiconv_open()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinarray\fR\fR +.ad +.RS 12n +.rt +Points to a byte array containing a sequence of character bytes in +\fIfromcode\fR codeset to be converted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinlen\fR\fR +.ad +.RS 12n +.rt +As an input parameter, the number of bytes to be converted in \fIinarray\fR. As +an output parameter, the number of bytes in \fIinarray\fR still not converted +after the conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoutarray\fR\fR +.ad +.RS 12n +.rt +Points to a byte array where converted character bytes in \fItocode\fR codeset +can be saved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoutlen\fR\fR +.ad +.RS 12n +.rt +As an input parameter, the number of available bytes at \fIoutarray\fR where +converted character bytes can be saved. As an output parameter, the number of +bytes still available at \fIoutarray\fR after the conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 12n +.rt +Indicates possible conversion options constructed by a bitwise-inclusive-OR of +the following values: +.sp +.ne 2 +.mk +.na +\fB\fBKICONV_IGNORE_NULL\fR\fR +.ad +.sp .6 +.RS 4n +Normally, \fBkiconvstr()\fR stops the conversion if it encounters \fBNULL\fR +byte even if the current \fIinlen\fR is pointing to a value larger than zero. +.sp +If this option is set, a \fBNULL\fR byte does not stop the conversion and the +conversion continues until the number of \fIinarray\fR bytes pointed by +\fIinlen\fR are all consumed for conversion or an error happened. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKICONV_REPLACE_INVALID\fR\fR +.ad +.sp .6 +.RS 4n +Normally, \fBkiconvstr()\fR stops the conversion if it encounters illegal or +incomplete characters with corresponding \fIerrno\fR values. +.sp +If this option is set, \fBkiconvstr()\fR does not stop the conversion and +instead treats such characters as non-identical conversion cases. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerrno\fR\fR +.ad +.RS 12n +.rt +Indicates the error when conversion is not completed or failed. The following +are possible values: +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 13n +.rt +The input conversion was stopped due to an input byte that does not belong to +the input codeset. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBE2BIG\fR\fR +.ad +.RS 13n +.rt +The input conversion was stopped due to lack of space in the output array. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 13n +.rt +The input conversion was stopped due to an incomplete character or shift +sequence at the end of the input array. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 13n +.rt +The requested conversion is not supported. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBkiconvstr()\fR function converts the sequence of characters from one +\fBcodeset\fR, in the array specified by \fIinarray\fR, into a sequence of +corresponding characters in another \fBcodeset\fR, in the array specified by +\fIoutarray\fR. The \fBcodesets\fR are those specified in \fIfromcode\fR and +\fItocode\fR parameters. The \fIinarray\fR parameter points to a character byte +array to the first character in the input array and \fIinlen\fR indicates the +number of bytes to the end of the array to be converted. The \fIoutarray\fR +parameter points to a character byte array to the first available byte in the +output array and \fIoutlen\fR indicates the number of the available bytes to +the end of the array. Unless \fBKICONV_IGNORE_NULL\fR is specified at flag, +\fBkiconvstr()\fR function normally stops when it encounters \fBNULL\fR byte +from the input array regardless of the current \fIinlen\fR value. +.sp +.LP +If \fBKICONV_REPLACE_INVALID\fR is not specified at flag and if a sequence of +input bytes does not form a valid character in the specified codeset, +conversion stops after the previous successfully converted character. If +\fBKICONV_REPLACE_INVALID\fR is not specified in \fIflag\fR and if the input +array ends with an incomplete character or shift sequence, conversion stops +after the previous successfully converted bytes. If the output array is not +large enough to hold the entire converted input, conversion stops just prior to +the input bytes that would cause the output array to overflow. The value +pointed to by \fIinlen\fR is decremented to reflect the number of bytes still +not converted in the input array. The value pointed to by \fIoutlen\fR is +decremented to reflect the number of bytes still available in the output array. +.sp +.LP +If \fBkiconvstr()\fR encounters a character in the input array that is legal, +but for which an identical character does not exist in the target +\fBcodeset\fR, \fBkiconvstr()\fR performs an implementation-defined conversion +(that is, a non-identical conversion) on this character. +.sp +.LP +If \fBKICONV_REPLACE_INVALID\fR is specified in \fIflag\fR and if +\fBkiconvstr()\fR encounters illegal or incomplete characters in the input +array, instead of stopping the conversion, \fBkiconvstr()\fR treats such +characters as if they are non-identical characters and does non-identical +conversions on such character bytes. +.SH RETURN VALUES +.sp +.LP +The \fBkiconvstr()\fR function updates the values pointed to by the \fIinlen\fR +and \fIoutlen\fR parameters to reflect the extent of the conversion and returns +the number of non-identical conversions performed. If the entire string in the +input array is converted, the value pointed to by \fIinlen\fR is 0. If the +input conversion is stopped due to any conditions mentioned above, the value +pointed to by \fIinlen\fR is non-zero and \fIerrno\fR is set to indicate the +condition. If an error occurs, \fBkiconvstr()\fR returns (\fBsize_t\fR)-1 and +sets \fIerrno\fR to indicate the error. +.SH CONTEXT +.sp +.LP +\fBkiconvstr()\fR can be called from user or interrupt context. +.SH EXAMPLES +.LP +\fBExample 1 \fRPerforming a Code Conversion +.sp +.LP +The following example converts a \fBNULL\fR-terminated \fBISO8859-2\fR pathname +string to a \fBUTF-8\fR string and treats illegal and incomplete characters as +non-identical conversion cases. The conversion does not stop even if it +encounters a \fBNULL\fR byte from the input array. + +.sp +.in +2 +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> + + : + +size_t ret; +char ib[MAXPATHLEN]; +char ob[MAXPATHLEN]; +size_t il, ol; +int err; + + : + +/* + * We got the pathname from somewhere. + * + * Calculate the length of input string including the terminating + * NULL byte and prepare other parameters for the conversion. + */ +(void) strlcpy(ib, pathname, MAXPATHLEN); +il = strlen(ib) + 1; +ol = MAXPATHLEN; + +/* + * Do the conversion. If the ret > 0, that's the number of + * non-identical character conversions happened during the conversion. + * Regardless of whether we have conversion failure or not, + * outarray could contain some converted characters. + */ +ret = kiconvstr("UTF-8", "ISO-8859-2", ib, &il, ob, &ol, + (KICONV_IGNORE_NULL|KICONV_REPLACE_INVALID), &err); +if (ret == (size_t)-1) { + /* Code conversion not supported? */ + if (err == EBADF) + return (-1); + + /* Output array too small? */ + if (err == E2BIG) + return (-2); + + /* Unknown error which isn't possible BTW. */ + return (-3); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBiconv\fR(3C), \fBiconv_close\fR(3C), \fBiconv_open\fR(3C), +\fBu8_strcmp\fR(3C), \fBu8_textprep_str\fR(3C), \fBu8_validate\fR(3C), +\fBuconv_u16tou32\fR(3C), \fBuconv_u16tou8\fR(3C), \fBuconv_u32tou16\fR(3C), +\fBuconv_u32tou8\fR(3C), \fBuconv_u8tou16\fR(3C), \fBuconv_u8tou32\fR(3C), +\fBattributes\fR(5), \fBkiconv\fR(9F), \fBkiconv_close\fR(9F), +\fBkiconv_open\fR(9F), \fBu8_strcmp\fR(9F), \fBu8_textprep_str\fR(9F), +\fBu8_validate\fR(9F), \fBuconv_u16tou32\fR(9F), \fBuconv_u16tou8\fR(9F), +\fBuconv_u32tou16\fR(9F), \fBuconv_u32tou8\fR(9F), \fBuconv_u8tou16\fR(9F), +\fBuconv_u8tou32\fR(9F) +.sp +.LP +The Unicode Standard: +.sp +.LP +http://www.unicode.org/standard/standard.html diff --git a/usr/src/man/man9f/kmem_alloc.9f b/usr/src/man/man9f/kmem_alloc.9f new file mode 100644 index 0000000000..810291c4d2 --- /dev/null +++ b/usr/src/man/man9f/kmem_alloc.9f @@ -0,0 +1,138 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kmem_alloc 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +kmem_alloc, kmem_zalloc, kmem_free \- allocate kernel memory +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kmem.h> + + + +\fBvoid *\fR\fBkmem_alloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBkmem_zalloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBkmem_free\fR(\fBvoid*\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 8n +.rt +Number of bytes to allocate. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 8n +.rt +Determines whether caller can sleep for memory. Possible flags are +\fBKM_SLEEP\fR to allow sleeping until memory is available, or \fBKM_NOSLEEP\fR +to return \fINULL\fR immediately if memory is not available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuf\fR\fR +.ad +.RS 8n +.rt +Pointer to allocated memory. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBkmem_alloc()\fR function allocates \fIsize\fR bytes of kernel memory and +returns a pointer to the allocated memory. The allocated memory is at least +double-word aligned, so it can hold any C data structure. No greater alignment +can be assumed. \fIflag\fR determines whether the caller can sleep for memory. +\fBKM_SLEEP\fR allocations may sleep but are guaranteed to succeed. +\fBKM_NOSLEEP\fR allocations are guaranteed not to sleep but may fail (return +\fINULL\fR) if no memory is currently available. The initial contents of memory +allocated using \fBkmem_alloc()\fR are random garbage. +.sp +.LP +The \fBkmem_zalloc()\fR function is like \fBkmem_alloc()\fR but returns +zero-filled memory. +.sp +.LP +The \fBkmem_free()\fR function frees previously allocated kernel memory. The +buffer address and size must exactly match the original allocation. Memory +cannot be returned piecemeal. +.SH RETURN VALUES +.sp +.LP +If successful, \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR return a pointer to +the allocated memory. If \fBKM_NOSLEEP\fR is set and memory cannot be allocated +without sleeping, \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR return \fINULL\fR. +.SH CONTEXT +.sp +.LP +The \fBkmem_alloc()\fR and \fBkmem_zalloc()\fR functions can be called from +interrupt context only if the \fBKM_NOSLEEP\fR flag is set. They can be called +from user context with any valid \fIflag\fR. The \fBkmem_free()\fR function can +be called from from user, interrupt, or kernel context. +.SH SEE ALSO +.sp +.LP +\fBcopyout\fR(9F), \fBfreerbuf\fR(9F), \fBgetrbuf\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +Memory allocated using \fBkmem_alloc()\fR is not paged. Available memory is +therefore limited by the total physical memory on the system. It is also +limited by the available kernel virtual address space, which is often the more +restrictive constraint on large-memory configurations. +.sp +.LP +Excessive use of kernel memory is likely to affect overall system performance. +Overcommitment of kernel memory will cause the system to hang or panic. +.sp +.LP +Misuse of the kernel memory allocator, such as writing past the end of a +buffer, using a buffer after freeing it, freeing a buffer twice, or freeing a +null or invalid pointer, will corrupt the kernel heap and may cause the system +to corrupt data or panic. +.sp +.LP +The initial contents of memory allocated using \fBkmem_alloc()\fR are random +garbage. This random garbage may include secure kernel data. Therefore, +uninitialized kernel memory should be handled carefully. For example, never +\fBcopyout\fR(9F) a potentially uninitialized buffer. +.SH NOTES +.sp +.LP +\fBkmem_alloc(0\fR, \fIflag\fR\fB)\fR always returns \fINULL\fR. +\fBkmem_free(NULL, 0)\fR is legal. diff --git a/usr/src/man/man9f/kmem_cache_create.9f b/usr/src/man/man9f/kmem_cache_create.9f new file mode 100644 index 0000000000..97c9faab51 --- /dev/null +++ b/usr/src/man/man9f/kmem_cache_create.9f @@ -0,0 +1,849 @@ +'\" 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 kmem_cache_create 9F "24 Jun 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +kmem_cache_create, kmem_cache_alloc, kmem_cache_free, kmem_cache_destroy, +kmem_cache_set_move \- kernel memory cache allocator operations +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kmem.h> + +\fBkmem_cache_t *\fR\fBkmem_cache_create\fR(\fBchar *\fR\fIname\fR, \fBsize_t\fR \fIbufsize\fR, + \fBsize_t\fR \fIalign\fR, \fBint\fR (*\fIconstructor\fR)(void *, void *, int), + \fBvoid\fR (*\fIdestructor\fR)(void *, void *), \fBvoid\fR (*\fIreclaim\fR)(void *), + \fBvoid\fR *\fIprivate\fR, \fBvoid\fR *\fIvmp\fR, \fBint\fR \fIcflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBkmem_cache_destroy\fR(\fBkmem_cache_t\fR *\fIcp\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBkmem_cache_alloc\fR(\fBkmem_cache_t\fR *\fIcp\fR, \fBint\fR \fIkmflag\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBkmem_cache_free\fR(\fBkmem_cache_t\fR *\fIcp\fR, \fBvoid\fR *\fIobj\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBkmem_cache_set_move\fR(\fBkmem_cache_t\fR *\fIcp\fR, \fBkmem_cbrc_t\fR (*\fImove\fR)(\fBvoid\fR *, + \fBvoid\fR *, \fBsize_t\fR *, \fBvoid\fR *)); +.fi + +.LP +.nf + [Synopsis for callback functions:] +.fi + +.LP +.nf +\fBint\fR (*\fIconstructor\fR)(\fBvoid\fR *\fIbuf\fR, \fBvoid\fR *\fIuser_arg\fR, \fBint\fR \fIkmflags\fR); +.fi + +.LP +.nf +\fBvoid\fR (*\fIdestructor\fR)(\fBvoid\fR *\fIbuf\fR, \fBvoid\fR *\fIuser_arg\fR); +.fi + +.LP +.nf +\fBkmem_cbrc_t\fR (*\fImove\fR)(\fBvoid\fR *\fIold\fR, \fBvoid\fR *\fInew\fR, \fBsize_t\fR \fIbufsize\fR, + \fBvoid\fR *\fIuser_arg\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.LP +The parameters for the \fBkmem_cache_*\fR functions are as follows: +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 15n +.rt +Descriptive name of a \fBkstat\fR(9S) structure of class \fBkmem_cache\fR. +Names longer than 31 characters are truncated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbufsize\fR\fR +.ad +.RS 15n +.rt +Size of the objects it manages. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIalign\fR\fR +.ad +.RS 15n +.rt +Required object alignment. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIconstructor\fR\fR +.ad +.RS 15n +.rt +Pointer to an object constructor function. Parameters are defined below. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdestructor\fR\fR +.ad +.RS 15n +.rt +Pointer to an object destructor function. Parameters are defined below. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreclaim\fR\fR +.ad +.RS 15n +.rt +Drivers should pass \fBNULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprivate\fR\fR +.ad +.RS 15n +.rt +Pass-through argument for constructor/destructor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvmp\fR\fR +.ad +.RS 15n +.rt +Drivers should pass \fBNULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcflags\fR\fR +.ad +.RS 15n +.rt +Drivers must pass 0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIkmflag\fR\fR +.ad +.RS 15n +.rt +Possible flags are: +.sp +.ne 2 +.mk +.na +\fB\fBKM_SLEEP\fR\fR +.ad +.RS 15n +.rt +Allow sleeping (blocking) until memory is available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKM_NOSLEEP\fR\fR +.ad +.RS 15n +.rt +Return NULL immediately if memory is not available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKM_PUSHPAGE\fR\fR +.ad +.RS 15n +.rt +Allow the allocation to use reserved memory. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIobj\fR\fR +.ad +.RS 15n +.rt +Pointer to the object allocated by \fBkmem_cache_alloc()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImove\fR\fR +.ad +.RS 15n +.rt +Pointer to an object relocation function. Parameters are defined below. +.RE + +.sp +.LP +The parameters for the callback constructor function are as follows: +.sp +.ne 2 +.mk +.na +\fB\fBvoid *\fIbuf\fR\fR\fR +.ad +.RS 18n +.rt +Pointer to the object to be constructed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBvoid *\fIuser_arg\fR\fR\fR +.ad +.RS 18n +.rt +The \fIprivate\fR parameter from the call to \fBkmem_cache_create()\fR; it is +typically a pointer to the soft-state structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBint \fIkmflags\fR\fR\fR +.ad +.RS 18n +.rt +Propagated \fIkmflag\fR values. +.RE + +.sp +.LP +The parameters for the callback destructor function are as follows: +.sp +.ne 2 +.mk +.na +\fB\fBvoid *\fIbuf\fR\fR\fR +.ad +.RS 18n +.rt +Pointer to the object to be deconstructed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBvoid *\fIuser_arg\fR\fR\fR +.ad +.RS 18n +.rt +The \fIprivate\fR parameter from the call to \fBkmem_cache_create()\fR; it is +typically a pointer to the soft-state structure. +.RE + +.sp +.LP +The parameters for the callback \fBmove()\fR function are as follows: +.sp +.ne 2 +.mk +.na +\fB\fBvoid *\fIold\fR\fR\fR +.ad +.RS 18n +.rt +Pointer to the object to be moved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBvoid *\fInew\fR\fR\fR +.ad +.RS 18n +.rt +Pointer to the object that serves as the copy destination for the contents of +the old parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsize_t \fIbufsize\fR\fR\fR +.ad +.RS 18n +.rt +Size of the object to be moved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBvoid *\fIuser_arg\fR\fR\fR +.ad +.RS 18n +.rt +The private parameter from the call to \fBkmem_cache_create()\fR; it is +typically a pointer to the \fBsoft-state\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +In many cases, the cost of initializing and destroying an object exceeds the +cost of allocating and freeing memory for it. The functions described here +address this condition. +.sp +.LP +Object caching is a technique for dealing with objects that are: +.RS +4 +.TP +.ie t \(bu +.el o +frequently allocated and freed, and +.RE +.RS +4 +.TP +.ie t \(bu +.el o +have setup and initialization costs. +.RE +.sp +.LP +The idea is to allow the allocator and its clients to cooperate to preserve the +invariant portion of an object's initial state, or constructed state, between +uses, so it does not have to be destroyed and re-created every time the object +is used. For example, an object containing a mutex only needs to have +\fBmutex_init()\fR applied once, the first time the object is allocated. The +object can then be freed and reallocated many times without incurring the +expense of \fBmutex_destroy()\fR and \fBmutex_init()\fR each time. An object's +embedded locks, condition variables, reference counts, lists of other objects, +and read-only data all generally qualify as constructed state. The essential +requirement is that the client must free the object (using +\fBkmem_cache_free()\fR) in its constructed state. The allocator cannot enforce +this, so programming errors will lead to hard-to-find bugs. +.sp +.LP +A driver should call \fBkmem_cache_create()\fR at the time of \fB_fini\fR(9E) +or \fBattach\fR(9E), and call the corresponding \fBkmem_cache_destroy()\fR at +the time of \fB_fini\fR(9E) or \fBdetach\fR(9E). +.sp +.LP +\fBkmem_cache_create()\fR creates a cache of objects, each of size +\fIbufsize\fR bytes, aligned on an \fIalign\fR boundary. Drivers not requiring +a specific alignment can pass 0. \fIname\fR identifies the cache for statistics +and debugging. \fIconstructor\fR and \fIdestructor\fR convert plain memory into +objects and back again; \fIconstructor\fR can fail if it needs to allocate +memory but cannot. \fIprivate\fR is a parameter passed to the constructor and +destructor callbacks to support parameterized caches (for example, a pointer to +an instance of the driver's soft-state structure). To facilitate debugging, +\fBkmem_cache_create()\fR creates a \fBkstat\fR(9S) structure of class +\fBkmem_cache\fR and name \fIname\fR. It returns an opaque pointer to the +object cache. +.sp +.LP +\fBkmem_cache_alloc()\fR gets an object from the cache. The object will be in +its constructed state. \fIkmflag\fR has either \fBKM_SLEEP\fR or +\fBKM_NOSLEEP\fR set, indicating whether it is acceptable to wait for memory if +none is currently available. +.sp +.LP +A small pool of reserved memory is available to allow the system to progress +toward the goal of freeing additional memory while in a low memory situation. +The \fBKM_PUSHPAGE\fR flag enables use of this reserved memory pool on an +allocation. This flag can be used by drivers that implement \fBstrategy\fR(9E) +on memory allocations associated with a single I/O operation. The driver +guarantees that the I/O operation will complete (or timeout) and, on +completion, that the memory will be returned. The \fBKM_PUSHPAGE\fR flag should +be used only in \fBkmem_cache_alloc()\fR calls. All allocations from a given +cache should be consistent in their use of the flag. A driver that adheres to +these restrictions can guarantee progress in a low memory situation without +resorting to complex private allocation and queuing schemes. If +\fBKM_PUSHPAGE\fR is specified, \fBKM_SLEEP\fR can also be used without causing +deadlock. +.sp +.LP +\fBkmem_cache_free()\fR returns an object to the cache. The object must be in +its constructed state. +.sp +.LP +\fBkmem_cache_destroy()\fR destroys the cache and releases all associated +resources. All allocated objects must have been previously freed. +.sp +.LP +\fBkmem_cache_set_move()\fR registers a function that the allocator may call to +move objects from sparsely allocated pages of memory so that the system can +reclaim pages that are tied up by the client. Since caching objects of the same +size and type already makes severe memory fragmentation unlikely, there is +generally no need to register such a function. The idea is to make it possible +to limit worst-case fragmentation in caches that exhibit a tendency to become +highly fragmented. Only clients that allocate a mix of long- and short-lived +objects from the same cache are prone to exhibit this tendency, making them +candidates for a \fBmove()\fR callback. +.sp +.LP +The \fBmove()\fR callback supplies the client with two addresses: the allocated +object that the allocator wants to move and a buffer selected by the allocator +for the client to use as the copy destination. The new parameter is an +allocated, constructed object ready to receive the contents of the old +parameter. The \fIbufsize\fR parameter supplies the size of the object, in case +a single move function handles multiple caches whose objects differ only in +size. Finally, the private parameter passed to the constructor and destructor +is also passed to the \fBmove()\fR callback. +.sp +.LP +Only the client knows about its own data and when it is a good time to move it. +The client cooperates with the allocator to return unused memory to the system, +and the allocator accepts this help at the client's convenience. When asked to +move an object, the client can respond with any of the following: +.sp +.in +2 +.nf +typedef enum kmem_cbrc { + KMEM_CBRC_YES, + KMEM_CBRC_NO, + KMEM_CBRC_LATER, + KMEM_CBRC_DONT_NEED, + KMEM_CBRC_DONT_KNOW +} kmem_cbrc_t; +.fi +.in -2 +.sp + +.sp +.LP +The client must not explicitly free either of the objects passed to the +\fBmove()\fR callback, since the allocator wants to free them directly to the +slab layer (bypassing the per-CPU magazine layer). The response tells the +allocator which of the two object parameters to free: +.sp +.ne 2 +.mk +.na +\fB\fBKMEM_CBRC_YES\fR\fR +.ad +.RS 23n +.rt +The client moved the object; the allocator frees the old parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKMEM_CBRC_NO\fR\fR +.ad +.RS 23n +.rt +The client refused to move the object; the allocator frees the new parameter +(the unused copy destination). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKMEM_CBRC_LATER\fR\fR +.ad +.RS 23n +.rt +The client is using the object and cannot move it now; the allocator frees the +new parameter (the unused copy destination). The client should use +\fBKMEM_CBRC_LATER\fR instead of \fBKMEM_CBRC_NO\fR if the object is likely to +become movable soon. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKMEM_CBRC_DONT_NEED\fR\fR +.ad +.RS 23n +.rt +The client no longer needs the object; the allocator frees both the old and new +parameters. This response is the client's opportunity to be a model citizen and +give back as much as it can. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKMEM_CBRC_DONT_KNOW\fR\fR +.ad +.RS 23n +.rt +The client does not know about the object because: +.sp +.ne 2 +.mk +.na +\fBa)\fR +.ad +.RS 6n +.rt +the client has just allocated the object and has not yet put it wherever it +expects to find known objects +.RE + +.sp +.ne 2 +.mk +.na +\fBb)\fR +.ad +.RS 6n +.rt +the client has removed the object from wherever it expects to find known +objects and is about to free the object +.RE + +.sp +.ne 2 +.mk +.na +\fBc)\fR +.ad +.RS 6n +.rt +the client has freed the object +.RE + +In all of these cases above, the allocator frees the new parameter (the unused +copy destination) and searches for the old parameter in the magazine layer. If +the object is found, it is removed from the magazine layer and freed to the +slab layer so that it will no longer tie up an entire page of memory. +.RE + +.sp +.LP +Any object passed to the \fBmove()\fR callback is guaranteed to have been +touched only by the allocator or by the client. Because memory patterns applied +by the allocator always set at least one of the two lowest order bits, the +bottom two bits of any pointer member (other than \fBchar *\fR or \fBshort +*\fR, which may not be 8-byte aligned on all platforms) are available to the +client for marking cached objects that the client is about to free. This way, +the client can recognize known objects in the \fBmove()\fR callback by the +unmarked (valid) pointer value. +.sp +.LP +If the client refuses to move an object with either \fBKMEM_CBRC_NO\fR or +\fBKMEM_CBRC_LATER\fR, and that object later becomes movable, the client can +notify the allocator by calling \fBkmem_cache_move_notify()\fR. Alternatively, +the client can simply wait for the allocator to call back again with the same +object address. Responding \fBKMEM_CRBC_NO\fR even once or responding +\fBKMEM_CRBC_LATER\fR too many times for the same object makes the allocator +less likely to call back again for that object. +.LP +.nf +[Synopsis for notification function:] +.fi + +.LP +.nf +\fBvoid\fR \fBkmem_cache_move_notify\fR(\fBkmem_cache_t\fR *\fIcp\fR, \fBvoid\fR *\fIobj\fR); +.fi + +.sp +.LP +The parameters for the \fBnotification\fR function are as follows: +.sp +.ne 2 +.mk +.na +\fB\fIcp\fR\fR +.ad +.RS 7n +.rt +Pointer to the object cache. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIobj\fR\fR +.ad +.RS 7n +.rt +Pointer to the object that has become movable since an earlier refusal to move +it. +.RE + +.SH CONTEXT +.sp +.LP +Constructors can be invoked during any call to \fBkmem_cache_alloc()\fR, and +will run in that context. Similarly, destructors can be invoked during any call +to \fBkmem_cache_free()\fR, and can also be invoked during +\fBkmem_cache_destroy()\fR. Therefore, the functions that a constructor or +destructor invokes must be appropriate in that context. Furthermore, the +allocator may also call the constructor and destructor on objects still under +its control without client involvement. +.sp +.LP +\fBkmem_cache_create()\fR and \fBkmem_cache_destroy()\fR must not be called +from interrupt context. \fBkmem_cache_create()\fR can also block for available +memory. +.sp +.LP +\fBkmem_cache_alloc()\fR can be called from interrupt context only if the +\fBKM_NOSLEEP\fR flag is set. It can be called from user or kernel context with +any valid flag. +.sp +.LP +\fBkmem_cache_free()\fR can be called from user, kernel, or interrupt context. +.sp +.LP +\fBkmem_cache_set_move()\fR is called from the same context as +\fBkmem_cache_create()\fR, immediately after \fBkmem_cache_create()\fR and +before allocating any objects from the cache. +.sp +.LP +The registered \fBmove()\fR callback is always invoked in the same global +callback thread dedicated for move requests, guaranteeing that no matter how +many clients register a \fBmove()\fR function, the allocator never tries to +move more than one object at a time. Neither the allocator nor the client can +be assumed to know the object's whereabouts at the time of the callback. +.SH EXAMPLES +.LP +\fBExample 1 \fRObject Caching +.sp +.LP +Consider the following data structure: + +.sp +.in +2 +.nf +struct foo { + kmutex_t foo_lock; + kcondvar_t foo_cv; + struct bar *foo_barlist; + int foo_refcnt; + }; +.fi +.in -2 + +.sp +.LP +Assume that a \fBfoo\fR structure cannot be freed until there are no +outstanding references to it (\fBfoo_refcnt == 0\fR) and all of its pending +\fBbar\fR events (whatever they are) have completed (\fBfoo_barlist == +NULL\fR). The life cycle of a dynamically allocated \fBfoo\fR would be +something like this: + +.sp +.in +2 +.nf +foo = kmem_alloc(sizeof (struct foo), KM_SLEEP); +mutex_init(&foo->foo_lock, ...); +cv_init(&foo->foo_cv, ...); +foo->foo_refcnt = 0; +foo->foo_barlist = NULL; + use foo; +ASSERT(foo->foo_barlist == NULL); +ASSERT(foo->foo_refcnt == 0); +cv_destroy(&foo->foo_cv); +mutex_destroy(&foo->foo_lock); +kmem_free(foo); +.fi +.in -2 + +.sp +.LP +Notice that between each use of a \fBfoo\fR object we perform a sequence of +operations that constitutes nothing but expensive overhead. All of this +overhead (that is, everything other than \fBuse foo\fR above) can be eliminated +by object caching. + +.sp +.in +2 +.nf +int +foo_constructor(void *buf, void *arg, int tags) +{ + struct foo *foo = buf; + mutex_init(&foo->foo_lock, ...); + cv_init(&foo->foo_cv, ...); + foo->foo_refcnt = 0; + foo->foo_barlist = NULL; + return (0); +} + +void +foo_destructor(void *buf, void *arg) +{ + struct foo *foo = buf; + ASSERT(foo->foo_barlist == NULL); + ASSERT(foo->foo_refcnt == 0); + cv_destroy(&foo->foo_cv); + mutex_destroy(&foo->foo_lock); +} + +user_arg = ddi_get_soft_state(foo_softc, instance); +(void) snprintf(buf, KSTAT_STRLEN, "foo%d_cache", + ddi_get_instance(dip)); +foo_cache = kmem_cache_create(buf, + sizeof (struct foo), 0, + foo_constructor, foo_destructor, + NULL, user_arg, 0); +.fi +.in -2 + +.sp +.LP +To allocate, use, and free a \fBfoo\fR object: + +.sp +.in +2 +.nf +foo = kmem_cache_alloc(foo_cache, KM_SLEEP); + use foo; +kmem_cache_free(foo_cache, foo); +.fi +.in -2 + +.sp +.LP +This makes \fBfoo\fR allocation fast, because the allocator will usually do +nothing more than fetch an already-constructed \fBfoo\fR from the cache. +\fBfoo_constructor\fR and \fBfoo_destructor\fR will be invoked only to populate +and drain the cache, respectively. + +.LP +\fBExample 2 \fRRegistering a Move Callback +.sp +.LP +To register a \fBmove()\fR callback: + +.sp +.in +2 +.nf +object_cache = kmem_cache_create(...); +kmem_cache_set_move(object_cache, object_move); +.fi +.in -2 + +.SH RETURN VALUES +.sp +.LP +If successful, the constructor function must return \fB0\fR. If KM_NOSLEEP is +set and memory cannot be allocated without sleeping, the constructor must +return -\fB1\fR. +.sp +.LP +\fBkmem_cache_create()\fR returns a pointer to the allocated cache. +.sp +.LP +If successful, \fBkmem_cache_alloc()\fR returns a pointer to the allocated +object. If \fBKM_NOSLEEP\fR is set and memory cannot be allocated without +sleeping, \fBkmem_cache_alloc()\fR returns \fBNULL\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBcondvar\fR(9F), \fBkmem_alloc\fR(9F), \fBmutex\fR(9F), \fBkstat\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fIThe Slab Allocator: An Object-Caching Kernel Memory Allocator\fR, Bonwick, +J.; USENIX Summer 1994 Technical Conference (1994). +.sp +.LP +\fIMagazines and vmem: Extending the Slab Allocator to Many CPUs and Arbitrary +Resources\fR, Bonwick, J. and Adams, J.; USENIX 2001 Technical Conference +(2001). +.SH NOTES +.sp +.LP +The constructor must be immediately reversible by the destructor, since the +allocator may call the constructor and destructor on objects still under its +control at any time without client involvement. +.sp +.LP +The constructor must respect the \fIkmflags\fR argument by forwarding it to +allocations made inside the \fIconstructor\fR, and must not ASSERT anything +about the given flags. +.sp +.LP +The user argument forwarded to the constructor must be fully operational before +it is passed to \fBkmem_cache_create()\fR. diff --git a/usr/src/man/man9f/kstat_create.9f b/usr/src/man/man9f/kstat_create.9f new file mode 100644 index 0000000000..2b487b83c4 --- /dev/null +++ b/usr/src/man/man9f/kstat_create.9f @@ -0,0 +1,243 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kstat_create 9F "13 Nov 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +kstat_create \- create and initialize a new kstat +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kstat.h> + + + +\fBkstat_t *\fR\fBkstat_create\fR(\fBconst char *\fR\fIks_module\fR, \fBint\fR \fIks_instance\fR, + \fBconst char *\fR\fIks_name\fR, \fBconst char *\fR\fIks_class\fR, \fBuchar_t\fR \fIks_type\fR, + \fBulong_t\fR \fIks_ndata\fR, \fBuchar_t\fR \fIks_flag\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIks_module\fR\fR +.ad +.RS 15n +.rt +The name of the provider's module (such as "\fBsd\fR", "\fBesp\fR", ...). The +"\fBcore\fR" kernel uses the name "unix". +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIks_instance\fR\fR +.ad +.RS 15n +.rt +The provider's instance number, as from \fBddi_get_instance\fR(9F). Modules +which do not have a meaningful instance number should use \fB0\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIks_name\fR\fR +.ad +.RS 15n +.rt +A pointer to a string that uniquely identifies this structure. Only +\fBKSTAT_STRLEN \(mi 1\fR characters are significant. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIks_class\fR\fR +.ad +.RS 15n +.rt +The general class that this kstat belongs to. The following classes are +currently in use: \fBdisk\fR, \fBtape\fR, \fBnet\fR, \fBcontroller\fR, +\fBvm\fR, \fBkvm\fR, \fBhat\fR, \fBstreams\fR, \fBkstat\fR, and \fBmisc\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIks_type\fR\fR +.ad +.RS 15n +.rt +The type of \fBkstat\fR to allocate. Valid types are: +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_TYPE_NAMED\fR\fR +.ad +.RS 20n +.rt +Allows more than one data record per \fBkstat\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_TYPE_INTR\fR\fR +.ad +.RS 20n +.rt +Interrupt; only one data record per \fBkstat\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_TYPE_IO\fR\fR +.ad +.RS 20n +.rt +\fBI/O\fR; only one data record per \fBkstat\fR +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIks_ndata\fR\fR +.ad +.RS 15n +.rt +The number of type-specific data records to allocate. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIks_flag\fR\fR +.ad +.RS 15n +.rt +A bit-field of various flags for this \fBkstat\fR. \fIks_flag\fR is some +combination of: +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_FLAG_VIRTUAL\fR\fR +.ad +.RS 25n +.rt +Tells \fBkstat_create()\fR not to allocate memory for the \fBkstat\fR data +section; instead, the driver will set the \fBks_data\fR field to point to the +data it wishes to export. This provides a convenient way to export existing +data structures. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_FLAG_WRITABLE\fR\fR +.ad +.RS 25n +.rt +Makes the \fBkstat\fR data section writable by root. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_FLAG_PERSISTENT\fR\fR +.ad +.RS 25n +.rt +Indicates that this \fBkstat\fR is to be persistent over time. For persistent +\fBkstat\fRs, \fBkstat_delete\fR(9F) simply marks the \fBkstat\fR as dormant; a +subsequent \fBkstat_create()\fR reactivates the kstat. This feature is provided +so that statistics are not lost across driver close/open (such as raw disk +\fBI/O\fR on a disk with no mounted partitions.) Note: Persistent \fBkstat\fRs +cannot be virtual, since \fBks_data\fR points to garbage as soon as the driver +goes away. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +\fBkstat_create()\fR is used in conjunction with \fBkstat_install\fR(9F) to +allocate and initialize a \fBkstat\fR(9S) structure. The method is generally as +follows: +.sp +.LP +\fBkstat_create()\fR allocates and performs necessary system initialization of +a \fBkstat\fR(9S) structure. \fBkstat_create()\fR allocates memory for the +entire \fBkstat\fR (header plus data), initializes all header fields, +initializes the data section to all zeroes, assigns a unique kstat \fBID\fR +(\fBKID\fR), and puts the kstat onto the system's \fBkstat\fR chain. The +returned kstat is marked invalid because the provider (caller) has not yet had +a chance to initialize the data section. +.sp +.LP +After a successful call to \fBkstat_create()\fR the driver must perform any +necessary initialization of the data section (such as setting the name fields +in a \fBkstat\fR of type \fBKSTAT_TYPE_NAMED\fR). Virtual \fBkstat\fRs must +have the \fBks_data\fR field set at this time. The provider may also set the +\fBks_update\fR, \fBks_private\fR, and \fBks_lock\fR fields if necessary. +.sp +.LP +Once the \fBkstat\fR is completely initialized, \fBkstat_install\fR(9F) is used +to make the \fBkstat\fR accessible to the outside world. +.SH RETURN VALUES +.sp +.LP +If successful, \fBkstat_create()\fR returns a pointer to the allocated +\fBkstat\fR. \fINULL\fR is returned upon failure. +.SH CONTEXT +.sp +.LP +\fBkstat_create()\fR can be called from user or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRAllocating and Initializing a \fBkstat\fR Structure +.sp +.in +2 +.nf +pkstat_t *ksp; + ksp = kstat_create(module, instance, name, class, type, ndata, flags); + if (ksp) { + /* ... provider initialization, if necessary */ + kstat_install(ksp); + } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBkstat\fR(3KSTAT), \fBddi_get_instance\fR(9F), \fBkstat_delete\fR(9F), +\fBkstat_install\fR(9F), \fBkstat_named_init\fR(9F), \fBkstat\fR(9S), +\fBkstat_named\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/kstat_delete.9f b/usr/src/man/man9f/kstat_delete.9f new file mode 100644 index 0000000000..20c3aa5f9b --- /dev/null +++ b/usr/src/man/man9f/kstat_delete.9f @@ -0,0 +1,62 @@ +'\" 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 kstat_delete 9F "4 Apr 1994" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +kstat_delete \- remove a kstat from the system +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kstat.h> + + + +\fBvoid\fR \fBkstat_delete\fR(\fBkstat_t *\fR\fIksp\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 currently installed \fBkstat\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBkstat_delete()\fR removes \fIksp\fR from the \fBkstat\fR chain and frees all +associated system resources. +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +\fBkstat_delete()\fR can be called from any context. +.SH SEE ALSO +.sp +.LP +\fBkstat_create\fR(9F), \fBkstat_install\fR(9F), \fBkstat_named_init\fR(9F), +\fBkstat\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +When calling \fBkstat_delete()\fR, the driver must not be holding that +\fBkstat\fR's \fBks_lock\fR. Otherwise, it may deadlock with a \fBkstat\fR +reader. diff --git a/usr/src/man/man9f/kstat_install.9f b/usr/src/man/man9f/kstat_install.9f new file mode 100644 index 0000000000..47a4222b8a --- /dev/null +++ b/usr/src/man/man9f/kstat_install.9f @@ -0,0 +1,87 @@ +'\" 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 kstat_install 9F "26 May 1994" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +kstat_install \- add a fully initialized kstat to the system +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kstat.h> + + + +\fBvoid\fR \fBkstat_install\fR(\fBkstat_t *\fR\fIksp\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 7n +.rt +Pointer to a fully initialized \fBkstat\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBkstat_install()\fR is used in conjunction with \fBkstat_create\fR(9F) to +allocate and initialize a \fBkstat\fR(9S) structure. +.sp +.LP +After a successful call to \fBkstat_create()\fR the driver must perform any +necessary initialization of the data section (such as setting the name fields +in a kstat of type \fBKSTAT_TYPE_NAMED\fR). Virtual kstats must have the +\fBks_data\fR field set at this time. The provider may also set the +\fBks_update\fR, \fBks_private\fR, and \fBks_lock\fR fields if necessary. +.sp +.LP +Once the kstat is completely initialized, \fBkstat_install\fR is used to make +the kstat accessible to the outside world. +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +\fBkstat_install()\fR can be called from user or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRAllocating and Initializing a \fBkstat\fR Structure +.sp +.LP +The method for allocating and initializing a \fBkstat\fR structure is generally +as follows: + +.sp +.in +2 +.nf +kstat_t *ksp; +ksp = kstat_create(module, instance, name, class, type, ndata, flags); +if (ksp) { + /* ... provider initialization, if necessary */ + kstat_install(ksp); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBkstat_create\fR(9F), \fBkstat_delete\fR(9F), \fBkstat_named_init\fR(9F), +\fBkstat\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/kstat_named_init.9f b/usr/src/man/man9f/kstat_named_init.9f new file mode 100644 index 0000000000..b392efd06c --- /dev/null +++ b/usr/src/man/man9f/kstat_named_init.9f @@ -0,0 +1,170 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH kstat_named_init 9F "29 Feb 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +kstat_named_init, kstat_named_setstr \- initialize a named kstat +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kstat.h> + + + +\fBvoid\fR \fBkstat_named_init\fR(\fBkstat_named_t *\fR\fIknp\fR, \fBconst char *\fR\fIname\fR, + \fBuchar_t\fR \fIdata_type\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBkstat_named_setstr\fR(\fBkstat_named_t *\fR\fIknp\fR, \fBconst char *\fR\fIstr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIknp\fR\fR +.ad +.RS 13n +.rt +Pointer to a \fBkstat_named\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 13n +.rt +The name of the statistic. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdata_type\fR\fR +.ad +.RS 13n +.rt +The type of value. This indicates which field of the \fBkstat_named\fR(9S) +structure should be used. Valid values are: +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_DATA_CHAR\fR\fR +.ad +.RS 24n +.rt +The "\fBchar\fR" field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_DATA_LONG\fR\fR +.ad +.RS 24n +.rt +The "\fBlong\fR" field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_DATA_ULONG\fR\fR +.ad +.RS 24n +.rt +The "\fBunsigned long\fR" field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_DATA_LONGLONG\fR\fR +.ad +.RS 24n +.rt +Obsolete. Use \fBKSTAT_DATA_INT64\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_DATA_ULONGLONG\fR\fR +.ad +.RS 24n +.rt +Obsolete. Use \fBKSTAT_DATA_UINT64\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_DATA_STRING\fR\fR +.ad +.RS 24n +.rt +Arbitrary length "\fBlong string\fR" field. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstr\fR\fR +.ad +.RS 13n +.rt +Pointer to a \fBNULL\fR-terminated string. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBkstat_named_init()\fR associates a name and a type with a +\fBkstat_named\fR(9S) structure. +.sp +.LP +\fBkstat_named_setstr()\fR associates \fIstr\fR with the named kstat \fBknp\fR. +It is an error for \fBknp\fR to be of type other than \fBKSTAT_DATA_STRING\fR. +The string argument must remain valid even after the function that is calling +\fBkstat_named_setstr()\fR is returned. This is the only supported method of +changing the value of long strings. +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +\fBkstat_named_init()\fR and \fBkstat_named_setstr()\fR can be called from user +or kernel context. +.SH SEE ALSO +.sp +.LP +\fBkstat_create\fR(9F), \fBkstat_install\fR(9F), \fBkstat\fR(9S), +\fBkstat_named\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/kstat_queue.9f b/usr/src/man/man9f/kstat_queue.9f new file mode 100644 index 0000000000..441182d5b9 --- /dev/null +++ b/usr/src/man/man9f/kstat_queue.9f @@ -0,0 +1,174 @@ +'\" 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 kstat_queue 9F "4 Apr 1994" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +kstat_queue, kstat_waitq_enter, kstat_waitq_exit, kstat_runq_enter, +kstat_runq_exit, kstat_waitq_to_runq, kstat_runq_back_to_waitq \- update I/O +kstat statistics +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kstat.h> + + + +\fBvoid\fR \fBkstat_waitq_enter\fR(\fBkstat_io_t *\fR\fIkiop\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBkstat_waitq_exit\fR(\fBkstat_io_t *\fR\fIkiop\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBkstat_runq_enter\fR(\fBkstat_io_t *\fR\fIkiop\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBkstat_runq_exit\fR(\fBkstat_io_t *\fR\fIkiop\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBkstat_waitq_to_runq\fR(\fBkstat_io_t *\fR\fIkiop\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBkstat_runq_back_to_waitq\fR(\fBkstat_io_t *\fR\fIkiop\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIkiop\fR \fR +.ad +.RS 9n +.rt +Pointer to a \fBkstat_io\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +A large number of \fBI/O\fR subsystems have at least two basic "lists" (or +queues) of transactions they manage: one for transactions that have been +accepted for processing but for which processing has yet to begin, and one for +transactions which are actively being processed (but not done). For this +reason, two cumulative time statistics are kept: wait (pre-service) time, and +run (service) time. +.sp +.LP +The \fBkstat_queue()\fR family of functions manage these times based on the +transitions between the driver wait queue and run queue. +.sp +.ne 2 +.mk +.na +\fB\fBkstat_waitq_enter()\fR\fR +.ad +.RS 30n +.rt +\fBkstat_waitq_enter()\fR should be called when a request arrives and is placed +into a pre-service state (such as just prior to calling \fBdisksort\fR(9F)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkstat_waitq_exit()\fR\fR +.ad +.RS 30n +.rt +\fBkstat_waitq_exit()\fR should be used when a request is removed from its +pre-service state. (such as just prior to calling the driver's \fBstart\fR +routine). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkstat_runq_enter()\fR\fR +.ad +.RS 30n +.rt +\fBkstat_runq_enter()\fR is also called when a request is placed in its service +state (just prior to calling the driver's start routine, but after +\fBkstat_waitq_exit()\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkstat_runq_exit()\fR\fR +.ad +.RS 30n +.rt +\fBkstat_runq_exit()\fR is used when a request is removed from its service +state (just prior to calling \fBbiodone\fR(9F)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkstat_waitq_to_runq()\fR\fR +.ad +.RS 30n +.rt +\fBkstat_waitq_to_runq()\fR transitions a request from the wait queue to the +run queue. This is useful wherever the driver would have normally done a +\fBkstat_waitq_exit()\fR followed by a call to \fBkstat_runq_enter()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBkstat_runq_back_to_waitq()\fR\fR +.ad +.RS 30n +.rt +\fBkstat_runq_back_to_waitq()\fR transitions a request from the run queue back +to the wait queue. This may be necessary in some cases (write throttling is an +example). +.RE + +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +\fBkstat_create()\fR can be called from user or kernel context. +.SH WARNINGS +.sp +.LP +These transitions must be protected by holding the \fBkstat\fR's \fBks_lock\fR, +and must be completely accurate (all transitions are recorded). Forgetting a +transition may, for example, make an idle disk appear 100% busy. +.SH SEE ALSO +.sp +.LP +\fBbiodone\fR(9F), \fBdisksort\fR(9F), \fBkstat_create\fR(9F), +\fBkstat_delete\fR(9F), \fBkstat_named_init\fR(9F), \fBkstat\fR(9S), +\fBkstat_io\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ldi_add_event_handler.9f b/usr/src/man/man9f/ldi_add_event_handler.9f new file mode 100644 index 0000000000..7d1f3fb54c --- /dev/null +++ b/usr/src/man/man9f/ldi_add_event_handler.9f @@ -0,0 +1,193 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldi_add_event_handler 9F "21 Aug 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_add_event_handler \- add NDI event service callback handler +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi_obsolete.h> + +\fBint\fR \fBldi_add_event_handler\fR(\fBldi_handle_t\fR \fIlh\fR, \fIddi_eventcookie_t ec\fR, + \fBvoid (*handler)(\fR\fIldi_handle_t\fR, \fIddi_eventcookie_t\fR, + \fBvoid *, void *) void *arg,\fR \fIldi_callback_id_t *id\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Obsolete +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIldi_handle_t lh\fR\fR +.ad +.sp .6 +.RS 4n +Layered handle representing event notification device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIddi_eventcookie_t ec\fR\fR +.ad +.sp .6 +.RS 4n +Cookie returned from call to \fBldi_get_eventcookie\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvoid (*handler)(ldi_handle_t, ddi_eventcookie_t, void *, void *)\fR\fR +.ad +.sp .6 +.RS 4n +Callback handler for NDI event service notification. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvoid *arg\fR\fR +.ad +.sp .6 +.RS 4n +Pointer to opaque data supplied by caller. Typically, this is a pointer to the +layered driver's softstate structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIldi_callback_id_t *id\fR\fR +.ad +.sp .6 +.RS 4n +Pointer to registration id, where a unique registration id is returned. +Registration id must be saved and used when calling +\fBldi_remove_event_handler\fR(9F) to unregister a callback handler. +.RE + +.SH DESCRIPTION +.sp +.LP +This function is obsolete and is only maintained for compatibility. Use of this +function is strongly discouraged. For equivalent functionality provided by new +interfaces, see \fBldi_ev_get_cookie\fR(9F) and +\fBldi_ev_register_callbacks\fR(9F). +.sp +.LP +The \fBldi_add_event_handler()\fR function adds a callback handler to be +invoked at the occurance of the event specified by the cookie. Adding a +callback handler is also known as subscribing to an event. Upon successful +subscription, the handler is invoked when the event occurs. You can unregister +the handler by using \fBldi_remove_event_handler\fR(9F). +.sp +.LP +An instance of a layered driver can register multiple handlers for an event or +a single handler for multiple events. Callback order is not defined and should +be assumed to be random. +.sp +.LP +The routine handler is invoked with the following arguments: +.sp +.ne 2 +.mk +.na +\fB\fBldi_handle_t\fR \fIlh\fR\fR +.ad +.RS 24n +.rt +Layered handle representing the device for which the event notification is +requested. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_eventcookie_t\fR \fIec\fR\fR +.ad +.RS 24n +.rt +Structure describing event that occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBvoid *\fR\fIarg\fR\fR +.ad +.RS 24n +.rt +Opaque data pointer provided by the driver during callback registration. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBvoid *\fR\fIimpl_data\fR\fR +.ad +.RS 24n +.rt +Pointer to event specific data defined by the framework that invokes the +callback function. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Callback handler registered successfully. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Failed to register callback handler. Possible reasons include lack of resources +or a bad cookie. +.RE + +.SH CONTEXT +.sp +.LP +The \fBldi_add_event_handler()\fR function can be called from user and kernel +contexts only. +.SH SEE ALSO +.sp +.LP +\fBldi_ev_get_cookie\fR(9F), \fBldi_ev_register_callbacks\fR(9F), +\fBldi_get_eventcookie\fR(9F), \fBldi_remove_event_handler\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Layered drivers must remove all registered callback handlers for a device +instance, represented by the layered handle, by calling +\fBldi_remove_event_handler\fR(9F) before the layered driver's \fBdetach(9E)\fR +routine completes. diff --git a/usr/src/man/man9f/ldi_aread.9f b/usr/src/man/man9f/ldi_aread.9f new file mode 100644 index 0000000000..fb341797f6 --- /dev/null +++ b/usr/src/man/man9f/ldi_aread.9f @@ -0,0 +1,101 @@ +'\" 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 ldi_aread 9F "3 June 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_aread, ldi_awrite \- Issue an asynchronous read or write request to a +device +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fB\fR\fBint\fR ldi_aread(\fBldi_handle_t\fR \fIlh\fR, \fB struct aio_req *\fR\fIaio_reqp\fR, \fBcred_t *\fR\fIcr\fR); +.fi + +.LP +.nf +\fBint\fR \fB ldi_awrite\fR(\fBldi_handle_t\fR \fIlh\fR, \fB struct aio_req *\fR\fIaio_reqp\fR, \fBcred_t *\fR\fIcr\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR \fR +.ad +.RS 13n +.rt +Layered handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcr\fR \fR +.ad +.RS 13n +.rt +Pointer to a credential structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaio_reqp\fR \fR +.ad +.RS 13n +.rt +Pointer to the \fBaio_req(9S)\fR structure that describes where the data is to +be stored or obtained from. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_awrite()\fR function passes an asynchronous write request to a +device entry point specified by the layered handle. This operation is supported +for block and character devices. +.sp +.LP +The \fBldi_aread()\fR function passes an asynchronous read request to a device +entry point specified by the layered handle. This operation is supported for +block and character devices. +.SH RETURN VALUES +.sp +.LP +The \fBldi_awrite()\fR and \fBldi_aread()\fR functions return \fB0\fR upon +success. If a failure occurs before the request is passed on to the device, the +possible return values are shown below. Otherwise any other error number may be +returned by the device. +.sp +.ne 2 +.mk +.na +\fBEINVAL\fR +.ad +.RS 11n +.rt +Invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fBENOTSUP\fR +.ad +.RS 11n +.rt +Operation is not supported for this device. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user context. diff --git a/usr/src/man/man9f/ldi_devmap.9f b/usr/src/man/man9f/ldi_devmap.9f new file mode 100644 index 0000000000..bbd267f1bc --- /dev/null +++ b/usr/src/man/man9f/ldi_devmap.9f @@ -0,0 +1,123 @@ +'\" 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 ldi_devmap 9F "3 June 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_devmap \- Issue a devmap request to a device +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_devmap\fR(\fBldi_handle_t\fR \fIlh\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 PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR\fR +.ad +.RS 10n +.rt +Layered handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdhp\fR\fR +.ad +.RS 10n +.rt +Opaque mapping handle used by the system to describe mapping. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoff\fR\fR +.ad +.RS 10n +.rt +User offset within the logical device memory at which mapping begins. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 10n +.rt +Mapping length (in bytes). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImaplen\fR\fR +.ad +.RS 10n +.rt +Pointer to length (in bytes) of validated mapping. (Less than or equal to +\fIlen\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImodel\fR\fR +.ad +.RS 10n +.rt +Data model type of current thread. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_devmap()\fR function passes an devmap request to the device entry +point for the device specified by the layered handle. This operation is +supported for character devices. +.SH RETURN VALUES +.sp +.LP +The \fBldi_devmap()\fR function returns \fB0\fR upon success. If a failure +occurs before the request is passed to the device, possible return values are +shown below. Otherwise any other error number may be returned by the device. +.sp +.ne 2 +.mk +.na +\fBEINVAL\fR +.ad +.RS 11n +.rt +Invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fBENOTSUP\fR +.ad +.RS 11n +.rt +Operation is not supported for this device. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. diff --git a/usr/src/man/man9f/ldi_dump.9f b/usr/src/man/man9f/ldi_dump.9f new file mode 100644 index 0000000000..1c36c9ccff --- /dev/null +++ b/usr/src/man/man9f/ldi_dump.9f @@ -0,0 +1,98 @@ +'\" 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 ldi_dump 9F "3 June 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_dump \- Issue a dump request to a device +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_dump\fR(\fBldi_handle_t\fR \fIlh\fR, \fBcaddr_t addr, daddr_t\fR\fI blkno\fR, \fB int\fR \fInblk\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR \fR +.ad +.RS 10n +.rt +Layered handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR \fR +.ad +.RS 10n +.rt +Area dump address. +.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 +The \fBldi_dump()\fR function passes a dump request to the device entry point +specified by the layered handle. This operation is supported for block devices. +.SH RETURN VALUES +.sp +.LP +The \fBldi_dump()\fR function returns \fB0\fR upon success. If a failure occurs +before the request is passed on to the device, the possible return values are +shown below. Otherwise any other error number may be returned by the device. +.sp +.ne 2 +.mk +.na +\fBEINVAL\fR +.ad +.RS 11n +.rt +Invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fBENOTSUP\fR +.ad +.RS 11n +.rt +Operation is not supported for this device. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. diff --git a/usr/src/man/man9f/ldi_ev_finalize.9f b/usr/src/man/man9f/ldi_ev_finalize.9f new file mode 100644 index 0000000000..f81590a243 --- /dev/null +++ b/usr/src/man/man9f/ldi_ev_finalize.9f @@ -0,0 +1,170 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldi_ev_finalize 9F "21 Aug 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_ev_finalize \- propagate disposition of a state change event +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBvoid\fR \fBldi_ev_finalize\fR(\fIdev_info_t *dip\fR, \fIminor_t minor\fR, \fIint spec_type\fR, + \fIint ldi_result\fR, \fIldi_ev_cookie_t cookie\fR, \fIvoid *ev_data\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev_info_t *dip\fR\fR +.ad +.sp .6 +.RS 4n +The \fBdevinfo\fR node of the layered consumer exporting the minor device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIminor_t minor\fR\fR +.ad +.sp .6 +.RS 4n +The minor number of the exported minor device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIint spec_type\fR\fR +.ad +.sp .6 +.RS 4n +The type of minor device (\fBS_IFCHR\fR or \fBS_IFBLK\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIint ldi_result\fR\fR +.ad +.sp .6 +.RS 4n +The final disposition of the state change. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIldi_ev_cookie_t cookie\fR\fR +.ad +.sp .6 +.RS 4n +An opaque event cookie for the event type returned by a previous call to +\fBldi_ev_get_cookie\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvoid *ev_data\fR\fR +.ad +.sp .6 +.RS 4n +Event specific data. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_ev_finalize()\fR function propagates the final disposition of an +event up the software stack. It may result in two actions: +.RS +4 +.TP +.ie t \(bu +.el o +Invocation of "finalize" \fBLDI\fR callback handlers registered by layered +drivers up the software stack. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Device contract "negotiation end" (\fBCT_EV_NEGEND\fR) events generated on +minors exported to \fBuserland\fR. +.RE +.sp +.LP +The event propagated up the software stack may be different than the event +received by the layered driver invoking \fBldi_ev_finalize()\fR. For example, a +volume manager may receive an "offline" event on one of it's \fBLDI\fR opened +disks, but may choose to propagate a "degraded" event on minors it exports to +\fBuserland\fR (since it may have more than one copy of the data). The event +cookie argument to \fBldi_ev_notify\fR(9F) may be different from the event +cookie currently possessed by the layered driver. If that is the case, the +layered driver must generate another event cookie via a new +\fBldi_ev_get_cookie\fR(9F) call. +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +This function can be called from user and kernel contexts only. +.SH EXAMPLES +.LP +\fBExample 1 \fRInvoking ldi_ev_finalize(9F) from widget's finalize callback +.sp +.LP +The following example shows how the \fBldi_ev_finalize()\fR function is invoked +from a widget's finalize callback: + +.sp +.in +2 +.nf +static void +widget_finalize(ldi_handle_t lh, ldi_ev_cookie_t foo_cookie, + int ldi_result, void *arg, void *ev_data) + +{ + ASSERT(strcmp(ldi_ev_get_type(foo_cookie), LDI_EV_FOO) == 0); + + /* Map imported minor to exported minors */ + widget_map(lh, &minor, &spec_type); + + if (ldi_result == LDI_EV_SUCCESS) { + ldi_ev_finalize(dip, minor, spec_type, + LDI_EV_SUCCESS, foo_cookie, ev_data); + } + + /* + * The event foo failed. Reconfigure yourself + * *before* propagating + */ + widget_reconfigure(lh, LDI_EV_FOO, REACQUIRE); + + ldi_ev_finalize(dip, minor, spec_type, LDI_EV_FAILURE, + foo_cookie, ev_data); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBldi_ev_get_cookie\fR(9F), \fBldi_ev_register_callbacks\fR(9F), +\fBldi_ev_remove_callbacks\fR(9F) diff --git a/usr/src/man/man9f/ldi_ev_get_cookie.9f b/usr/src/man/man9f/ldi_ev_get_cookie.9f new file mode 100644 index 0000000000..440579dc2d --- /dev/null +++ b/usr/src/man/man9f/ldi_ev_get_cookie.9f @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldi_ev_get_cookie 9F "21 Aug 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_ev_get_cookie \- get an LDI event cookie for a specified event +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_ev_get_cookie\fR(\fIldi_handle_t lh\fR, \fIchar *evname\fR, + \fIldi_ev_cookie_t *cookiep\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIldi_handle_t lh\fR\fR +.ad +.sp .6 +.RS 4n +A layered handle representing the device for which the event notification was +requested. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIchar *evname\fR\fR +.ad +.sp .6 +.RS 4n +The string name of the event. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIldi_ev_cookie_t *cookiep\fR\fR +.ad +.sp .6 +.RS 4n +A pointer to type \fBldi_ev_cookie_t\fR. Contains a pointer to the event cookie +on return. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_ev_get_cookie()\fR function accepts the string name of a state +change event affecting the device represented by the layered driver handle +"\fBlh\fR" and returns an opaque cookie on success. The call is successful if +the framework supports event notification for the event named by +"\fBevname\fR". If successful, the function returns an opaque cookie through +the "\fBcookiep\fR" parameter. The cookie is required in subsequent calls for +registering callbacks on events. +.sp +.LP +The following two LDI events are currently defined: +.sp +.ne 2 +.mk +.na +\fB\fBLDI_EV_OFFLINE\fR\fR +.ad +.sp .6 +.RS 4n +The device is moving to the offline state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDI_EV_DEGRADE\fR\fR +.ad +.sp .6 +.RS 4n +The device is moving to the degraded state. +.RE + +.sp +.LP +\fBldi_ev_get_cookie()\fR also accepts the string name of any events defined +for NDI event services. For such events, \fBldi_ev_get_cookie()\fR replaces +\fBldi_get_eventcookie\fR(9F) (which is now obsolete). +.SH RETURN VALUES +.sp +.LP +The return values for this function are: +.sp +.ne 2 +.mk +.na +\fB\fBLDI_EV_SUCCESS\fR\fR +.ad +.sp .6 +.RS 4n +The event cookie was created successfully. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDI_EV_FAILURE\fR\fR +.ad +.sp .6 +.RS 4n +An error occurred and the cookie was not created. +.RE + +.SH CONTEXT +.sp +.LP +This function can be called from user and kernel contexts only. +.SH SEE ALSO +.sp +.LP +\fBldi_ev_register_callbacks\fR(9F), \fBldi_ev_remove_callbacks\fR(9F) diff --git a/usr/src/man/man9f/ldi_ev_get_type.9f b/usr/src/man/man9f/ldi_ev_get_type.9f new file mode 100644 index 0000000000..6dabe383af --- /dev/null +++ b/usr/src/man/man9f/ldi_ev_get_type.9f @@ -0,0 +1,52 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldi_ev_get_type 9F "21 Aug 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_ev_get_type \- get event name string from event cookie +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_ev_get_type\fR(\fIldi_ev_cookie_t cookie\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIldi_ev_cookie_t cookie\fR\fR +.ad +.sp .6 +.RS 4n +An opaque event cookie for the event type returned by a previous call to +\fBldi_ev_get_cookie\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_ev_get_type()\fR function returns the event string represented by +the \fBLDI\fR event cookie "\fBcookie\fR". +.SH RETURN VALUES +.sp +.LP +On success, this function returns the event string represented by +"\fBcookie\fR". On failure, this function returns \fBNULL\fR. +.SH CONTEXT +.sp +.LP +This function can be called from user and kernel contexts only. +.SH SEE ALSO +.sp +.LP +\fBldi_ev_get_cookie\fR(9F), \fBldi_ev_register_callbacks\fR(9F), +\fBldi_ev_remove_callbacks\fR(9F) diff --git a/usr/src/man/man9f/ldi_ev_notify.9f b/usr/src/man/man9f/ldi_ev_notify.9f new file mode 100644 index 0000000000..afe1c4f132 --- /dev/null +++ b/usr/src/man/man9f/ldi_ev_notify.9f @@ -0,0 +1,193 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldi_ev_notify 9F "21 Aug 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_ev_notify \- propagate notification of a state change event +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_ev_notify\fR(\fIdev_info_t *dip\fR, \fIminor_t minor\fR, \fIint spec_type\fR, + \fIldi_ev_cookie_t cookie\fR, \fIvoid *ev_data\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdev_info_t *dip\fR\fR +.ad +.sp .6 +.RS 4n +The \fBdevinfo\fR node of the layered consumer exporting the minor device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIminor_t minor\fR\fR +.ad +.sp .6 +.RS 4n +The minor number of the exported minor device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIint spec_type\fR\fR +.ad +.sp .6 +.RS 4n +The type of minor device (\fBS_IFCHR\fR or \fBS_IFBLK\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIldi_ev_cookie_t cookie\fR\fR +.ad +.sp .6 +.RS 4n +An opaque event cookie for the event type returned by a previous call to +\fBldi_ev_get_cookie\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvoid *ev_data\fR\fR +.ad +.sp .6 +.RS 4n +Event specific data. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_ev_notify()\fR function propagates an event up the software stack. +It may result in two actions: +.RS +4 +.TP +.ie t \(bu +.el o +Invocation of \fBLDI\fR callback handlers registered by layered drivers up the +software stack. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Device contract events generated on minors exported to \fBuserland\fR. +.RE +.sp +.LP +The event propagated up the software stack may be different than the event +received by the layered driver invoking \fBldi_ev_notify()\fR. For example, a +volume manager may receive an "offline" event on one of it's \fBLDI\fR opened +disks, but may choose to propagate a "degraded" event on minors it exports to +\fBuserland\fR (since it may have more than one copy of the data). The event +cookie argument to \fBldi_ev_notify()\fR may be different from the event cookie +currently possessed by the layered driver. If that is the case, the layered +driver must generate another event cookie via a new \fBldi_ev_get_cookie\fR(9F) +call. +.sp +.LP +The\fBldi_ev_*\fR interfaces are designed to ensure that a "finalize" call is +generated for layered driver consumers at the earliest point where an +\fBLDI_EV_FAILURE\fR is detected. If this happens inside the \fBLDI\fR event +framework, then the framework will invoke finalize. In the event a layered +driver detects/generates an \fBLDI_EV_FAILURE\fR, then the layered driver must +invoke \fBldi_ev_finalize()\fR. The following is an example of a layered driver +invoking \fBldi_ev_finalize()\fR for the "foo" event: +.sp +.in +2 +.nf +static int + widget_notify(ldi_handle_t lh, ldi_ev_cookie_t foo_cookie, void *arg, + void *ev_data) + { + + ASSERT(strcmp(ldi_ev_get_type(foo_cookie), LDI_EV_FOO) == 0); + + /* Map imported minors to exported minor */ + widget_map(lh, &minor, &spec_type); + + /* + * Call ldi_ev_notify() to propagate events to our consumers. + * This *must* happen before we check if widget should block + * foo + */ + if (ldi_ev_notify(dip, minor, spec_type, foo_cookie, ev_data) + != LDI_EV_SUCCESS) + return (LDI_EV_FAILURE); + + /* + * Next, check if we can allow the foo event + */ + if (widget_release(lh, LDI_EV_FOO) == WIDGET_SUCCESS) { + return (LDI_EV_SUCCESS) + } + + /* + * We cannot permit the foo event. The first layer that detects + * failure i.e. us, must generate finalize events for *our* + * consumers + */ + ldi_ev_finalize(dip, minor, spec_type, LDI_EV_FAILURE, + foo_cookie, ev_data); + + return (LDI_EV_FAILURE); +} +.fi +.in -2 + +.SH RETURN VALUES +.sp +.LP +The return values for this function are: +.sp +.ne 2 +.mk +.na +\fB\fBLDI_EV_SUCCESS\fR\fR +.ad +.sp .6 +.RS 4n +Consumers up the software stack permit state change. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDI_EV_FAILURE\fR\fR +.ad +.sp .6 +.RS 4n +Consumers are blocking the state change. +.RE + +.SH CONTEXT +.sp +.LP +This function can be called from user and kernel context only. +.SH SEE ALSO +.sp +.LP +\fBldi_ev_get_cookie\fR(9F), \fBldi_ev_register_callbacks\fR(9F), +\fBldi_ev_remove_callbacks\fR(9F) diff --git a/usr/src/man/man9f/ldi_ev_register_callbacks.9f b/usr/src/man/man9f/ldi_ev_register_callbacks.9f new file mode 100644 index 0000000000..d35286d948 --- /dev/null +++ b/usr/src/man/man9f/ldi_ev_register_callbacks.9f @@ -0,0 +1,538 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldi_ev_register_callbacks 9F "21 Aug 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_ev_register_callbacks \- add a notify and/or finalize callback +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_ev_get_cookie\fR(\fIldi_handle_t lh\fR, \fIldi_ev_cookie_t *cookie\fR, + \fIldi_ev_callback_t *callb\fR, \fBvoid\fR \fI*arg\fR, \fIldi_ev_callback_id_t *id\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIldi_handle_t lh\fR\fR +.ad +.sp .6 +.RS 4n +A layered handle representing the device for which the event notification was +requested. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIldi_ev_cookie_t *cookie\fR\fR +.ad +.sp .6 +.RS 4n +An opaque event cookie for the event type returned by a previous call to +\fBldi_ev_get_cookie\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIldi_ev_callback_t *callb\fR\fR +.ad +.sp .6 +.RS 4n +A data structure which currently has the following members: +.sp +.in +2 +.nf +struct ldi_ev_callback { + uint_t cb_vers; + int (*cb_notify)(ldi_handle_t, + ldi_ev_cookie_t cookie, + void *arg, void *ev_data); + void (*cb_finalize)(ldi_handle_t, + ldi_ev_cookie_t cookie, + int ldi_result, + void *arg, + void *ev_data); + } ldi_ev_callback_t; +.fi +.in -2 + +where +.sp +.ne 2 +.mk +.na +\fB\fBcb_vers\fR\fR +.ad +.RS 11n +.rt +Version of callback vector. Must be set to \fBLDI_EV_CB_VERS\fR by the caller. +.sp +The arguments passed into the callbacks when they are invoked, include: +.sp +.ne 2 +.mk +.na +\fB\fBint ldi_result\fR\fR +.ad +.sp .6 +.RS 4n +The actual result of the state change operation/event passed to finalize +callback: \fBLDI_EV_SUCCESS\fR: The state change succeeded +\fBLDI_EV_FAILURE\fR: The state change failed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBvoid *ev_data\fR\fR +.ad +.sp .6 +.RS 4n +Event specific data. +.RE + +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBvoid *arg\fR\fR +.ad +.sp .6 +.RS 4n +A pointer to opaque caller private data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldi_ev_callback_id_t *id\fR\fR +.ad +.sp .6 +.RS 4n +Unique system wide registration id returned by ldi_ev_register_callbacks(9F) +upon successful registration. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_ev_register_callbacks()\fR interface allows layered drivers to +register notify and finalize callbacks for certain events. These events are +listed in the \fBldi_ev_get_cookie\fR(9F) man page. The notify callback is +invoked only for events that can be blocked, just before the event occurs. The +notify event is not called for events serviced by the \fBNDI\fR event service +framework since such events are by definition asynchronous. Only the finalize +callback is invoked for such events. Layered drivers that have registered +notify callbacks for that event have the opportunity of blocking such events. +The finalize callback is invoked once the final disposition of the state of a +device (specifically a device minor node) is known. The callback is invoked +with this result, either \fBLDI_EV_SUCCESS\fR (state change succeeded) or +\fBLDI_EV_FAILURE\fR (state change failed). This allows layered driver +consumers to finalize any changes they made in response to a previous "notify" +callback. +.sp +.LP +For example, a layered driver's notify callback may be invoked in response to a +\fBLDI_EV_OFFLINE\fR event. The layered driver may reconfigure itself to stop +using the device and permit the change to go forward. Once that happens, the +\fBI/O\fR framework attempts to actually take the device offline. This offline +attempt can have two possible outcomes: success or failure. In the former case, +the finalize callback is invoked with the \fIldi_result\fR argument set to +\fBLDI_EV_SUCCESS\fR and the layered driver knows that the device has been +taken offline. In the latter case, finalize is invoked with the +\fIldi_result\fR set to \fBLDI_EV_FAILURE\fR and the layered driver knows that +the state change failed. In this case, it may choose to reconfigure itself to +start using the device again. +.sp +.LP +Finalize callbacks can be registered for all events including events that +cannot be blocked. +.sp +.LP +A layered driver can also propagate these events up the software stack by using +interfaces offered by the \fBLDI\fR event framework. The layered driver may use +\fBldi_ev_notify()\fR to propagate notify events occurring on minors it imports +onto minors it exports. Similarly, it may use \fBldi_ev_finalize()\fR to +propagate finalize events. Both \fBldi_ev_notify()\fR and +\fBldi_ev_finalize()\fR propagate events to device contracts as well as LDI +callbacks registered against the exported minor nodes. +.sp +.LP +The \fBLDI\fR event framework has the following guarantees and requirements +with respect to these callbacks: +.RS +4 +.TP +1. +The \fBnotify()\fR callback is invoked before an event (represented by the +event cookie) occurs on a device (represented by the layered driver handle) and +is invoked only for events that can be blocked. If the callback returns +\fBLDI_EV_FAILURE\fR, the event is blocked. If the callback returns +\fBLDI_EV_SUCCESS\fR, the event is allowed to proceed. If any other value is +returned, it is an error. An error message is logged and the event is blocked. +An example of an event that can be blocked and for which notify callbacks may +be invoked is the offline event \fBLDI_EV_OFFLINE\fR. +.RE +.RS +4 +.TP +2. +The finalize callback is invoked for all events (including events that +cannot be blocked) after the event has occurred. It is invoked with either +\fBLDI_EV_SUCCESS\fR indicating that the event successfully happened or +\fBLDI_EV_FAILURE\fR indicating that the event did not occur. The finalize +callback returns no values. Good examples of events that cannot be blocked are +the degrade event (\fBLDI_EV_DEGRADE\fR) and events serviced by the \fBNDI\fR +event service framework. +.RE +.RS +4 +.TP +3. +Layered drivers may register one or both of these callbacks (that is, only +for a notify event or only for a finalize event or for both) against any +\fBLDI\fR handle that they may possess. If a finalize or notify event is not +being registered, the corresponding pointer in the \fIldi_ev_callback_t\fR +structure must be set to \fBNULL\fR. It is an error to attempt a registration +with both callbacks set to \fBNULL\fR. +.RE +.RS +4 +.TP +4. +A notify and/or finalize callback is invoked only if the corresponding +\fBLDI\fR handle is open. If an \fBLDI\fR handle against which the callbacks +are registered is closed, the corresponding finalize and notify callbacks is +not invoked as it is assumed that the layered driver is no longer interested in +the device. See number 5 below for the exception to this rule. +.RE +.RS +4 +.TP +5. +A layered driver that closes it's \fBLDI\fR handle in it's notify routine +receives the corresponding finalize callback after the event has occurred. +Because the \fBLDI\fR handle has been closed, the finalize callback is invoked +with a \fBNULL\fR \fBLDI\fR handle. It is the responsibility of the layered +driver to maintain state in it's private "\fIarg\fR" parameter so that it can +reopen the device (if desired) in it's finalize callback. +.sp +One example where this may happen is with the \fBLDI_EV_OFFLINE\fR event. A +layered driver's notify callback may be invoked for an offline event. The +layered driver may choose to allow this event to proceed. In that case, since +it has a layered open of the device, it must close the \fBLDI\fR handle so that +the offline event can succeed (an offline of a device does not succeed if there +is any open of the device, layered or otherwise). Since the layered driver has +closed the \fBLDI\fR handle in the notify routine, it's finalize callback (if +any) is invoked with a \fBNULL\fR \fBLDI\fR handle. It is the responsibility of +the layered driver to maintain state (such as the device path or \fBdevid\fR) +in it's private "\fIarg\fR" parameter, so that in the finalize routine, it can +do a layered open of the device if the device offline failed. +.sp +This is the only exception where the finalize callback is invoked if the +\fBLDI\fR handle has been closed. In all other cases if the \fBLDI\fR handle +has been closed, no corresponding callbacks is invoked. +.RE +.RS +4 +.TP +6. +In order for the offline event to succeed (\fBLDI_EV_OFFLINE\fR), it is +imperative that there be no opens (including \fBLDI\fR handles) to the device. +If a layered driver's notify callback is invoked for an offline event and the +driver intends to allow the offline to proceed, the driver must close the +corresponding \fBLDI\fR handle. +.RE +.RS +4 +.TP +7. +The notify and finalize callbacks are not automatically unregistered even if +the corresponding \fBLDI\fR handle has been closed. It is the responsibility of +the layered driver to unregister these callbacks when they are not required. It +may do so using the \fBldi_ev_remove_callbacks\fR(9F) interface. The \fBLDI\fR +framework may panic if the entity registering the callback (such as a +\fBdip\fR, \fBdev_t\fR or \fBmodule\fR) no longer exists on the system and the +corresponding callbacks have not been unregistered. +.RE +.RS +4 +.TP +8. +The \fBLDI\fR event framework guarantees that if a layered driver receives a +notify event, it also receives a finalize event except if the layered consumer +itself blocked the event (that is, it returned \fBLDI_EV_FAILURE\fR from it's +notify callback. In this case, the layered driver knows that the event has been +blocked and therefore does not need the finalize callback. +.RE +.RS +4 +.TP +9. +If a layered driver propagates notify events on minors it imports to minors +it exports, it must first propagate these events up the software stack via +\fBldi_eve_notify()\fR in it's notify callback. It must do so before attempting +to check if it blocks the event. This is required, because a layered driver +cannot release the device if consumers up the stack are still using the device. +If \fBldi_ev_notify()\fR returns \fBLDI_EV_FAILURE\fR, the callback must +immediately return \fBLDI_EV_FAILURE\fR from it's notify callback. If +\fBldi_ev_notify()\fR returns \fBLDI_EV_SUCCESS\fR, then the state change is +permissible as far as consumers higher up in the software stack are concerned. +The layered driver must then determine if it can permit the state change. If +the state change is to be allowed, the layered driver must return +\fBLDI_EV_SUCCESS\fR. If the layered driver determines that the state change +should not be permitted, it must invoke \fBldi_ev_finalize()\fR on minors it +exports with a result of \fBLDI_EV_FAILURE\fR (to inform consumers up the +stack) and then return \fBLDI_EV_FAILURE\fR from it's notify callback. +.RE +.RS +4 +.TP +10. +The \fBLDI\fR event framework generates finalize events at the earliest +point where a failure is detected. If the failure is detected in the framework +(such as in \fBldi_ev_notify()\fR) the framework generates the finalize events. +In the event that a failure is first detected in a layered driver (that is, in +the notify callback of a layered driver) the layered driver must use +\fBldi_ev_finalize()\fR to send finalize events up the software stack . See +the examples for code snippets describing this scenario. +.RE +.RS +4 +.TP +11. +The finalize callback must first reconfigure itself before attempting to +propagate the event up the software stack via \fBldi_ev_finalize\fR(9F). This +is so that the minors it exports are available and ready for use before the +finalize event is propagated up the software stack. +.RE +.RS +4 +.TP +12. +It may so happen that the event propagated up the software stack is not the +same as the event for which a layered driver's notify/finalize callback is +invoked. For example, a layered driver's callback(s) may be invoked for an +offline event, but the driver may choose to only propagate the degraded event +to its consumers (since it may have a mirror/copy of the data on the device.) +In that case, the layered driver must generate a different event cookie (that +is, one corresponding to the degraded event via \fBldi_ev_get_cookie\fR(9F)) +and use that cookie in its propagation calls (that is, \fBldi_ev_notify\fR(9F) +and \fBldi_ev_finalize\fR(9F)). +.RE +.sp +.LP +Once the registration of the callback(s) is successful, an opaque +\fIldi_ev_callback_id_t\fR structure is returned which may be used to +unregister the callback(s) later. +.SH RETURN VALUES +.sp +.LP +The return values for this function are: +.sp +.ne 2 +.mk +.na +\fB\fBLDI_EV_SUCCESS\fR\fR +.ad +.sp .6 +.RS 4n +Callback(s) added successfully. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBLDI_EV_FAILURE\fR\fR +.ad +.sp .6 +.RS 4n +Failed to add callback(s). +.RE + +.SH CONTEXT +.sp +.LP +This function can be called from user and kernel contexts only. +.SH EXAMPLES +.LP +\fBExample 1 \fRRegistration and Callbacks for the OFFLINE Event +.sp +.LP +The following example shows how the \fBldi_ev_register_callbacks()\fR function +performs a registration and callback for the offline event: + +.sp +.in +2 +.nf +static int +event_register(void) +{ + ldi_handle_t lh; + ldi_ev_callback_t callb; + ldi_ev_cookie_t off_cookie; + + if (ldi_ev_get_cookie(lh, LDI_EV_OFFLINE, &off_cookie) + == LDI_EV_FAILURE) + goto fail; + + + callb.cb_vers = LDI_EV_CB_VERS; + callb.cb_notify = off_notify; + callb.cb_finalize = off_finalize; + + if (ldi_ev_register_callbacks(lh, off_cookie, &callb, arg, &id) + != LDI_EV_SUCCESS) + goto fail; +} + +static void +event_unregister(ldi_ev_callback_id_t id) +{ + ldi_ev_remove_callbacks(id); +} + +static int +off_notify(ldi_handle_t lh, ldi_ev_cookie_t off_cookie, void *arg, + void *ev_data) +{ + + ASSERT(strcmp(ldi_ev_get_type(off_cookie), LDI_EV_OFFLINE) == 0); + + /* Map imported minors to exported minor */ + widget_map(lh, &minor, &spec_type); + + /* + * Call ldi_ev_notify() to propagate events to our consumers. + * This *must* happen before we check if offline should be blocked + */ + if (ldi_ev_notify(dip, minor, spec_type, off_cookie, ev_data) + != LDI_EV_SUCCESS) + return (LDI_EV_FAILURE); + + /* + * Next, check if we can allow the offline + */ + if (widget_check(lh) == WIDGET_SUCCESS) { + widget_save_path(arg, lh); + widget_reconfigure(lh, RELEASE); + ldi_close(lh); + return (LDI_EV_SUCCESS) + } + + /* + * We cannot permit the offline. The first layer that detects + * failure i.e. us, must generate finalize events for our + consumers + */ + ldi_ev_finalize(dip, minor, spec_type, LDI_EV_FAILURE, off_cookie, + ev_data); + + return (LDI_EV_FAILURE); +} + +/* +/* + * The finalize callback will only be called if we returned LDI_EV_SUCCESS + * in our notify callback. ldi_result passed in may be SUCCESS or FAILURE + */ +static void +off_finalize(ldi_handle_t NULL_lh, ldi_ev_cookie_t off_cookie, + int ldi_result, void *arg, void *ev_data) +{ + ldi_handle_t lh; + + ASSERT(strcmp(ldi_ev_get_type(off_cookie), LDI_EV_OFFLINE) == 0); + + path = widget_get_path(arg); + + widget_map_by_path(path, &minor, &spec_type); + + if (ldi_result == LDI_EV_SUCCESS) { + ldi_ev_finalize(dip, minor, spec_type, LDI_EV_SUCCESS, + off_cookie, ev_data); + return; + } + + /* The offline failed. Reopen the device */ + ldi_open_by_name(path, &lh); + widget_reconfigure(lh, REACQUIRE); + + ldi_ev_finalize(dip, minor, spec_type, LDI_EV_FAILURE, off_cookie, + ev_data); +} +.fi +.in -2 + +.LP +\fBExample 2 \fRRegistration and Callbacks for the DEGRADE Event +.sp +.LP +The following example shows how the \fBldi_ev_register_callbacks()\fR function +performs a registration and callback for the degrade event: + +.sp +.in +2 +.nf +static int +event_register(void) +{ + ldi_handle_t lh; + ldi_ev_callback_t callb; + ldi_ev_cookie_t dgrd_cookie; + + if (ldi_ev_get_cookie(lh, LDI_EV_DEGRADE, &dgrd_cookie) + == LDI_EV_FAILURE) + goto fail; + + /* no notify callbacks allowed for degrade events */ + callb.cb_vers = LDI_EV_CB_VERS; + callb.cb_notify = NULL; /* NULL, notify cannot be used for + DEGRADE */ + callb.cb_finalize = dgrd_finalize; + + if (ldi_ev_register_callbacks(lh, dgrd_cookie, &callb, arg, &id) + != LDI_EV_SUCCESS) + goto fail; +} + +static void +event_unregister(ldi_ev_callback_id_t id) +{ + ldi_ev_remove_callbacks(id); +} + +/* + * For degrade events. ldi_result will always be LDI_EV_SUCCESS + */ +static void +dgrd_finalize(ldi_handle_t lh, ldi_ev_cookie_t off_cookie, + int ldi_result, void *arg, void *ev_data) +{ + ASSERT(ldi_result == LDI_EV_SUCCESS); + ASSERT(strcmp(ldi_ev_get_type(off_cookie), LDI_EV_DEGRADE) == 0); + + widget_map(lh, &minor, &spec_type); + + widget_reconfigure(lh, RELEASE); + + ldi_ev_finalize(dip, minor, spec_type, LDI_EV_SUCCESS, d + grd_cookie, ev_data); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBldi_ev_finalize\fR(9F), \fBldi_ev_get_cookie\fR(9F), +\fBldi_ev_notify\fR(9F), \fBldi_ev_remove_callbacks\fR(9F) diff --git a/usr/src/man/man9f/ldi_ev_remove_callbacks.9f b/usr/src/man/man9f/ldi_ev_remove_callbacks.9f new file mode 100644 index 0000000000..f2fde4bd24 --- /dev/null +++ b/usr/src/man/man9f/ldi_ev_remove_callbacks.9f @@ -0,0 +1,60 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldi_ev_remove_callbacks 9F "21 Aug 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_ev_remove_callbacks \- remove all callbacks for a given callback ID +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBvoid\fR \fBldi_ev_remove_callbacks\fR(\fIldi_ev_callback_id_t id\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIldi_ev_callback_id_t id\fR\fR +.ad +.sp .6 +.RS 4n +An opaque data structure returned on successful calls to +\fBldi_ev_register_callbacks\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_ev_remove_callback()\fR function unregisters any callbacks that were +registered via \fBldi_ev_register_callbacks\fR(9F). Once this function returns, +the callback \fBID\fR is no longer valid. +.sp +.LP +The finalize and notify callbacks exist independently of the \fBLDI\fR handle +and are not automatically removed when the \fBLDI\fR handle is closed. The +layered driver removes these callbacks via \fBldi_ev_remove_callbacks()\fR() +when the callbacks are no longer needed. The \fBLDI\fR framework may panic the +system if the entity registering the callback (a \fBdev_t\fR, \fBdip\fR or +\fBmodule\fR) no longer exists on the system and the callbacks have not been +unregistered. +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +This function can be called from user and kernel contexts only. +.SH SEE ALSO +.sp +.LP +\fBldi_ev_get_cookie\fR(9F), \fBldi_ev_register_callbacks\fR(9F) diff --git a/usr/src/man/man9f/ldi_get_dev.9f b/usr/src/man/man9f/ldi_get_dev.9f new file mode 100644 index 0000000000..16d6845039 --- /dev/null +++ b/usr/src/man/man9f/ldi_get_dev.9f @@ -0,0 +1,165 @@ +'\" 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 ldi_get_dev 9F "3 June 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_get_dev, ldi_get_otyp, ldi_get_devid, ldi_get_minor_name \- Extract +information from a layered handle +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_get_dev\fR(\fBldi_handle_t lh\fR, \fBdev_t *\fR\fIdevp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldi_get_otyp\fR(\fBldi_handle_t lh\fR, \fBint *\fR\fIotyp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldi_get_devid\fR(\fBldi_handle_t lh\fR, \fBddi_devid_t *\fR\fIdevid\fR); +.fi + +.LP +.nf +\fBint\fR \fBldi_get_minor_name\fR(\fBldi_handle_t lh\fR, \fBchar **\fR\fIminor_name\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR \fR +.ad +.RS 15n +.rt +Layered handle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIotyp\fR \fR +.ad +.RS 15n +.rt +Indicates on which interface the driver was opened. Valid settings are: +.sp +.ne 2 +.mk +.na +\fBOTYP_BLK\fR +.ad +.RS 12n +.rt +Open device block interface. +.RE + +.sp +.ne 2 +.mk +.na +\fBOTYP_CHR\fR +.ad +.RS 12n +.rt +Open device character interface. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdevp\fR \fR +.ad +.RS 15n +.rt +Pointer to a device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdevid\fR \fR +.ad +.RS 15n +.rt +Device ID. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIminor_name\fR \fR +.ad +.RS 15n +.rt +Minor device node name. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_get_dev()\fR function retrieves the \fBdev_t\fR associated with a +layered handle. +.sp +.LP +The \fBldi_get_otyp()\fR retrieves the open flag that was used to open the +device associated with the layered handle. +.sp +.LP +The \fBldi_get_devid()\fR function retrieves a \fIdevid\fR for the device +associated with the layered handle. The caller should use +\fBddi_devid_free()\fR to free the devid when done with it. +.sp +.LP +The \fBldi_get_minor_name()\fR function retrieves the name of the minor node +opened for the device associated with the layered handle. +\fBldi_get_minor_name()\fR allocates a buffer containing the minor node name +and returns it via the \fIminor_name\fR parameter. The caller should use +\fBkmem_free()\fR to release the buffer when done with it. +.SH RETURN VALUES +.sp +.LP +The \fBldi_get_dev()\fR, \fBldi_get_otyp()\fR, \fBldi_get_devid()\fR, and +\fBldi_get_devid()\fR functions return \fB0\fR upon success. +.sp +.LP +In case of an error, the following values may be returned: +.sp +.ne 2 +.mk +.na +\fBEINVAL\fR +.ad +.RS 11n +.rt +Invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fBENOTSUP\fR +.ad +.RS 11n +.rt +The operation is not supported for this device. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. diff --git a/usr/src/man/man9f/ldi_get_eventcookie.9f b/usr/src/man/man9f/ldi_get_eventcookie.9f new file mode 100644 index 0000000000..7535caa426 --- /dev/null +++ b/usr/src/man/man9f/ldi_get_eventcookie.9f @@ -0,0 +1,109 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldi_get_eventcookie 9F "21 Aug 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_get_eventcookie \- retrieve NDI event service cookie +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi_obsolete.h> + +\fBint\fR \fBldi_get_eventcookie\fR(\fBldi_handle_t\fR \fIlh\fR, \fIchar *name\fR + \fIddi_eventcookie_t *ecp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Obsolete +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIldi_handle_t lh\fR\fR +.ad +.RS 26n +.rt +Layered handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIchar *name\fR\fR +.ad +.RS 26n +.rt +null-terminated string containing the event name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIddi_eventcookie_t *ecp\fR\fR +.ad +.RS 26n +.rt +Pointer to the kernel event cookie. +.RE + +.SH DESCRIPTION +.sp +.LP +This function is obsolete and is only maintained for compatibility. Use of this +function is strongly discouraged. For equivalent functionality provided by new +interfaces, see \fBldi_ev_get_cookie\fR(9F) and +\fBldi_ev_register_callbacks\fR(9F). +.sp +.LP +The \fBldi_get_eventcookie()\fR function queries the device tree for a cookie +matching the given event name and returns a reference to that cookie. The +search is performed by calling up the device tree hierarchy of the device +represented by the layered driver handle until the request is satisfied by a +bus nexus driver, or the top of the dev_info tree is reached. +.sp +.LP +The cookie returned by this function can be used to register a callback handler +with \fBldi_add_event_handler\fR(9F). +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Cookie handle is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Request was not serviceable by any nexus driver in the target device's +ancestral device tree hierarchy. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel contexts. +.SH SEE ALSO +.sp +.LP +\fBldi_ev_get_cookie\fR(9F), \fBldi_ev_register_callbacks\fR(9F), +\fBldi_add_event_handler\fR(9F), \fBldi_remove_event_handler\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ldi_get_size.9f b/usr/src/man/man9f/ldi_get_size.9f new file mode 100644 index 0000000000..9d8edea96a --- /dev/null +++ b/usr/src/man/man9f/ldi_get_size.9f @@ -0,0 +1,84 @@ +'\" 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 ldi_get_size 9F "18 Mar 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_get_size \- Retrieve device size +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_get_size\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint64_t *\fR\fIsizep\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR \fR +.ad +.RS 10n +.rt +Layered handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsizep\fR \fR +.ad +.RS 10n +.rt +Pointer to the caller's unsigned 64-bit integer buffer. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_get_size()\fR function uses the layered driver handle to calculate +and return a device's size. The device size is returned within the caller +supplied buffer (*\fIsizep\fR). A valid layered driver handle must be obtained +via the \fBldi_open_by_name\fR(9F) interface prior to calling +\fBldi_get_size()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBldi_get_size()\fR function returns the following values: +.sp +.ne 2 +.mk +.na +\fBDDI_SUCCESS\fR +.ad +.RS 15n +.rt +The device size has been returned within the caller supplied buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fBDDI_FAILURE\fR +.ad +.RS 15n +.rt +The device size could not be found or determined. +.RE + +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBldi_open_by_name\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ldi_ident_from_dev.9f b/usr/src/man/man9f/ldi_ident_from_dev.9f new file mode 100644 index 0000000000..8af41a1ae1 --- /dev/null +++ b/usr/src/man/man9f/ldi_ident_from_dev.9f @@ -0,0 +1,123 @@ +'\" 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 ldi_ident_from_dev 9F "26 Mar 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_ident_from_dev, ldi_ident_from_stream, ldi_ident_from_dip, +ldi_ident_release \- ldi cookie management +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_ident_from_dip\fR(\fBdev_info_t *\fR\fIdip\fR, \fBldi_ident_t *\fR\fIlip\fR); +.fi + +.LP +.nf +\fBint\fR \fBldi_ident_from_dev\fR(\fBdev_t\fR \fIdev\fR, \fBldi_ident_t *\fR\fIlip\fR); +.fi + +.LP +.nf +\fBint\fR \fBldi_ident_from_stream\fR(\fBstruct queue *\fR\fIsq\fR, \fBldi_ident_t *\fR\fIlip\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBldi_ident_release\fR(\fBldi_ident_t\fR \fIli\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIli\fR\fR +.ad +.RS 7n +.rt +ldi identifier +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlip\fR\fR +.ad +.RS 7n +.rt +ldi identifier pointer +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 7n +.rt +pointer to device info node +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR\fR +.ad +.RS 7n +.rt +device number +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsq\fR\fR +.ad +.RS 7n +.rt +pointer to a stream queue +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_ident_from_dev()\fR function allocates and returns an ldi +identifier that is associated with the device number specified by \fIdev\fR. +The new ldi identifier is returned in the ldi identifier pointer parameter +\fIlip\fR. +.sp +.LP +The \fBldi_ident_from_dip()\fR function allocates and returns an ldi +identifier that is associated with the device info node pointed to by dip. The +new ldi identifier is returned in the ldi identifier pointer parameter +\fIlip\fR. +.sp +.LP +The \fBldi_ident_from_stream()\fR function allocates and returns an ldi +identifier that is associated with the stream pointed to by \fIqueue\fR. The +new ldi identifier is returned in the ldi identifier pointer parameter +\fIlip\fR. +.sp +.LP +The \fBldi_ident_release()\fR function releases an identifier that was +allocated by one of the \fBldi_ident_from_*()\fR functions. +.SH RETURN VALUES +.sp +.LP +The \fBldi_ident_from_dev()\fR, \fBldi_ident_from_dip()\fR, and +\fBldi_ident_from_stream()\fR functions return \fB0\fR upon success. +.sp +.LP +All of these functions return \fBEINVAL\fR for invalid input parameters. +.SH CONTEXT +.sp +.LP +These functions can be called from user or kernel context. diff --git a/usr/src/man/man9f/ldi_ioctl.9f b/usr/src/man/man9f/ldi_ioctl.9f new file mode 100644 index 0000000000..f48c9d04ea --- /dev/null +++ b/usr/src/man/man9f/ldi_ioctl.9f @@ -0,0 +1,195 @@ +'\" 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 ldi_ioctl 9F "3 June 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_ioctl \- send an ioctl to a device +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + + + +\fBint\fR \fBldi_ioctl\fR(\fBldi_handle_t\fR \fIlh\fR, \fBint\fR \fIcmd\fR, \fBintptr_t\fR \fIarg\fR, \fBint\fR \fImode\fR, + \fBcred_t *\fR\fIcr\fR, \fBint *\fR\fIrvalp\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR\fR +.ad +.RS 9n +.rt +Layered handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcr\fR\fR +.ad +.RS 9n +.rt +Pointer to a credential structure used to open a device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrvalp\fR\fR +.ad +.RS 9n +.rt +Caller return value. (May be set by driver and is valid only if the +\fBioctl()\fR succeeds). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmd\fR\fR +.ad +.RS 9n +.rt +Command argument. Interpreted by driver \fBioctl()\fR as the operation to be +performed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 9n +.rt +Driver parameter. Argument interpretation is driver dependent and usually +depends on the command type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImode\fR\fR +.ad +.RS 9n +.rt +Bit field that contains: +.sp +.ne 2 +.mk +.na +\fBFKIOCTL\fR +.ad +.RS 11n +.rt +Inform the target device that the ioctl originated from within the kernel. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_ioctl()\fR function passes an ioctl request to the device entry +point for the device specified by the layered handle. This operation is +supported for block, character, and streams devices. +.sp +.LP +If \fIarg\fR is interpreted as a pointer (that is, as not an immediate value) +and the data pointed to by \fIarg\fR is in the kernels address space, the +\fBFKIOCTL\fR flag should be set. This indicates to the target driver that no +data model conversion is necessary. +.sp +.LP +If the caller of \fBldi_ioctl()\fR is not the originator of the ioctl data +pointed to by \fIarg\fR, (for example, when passing on an ioctl request from a +user process), the caller must pass on the mode parameter from the original +ioctl. This is because the mode parameter contains the contains the +\fBFMODELS\fR bits that enable the target driver to determine the data model of +the process which originated the ioctl and perform any necessary conversions. +See \fBddi_model_convert_from\fR(9F) for more information. +.SH STREAM IOCTLS +.sp +.LP +For a general description of streams ioctls see \fBstreamio\fR(7I). +\fBldi_ioctl()\fR supports a number of streams ioctls, using layered handles in +the place of file descriptors. When issuing streams ioctls the \fBFKIOCTL\fR +parameter should be specified. The possible return values for supported ioctl +commands are also documented in \fBstreamio\fR(7I). +.sp +.LP +The following streams ioctls are supported: +.sp +.ne 2 +.mk +.na +\fBI_PLINK\fR +.ad +.RS 13n +.rt +Behaves as documented in \fBstreamio\fR(7I). The layered handle \fIlh\fR should +point to the streams multiplexer. The \fIarg\fR parameter should point to a +layered handle for another streams driver. +.RE + +.sp +.ne 2 +.mk +.na +\fBI_UNPLINK\fR +.ad +.RS 13n +.rt +Behaves as documented in \fBstreamio\fR(7I)). The layered handle \fIlh\fR +should point to the streams multiplexer. The \fIarg\fR parameter is the +multiplexor ID number returned by \fBI_PLINK\fR when the streams were linked. +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBldi_ioctl()\fR function returns \fB0\fR upon success. If a failure +occurs before the request is passed on to the device, possible return values +are shown below. Otherwise any other error number may be returned by the +device. +.sp +.ne 2 +.mk +.na +\fBEINVAL\fR +.ad +.RS 11n +.rt +Invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fBENOTSUP\fR +.ad +.RS 11n +.rt +Operation is not supported for this device. +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBstreamio\fR(7I), \fBddi_model_convert_from\fR(9F) diff --git a/usr/src/man/man9f/ldi_open_by_dev.9f b/usr/src/man/man9f/ldi_open_by_dev.9f new file mode 100644 index 0000000000..cc006ccba9 --- /dev/null +++ b/usr/src/man/man9f/ldi_open_by_dev.9f @@ -0,0 +1,402 @@ +'\" 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 ldi_open_by_dev 9F "9 Aug 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_open_by_dev, ldi_open_by_name, ldi_open_by_devid, ldi_close \- open and +close devices +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_open_by_dev\fR(\fBdev_t *\fR\fIdevp\fR, \fBint\fR \fIotyp\fR, \fBint\fR \fIflag\fR, \fBcred_t *\fR\fIcr\fR, + \fBldi_handle_t *\fR\fIlhp\fR, \fBldi_ident_t\fR \fIli\fR); +.fi + +.LP +.nf +\fBint\fR \fBldi_open_by_name\fR(\fBchar *\fR\fIpathname\fR, \fBint\fR \fIflag\fR, \fBcred_t *\fR\fIcr\fR, + \fBldi_handle_t *\fR\fIlhp\fR, \fBldi_ident_t\fR \fIli\fR); +.fi + +.LP +.nf +\fBint\fR \fBldi_open_by_devid\fR(\fBddi_devid_t\fR \fIdevid\fR, \fBchar *\fR\fIminor_name\fR, \fBint\fR \fIflag\fR, + \fBcred_t *\fR\fIcr\fR, \fBldi_handle_t *\fR\fIlhp\fR, \fBldi_ident_t\fR \fIli\fR); +.fi + +.LP +.nf +\fBint\fR \fBldi_close\fR(\fBldi_handle_t\fR \fIlh\fR, \fBint\fR \fIflag\fR, \fBcred_ t *\fR\fIcr\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR\fR +.ad +.RS 14n +.rt +Layered handle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlhp\fR\fR +.ad +.RS 14n +.rt +Pointer to a layered handle that is returned upon a successful open. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIli\fR\fR +.ad +.RS 14n +.rt +LDI identifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcr\fR\fR +.ad +.RS 14n +.rt +Pointer to the credential structure used to open a device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdevp\fR\fR +.ad +.RS 14n +.rt +Pointer to a device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpathname\fR\fR +.ad +.RS 14n +.rt +Pathname to a device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdevid\fR\fR +.ad +.RS 14n +.rt +Device ID. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIminor_name\fR\fR +.ad +.RS 14n +.rt +Minor device node name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIotyp\fR\fR +.ad +.RS 14n +.rt +Flag passed to the driver indicating which interface is open. Valid settings +are: +.sp +.ne 2 +.mk +.na +\fBOTYP_BLK\fR +.ad +.RS 12n +.rt +Open the device block interface. +.RE + +.sp +.ne 2 +.mk +.na +\fBOTYP_CHR\fR +.ad +.RS 12n +.rt +Open the device character interface. +.RE + +Only one OTYP flag can be specified. To open streams devices, specify +\fBOTYP_CHR\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 14n +.rt +Bit field that instructs the driver on how to open the device. Valid settings +are: +.sp +.ne 2 +.mk +.na +\fBFEXCL\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 +\fBFNDELAY\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 +\fBFREAD\fR +.ad +.RS 11n +.rt +Open the device with read-only permission. (If ORed with \fBFWRITE\fR, allow +both read and write access). +.RE + +.sp +.ne 2 +.mk +.na +\fBFWRITE\fR +.ad +.RS 11n +.rt +Open a device with write-only permission (if ORed with \fBFREAD\fR, then allow +both read and write access). +.RE + +.sp +.ne 2 +.mk +.na +\fBFNOCTTY\fR +.ad +.RS 11n +.rt +Open the device. If the device is a tty, do not attempt to open it as a +session-controlling tty. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_open_by_dev()\fR, \fBldi_open_by_name()\fR and +\fBldi_open_by_devid()\fR functions allow a caller to open a block, character, +or streams device. Upon a successful open, a layered handle to the device is +returned via the layered handle pointed to by \fIlhp\fR. The ldi identifier +passed to these functions is previously allocated with +\fBldi_ident_from_stream\fR(9F), \fBldi_ident_from_dev\fR(9F), and +\fBldi_ident_from_dip\fR(9F). +.sp +.LP +The \fBldi_open_by_dev()\fR function opens a device specified by the dev_t +pointed to by devp. Upon successful open, the caller should check the value of +the dev_t to see if it has changed. (Cloning devices will change this value +during opens.) When opening a streams device, otyp must be OTYP_CHR. +.sp +.LP +The \fBldi_open_by_devid()\fR function opens a device by devid. The caller must +specify the minor node name to open. +.sp +.LP +The \fBldi_open_by_name()\fR function opens a device by pathname. Pathname is a +null terminated string in the kernel address space. Pathname must be an +absolute path, meaning that it must begin with '/'. The format of the pathname +supplied to this function is either a \fB/devices\fR path or any other +filesystem path to a device node. Opens utilizing \fB/devices\fR paths are +supported before root is mounted. Opens utilizing other filesystem paths to +device nodes are supported only if root is already mounted. +.sp +.LP +The \fBldi_close()\fR function closes a layered handle that was obtained with +either \fBldi_open_by_dev()\fR, \fBldi_open_by_name()\fR, or +\fBldi_open_by_devid()\fR. After \fBldi_close()\fR returns the layered handle, +the \fIlh\fR that was previously passed in is no longer valid. +.SH RETURN VALUES +.sp +.LP +The \fBldi_close()\fR function returns \fB0\fR for success. \fBEINVAL\fR is +returned for invalid input parameters. Otherwise, any other error number may be +returned by the device. +.sp +.LP +The \fBldi_open_by_dev()\fR and \fBldi_open_by_devid()\fR functions return +\fB0\fR upon success. If a failure occurs before the device is open, possible +return values are shown below. Otherwise any other error number may be returned +by the device. +.sp +.ne 2 +.mk +.na +\fBEINVAL\fR +.ad +.RS 10n +.rt +Invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fBENODEV\fR +.ad +.RS 10n +.rt +Requested device does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fBENXIO\fR +.ad +.RS 10n +.rt +Unsupported device operation or access mode. +.RE + +.sp +.LP +The \fBldi_open_by_name()\fR function returns \fB0\fR upon success. If a +failure occurs before the device is open, possible return values are shown +below. Otherwise any other error number may be returned by the device. +.sp +.ne 2 +.mk +.na +\fBEINVAL\fR +.ad +.RS 10n +.rt +Invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fBENODEV\fR +.ad +.RS 10n +.rt +Requested device path does not exist. +.RE + +.sp +.ne 2 +.mk +.na +\fBEACCES\fR +.ad +.RS 10n +.rt +Search permission is denied on a component of the path prefix, or the file +exists and the permissions specified by \fIcr\fR are denied. +.RE + +.sp +.ne 2 +.mk +.na +\fBENXIO\fR +.ad +.RS 10n +.rt +Unsupported device operation or access mode. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.sp +.LP +These functions should not be called from a device's attach, detach, or power +entry point. This could result in a system crash or deadlock. +.SH SEE ALSO +.sp +.LP +\fBscsi_vhci\fR(7D), \fBldi_ident_from_dev\fR(9F), +\fBldi_ident_from_dip\fR(9F), \fBldi_ident_from_stream\fR(9F) +.SH NOTES +.sp +.LP +Use only OTYP_CHR or OTYP_BLK options when you use the \fBldi_open_by_dev()\fR +and \fBldi_open_by_devid()\fR functions to open a device. Other flags, +including OTYP_LYR, have been deprecated and should not be used with these +interfaces. +.sp +.LP +The caller should be aware of cases when multiple paths to a single device may +exist. (This can occur for scsi disk devices if \fBscsi_vhci\fR(7D)) is +disabled or a disk is connected to multiple controllers not supported by +scsi_vhci(7D). +.sp +.LP +In these cases, \fBldi_open_by_devid()\fR returns a device handle that +corresponds to a particular path to a target device. This path may not be the +same across multiple calls to \fBldi_open_by_devid()\fR. Device handles +associated with the same device but different access paths should have +different filesystem device paths and dev_t values. +.sp +.LP +In the cases where multiple paths to a device exist and access to the device +has not been virtualized via MPXIO (as with scsi disk devices not accessed via +\fBscsi_vhci\fR(7D)), the LDI does not provide any path fail-over capabilities. +If the caller wishes to do their own path management and failover they should +open all available paths to a device via \fBldi_open_by_name()\fR. diff --git a/usr/src/man/man9f/ldi_poll.9f b/usr/src/man/man9f/ldi_poll.9f new file mode 100644 index 0000000000..8b6fc1aa66 --- /dev/null +++ b/usr/src/man/man9f/ldi_poll.9f @@ -0,0 +1,214 @@ +'\" 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 ldi_poll 9F "3 June 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_poll \- Poll a device +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + + + +\fBint\fR \fBldi_poll\fR(\fBldi_handle_t\fR \fIlh\fR, \fBshort\fR \fIevents\fR, \fBint\fR \fIanyyet\fR, \fBshort *\fR\fIreventsp\fR, + \fBstruct pollhead **\fR\fIphpp\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR \fR +.ad +.RS 13n +.rt +Layered handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevents\fR \fR +.ad +.RS 13n +.rt +Potential events. Valid events are: +.sp +.ne 2 +.mk +.na +\fBPOLLIN\fR +.ad +.RS 14n +.rt +Data other than high priority data may be read without blocking. +.RE + +.sp +.ne 2 +.mk +.na +\fBPOLLOUT\fR +.ad +.RS 14n +.rt +Normal data may be written without blocking. +.RE + +.sp +.ne 2 +.mk +.na +\fBPOLLPRI\fR +.ad +.RS 14n +.rt +High priority data may be received without blocking. +.RE + +.sp +.ne 2 +.mk +.na +\fBPOLLHUP\fR +.ad +.RS 14n +.rt +Device hangup has occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fBPOLLERR\fR +.ad +.RS 14n +.rt +An error has occurred on the device. +.RE + +.sp +.ne 2 +.mk +.na +\fBPOLLRDNORM\fR +.ad +.RS 14n +.rt +Normal data (priority band = 0) may be read without blocking. +.RE + +.sp +.ne 2 +.mk +.na +\fBPOLLRDBAND\fR +.ad +.RS 14n +.rt +Data from a non-zero priority band may be read without blocking. +.RE + +.sp +.ne 2 +.mk +.na +\fBPOLLWRNORM\fR +.ad +.RS 14n +.rt +Data other than high priority data may be read without blocking. +.RE + +.sp +.ne 2 +.mk +.na +\fBPOLLWRBAND\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 13n +.rt +A flag that is non-zero if any other file descriptors in the +pollfd array have events pending. The \fBpoll\fR(2) system call takes a pointer +to an array of pollfd structures as one of its arguments. See +\fBpoll\fR(2) for more details. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreventsp\fR \fR +.ad +.RS 13n +.rt +Pointer to a bitmask of the returned events satisfied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIphpp\fR \fR +.ad +.RS 13n +.rt +Pointer to a pointer to a pollhead structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_poll()\fR function passes a poll request to the device entry point +for the device specified by the layered handle. This operation is supported for +block, character, and streams devices. +.SH RETURN VALUES +.sp +.LP +The \fBldi_poll()\fR function returns \fB0\fR upon success. If a failure occurs +before the request is passed on to the device, possible return values are: +.sp +.ne 2 +.mk +.na +\fBEINVAL\fR +.ad +.RS 11n +.rt +Invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fBENOTSUP\fR +.ad +.RS 11n +.rt +Operation is not supported for this device. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. diff --git a/usr/src/man/man9f/ldi_prop_exists.9f b/usr/src/man/man9f/ldi_prop_exists.9f new file mode 100644 index 0000000000..f42573f281 --- /dev/null +++ b/usr/src/man/man9f/ldi_prop_exists.9f @@ -0,0 +1,183 @@ +'\" 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 ldi_prop_exists 9F "3 June 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_prop_exists \- Check for the existence of a property +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_prop_exists\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR\fR +.ad +.RS 9n +.rt +Layered handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 9n +.rt +Possible flag values are some combination of: +.RE + +.sp +.ne 2 +.mk +.na +\fBLDI_DEV_T_ANY\fR +.ad +.RS 21n +.rt +Match the lookup request independent of the actual dev_t value that was used +when the property was created. The flag indicates any dev_t value (including +DDI_DEV_T_NONE) associated with a possible property match satisfies the +matching criteria. +.RE + +.sp +.ne 2 +.mk +.na +\fBDDI_PROP_DONTPASS\fR +.ad +.RS 21n +.rt +Do not pass request to parent device information node if the property is not +found. +.RE + +.sp +.ne 2 +.mk +.na +\fBDDI_PROP_NOTPROM\fR +.ad +.RS 21n +.rt +Do not look at PROM properties (ignored on platforms that do not support PROM +properties). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 21n +.rt +String containing the name of the property. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBldi_prop_exists()\fR checks for the existence of a property associated with +a device represented by the layered driver handle, regardless of the property +value data type. +.sp +.LP +Properties are searched for based on the dip and dev_t values associated with +the layered handle, and the property name. This association is handled by the +layered driver infrastructure on behalf of the consumers of +\fBldi_prop_exists()\fR. +.sp +.LP +The property search order is as follows: +.RS +4 +.TP +1. +Search software-properties created by the driver. +.RE +.RS +4 +.TP +2. +Search the software properties created by the system (or nexus nodes in the +device info tree). +.RE +.RS +4 +.TP +3. +Search the driver global properties list. +.RE +.RS +4 +.TP +4. +If DDI_PROP_NOTPROM is not set, search the PROM properties (if they exist). +.RE +.RS +4 +.TP +5. +If DDI_PROP_DONTPASS is not set, pass this request to the parent device +information node of the device represented by the layered handle. +.RE +.RS +4 +.TP +6. +Return \fB0\fR if not found and \fB1\fR if found. +.RE +.sp +.LP +Typically, the specific dev_t value associated with the device represented by +the layered handle (ldi_handle_t) is used as a part of the property match +criteria. This association is handled by the layered driver infrastructure on +behalf of the consumers of the ldi property look up functions. +.sp +.LP +However, if the LDI_DEV_T_ANY flag is used, the ldi property lookup functions +will match the request regardless of the dev_t value associated with the +property at the time of its creation. If a property was created with a dev_t +set to DDI_DEV_T_NONE, the only way to look up this property is with the +LDI_DEV_T_ANY flag. PROM properties are always created with a dev_t set to +DDI_DEV_T_NONE. +.sp +.LP +name must always be set to the name of the property being looked up. +.SH RETURN VALUES +.sp +.LP +\fBldi_prop_exists()\fR returns \fB1\fR if the property exists and \fB0\fR +otherwise. +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. +.SH EXAMPLE +.sp +.in +2 +.nf +The following example demonstrates the use of ldi_prop_exists(). + + /* Determine the existence of the "interrupts" property */ + ldi_prop_exists(lh, LDI_DEV_T_ANY|DDI_PROP_NOTPROM, "interrupts"); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBddi_prop_exists(9F)\fR +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ldi_prop_get_int.9f b/usr/src/man/man9f/ldi_prop_get_int.9f new file mode 100644 index 0000000000..1f42880910 --- /dev/null +++ b/usr/src/man/man9f/ldi_prop_get_int.9f @@ -0,0 +1,219 @@ +'\" 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 ldi_prop_get_int 9F "3 June 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_prop_get_int, ldi_prop_get_int64 \- Lookup integer property +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_prop_get_int\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, + \fBint\fR \fIdefvalue\fR); +.fi + +.LP +.nf +\fBint\fR\fB64_t ldi_prop_get_int64\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, + \fBint64_t \fR\fIdefvalue\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR \fR +.ad +.RS 10n +.rt +Layered handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR \fR +.ad +.RS 10n +.rt +Possible flag values are some combination of: +.sp +.ne 2 +.mk +.na +\fBLDI_DEV_T_ANY\fR +.ad +.RS 21n +.rt +Match the lookup request independent of the actual dev_t value that was used +when the property was created. Indicates any dev_t value (including +DDI_DEV_T_NONE) associated with a possible property match satisfies the +matching criteria. +.RE + +.sp +.ne 2 +.mk +.na +\fBDDI_PROP_DONTPASS\fR +.ad +.RS 21n +.rt +Do not pass request to parent device information node if property not found. +.RE + +.sp +.ne 2 +.mk +.na +\fBDDI_PROP_NOTPROM\fR +.ad +.RS 21n +.rt +Do not look at PROM properties (ignored on platforms that do not support PROM +properties). +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBname\fR +.ad +.RS 12n +.rt +String containing the property name. +.RE + +.sp +.ne 2 +.mk +.na +\fBdefvalue\fR +.ad +.RS 12n +.rt +Integer value that is returned if the property is not found. +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH DESCRIPTION +.sp +.LP +The \fBldi_prop_get_int()\fR and \fBldi_prop_get_int64()\fR functions search +for an integer property associated with a device represented by the layered +driver handle. If the integer property is found, the functions return the +property value. +.sp +.LP +Properties are searched for based on the dip and dev_t values associated with +the layered handle, the property name, and type of the data (integer). +.sp +.LP +The property search order is as follows: +.RS +4 +.TP +1. +Search software properties created by the driver. +.RE +.RS +4 +.TP +2. +Search the software properties created by the system (or nexus nodes in the +device info tree). +.RE +.RS +4 +.TP +3. +Search the driver global properties list. +.RE +.RS +4 +.TP +4. +If DDI_PROP_NOTPROM is not set, search the PROM properties (if they exist). +.RE +.RS +4 +.TP +5. +If DDI_PROP_DONTPASS is not set, pass this request to the parent device +information node of the device represented by the layered handle. +.RE +.RS +4 +.TP +6. +Return defvalue. +.RE +.sp +.LP +Typically, the specific dev_t value associated with the device represented by +the layered handle (ldi_handle_t) is used as a part of the property match +criteria. This association is handled by the layered driver infrastructure on +behalf of the consumers of the ldi property look up functions. +.sp +.LP +However, if the LDI_DEV_T_ANY flag is used, the ldi property lookup functions +match the request regardless of the dev_t value associated with the property at +the time of its creation. If a property was created with a dev_t set to +DDI_DEV_T_NONE, the only way to look up this property is with the LDI_DEV_T_ANY +flag. PROM properties are always created with a dev_t set to DDI_DEV_T_NONE. +.sp +.LP +name must always be set to the name of the property being looked up. +.sp +.LP +The return value of the routine is the value of property. If the property is +not found, the argument defvalue is returned as the property value. +.sp +.LP +\fBldi_prop_get_int64()\fR does not search the PROM for 64-bit property values. +.SH RETURN VALUES +.sp +.LP +\fBldi_prop_get_int()\fR and \fBldi_prop_get_int64()\fR return the property +value. If the property is not found, the argument \fBdefvalue\fR is returned. +If the property is found, but cannot be decoded into an int or an int64_t, +DDI_PROP_NOT_FOUND is returned. +.SH CONTEXT +.sp +.LP +\fBldi_prop_get_int()\fR and \fBldi_prop_get_int64()\fR can be called from user +or kernel context. +.SH EXAMPLES +.sp +.LP +Using\fB ldi_prop_get_int64()\fR. +.sp +.in +2 +.nf +The following example demonstrates the use of ldi_prop_get_int64(). + + /* + * Get the value of the integer "timeout" property, using + * our own default if no such property exists + */ + + int64_t timeout, defval; + + timeout = ldi_prop_get_int64(lh, LDI_DEV_T_ANY|DDI_PROP_DONTPASS, + propname, defval); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBddi_prop_get_int\fR(9F), \fBddi_prop_get_int64\fR(9F), +\fBldi_prop_exists\fR(9F). +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ldi_prop_lookup_int_array.9f b/usr/src/man/man9f/ldi_prop_lookup_int_array.9f new file mode 100644 index 0000000000..1ab7719ae7 --- /dev/null +++ b/usr/src/man/man9f/ldi_prop_lookup_int_array.9f @@ -0,0 +1,480 @@ +'\" 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 ldi_prop_lookup_int_array 9F "3 June 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_prop_lookup_int_array, ldi_prop_lookup_int64_array, +ldi_prop_lookup_string_array, ldi_prop_lookup_string, +ldi_prop_lookup_byte_array \- Lookup property information +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_prop_lookup_int_array\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, + \fBint **\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldi_prop_lookup_int64_array\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, + \fBint64_t **\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldi_prop_lookup_string_array\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint_t\fR \fIflags\fR, + \fBchar *\fR\fIname\fR, \fBchar ***\fR\fIdatap\fR, \fBuint_t *\fR\fInelementsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBldi_prop_lookup_string\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, + \fBchar **\fR\fIdatap\fR); +.fi + +.LP +.nf +\fBint\fR \fBldi_prop_lookup_byte_array\fR(\fBldi_handle_t\fR \fIlh\fR, \fBuint_t\fR \fIflags\fR, \fBchar *\fR\fIname\fR, + \fBuchar_t **\fR\fIdatap\fR, \fBuint_t *\fR\fInelements\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR\fR +.ad +.RS 9n +.rt +Layered handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 9n +.rt +Possible flag values are some combination of: +.sp +.ne 2 +.mk +.na +\fBLDI_DEV_T_ANY\fR +.ad +.RS 21n +.rt +Match the lookup request independent of the actual \fBdev_t\fR value that was +used when the property was created. The flag indicates any \fBdev_t\fR value +(including DDI_DEV_T_NONE) associated with a possible property match will +satisfy the matching criteria. +.RE + +.sp +.ne 2 +.mk +.na +\fBDDI_PROP_DONTPASS\fR +.ad +.RS 21n +.rt +Do not pass request to parent device information node if the property is not +found. +.RE + +.sp +.ne 2 +.mk +.na +\fBDDI_PROP_NOTPROM\fR +.ad +.RS 21n +.rt +Do not look at PROM properties (ignored on platforms that do not support PROM +properties). +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fBname\fR +.ad +.RS 13n +.rt +String containing the property name. +.RE + +.sp +.ne 2 +.mk +.na +\fBnelements\fR +.ad +.RS 13n +.rt +The address of an unsigned integer which, upon successful return, contains the +number of elements accounted for in the memory pointed at by datap. Depending +on the interface you use, the elements are either integers, strings or bytes. +.RE + +.sp +.LP +datap +.sp +.ne 2 +.mk +.na +\fBldi_prop_lookup_int_array()\fR +.ad +.sp .6 +.RS 4n +Pointer address to an array of integers which, upon successful return, point to +memory containing the integer array property value. +.RE + +.sp +.ne 2 +.mk +.na +\fBldi_prop_lookup_int64_array()\fR +.ad +.sp .6 +.RS 4n +Pointer address to an array of 64-bit integers which, upon successful return, +point to memory containing the integer array property value. +.RE + +.sp +.ne 2 +.mk +.na +\fBldi_prop_lookup_string_array()\fR +.ad +.sp .6 +.RS 4n +Pointer address to an array of strings which, upon successful return, point to +memory containing the array of strings. The string array is formatted as an +array of pointers to NULL terminated strings, much like the argv argument to +\fBexecve(2)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBldi_prop_lookup_string()\fR +.ad +.sp .6 +.RS 4n +Pointer address to a string which, upon successful return, points to memory +containing the NULL terminated string value of the property. +.RE + +.sp +.ne 2 +.mk +.na +\fBldi_prop_lookup_byte_array()\fR +.ad +.sp .6 +.RS 4n +Pointer address to an array of bytes which, upon successful return, point to +memory containing the property byte array value. +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The property look up functions search for and, if found, return the value of a +given property. Properties are searched for based on the dip and dev_t values +associated with the layered handle, the property name, and type of the data +(integer, string, or byte). +.sp +.LP +The property search order is as follows: +.RS +4 +.TP +1. +Search software properties created by the driver. +.RE +.RS +4 +.TP +2. +Search the software properties created by the system (or nexus nodes in the +device info tree). +.RE +.RS +4 +.TP +3. +Search the driver global properties list. +.RE +.RS +4 +.TP +4. +If DDI_PROP_NOTPROM is not set, search the PROM properties (if they exist). +.RE +.RS +4 +.TP +5. +If DDI_PROP_DONTPASS is not set, pass this request to the parent device +information node of the device represented by the layered handle. +.RE +.RS +4 +.TP +6. +Return \fBDDI_PROP_NOT_FOUND\fR. +.RE +.sp +.LP +Typically, the specific dev_t value associated with the device represented by +the layered handle (ldi_handle_t) is used as a part of the property match +criteria. This association is handled by the layered driver infrastructure on +behalf of the consumers of the ldi property look up functions. +.sp +.LP +However, if the LDI_DEV_T_ANY flag is used, the ldi property lookup functions +match the request regardless of the dev_t value associated with the property at +the time of its creation. If a property was created with a dev_t set to +DDI_DEV_T_NONE, then the only way to look up this property is with the +LDI_DEV_T_ANY flag. PROM properties are always created with a dev_t set to +DDI_DEV_T_NONE. +.sp +.LP +name must always be set to the name of the property being looked up. +.sp +.LP +For the l\fBdi_prop_lookup_int_array()\fR, \fBldi_prop_lookup_int64_array()\fR, +\fBldi_prop_lookup_string_array()\fR, \fBldi_prop_lookup_string()\fR, and +\fBldi_prop_lookup_byte_array()\fR functions, datap is the address of a pointer +which, upon successful return, points to memory containing the value of the +property. In each case *datap points to a different type of property value. See +the individual descriptions of the functions below for details on the different +return values. nelementsp is the address of an unsigned integer which, upon +successful return, contains the number of integer, string or byte elements +accounted for in the memory pointed at by *datap. +.sp +.LP +All of the property look up functions may block to allocate memory needed to +hold the value of the property. +.sp +.LP +When a driver has obtained a property with any look up function and is finished +with that property, it must be freed by call \fBddi_prop_free()\fR. +\fBddi_prop_free()\fR must be called with the address of the allocated +property. For instance, if you call \fBldi_prop_lookup_int_array()\fR with +datap set to the address of a pointer to an integer, &my-int-ptr, the companion +free call is ddi_prop_free(my-int-ptr). +.sp +.LP +Property look up functions are described below: +.sp +.ne 2 +.mk +.na +\fB\fBldi_prop_lookup_int_array()\fR\fR +.ad +.sp .6 +.RS 4n +This function searches for and returns an array of integer property values. An +array of integers is defined to *nelementsp number of 4 byte long integer +elements. datap should be set to the address of a pointer to an array of +integers which, upon successful return, will point to memory containing the +integer array value of the property. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldi_prop_lookup_int64_array()\fR\fR +.ad +.sp .6 +.RS 4n +This function searches for and returns an array of integer property values. An +array of integers is defined to *nelementsp number of 8 byte long integer +elements. datap should be set to the address of a pointer to an array of +integers which, upon successful return, will point to memory containing the +integer array value of the property This function does not search the PROM for +64-bit property values. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldi_prop_lookup_string_array()\fR\fR +.ad +.sp .6 +.RS 4n +This function searches for and returns a property that is an array of strings. +datap should be set to an address of a pointer to an array of strings which, +upon successful return, will point to memory containing the array of strings. +The array of strings is formatted as an array of pointers to null-terminated +strings, much like the argv argument to \fBexecve\fR(2). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldi_prop_lookup_string()\fR\fR +.ad +.sp .6 +.RS 4n +This function searches for and returns a property that is a null-terminated +string. datap should be set to the address of a pointer to a string which, upon +successful return, points to memory containing the string value of the +property. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBldi_prop_lookup_byte_array()\fR\fR +.ad +.sp .6 +.RS 4n +This function searches for and returns a property that is an array of bytes. +datap should be set to the address of a pointer to an array of bytes which, +upon successful return, points to memory containing the byte array value of +the property. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBddi_prop_free()\fR\fR +.ad +.sp .6 +.RS 4n +Frees the resources associated with a property previously allocated using +\fBldi_prop_lookup_int_array()\fR, \fBldi_prop_lookup_int64_array()\fR, +\fBldi_prop_lookup_string_array()\fR, \fBldi_prop_lookup_string()\fR, and +\fBldi_prop_lookup_byte_array()\fR. +.RE + +.SH RETURN VALUES +.sp +.LP +The functions \fBldi_prop_lookup_int_array()\fR, +\fBldi_prop_lookup_int64_array()\fR, \fBldi_prop_lookup_string_array()\fR, +\fBldi_prop_lookup_string()\fR, and \fBldi_prop_lookup_byte_array()\fR return +the following values: +.sp +.ne 2 +.mk +.na +\fBDDI_PROP_SUCCESS\fR +.ad +.RS 26n +.rt +Property found and returned. +.RE + +.sp +.ne 2 +.mk +.na +\fBDDI_PROP_INVAL_ARG\fR +.ad +.RS 26n +.rt +If an attempt is made to look up a property with a NULL ldi handle, name is +NULL or name is a the null string. +.RE + +.sp +.ne 2 +.mk +.na +\fBDDI_PROP_NOT_FOUND\fR +.ad +.RS 26n +.rt +Property not found. +.RE + +.sp +.ne 2 +.mk +.na +\fBDDI_PROP_UNDEFINED\fR +.ad +.RS 26n +.rt +Prop explicitly undefined (see \fBddi_prop_undefine(9F\fR)). +.RE + +.sp +.ne 2 +.mk +.na +\fBDDI_PROP_CANNOT_DECODE\fR +.ad +.RS 26n +.rt +Property value cannot be decoded. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.SH EXAMPLE +.sp +.in +2 +.nf +Using ldi_prop_lookup_int64_array(). + + The following example demonstrates the use of + ldi_prop_lookup_int64_array(). + + + int64_t *options; + uint_t noptions; + + /* + * Get the data associated with the integer "options" property + * array, along with the number of option integers + */ + + if (ldi_prop_lookup_int64_array(lh, + LDI_DEV_T_ANY|DDI_PROP_NOTPROM, "options", + &options, &noptions) == DDI_PROP_SUCCESS) { + /* + * Process the options data from the property + * we just received. Let's do "our thing" with data. + */ + xx_process_options(options, noptions); + + /* + * Free the memory allocated for the property data + */ + ddi_prop_free(options); + } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBexecve\fR(2), \fBddi_prop_free\fR(9F), \fBddi_prop_lookup\fR(9F), +\fBldi_prop_exists\fR(9F) . +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ldi_putmsg.9f b/usr/src/man/man9f/ldi_putmsg.9f new file mode 100644 index 0000000000..6e194722e3 --- /dev/null +++ b/usr/src/man/man9f/ldi_putmsg.9f @@ -0,0 +1,128 @@ +'\" 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 ldi_putmsg 9F "3 June 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_putmsg, ldi_getmsg \- Read/write message blocks from/to a stream +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_putmsg\fR(\fBldi_handle_t\fR\fI lh\fR, \fBmblk_t *\fR\fIsmp\fR); +.fi + +.LP +.nf +\fBint\fR \fB ldi_getmsg\fR(\fBldi_handle_t\fR \fIlh\fR, \fBmblk_t **\fR\fIrmp\fR, \fBtimestruc_t *\fR\fItimeo\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR \fR +.ad +.RS 10n +.rt +Layered handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsmp\fR \fR +.ad +.RS 10n +.rt +Message block to send. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrmp\fR \fR +.ad +.RS 10n +.rt +Message block to receive. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItimeo\fR \fR +.ad +.RS 10n +.rt +Optional timeout for data reception. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_putmsg\fR function allows a caller to send a message block to a +streams device specified by the layered handle \fIlh\fR. Once the message (smp) +has been passed to \fBldi_putmsg()\fR, the caller must not free the message +even if an error occurs. +.sp +.LP +The \fBldi_getmsg()\fR function allows a caller to receive a message block from +a streams device specified by the layered handle \fIlh\fR. Callers must free +the message received with \fBfreemsg\fR(9F). +.sp +.LP +If a NULL timeout value is specified when the caller receives a message, the +caller sleeps until a message is received. +.SH RETURN VALUES +.sp +.LP +The \fBldi_putmsg()\fR and \fBldi_getmsg()\fR functions return \fB0\fR upon +success. If a failure occurs before the request is passed to the device, the +possible return values are shown below. Otherwise any other error number may be +returned by the device. +.sp +.ne 2 +.mk +.na +\fBEINVAL\fR +.ad +.RS 11n +.rt +Invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fBENOTSUP\fR +.ad +.RS 11n +.rt +Operation is not supported for this device. +.sp +The \fBldi_getmsg()\fR function may also return: +.sp +.ne 2 +.mk +.na +\fBETIME\fR +.ad +.RS 9n +.rt +Returned if the timeout \fBtimeo\fR expires with no messages received. +.RE + +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. diff --git a/usr/src/man/man9f/ldi_read.9f b/usr/src/man/man9f/ldi_read.9f new file mode 100644 index 0000000000..b03a36e14a --- /dev/null +++ b/usr/src/man/man9f/ldi_read.9f @@ -0,0 +1,100 @@ +'\" 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 ldi_read 9F "3 June 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_read, ldi_write \- Read and write from a device +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fB\fR\fBint\fR ldi_read(\fBldi_handle_t\fR \fIlh\fR, \fBstruct uio *\fR\fIuiop\fR, \fBcred_t *\fR\fIcr\fR); +.fi + +.LP +.nf +\fBint\fR \fB ldi_write\fR(\fBldi_handle_t\fR \fIlh\fR, \fBstruct uio *\fR\fIuiop\fR, \fBcred_t *\fR\fIcr\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR \fR +.ad +.RS 9n +.rt +Layered handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcr\fR \fR +.ad +.RS 9n +.rt +Pointer to a credential structure used to open a device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuiop\fR \fR +.ad +.RS 9n +.rt +Pointer to the \fBuio(9S)\fR structure. \fBuio(9S)\fR specifies the location +of the read or write data. (Either userland or kernel.) +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_read()\fR function passes a read request to the device entry point +for the device specified by the layered handle. This operation is supported +for block, character, and streams devices. +.sp +.LP +The \fBldi_write()\fR function passes a write request to the device entry +point for a device specified by the layered handle. This operation is supported +for block, character, and streams devices. +.SH RETURN VALUES +.sp +.LP +The \fBldi_read()\fR and \fBldi_write()\fR functions return \fB0\fR upon +success. If a failure occurs before the request is passed to the device, the +possible return values are shown below. Otherwise any other error number may be +returned by the device. +.sp +.ne 2 +.mk +.na +\fBEINVAL\fR +.ad +.RS 11n +.rt +Invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fBENOTSUP\fR +.ad +.RS 11n +.rt +Operation is not supported for this device. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. diff --git a/usr/src/man/man9f/ldi_remove_event_handler.9f b/usr/src/man/man9f/ldi_remove_event_handler.9f new file mode 100644 index 0000000000..48c50e324f --- /dev/null +++ b/usr/src/man/man9f/ldi_remove_event_handler.9f @@ -0,0 +1,94 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ldi_remove_event_handler 9F "21 Aug 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_remove_event_handler \- remove an NDI event service callback +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi_obsolete.h> + +\fBint\fR \fBldi_remove_event_handler\fR(\fBldi_handle_t\fR \fIlh\fR, + \fIldi_callback_id_t id\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Obsolete +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIldi_handle_t lh\fR\fR +.ad +.RS 24n +.rt +Layered handle representing the device for which the event notification is +requested. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIldi_callback_id_t id\fR\fR +.ad +.RS 24n +.rt +Unique system-wide registration ID returned by \fBldi_add_event_handler\fR(9F) +upon successful registration. +.RE + +.SH DESCRIPTION +.sp +.LP +This function is obsolete and is only maintained for compatibility. Use of this +function is strongly discouraged. For equivalent functionality provided by new +interfaces, see \fBldi_ev_register_callbacks\fR(9F) and +\fBldi_ev_remove_callbacks\fR(9F). +.sp +.LP +The \fBldi_remove_event_handler()\fR function removes the callback handler +specified by the registration ID (\fIldi_callback_id_t\fR). Upon successful +removal, the callback handler is removed from the system and is not invoked at +the event occurance. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Callback handler removed successfully. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Failed to remove callback handler. +.RE + +.SH CONTEXT +.sp +.LP +This function can be called from user and kernel contexts only. +.SH SEE ALSO +.sp +.LP +\fBldi_ev_register_callbacks\fR(9F), \fBldi_ev_remove_callbacks\fR(9F), +\fBldi_add_event_handler\fR(9F), \fBldi_get_eventcookie\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ldi_strategy.9f b/usr/src/man/man9f/ldi_strategy.9f new file mode 100644 index 0000000000..4411c02c5a --- /dev/null +++ b/usr/src/man/man9f/ldi_strategy.9f @@ -0,0 +1,81 @@ +'\" 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 ldi_strategy 9F "3 June 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ldi_strategy \- Device strategy request +.SH SYNOPSIS +.LP +.nf +#include <sys/sunldi.h> + +\fBint\fR \fBldi_strategy\fR(\fBldi_handle_t\fR \fIlh\fR, \fB struct buf *\fR\fIbp\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIlh\fR \fR +.ad +.RS 7n +.rt +Layered handle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR \fR +.ad +.RS 7n +.rt +Pointer to the \fBbuf(9S)\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBldi_strategy()\fR function passes a strategy request to the device entry +point for the device specified by the layered handle. This operation is +supported for block devices. +.SH RETURN VALUES +.sp +.LP +The \fBldi_strategy()\fR function returns \fB0\fR if the strategy request has +been passed on to the target device. Other possible return values are: +.sp +.ne 2 +.mk +.na +\fBEINVAL\fR +.ad +.RS 11n +.rt +Invalid input parameters. +.RE + +.sp +.ne 2 +.mk +.na +\fBENOTSUP\fR +.ad +.RS 11n +.rt +Operation is not supported for this device. +.RE + +.sp +.LP +Once the request has been passed on to the target devices strategy entry point, +any further errors will be reported by \fBbioerror\fR(9F) and +\fBbiodone\fR(9F). See the \fBstrategy\fR(9E) entry point for more information. +.SH CONTEXT +.sp +.LP +This function may be called from user or kernel context. diff --git a/usr/src/man/man9f/linkb.9f b/usr/src/man/man9f/linkb.9f new file mode 100644 index 0000000000..9f9399a35e --- /dev/null +++ b/usr/src/man/man9f/linkb.9f @@ -0,0 +1,80 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (C) 2006, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH linkb 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +linkb \- concatenate two message blocks +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBvoid\fR \fBlinkb\fR(\fBmblk_t *\fR\fImp1\fR, \fBmblk_t *\fR\fImp2\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH DESCRIPTION +.sp +.LP +The \fBlinkb()\fR function creates a new message by adding \fImp2\fR to the +tail of \fImp1\fR. The continuation pointer, \fBb_cont\fR, of \fImp1\fR is set +to point to \fImp2\fR. +.sp +.LP +The following figure describes how the \fBlinkb(m1, m2);\fR function +concatenates two message blocks, \fBmp1\fR and \fBmp2\fR: +.sp +Printed copy or docs.sun.com shows a figure that describes how the linkb(m1, +m2); function creates a new message by adding mp1 to the tail of mp2 +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp1\fR\fR +.ad +.RS 7n +.rt +The message to which \fImp2\fR is to be added. \fBmblk_t\fR is an instance of +the \fBmsgb\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp2\fR\fR +.ad +.RS 7n +.rt +The message to be added. +.RE + +.SH CONTEXT +.sp +.LP +The \fBlinkb()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +See \fBdupb\fR(9F) for an example that uses \fBlinkb()\fR. +.SH SEE ALSO +.sp +.LP +\fBdupb\fR(9F), \fBunlinkb\fR(9F), \fBmsgb\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR\fI\fR diff --git a/usr/src/man/man9f/list_create.9f b/usr/src/man/man9f/list_create.9f new file mode 100644 index 0000000000..d90c89e8fd --- /dev/null +++ b/usr/src/man/man9f/list_create.9f @@ -0,0 +1,193 @@ +'\" 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 list_create 9F "17 Sep 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +list_create, list_destroy, list_insert_after, list_insert_before, +list_insert_head, list_insert_tail, list_remove, list_remove_head, +list_remove_tail, list_head, list_tail, list_next, list_prev, list_is_empty, +list_link_init, list_link_active, list_move_tail, list_link_replace \- list +functions +.SH SYNOPSIS +.LP +.nf +#include <sys/list.h> + +\fBvoid\fR \fBlist_create\fR(\fBlist_t *\fR \fIlist\fR, \fBsize_t\fR \fIsize\fR, \fBsize_t\fR \fIoffset\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBlist_destroy\fR(\fBlist_t *\fR \fIlist\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBlist_insert_after\fR(\fBlist_t *\fR \fIlist\fR, \fBvoid *\fR\fIreference_item\fR, + \fBvoid *\fR\fInew_item\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBlist_insert_before\fR(\fBlist_t *\fR \fIlist\fR, \fBvoid *\fR\fIreference_item\fR, + \fBvoid *\fR\fInew_item\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBlist_insert_head\fR(\fBlist_t *\fR \fIlist\fR*, \fBvoid *\fR\fInew_item\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBlist_insert_tail\fR(\fBlist_t *\fR \fIlist\fR, \fBvoid *\fR\fInew_item\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBlist_remove\fR(\fBlist_t *\fR \fIlist\fR, \fBvoid *\fRitem); +.fi + +.LP +.nf +\fBvoid *\fR\fBlist_remove_head\fR(\fBlist_t *\fR \fIlist\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBlist_remove_tail\fR(\fBlist_t *\fR \fIlist\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBlist_head\fR(\fBlist_t *\fR \fIlist\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBlist_tail\fR(\fBlist_t *\fR \fIlist\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBlist_next\fR(\fBlist_t *\fR \fIlist\fR, \fBvoid *\fR\fIreference_item\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBlist_prev\fR(\fBlist_t *\fR \fIlist\fR, \fBvoid *\fR\fIreference_item\fR); +.fi + +.LP +.nf +\fBint\fR \fBlist_is_empty\fR(\fBlist_t *\fR \fIlist\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBlist_link_init\fR(\fBlist_node_t *\fR\fInode\fR); +.fi + +.LP +.nf +\fBint\fR \fBlist_link_active\fR(\fBlist_node_t *\fR\fInode\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBlist_move_tail\fR(\fBlist_t *\fR\fIdst\fR, \fBlist_t *\fR\fIsrc\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBlist_link_replace\fR(\fBlist_node_t *\fR\fInode1\fR, \fBlist_node_t *\fR\fInode2\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBlist_create()\fR function initializes a new list. The driver supplies +the storage for the list handle, the size of an individual element, and the +offset of a \fBlist_node_t\fR within the element to use for the links of the +list. +.sp +.LP +The \fBlist_destroy()\fR function destroys the list handle, including freeing +any resources that may have been internally allocated for the list. The list +must be empty when this function is called. +.sp +.LP +The \fBlist_insert_after()\fR and \fBlist_insert_before()\fR functions insert +\fInew_item\fR into the linked list at a location after or before the reference +item, which must already be on the list. +.sp +.LP +The \fBlist_insert_head()\fR and \fBlist_insert_tail()\fR functions insert the +\fInew_item\fR on the list at either the head or tail of the list. (The head +is the first item, the tail is the last item). +.sp +.LP +The \fBlist_remove()\fR function removes the item from the list. +.sp +.LP +The \fBlist_remove_head()\fR and \fBlist_remove_tail()\fR functions remove the +head (first) or tail (last) item from the list. The item removed is returned to +the caller. If the list is empty when these functions are called, then no +change is made and \fINULL\fR is returned to the caller. +.sp +.LP +The \fBlist_head()\fR and \fBlist_tail()\fR functions simply return the head +(first) or tail (last) item on the list. \fINULL\fR is returned if the list is +empty. +.sp +.LP +The \fBlist_next()\fR and \fBlist_prev()\fR functions return the next or +previous item in the list, relative to the named reference item which must be +linked on the list. +.sp +.LP +The \fBlist_is_empty()\fR function returns 0 if the list has items in it, or +non-zero otherwise. +.sp +.LP +The \fBlist_link_init()\fR function initializes the \fBlist_node_t\fR. It is +functionally equivalent to \fBbzero\fR(\fInode\fR, \fBsizeof\fR(*\fInode\fR)); +.sp +.LP +The \fBlist_link_active()\fR function returns non-zero if the node is on an +active list. +.sp +.LP +The \fBlist_move_tail()\fR function is used to append the items on the +\fIsrc\fR list to the end of the \fIdst\fR list. It is mandatory that the two +lists were initialized using identical size and offset parameters. Upon +completion, the \fIsrc\fR list will be empty. +.sp +.LP +The \fBlist_link_replace()\fR function swaps two items on a list. Note that +the items need not be on the same list, but extreme care must be used to ensure +that both lists are protected from concurrent accesses and that the lists were +initialized with identical size and offset parameters. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5) diff --git a/usr/src/man/man9f/makecom.9f b/usr/src/man/man9f/makecom.9f new file mode 100644 index 0000000000..7486871682 --- /dev/null +++ b/usr/src/man/man9f/makecom.9f @@ -0,0 +1,187 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. , All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH makecom 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +makecom, makecom_g0, makecom_g0_s, makecom_g1, makecom_g5 \- make a packet for +SCSI commands +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + +\fBvoid\fR \fBmakecom_g0\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR, \fBstruct scsi_device *\fR\fIdevp\fR, + \fBint\fR \fIflag\fR, \fBint\fR \fIcmd\fR, \fBint\fR \fIaddr\fR, \fBint\fR \fIcnt\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBmakecom_g0_s\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR, \fBstruct scsi_device *\fR\fIdevp\fR, + \fBint\fR \fIflag\fR, \fBint\fR \fIcmd\fR, \fBint\fR \fIcnt\fR, \fBint\fR \fIfixbit\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBmakecom_g1\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR, \fBstruct scsi_device *\fR\fIdevp\fR, + \fBint\fR \fIflag\fR, \fBint\fR \fIcmd\fR, \fBint\fR \fIaddr\fR, \fBint\fR \fIcnt\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBmakecom_g5\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR, \fBstruct scsi_device *\fR\fIdevp\fR, + \fBint\fR \fIflag\fR, \fBint\fR \fIcmd\fR, \fBint\fR \fIaddr\fR, \fBint\fR \fIcnt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +These interfaces are obsolete. \fBscsi_setup_cdb\fR(9F) should be used instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR\fR +.ad +.RS 10n +.rt +Pointer to an allocated \fBscsi_pkt\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdevp\fR\fR +.ad +.RS 10n +.rt +Pointer to the target's \fBscsi_device\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 10n +.rt +Flags for the \fBpkt_flags\fR member. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmd\fR\fR +.ad +.RS 10n +.rt +First byte of a group 0 or 1 or 5 \fBSCSI\fR \fBCDB\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR\fR +.ad +.RS 10n +.rt +Pointer to the location of the data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcnt\fR\fR +.ad +.RS 10n +.rt +Data transfer length in units defined by the SCSI device type. For sequential +devices \fIcnt\fR is the number of bytes. For block devices, \fIcnt\fR is the +number of blocks. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfixbit\fR\fR +.ad +.RS 10n +.rt +Fixed bit in sequential access device commands. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmakecom\fR functions initialize a packet with the specified command +descriptor block, \fIdevp\fR and transport flags. The \fBpkt_address\fR, +\fBpkt_flags\fR, and the command descriptor block pointed to by \fBpkt_cdbp\fR +are initialized using the remaining arguments. Target drivers may use +\fBmakecom_g0()\fR for Group 0 commands (except for sequential access devices), +or \fBmakecom_g0_s()\fR for Group 0 commands for sequential access devices, or +\fBmakecom_g1()\fR for Group 1 commands, or \fBmakecom_g5()\fR for Group 5 +commands. \fIfixbit\fR is used by sequential access devices for accessing fixed +block sizes and sets the tag portion of the \fBSCSI\fR \fBCDB\fR. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBmakecom\fR Functions +.sp +.in +2 +.nf +if (blkno >= (1<<20)) { + makecom_g1(pkt, SD_SCSI_DEVP, pflag, SCMD_WRITE_G1, + (int) blkno, nblk); +} else { + makecom_g0(pkt, SD_SCSI_DEVP, pflag, SCMD_WRITE, + (int) blkno, nblk); +} +.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 +\fBattributes\fR(5), \fBscsi_setup_cdb\fR(9F), \fBscsi_device\fR(9S), +\fBscsi_pkt\fR(9S) +.sp +.LP +\fIANSI Small Computer System Interface-2 (SCSI-2)\fR +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The \fBmakecom_g0()\fR, \fBmakecom_g0_s()\fR, \fBmakecom_g1()\fR, and +\fBmakecom_g5()\fR functions are obsolete and will be discontinued in a future +release. These functions have been replaced by the \fBscsi_setup_cdb()\fR +function. See \fBscsi_setup_cdb\fR(9F). diff --git a/usr/src/man/man9f/makedevice.9f b/usr/src/man/man9f/makedevice.9f new file mode 100644 index 0000000000..ce970c0426 --- /dev/null +++ b/usr/src/man/man9f/makedevice.9f @@ -0,0 +1,68 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH makedevice 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +makedevice \- make device number from major and minor numbers +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/mkdev.h> +#include <sys/ddi.h> + + + +\fBdev_t\fR \fBmakedevice\fR(\fBmajor_t\fR \fImajnum\fR, \fBminor_t\fR \fIminnum\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImajnum\fR\fR +.ad +.RS 10n +.rt +Major device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIminnum\fR\fR +.ad +.RS 10n +.rt +Minor device number. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmakedevice()\fR function creates a device number from a major and minor +device number. \fBmakedevice()\fR should be used to create device numbers so +the driver will port easily to releases that treat device numbers differently. +.SH RETURN VALUES +.sp +.LP +The device number, containing both the major number and the minor number, is +returned. No validation of the major or minor numbers is performed. +.SH CONTEXT +.sp +.LP +The \fBmakedevice()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBgetmajor\fR(9F), \fBgetminor\fR(9F) diff --git a/usr/src/man/man9f/max.9f b/usr/src/man/man9f/max.9f new file mode 100644 index 0000000000..4cfeb76258 --- /dev/null +++ b/usr/src/man/man9f/max.9f @@ -0,0 +1,66 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH max 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +max \- return the larger of two integers +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> + + + +\fBint\fR \fBmax\fR(\fBint\fR \fIint1\fR, \fBint\fR \fIint2\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIint1\fR\fR +.ad +.RS 8n +.rt +The first integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIint2\fR\fR +.ad +.RS 8n +.rt +The second integer. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmax()\fR function compares two signed integers and returns the larger of +the two. +.SH RETURN VALUES +.sp +.LP +The larger of the two numbers. +.SH CONTEXT +.sp +.LP +The \fBmax()\fR function can be called from user, interrupt, or kernel context. +.SH SEE ALSO +.sp +.LP +\fBmin\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/mcopyin.9f b/usr/src/man/man9f/mcopyin.9f new file mode 100644 index 0000000000..7c8bf20dd2 --- /dev/null +++ b/usr/src/man/man9f/mcopyin.9f @@ -0,0 +1,102 @@ +'\" 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 mcopyin 9F "9 June 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +mcopyin \- Convert an M_IOCTL or M_IOCDATA message to an M_COPYIN +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/strsun.h> + + + +\fBvoid\fR \fBmcopyin\fR(\fBmblk_t *\fR\fImp\fR, \fBvoid *\fR\fIprivate\fR, \fBsize_t\fR \fIsize\fR, + \fBvoid *\fR \fIuseraddr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 12n +.rt +M_IOCTL or M_IOCDATA message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprivate\fR\fR +.ad +.RS 12n +.rt +Value to which the \fBcq_private\fR field of \fBcopyreq\fR(9S) is set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 12n +.rt +Value to which the \fBcq_size\fR field of \fBcopyreq\fR(9S) is set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuseraddr\fR\fR +.ad +.RS 12n +.rt +Optionally, the value to which the \fBcq_addr\fR field of \fBcopyreq\fR(9S) is +set. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmcopyin()\fR function converts an M_IOCTL or M_IOCDATA message into an +M_COPYIN message using the supplied arguments. +.sp +.LP +To convert the message, \fBmcopyin()\fR changes the message type to M_COPYIN, +and its payload from a \fBiocblk\fR(9S) to a \fBcopyreq\fR(9S). Since the +\fBiocblk\fR(9S) and \fBcopyreq\fR(9S) are designed to overlay one another, the +only fields which must be updated are \fBcq_private\fR, \fBcq_size\fR, and +\fBcq_addr\fR, which are set to the supplied values. If \fIuseraddr\fR is +passed as NULL, \fImp\fR must be a transparent M_IOCTL, and \fBcq_addr\fR is +assigned the pointer-sized quantity found at \fBmp->b_cont->b_rptr\fR. +.sp +.LP +Any trailing message blocks associated with \fImp\fR are freed. +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +This function can be called from user, kernel or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBmcopyout\fR(9F), \fBcopyreq\fR(9S) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/mcopymsg.9f b/usr/src/man/man9f/mcopymsg.9f new file mode 100644 index 0000000000..d1c3711ba0 --- /dev/null +++ b/usr/src/man/man9f/mcopymsg.9f @@ -0,0 +1,74 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mcopymsg 9F "16 Oct 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +mcopymsg \- Copy message contents into a buffer and free message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/strsun.h> + + + +\fBvoid\fR \fBmcopymsg\fR(\fBmblk_t *\fR\fImp\fR, \fBvoid *\fR\fIbuf\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 7n +.rt +Message to be copied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuf\fR\fR +.ad +.RS 7n +.rt +Buffer in which to copy. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmcopymsg()\fR function copies the contents of the specified message into +the specified buffer. If the message consists of more than a single message +block, the contents of each message block are placed consecutively into the +buffer. After copying the message contents to \fIbuf\fR, \fBmcopymsg()\fR frees +the message \fImp\fR. +.sp +.LP +The provided buffer must be large enough to accommodate the message. If the +buffer is not large enough, the results are unspecified. The \fBmsgsize\fR(9F) +function can be used to calculate the total size of the message beforehand. +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +This function can be called from user, kernel or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBfreemsg\fR(9F), \fBmsgsize\fR(9F) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/mcopyout.9f b/usr/src/man/man9f/mcopyout.9f new file mode 100644 index 0000000000..d259515266 --- /dev/null +++ b/usr/src/man/man9f/mcopyout.9f @@ -0,0 +1,114 @@ +'\" 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 mcopyout 9F "9 June 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +mcopyout \- Convert an M_IOCTL or M_IOCDATA message to an M_COPYOUT +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/strsun.h> + + + +\fBvoid\fR \fBmcopyout\fR(\fBmblk_t *\fR\fImp\fR, \fBvoid *\fR\fIprivate\fR, \fBsize_t\fR \fIsize\fR, \fBvoid *\fR\fIuseraddr\fR, + \fBmblk_t *\fR\fIdp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 12n +.rt +M_IOCTL or M_IOCDATA message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprivate\fR\fR +.ad +.RS 12n +.rt +Value to set the cq_private field of the \fBcopyreq\fR(9S) to. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 12n +.rt +Value to set the cq_size field of the \fBcopyreq\fR(9S) to. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuseraddr\fR\fR +.ad +.RS 12n +.rt +Optionally, the value to set the cq_addr field of the \fBcopyreq\fR(9S) to. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdp\fR\fR +.ad +.RS 12n +.rt +Optionally, the payload to copy out. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmcopyout()\fR function converts an M_IOCTL or M_IOCDATA message into an +M_COPYOUT message using the supplied arguments. +.sp +.LP +To convert the message, \fBmcopyout()\fR changes the message type to M_COPYOUT, +and its payload from a \fBiocblk\fR(9S) to a \fBcopyreq\fR(9S). Since the +\fBiocblk\fR(9S) and \fBcopyreq\fR(9S) are designed to overlay one another, the +only fields which must be updated are \fBcq_private\fR, \fBcq_size\fR, and +\fBcq_addr\fR, which are set to the supplied values. If \fIuseraddr\fR is +passed as NULL, the M_IOCTL must be transparent and \fBcq_addr\fR is assigned +the pointer-sized quantity found at \fBmp->b_cont->b_rptr\fR. +.sp +.LP +If \fIdp\fR is not NULL, any trailing message blocks associated with \fImp\fR +are freed, \fBmp->b_cont\fR is reset to \fIdp\fR and \fBdp->b_wptr\fR is set to +\fBdp->b_rptr + size\fR. Otherwise, any trailing message blocks are unaffected. +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +This function can be called from user, kernel or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBmcopyin\fR(9F), \fBcopyreq\fR(9S), \fBiocblk\fR(9S) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/membar_ops.9f b/usr/src/man/man9f/membar_ops.9f new file mode 100644 index 0000000000..d82abfbb5a --- /dev/null +++ b/usr/src/man/man9f/membar_ops.9f @@ -0,0 +1,111 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH membar_ops 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +membar_ops, membar_enter, membar_exit, membar_producer, membar_consumer \- +memory access synchronization barrier operations +.SH SYNOPSIS +.LP +.nf +#include <sys/atomic.h> + +\fBvoid\fR \fBmembar_enter\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBmembar_exit\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBmembar_producer\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBmembar_consumer\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBmembar_enter()\fR function is a generic memory barrier used during lock +entry. It is placed after the memory operation that acquires the lock to +guarantee that the lock protects its data. No stores from after the memory +barrier will reach visibility and no loads from after the barrier will be +resolved before the lock acquisition reaches global visibility. +.sp +.LP +The \fBmembar_exit()\fR function is a generic memory barrier used during lock +exit. It is placed before the memory operation that releases the lock to +guarantee that the lock protects its data. All loads and stores issued before +the barrier will be resolved before the subsequent lock update reaches +visibility. +.sp +.LP +The \fBmembar_enter()\fR and \fBmembar_exit()\fR functions are used together to +allow regions of code to be in relaxed store order and then ensure that the +load or store order is maintained at a higher level. They are useful in the +implementation of mutex exclusion locks. +.sp +.LP +The \fBmembar_producer()\fR function arranges for all stores issued before this +point in the code to reach global visibility before any stores that follow. +This is useful in producer modules that update a data item, then set a flag +that it is available. The memory barrier guarantees that the available flag is +not visible earlier than the updated data, thereby imposing store ordering. +.sp +.LP +The \fBmembar_consumer()\fR function arranges for all loads issued before this +point in the code to be completed before any subsequent loads. This is useful +in consumer modules that check if data is available and read the data. The +memory barrier guarantees that the data is not sampled until after the +available flag has been seen, thereby imposing load ordering. +.SH RETURN VALUES +.sp +.LP +No values are returned. +.SH ERRORS +.sp +.LP +No errors are defined. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.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 +\fBatomic_add\fR(9F), \fBatomic_and\fR(9F), \fBatomic_bits\fR(9F), +\fBatomic_cas\fR(9F), \fBatomic_dec\fR(9F), \fBatomic_inc\fR(9F), +\fBatomic_ops\fR(9F), \fBatomic_or\fR(9F), \fBatomic_swap\fR(9F), +\fBattributes\fR(5), \fBatomic_ops\fR(3C) +.SH NOTES +.sp +.LP +Atomic instructions (see \fBatomic_ops\fR(9F)) ensure global visibility of +atomically-modified variables on completion. In a relaxed store order system, +this does not guarantee that the visibility of other variables will be +synchronized with the completion of the atomic instruction. If such +synchronization is required, memory barrier instructions must be used. diff --git a/usr/src/man/man9f/memchr.9f b/usr/src/man/man9f/memchr.9f new file mode 100644 index 0000000000..ed7daa0634 --- /dev/null +++ b/usr/src/man/man9f/memchr.9f @@ -0,0 +1,126 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH memchr 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +memchr, memcmp, memcpy, memmove, memset \- Memory operations +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> + + + +\fBvoid *\fR\fBmemchr\fR(\fBconst void *\fR\fIs\fR, \fBint\fR \fIc\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBint\fR \fBmemcmp\fR(\fBconst void *\fR\fIs1\fR, \fBconst void *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBmemcpy\fR(\fBvoid *restrict\fR \fIs1\fR, \fBconst void *restrict\fR \fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBmemmove\fR(\fBvoid *\fR\fIs1\fR, \fBconst void *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBmemset\fR(\fBvoid *\fR\fIs\fR, \fBint\fR \fIc\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdst\fR\fR +.ad +.RS 10n +.rt +Pointers to character strings. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIn\fR\fR +.ad +.RS 10n +.rt +Count of characters to be copied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIs1\fR, \fIs2\fR\fR +.ad +.RS 10n +.rt +Pointers to character strings. +.RE + +.SH DESCRIPTION +.sp +.LP +These functions operate as efficiently as possible on memory areas (arrays of +bytes bounded by a count, not terminated by a null character). They do not +check for the overflow of any receiving memory area. +.sp +.LP +The \fBmemchr()\fR function returns a pointer to the first occurrence of +\fIc\fR (converted to an \fBunsigned char\fR) in the first \fIn\fR bytes (each +interpreted as an \fBunsigned char\fR) of memory area \fIs\fR, or a null +pointer if \fIc\fR does not occur. +.sp +.LP +The \fBmemcmp()\fR function compares its arguments, looking at the first +\fIn\fR bytes (each interpreted as an \fBunsigned char\fR), and returns an +integer less than, equal to, or greater than 0, according as \fIs1\fR is +lexicographically less than, equal to, or greater than \fIs2\fR when taken to +be unsigned characters. +.sp +.LP +The \fBmemcpy()\fR function copies \fIn\fR bytes from memory area \fIs2\fR to +\fIs1\fR. It returns \fIs1\fR. If copying takes place between objects that +overlap, the behavior is undefined. +.sp +.LP +The \fBmemmove()\fR function copies \fIn\fR bytes from memory area \fIs2\fR to +memory area \fIs1\fR. Copying between objects that overlap will take place +correctly. It returns \fIs1\fR. +.sp +.LP +The \fBmemset()\fR function sets the first \fIn\fR bytes in memory area \fIs\fR +to the value of \fIc\fR (converted to an \fBunsigned char\fR). It returns +\fIs\fR. +.SH USAGE +.sp +.LP +Using \fBmemcpy()\fR might be faster than using \fBmemmove()\fR if the +application knows that the objects being copied do not overlap. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.SH SEE ALSO +.sp +.LP +\fBbcopy\fR(9F), \fBddi_copyin\fR(9F), \fBstrcpy\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/merror.9f b/usr/src/man/man9f/merror.9f new file mode 100644 index 0000000000..678069dfb2 --- /dev/null +++ b/usr/src/man/man9f/merror.9f @@ -0,0 +1,94 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH merror 9F "9 June 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +merror \- Send an M_ERROR message upstream +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/strsun.h> + + + +\fBvoid\fR \fBmerror\fR(\fBqueue_t *\fR\fIwq\fR, \fBmblk_t *\fR\fImp\fR, \fBint\fR \fIerror\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIwq\fR\fR +.ad +.RS 9n +.rt +Write queue associated with the read queue to send the M_ERROR on. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 9n +.rt +Optionally, a STREAMS message to convert to an M_ERROR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerror\fR\fR +.ad +.RS 9n +.rt +Error code to include in the M_ERROR message. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmerror()\fR function constructs an M_ERROR message, and sends the +resulting message upstream. +.sp +.LP +If \fImp\fR is NULL, \fBmerror()\fR allocates a one-byte M_ERROR message. If +\fImp\fR is non-NULL, \fBmerror()\fR attempts to convert the passed-in message +to an M_ERROR. However, if the passed-in message has more than one reference +(see \fBdupmsg\fR(9F)), or if it is of zero length, it is freed and a new +message is allocated. +.sp +.LP +If the allocation or conversion fails, \fBmerror()\fR silently fails. +Otherwise, the resulting one-byte data block is assigned the specified error +code and sent upstream. +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +This function can be called from user, kernel or interrupt context. +.SH NOTES +.sp +.LP +Callers must not hold any locks across an \fBmerror()\fR that can be acquired +as part of \fBput\fR(9E) processing. +.SH SEE ALSO +.sp +.LP +\fBput\fR(9E), \fBdupmsg\fR(9F) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/mexchange.9f b/usr/src/man/man9f/mexchange.9f new file mode 100644 index 0000000000..378fa5546c --- /dev/null +++ b/usr/src/man/man9f/mexchange.9f @@ -0,0 +1,115 @@ +'\" 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 mexchange 9F "9 June 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +mexchange \- Exchange one message for another +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/strsun.h> + + + +\fBmblk_t *\fR\fBmexchange\fR(\fBqueue_t *\fR\fIwq\fR, \fBmblk_t *\fR\fImp\fR, \fBsize_t\fR \fIsize\fR, + \fBuchar_t\fR \fItype\fR, \fBint32_t\fR \fIprimtype\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIwq\fR\fR +.ad +.RS 12n +.rt +Optionally, write queue associated with the read queue to be used on failure +(see below). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 12n +.rt +Optionally, the message to exchange. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 12n +.rt +Size of the returned message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 12n +.rt +Type of the returned message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprimtype\fR\fR +.ad +.RS 12n +.rt +Optionally, a 4 byte value to store at the beginning of the returned message. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmexchange()\fR function exchanges the passed in message for another +message of the specified \fIsize\fR and \fItype\fR. +.sp +.LP +If \fImp\fR is not NULL, is of at least \fIsize\fR bytes, and has only one +reference (see \fBdupmsg\fR(9F)), \fImp\fR is converted to be of the specified +\fIsize\fR and \fItype\fR. Otherwise, a new message of the specified \fIsize\fR +and \fItype\fR is allocated. If allocation fails, and \fIwq\fR is not NULL, +\fBmerror\fR(9F) attempts to send an error to the stream head. +.sp +.LP +Finally, if \fIprimtype\fR is not -1 and \fIsize\fR is at least 4 bytes, the +first 4 bytes are assigned to be \fIprimtype\fR. This is chiefly useful for +STREAMS-based protocols such as \fBDLPI\fR and \fBTPI\fR which store the +protocol message type in the first 4 bytes of each message. +.SH RETURN VALUES +.sp +.LP +A pointer to the requested message is returned on success. NULL is returned on +failure. +.SH CONTEXT +.sp +.LP +This function can be called from user, kernel or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBdupmsg\fR(9F), \fBmerror\fR(9F) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/min.9f b/usr/src/man/man9f/min.9f new file mode 100644 index 0000000000..9519cc03b2 --- /dev/null +++ b/usr/src/man/man9f/min.9f @@ -0,0 +1,66 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH min 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +min \- return the lesser of two integers +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> + + + +\fBint\fR \fBmin\fR(\fBint\fR \fIint1\fR, \fBint\fR \fIint2\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIint1\fR\fR +.ad +.RS 8n +.rt +The first integer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIint2\fR\fR +.ad +.RS 8n +.rt +The second integer. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmin()\fR function compares two signed integers and returns the lesser of +the two. +.SH RETURN VALUES +.sp +.LP +The lesser of the two integers. +.SH CONTEXT +.sp +.LP +The \fBmin()\fR function can be called from user, interrupt, or kernel context. +.SH SEE ALSO +.sp +.LP +\fBmax\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/mioc2ack.9f b/usr/src/man/man9f/mioc2ack.9f new file mode 100644 index 0000000000..68111a366a --- /dev/null +++ b/usr/src/man/man9f/mioc2ack.9f @@ -0,0 +1,97 @@ +'\" 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 mioc2ack 9F "9 June 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +mioc2ack \- Convert an M_IOCTL message to an M_IOCACK message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/strsun.h> + + + +\fBvoid\fR \fBmioc2ack\fR(\fBmblk_t *\fR\fImp\fR, \fBmblk_t *\fR\fIdp\fR, \fBsize_t\fR \fIcount\fR, \fBint\fR \fIrval\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 9n +.rt +M_IOCTL message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdp\fR\fR +.ad +.RS 9n +.rt +Payload to associate with M_IOCACK message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcount\fR\fR +.ad +.RS 9n +.rt +Value to set the ioc_count of the \fBiocblk\fR(9S) to. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrval\fR\fR +.ad +.RS 9n +.rt +Value to set the ioc_rval of the \fBiocblk\fR(9S) to. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmioc2ack()\fR function converts an M_IOCTL message into an M_IOCACK +message using the supplied arguments. +.sp +.LP +To convert the message, \fBmioc2ack()\fR changes the message type to M_IOCACK, +sets the \fBioc_count\fR and \fBioc_rval\fR members of the \fBiocblk\fR(9S) +associated with \fImp\fR to the passed-in values, and clears the +\fBioc_error\fR field. Further, it frees any message blocks chained off of +\fBmp->b_cont\fR and resets \fBmp->b_cont\fR to \fIdp\fR. Finally, if \fIdp\fR +is not NULL, \fBmioc2ack()\fR resets \fBdp->b_wptr\fR to be \fBdp->b_rptr + +count\fR (that is, it sets \fIdp\fR to be exactly \fIcount\fR bytes in length). +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +This function can be called from user, kernel or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBmiocack\fR(9F), \fBmiocnak\fR(9F), \fBiocblk\fR(9S) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/miocack.9f b/usr/src/man/man9f/miocack.9f new file mode 100644 index 0000000000..3179c89c90 --- /dev/null +++ b/usr/src/man/man9f/miocack.9f @@ -0,0 +1,106 @@ +'\" 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 miocack 9F "9 June 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +miocack \- Positively acknowledge an M_IOCTL message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/strsun.h> + + + +\fBvoid\fR \fBmiocack\fR(\fBqueue_t *\fR\fIwq\fR, \fBmblk_t *\fR\fImp\fR, \fBint\fR\fIcount\fR, \fBint\fR \fIrval\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIwq\fR\fR +.ad +.RS 9n +.rt +Write queue associated with the read queue to send the M_IOCACK on. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 9n +.rt +M_IOCTL message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcount\fR\fR +.ad +.RS 9n +.rt +Value to set the ioc_count of the \fBiocblk\fR(9S) to. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrval\fR\fR +.ad +.RS 9n +.rt +Value to set the ioc_rval of the \fBiocblk\fR(9S) to. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmiocack()\fR function converts an M_IOCTL message into a M_IOCACK +message and sends the resulting message upstream. +.sp +.LP +To convert the message, \fBmiocack()\fR changes the message type to M_IOCACK, +sets the 'ioc_count' and 'ioc_rval' members of the \fBiocblk\fR(9S) associated +with \fImp\fR to the passed-in values, and clears the 'ioc_error' field. If the +caller specifies a non-zero value for count, it is expected that the caller has +already set 'mp->b_cont' field to point to a message block with a length of at +least \fIcount\fR bytes. +.sp +.LP +Callers that only need to perform the message conversion, or need to perform +additional steps between the conversion and the sending of the M_IOCACK +should use \fBmioc2ack\fR(9F). +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +This function can be called from user, kernel or interrupt context. +.SH NOTES +.sp +.LP +Callers must not hold any locks across a \fBmiocack()\fR that can be acquired +as part of \fBput\fR(9E) processing. +.SH SEE ALSO +.sp +.LP +\fBmioc2ack\fR(9F), \fBput\fR(9E), \fBiocblk\fR(9S) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/miocnak.9f b/usr/src/man/man9f/miocnak.9f new file mode 100644 index 0000000000..f0a81478bd --- /dev/null +++ b/usr/src/man/man9f/miocnak.9f @@ -0,0 +1,101 @@ +'\" 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 miocnak 9F "9 June 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +miocnak \- Negatively acknowledge an M_IOCTL message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/strsun.h> + + + +\fBvoid\fR \fBmiocnak\fR(\fBqueue_t *\fR\fIwq\fR, \fBmblk_t *\fR\fImp\fR, \fBint\fR \fIcount\fR, \fBint\fR \fIerror\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIwq\fR\fR +.ad +.RS 9n +.rt +Write queue associated with the read queue to send the M_IOCNAK on. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 9n +.rt +M_IOCTL message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcount\fR\fR +.ad +.RS 9n +.rt +Value to set the ioc_count of the \fBiocblk\fR(9S) to. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerror\fR\fR +.ad +.RS 9n +.rt +Value to set the ioc_error of the \fBiocblk\fR(9S) to. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmiocnak()\fR function converts an M_IOCTL message into an M_IOCNAK +message and sends the resulting message upstream. +.sp +.LP +To convert the message, \fBmiocnak()\fR changes the message type to M_IOCNAK, +sets the\fB ioc_count\fR and \fBioc_error\fR members of the \fBiocblk\fR(9S) +associated with \fImp\fR to the passed-in values, and clears the \fBioc_rval\fR +field. Since payloads cannot currently be associated with M_IOCNAK messages, +\fIcount\fR must always be zero. If \fIerror\fR is passed as zero, \fBEINVAL\fR +is assumed. +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +This function can be called from user, kernel or interrupt context. +.SH NOTES +.sp +.LP +Callers must not hold any locks across a \fBmiocnak()\fR that can be acquired +as part of \fBput\fR(9E) processing. +.SH SEE ALSO +.sp +.LP +\fBmioc2ack\fR(9F), \fBmiocack\fR(9F), \fBput\fR(9E), \fBiocblk\fR(9S) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/miocpullup.9f b/usr/src/man/man9f/miocpullup.9f new file mode 100644 index 0000000000..9203cc8b84 --- /dev/null +++ b/usr/src/man/man9f/miocpullup.9f @@ -0,0 +1,72 @@ +'\" 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 miocpullup 9F "9 June 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +miocpullup \- Prepare the payload of an M_IOCTL message for access +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/strsun.h> + + + +\fBint\fR \fBmiocpullup\fR(\fBmblk_t *\fR\fImp\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 8n +.rt +M_IOCTL message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 8n +.rt +Number of bytes to prepare. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmiocpullup()\fR function prepares the payload of the specified M_IOCTL +message for access by ensuring that it consists of at least \fIsize\fR bytes of +data. +.sp +.LP +If the M_IOCTL message is transparent, or its total payload is less than +\fIsize\fR bytes, an error is returned. Otherwise, the payload is concatenated +as necessary to provide contiguous access to at least \fIsize\fR bytes of data. +As a special case, if \fIsize\fR is zero, \fBmiocpullup()\fR returns +successfully, even if no payload exists. +.SH RETURN VALUES +.sp +.LP +Zero is returned on success. Otherwise an errno value is returned indicating +the problem. +.SH CONTEXT +.sp +.LP +This function can be called from user, kernel or interrupt context. +.SH SEE ALSO +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/mkiocb.9f b/usr/src/man/man9f/mkiocb.9f new file mode 100644 index 0000000000..35b207d995 --- /dev/null +++ b/usr/src/man/man9f/mkiocb.9f @@ -0,0 +1,284 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH mkiocb 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +mkiocb \- allocates a STREAMS ioctl block for M_IOCTL messages in the kernel. +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBmblk_t *\fR\fBmkiocb\fR(\fBuint_t\fR \fIcommand\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcommand\fR\fR +.ad +.RS 11n +.rt +ioctl command for the \fBioc_cmd\fR field. +.RE + +.SH DESCRIPTION +.sp +.LP +STREAMS modules or drivers might need to issue an ioctl to a lower module or +driver. The \fBmkiocb()\fR function tries to allocate (using \fBallocb\fR(9F)) +a STREAMS \fBM_IOCTL\fR message block (\fBiocblk\fR(9S)). Buffer allocation +fails only when the system is out of memory. If no buffer is available, the +\fBqbufcall\fR(9F) function can help a module recover from an allocation +failure. +.sp +.LP +The \fBmkiocb\fR function returns a \fBmblk_t\fR structure which is large +enough to hold any of the ioctl messages (\fBiocblk\fR(9S), \fBcopyreq\fR(9S) +or \fBcopyresp\fR(9S)), and has the following special properties: +.sp +.ne 2 +.mk +.na +\fB\fBb_wptr\fR\fR +.ad +.RS 20n +.rt +Set to \fBb_rptr + sizeof(struct iocblk)\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBb_cont\fR\fR +.ad +.RS 20n +.rt +Set to \fINULL.\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBb_datap->db_type\fR\fR +.ad +.RS 20n +.rt +Set to \fBM_IOCTL\fR. +.RE + +.sp +.LP +The fields in the iocblk structure are initialized as follows: +.sp +.ne 2 +.mk +.na +\fB\fBioc_cmd\fR\fR +.ad +.RS 13n +.rt +Set to the command value passed in. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBioc_id\fR\fR +.ad +.RS 13n +.rt +Set to a unique identifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBioc_cr\fR\fR +.ad +.RS 13n +.rt +Set to point to a credential structure encoding the maximum system privilege +and which does not need to be freed in any fashion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBioc_count\fR\fR +.ad +.RS 13n +.rt +Set to 0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBioc_rval\fR\fR +.ad +.RS 13n +.rt +Set to 0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBioc_error\fR\fR +.ad +.RS 13n +.rt +Set to 0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBioc_flags\fR\fR +.ad +.RS 13n +.rt +Set to \fBIOC_NATIVE\fR to reflect that this is native to the running kernel. +.RE + +.SH RETURN VALUES +.sp +.LP +Upon success, the \fBmkiocb()\fR function returns a pointer to the allocated +\fBmblk_t\fR of type \fBM_IOCTL\fR. +.sp +.LP +On failure, it returns a null pointer. +.SH CONTEXT +.sp +.LP +The \fBmkiocb()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBM_IOCTL\fR Allocation +.sp +.LP +The first example shows an \fBM_IOCTL\fR allocation with the ioctl command +\fBTEST_CMD\fR. If the \fBiocblk\fR(9S) cannot be allocated, \fINULL\fR is +returned, indicating an allocation failure (line 5). In line 11, the +\fBputnext\fR(9F) function is used to send the message downstream. + +.sp +.in +2 +.nf +1 test_function(queue_t *q, test_info_t *testinfo) + 2 { + 3 mblk_t *mp; + 4 + 5 if ((mp = mkiocb(TEST_CMD)) == NULL) + 6 return (0); + 7 + 8 /* save off ioctl ID value */ + 9 testinfo->xx_iocid = ((struct iocblk *)mp->b_rptr)->ioc_id; +10 +11 putnext(q, mp); /* send message downstream */ +12 return (1); +13 } +.fi +.in -2 + +.LP +\fBExample 2 \fRThe ioctl \fBID \fRValue +.sp +.LP +During the read service routine, the ioctl \fBID \fRvalue for \fBM_IOCACK\fR or +\fBM_IOCNAK\fR should equal the ioctl that was previously sent by this module +before processing. + +.sp +.in +2 +.nf + + 1 test_lrsrv(queue_t *q) + 2 { + 3 ... + 4 + 5 switch (DB_TYPE(mp)) { + 6 case M_IOCACK: + 7 case M_IOCNAK: + 8 /* Does this match the ioctl that this module sent */ + 9 ioc = (struct iocblk*)mp->b_rptr; +10 if (ioc->ioc_id == testinfo->xx_iocid) { +11 /* matches, so process the message */ +12 ... +13 freemsg(mp); +14 } +15 break; +16 } +17 ... +18 } +.fi +.in -2 + +.LP +\fBExample 3 \fRAn iocblk Allocation Which Fails +.sp +.LP +The next example shows an iocblk allocation which fails. Since the open routine +is in user context, the caller may block using \fBqbufcall\fR(9F) until memory +is available. + +.sp +.in +2 +.nf +1 test_open(queue_t *q, dev_t devp, int oflag, int sflag, + cred_t *credp) + 2 { + 3 while ((mp = mkiocb(TEST_IOCTL)) == NULL) { + 4 int id; + 5 + 6 id = qbufcall(q, sizeof (union ioctypes), BPRI_HI, + 7 dummy_callback, 0); + 8 /* Handle interrupts */ + 9 if (!qwait_sig(q)) { +10 qunbufcall(q, id); +11 return (EINTR); +12 } +13 } +14 putnext(q, mp); +15 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBallocb\fR(9F), \fBputnext\fR(9F), \fBqbufcall\fR(9F), \fBqwait_sig\fR(9F), +\fBcopyreq\fR(9S), \fBcopyresp\fR(9S), \fBiocblk\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH WARNINGS +.sp +.LP +It is the module's responsibility to remember the \fBID\fR value of the +\fBM_IOCTL\fR that was allocated. This will ensure proper cleanup and \fBID\fR +matching when the \fBM_IOCACK\fR or \fBM_IOCNAK\fR is received. diff --git a/usr/src/man/man9f/mod_install.9f b/usr/src/man/man9f/mod_install.9f new file mode 100644 index 0000000000..acc87fc0ce --- /dev/null +++ b/usr/src/man/man9f/mod_install.9f @@ -0,0 +1,121 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc., All Rights Removed +.\" 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 mod_install 9F "8 Jul 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +mod_install, mod_remove, mod_info, mod_modname \- add, remove or query a +loadable module +.SH SYNOPSIS +.LP +.nf +#include <sys/modctl.h> + + + +\fBint\fR \fBmod_install\fR(\fBstruct modlinkage *\fR\fImodlinkage\fR); +.fi + +.LP +.nf +\fBint\fR \fBmod_remove\fR(\fBstruct modlinkage *\fR\fImodlinkage\fR); +.fi + +.LP +.nf +\fBint\fR \fBmod_info\fR(\fBstruct modlinkage *\fR\fImodlinkage\fR, + \fBstruct modinfo *\fR\fImodinfo\fR); +.fi + +.LP +.nf +\fBconst\fR \fBchar *\fR\fImod_modname\fR(\fBstruct modlinkage *\fR\fImodlinkage\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImodlinkage\fR\fR +.ad +.RS 14n +.rt +Pointer to the loadable module's \fBmodlinkage\fR structure which describes +what type(s) of module elements are included in this loadable module. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImodinfo\fR\fR +.ad +.RS 14n +.rt +Pointer to the \fBmodinfo\fR structure passed to \fB_info\fR(9E). +.RE + +.SH DESCRIPTION +.sp +.LP +\fBmod_install()\fR must be called from a module's \fB_init\fR(9E) routine. +.sp +.LP +\fBmod_remove()\fR must be called from a module's \fB_fini\fR(9E) routine. +.sp +.LP +\fBmod_info()\fR must be called from a module's \fB_info\fR(9E) routine. +.sp +.LP +\fBmod_modname()\fR can be called from any module routine. +.sp +.LP +When \fB_init\fR(9E) is executing, its call to \fBmod_install()\fR enables +other threads to call \fBattach\fR(9E) even prior to \fBmod_install()\fR +returning and \fB_init\fR(9E) completion. From a programming standpoint this +means that all \fB_init\fR(9E) initialization must occur prior to +\fB_init\fR(9E) calling \fBmod_install()\fR. If \fBmod_install()\fR fails +(non-zero return value), any initialization must be undone. +.sp +.LP +When \fB_fini\fR(9E) is executing, another thread may call \fBattach\fR(9E) +prior to \fB_fini\fR(9E) calling \fBmod_remove()\fR. If this occurs, the +\fBmod_remove()\fR fails (non-zero return). From a programming standpoint, this +means that \fB_init\fR(9E) initilizations should only be undone after a +successful return from \fBmod_remove()\fR. +.sp +.LP +To query the name of a module, use \fBmod_modname()\fR. If the module is a +driver, the module name is the same as the driver name. This function can be +used to avoid compiled-in knowledge of the module name, and is of particular +use when \fB_init\fR(9E) needs to call a function like \fBkstat_create\fR(9F). +.SH RETURN VALUES +.sp +.LP +\fBmod_install()\fR and \fBmod_remove()\fR return \fB0\fR upon success and +non-zero on failure. +.sp +.LP +\fBmod_info()\fR returns a non-zero value on success and \fB0\fR upon failure. +.sp +.LP +\fBmod_modname()\fR returns the name of the module. The returned name remains +valid as long as the module remains loaded. +.SH EXAMPLES +.sp +.LP +See \fB_init\fR(9E) for an example that uses these functions. +.SH SEE ALSO +.sp +.LP +\fB_fini\fR(9E), \fB_info\fR(9E), \fB_init\fR(9E), \fBkstat_create\fR(9F), +\fBmodldrv\fR(9S), \fBmodlinkage\fR(9S), \fBmodlstrmod\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/msgdsize.9f b/usr/src/man/man9f/msgdsize.9f new file mode 100644 index 0000000000..8a0687cd21 --- /dev/null +++ b/usr/src/man/man9f/msgdsize.9f @@ -0,0 +1,64 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH msgdsize 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +msgdsize \- return the number of bytes in a message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBsize_t\fR \fBmsgdsize\fR(\fBmblk_t *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 6n +.rt +Message to be evaluated. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmsgdsize()\fR function counts the number of bytes in a data message. +Only bytes included in the data blocks of type \fBM_DATA\fR are included in the +count. +.SH RETURN VALUES +.sp +.LP +The number of data bytes in a message, expressed as an integer. +.SH CONTEXT +.sp +.LP +The \fBmsgdsize()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +See \fBbufcall\fR(9F) for an example that uses \fBmsgdsize()\fR. +.SH SEE ALSO +.sp +.LP +\fBbufcall\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/msgpullup.9f b/usr/src/man/man9f/msgpullup.9f new file mode 100644 index 0000000000..531fba8dd0 --- /dev/null +++ b/usr/src/man/man9f/msgpullup.9f @@ -0,0 +1,101 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH msgpullup 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +msgpullup \- concatenate bytes in a message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBmblk_t *\fR\fBmsgpullup\fR(\fBmblk_t *\fR\fImp\fR, \fBssize_t\fR \fIlen\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 7n +.rt +Pointer to the message whose blocks are to be concatenated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 7n +.rt +Number of bytes to concatenate. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmsgpullup()\fR function concatenates and aligns the first \fIlen\fR data +bytes of the message pointed to by \fImp\fR, copying the data into a new +message. Any remaining bytes in the remaining message blocks will be copied and +linked onto the new message. The original message is unaltered. If \fIlen\fR +equals \fB\(mi1\fR, all data are concatenated. If \fIlen\fR bytes of the same +message type cannot be found, \fBmsgpullup()\fR fails and returns \fINULL\fR. +.SH RETURN VALUES +.sp +.LP +The \fBmsgpullup\fR function returns the following values: +.sp +.ne 2 +.mk +.na +\fB\fBNon-null\fR\fR +.ad +.RS 12n +.rt +Successful completion. A pointer to the new message is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fINULL\fR\fR +.ad +.RS 12n +.rt +An error occurred. +.RE + +.SH CONTEXT +.sp +.LP +The \fBmsgpullup()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBsrv\fR(9E), \fBallocb\fR(9F), \fBpullupmsg\fR(9F), \fBmsgb\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH NOTES +.sp +.LP +The \fBmsgpullup()\fR function is a \fBDKI\fR-compliant replacement for the +older \fBpullupmsg\fR(9F) routine. Users are strongly encouraged to use +\fBmsgpullup()\fR instead of \fBpullupmsg\fR(9F). diff --git a/usr/src/man/man9f/msgsize.9f b/usr/src/man/man9f/msgsize.9f new file mode 100644 index 0000000000..7d86aadd70 --- /dev/null +++ b/usr/src/man/man9f/msgsize.9f @@ -0,0 +1,55 @@ +'\" 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 msgsize 9F "9 June 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +msgsize \- Return the total number of bytes in a message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/strsun.h> + + + +\fBsize_t\fR \fBmsgsize\fR(\fBmblk_t *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 6n +.rt +Message to be evaluated. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBmsgsize()\fR function counts the number of bytes in a message, +regardless of the data type of the underlying data blocks. +.SH RETURN VALUES +.sp +.LP +Number of bytes in the message. +.SH CONTEXT +.sp +.LP +This function can be called from user, kernel or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBmsgdsize\fR(9F) +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/mt-streams.9f b/usr/src/man/man9f/mt-streams.9f new file mode 100644 index 0000000000..bd1447ee43 --- /dev/null +++ b/usr/src/man/man9f/mt-streams.9f @@ -0,0 +1,185 @@ +'\" te +.\" Copyright (c) 2002, 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 mt-streams 9F "5 May 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +mt-streams \- STREAMS multithreading +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +STREAMS drivers configure the degree of concurrency using the \fBcb_flag\fR +field in the \fBcb_ops\fR structure (see \fBcb_ops\fR(9S)). The corresponding +field for \fBSTREAMS \fRmodules is the \fBf_flag\fR in the \fBfmodsw\fR +structure. +.sp +.LP +For the purpose of restricting and controlling the concurrency in +drivers/modules, we define the concepts of \fBinner\fR and \fBouter +perimeters\fR. A driver/module can be configured either to have no perimeters, +to have only an inner or an outer perimeter, or to have both an inner and an +outer perimeter. Each perimeter acts as a readers-writers lock, that is, there +can be multiple concurrent readers or a single writer. Thus, each perimeter can +be entered in two modes: shared (reader) or exclusive (writer). The mode +depends on the perimeter configuration and can be different for the different +\fBSTREAMS \fRentry points ( \fBopen\fR(9E), \fBclose\fR(9E), \fBput\fR(9E), or +\fBsrv\fR(9E)). +.sp +.LP +The concurrency for the different entry points is (unless specified otherwise) +to enter with exclusive access at the inner perimeter (if present) and shared +access at the outer perimeter (if present). +.sp +.LP +The perimeter configuration consists of flags that define the presence and +scope of the inner perimeter, the presence of the outer perimeter (which can +only have one scope), and flags that modify the default concurrency for the +different entry points. +.sp +.LP +All MT safe modules/drivers specify the \fBD_MP\fR flag. +.SS "Inner Perimeter Flags" +.sp +.LP +The inner perimeter presence and scope are controlled by the mutually exclusive +flags: +.sp +.ne 2 +.mk +.na +\fB\fBD_MTPERQ\fR\fR +.ad +.RS 21n +.rt +The module/driver has an inner perimeter around each queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBD_MTQPAIR\fR\fR +.ad +.RS 21n +.rt +The module/driver has an inner perimeter around each read/write pair of queues. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBD_MTPERMOD\fR\fR +.ad +.RS 21n +.rt +The module/driver has an inner perimeter that encloses all the +module's/driver's queues. +.RE + +.sp +.ne 2 +.mk +.na +\fBNone of the above\fR +.ad +.RS 21n +.rt +The module/driver has no inner perimeter. +.RE + +.SS "Outer Perimeter Flags" +.sp +.LP +The outer perimeter presence is configured using: +.sp +.ne 2 +.mk +.na +\fB\fBD_MTOUTPERIM\fR\fR +.ad +.RS 16n +.rt +In addition to any inner perimeter, the module/driver has an outer perimeter +that encloses all the module's/driver's queues. This can be combined with all +the inner perimeter options except \fBD_MTPERMOD.\fR +.RE + +.sp +.LP +Note that acquiring exclusive access at the outer perimeter (that is, using +\fBqwriter\fR(9F) with the \fBPERIM_OUTER\fR flag) can incur significant +performance penalties, which grow linearly with the number of open instances of +the module or driver in the system. +.sp +.LP +The default concurrency can be modified using: +.sp +.ne 2 +.mk +.na +\fB\fBD_MTPUTSHARED\fR\fR +.ad +.RS 17n +.rt +This flag modifies the default behavior when \fBput\fR(9E) procedure are +invoked so that the inner perimeter is entered shared instead of exclusively. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBD_MTOCEXCL\fR\fR +.ad +.RS 17n +.rt +This flag modifies the default behavior when \fBopen\fR(9E) and \fBclose\fR(9E) +procedures are invoked so the outer perimeter is entered exclusively instead of +shared. +.sp +Note that drivers and modules using this flag can cause significant system +performance degradation during stream open or close when many instances of the +driver or module are in use simultaneously. For this reason, use of this flag +is discouraged. Instead, since \fBopen\fR(9E) and \fBclose\fR(9E) both execute +with user context, developers are encouraged to use traditional synchronization +routines such as \fBcv_wait_sig\fR(9F) to coordinate with other open instances +of the module or driver. +.RE + +.sp +.LP +The module/driver can use \fBqwait\fR(9F) or \fBqwait_sig()\fR in the +\fBopen\fR(9E) and \fBclose\fR(9E) procedures if it needs to wait "outside" the +perimeters. +.sp +.LP +The module/driver can use \fBqwriter\fR(9F) to upgrade the access at the inner +or outer perimeter from shared to exclusive. +.sp +.LP +The use and semantics of \fBqprocson()\fR and \fBqprocsoff\fR(9F) is +independent of the inner and outer perimeters. +.SH SEE ALSO +.sp +.LP +\fBclose\fR(9E), \fBopen\fR(9E), \fBput\fR(9E), \fBsrv\fR(9E), +\fBqprocsoff\fR(9F), \fBqprocson\fR(9F), \fBqwait\fR(9F), \fBqwriter\fR(9F), +\fBcb_ops\fR(9S) +.sp +.LP +\fISTREAMS Programming Guide\fR +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/mutex.9f b/usr/src/man/man9f/mutex.9f new file mode 100644 index 0000000000..509650ab22 --- /dev/null +++ b/usr/src/man/man9f/mutex.9f @@ -0,0 +1,274 @@ +'\" 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 mutex 9F "21 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +mutex, mutex_enter, mutex_exit, mutex_init, mutex_destroy, mutex_owned, +mutex_tryenter \- mutual exclusion lock routines +.SH SYNOPSIS +.LP +.nf +#include <sys/ksynch.h> + +\fBvoid\fR \fBmutex_init\fR(\fBkmutex_t *\fR\fImp\fR, \fBchar *\fR\fIname\fR, \fBkmutex_type_t\fR \fItype\fR, + \fBvoid *\fR\fIarg\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBmutex_destroy\fR(\fBkmutex_t *\fR\fImp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBmutex_enter\fR(\fBkmutex_t *\fR\fImp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBmutex_exit\fR(\fBkmutex_t *\fR\fImp\fR); +.fi + +.LP +.nf +\fBint\fR \fBmutex_owned\fR(\fBkmutex_t *\fR\fImp\fR); +.fi + +.LP +.nf +\fBint\fR \fBmutex_tryenter\fR(\fBkmutex_t *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 8n +.rt +Pointer to a kernel mutex lock (\fBkmutex_t\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 8n +.rt +Descriptive string. This is obsolete and should be \fINULL\fR. (Non-\fINULL\fR +strings are legal, but they are a waste of kernel memory.) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 8n +.rt +Type of mutex lock. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 8n +.rt +Type-specific argument for initialization routine. +.RE + +.SH DESCRIPTION +.sp +.LP +A mutex enforces a policy of mutual exclusion. Only one thread at a time may +hold a particular mutex. Threads trying to lock a held mutex will block until +the mutex is unlocked. +.sp +.LP +Mutexes are strictly bracketing and may not be recursively locked, meaning that +mutexes should be exited in the opposite order they were entered, and cannot be +reentered before exiting. +.sp +.LP +\fBmutex_init()\fR initializes a mutex. It is an error to initialize a mutex +more than once. The \fItype\fR argument should be set to \fBMUTEX_DRIVER\fR. +.sp +.LP +\fIarg\fR provides type-specific information for a given variant type of mutex. +When \fBmutex_init()\fR is called for driver mutexes, if the mutex is used by +the interrupt handler, the \fIarg\fR should be the interrupt priority returned +from \fBddi_intr_get_pri\fR(9F) or \fBddi_intr_get_softint_pri\fR(9F). Note +that \fIarg\fR should be the value of the interrupt priority cast by calling +the \fBDDI_INTR_PRI\fR macro. If the mutex is never used inside an interrupt +handler, the argument should be \fINULL\fR. +.sp +.LP +\fBmutex_enter()\fR is used to acquire a mutex. If the mutex is already held, +then the caller blocks. After returning, the calling thread is the owner of the +mutex. If the mutex is already held by the calling thread, a panic ensues. +.sp +.LP +\fBmutex_owned()\fR should only be used in \fBASSERT()\fR and may be enforced +by not being defined unless the preprocessor symbol \fBDEBUG\fR is defined. Its +return value is non-zero if the current thread (or, if that cannot be +determined, at least some thread) holds the mutex pointed to by \fImp\fR. +.sp +.LP +\fBmutex_tryenter()\fR is very similar to \fBmutex_enter()\fR except that it +doesn't block when the mutex is already held. \fBmutex_tryenter()\fR returns +non-zero when it acquired the mutex and 0 when the mutex is already held. +.sp +.LP +\fBmutex_exit()\fR releases a mutex and will unblock another thread if any are +blocked on the mutex. +.sp +.LP +\fBmutex_destroy()\fR releases any resources that might have been allocated by +\fBmutex_init()\fR. \fBmutex_destroy()\fR must be called before freeing the +memory containing the mutex, and should be called with the mutex unheld (not +owned by any thread). The caller must be sure that no other thread attempts to +use the mutex. +.SH RETURN VALUES +.sp +.LP +\fBmutex_tryenter()\fR returns a non-zero value on success and zero on failure. +.sp +.LP +\fBmutex_owned()\fR returns a non-zero value if the calling thread currently +holds the mutex pointed to by \fImp\fR, or when that cannot be determined, if +any thread holds the mutex. Otherwise \fBmutex_owned()\fR returns zero. +.SH CONTEXT +.sp +.LP +These functions can be called from user, kernel, or high-level interrupt +context, except for \fBmutex_init()\fR and \fBmutex_destroy()\fR, which can be +called from user or kernel context only. +.SH EXAMPLES +.LP +\fBExample 1 \fRInitializing a Mutex +.sp +.LP +A driver might do this to initialize a mutex that is part of its unit structure +and used in its interrupt routine: + +.sp +.in +2 +.nf +ddi_intr_get_pri(hdlp, &pri); +mutex_init(&un->un_lock, NULL, MUTEX_DRIVER, DDI_INTR_PRI(pri)); +ddi_intr_add_handler(hdlp, xxintr, (caddr_t)un, NULL); +.fi +.in -2 + +.LP +\fBExample 2 \fRCalling a Routine with a Lock +.sp +.LP +A routine that expects to be called with a certain lock held might have the +following ASSERT: + +.sp +.in +2 +.nf +xxstart(struct xxunit *un) +{ + ASSERT(mutex_owned(&un->un_lock)); +\&... +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBlockstat\fR(1M), \fBIntro\fR(9F), \fBcondvar\fR(9F), +\fBddi_intr_alloc\fR(9F), \fBddi_intr_add_handler\fR(9F), +\fBddi_intr_get_pri\fR(9F), \fBddi_intr_get_softint_pri\fR(9F), +\fBrwlock\fR(9F), \fBsemaphore\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Compiling with \fB_LOCKTEST\fR or \fB_MPSTATS\fR defined has no effect. To +gather lock statistics, see \fBlockstat\fR(1M). +.sp +.LP +The address of a \fBkmutex_t\fR lock must be aligned on an 8-byte boundary for +64-bit kernels, or a 4-byte boundary for 32-bit kernels. Violation of this +requirement will result in undefined behavior, including, but not limited to, +failure of mutual exclusion or a system panic. +.sp +.LP +To write scalable, responsive drivers that do not hang, panic or deadlock the +system, follow these guidelines: +.br +.in +2 +Never return from a driver entry point with a mutex held. +.in -2 +.br +.in +2 +Never hold a mutex when calling a service that may block, for example +\fBkmem_alloc\fR(9F) with KM_SLEEP or \fBdelay\fR(9F). +.in -2 +.br +.in +2 +Always acquire mutexes in a consistent order. If a critical section acquires +mutex A followed by B, and elsewhere in the driver mutex B is acquired before +A, the driver can deadlock with one thread holding A and waiting for B and +another thread holding B while waiting for A. +.in -2 +.br +.in +2 +Always use a mutex to enforce exclusive access to data, not instruction paths. +.in -2 +.br +.in +2 +Acquiring a lock in user context that is also acquired in interrupt context +means that, as long as that lock is held, the driver instance holding the lock +is subject to all the rules and limitations of interrupt context. +.in -2 +.br +.in +2 +In most cases, a mutex can and should be acquired and released within the same +function. +.in -2 +.br +.in +2 +Liberal use of debugging aids like ASSERT(mutex_owned(&mutex)) can help find +callers of a function which should be holding a mutex but are not. This means +you need to test your driver compiled with DEBUG. +.in -2 +.br +.in +2 +Do not use a mutex to set driver state. However, you should use a mutex to +protect driver state data. +.in -2 +.br +.in +2 +Use per-instance and automatic data where possible to reduce the amount of +shared data. Per-instance data can be protected by a per-instance lock to +improve scalability and reduce contention with multiple hardware instances. +.in -2 +.br +.in +2 +Avoid global data and global mutexes whenever possible. +.in -2 +.br +.in +2 + +.in -2 diff --git a/usr/src/man/man9f/net_event_notify_register.9f b/usr/src/man/man9f/net_event_notify_register.9f new file mode 100644 index 0000000000..140c585576 --- /dev/null +++ b/usr/src/man/man9f/net_event_notify_register.9f @@ -0,0 +1,182 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_event_notify_register 9F "30 Oct 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_event_notify_register, net_event_notify_unregister \- add/delete a function +to be called for changes to a event +.SH SYNOPSIS +.LP +.nf +#include <sys/hook.h> +#include <sys/neti.h> + +\fBint\fR \fBnet_event_notify_register\fR(\fBnet_handle_t\fR \fIfamily\fR, \fBchar\fR + *\fIevent\fR, \fBhook_notify_fn_t\fR *\fIcallback\fR, \fBvoid\fR *\fIarg\fR); + +\fBint\fR \fBnet_event_notify_unregister\fR(\fBnet_handle_t\fR \fIfamily\fR, \fBchar\fR + *\fIevent\fR, \fBhook_notify_fn_t\fR *\fIcallback\fR); + +\fBtypedef int\fR (* \fBhook_notify_fn_t\fR)(\fBhook_notify_cmd_t command,\fR + \fBvoid\fR *\fIarg\fR, \fBconst char\fR *\fIname1\fR, \fBconst char\fR *\fIname2\fR, \fBconst char\fR + *\fIname3\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIfamily\fR\fR +.ad +.RS 12n +.rt +value returned from a successful call to \fBnet_protocol_lookup()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 12n +.rt +function to call when a change occurs. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevent\fR\fR +.ad +.RS 12n +.rt +name of the event for which notification of change is desired. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 12n +.rt +pointer to pass into the \fBcallback()\fR function when a change occurs. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_event_notify_register()\fR function registers a function represented +by the pointer \fIcallback\fR to be called when there is a change to the event +represented by \fIfamily\fR. The types of changes for which notifications are +available for is currently limited to the addition and removal of hooks. +.sp +.LP +The \fBnet_event_notify_unregister()\fR function indicates that there is no +longer any desire to receive notification of changes to the event through +function calls to the specified \fIcallback\fR. +.sp +.LP +The name of a hook should be considered a private interface unless otherwise +specified. The hook names used by \fBIPFilter\fR in Solaris are a public, but +uncommitted, interface. +.sp +.LP +Multiple \fIcallback\fR functions may be registered through this interface. The +same set of parameters is passed to each \fIcallback\fR function. The memory +referenced through the pointers passed to the \fIcallback\fR should be +treated as pointing to read-only memory. Changing this data is strictly +prohibited. +.sp +.LP +The function that is called when the \fIevent\fR occurs must not block any +other events. +.sp +.LP +The arguments passed through to the \fBcallback\fR are as follows (the command +is either \fBHN_REGISTER\fR or \fBHN_UNREGISTER\fR): +.sp +.ne 2 +.mk +.na +\fB\fIname1\fR\fR +.ad +.RS 9n +.rt +is the name of the protocol. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname2\fR\fR +.ad +.RS 9n +.rt +is the name of the event +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname3\fR\fR +.ad +.RS 9n +.rt +is the name of the hook being added/removed +.RE + +.SH RETURN VALUES +.sp +.LP +If these functions succeed, 0 is returned. Otherwise, the following error is +returned: +.sp +.ne 2 +.mk +.na +\fBEEXIST\fR +.ad +.RS 10n +.rt +the given callback function is already registered. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBnet_hook_register\fR(9F), +\fBnet_hook_unregister\fR(9F), \fBnet_protocol_lookup\fR(9F) diff --git a/usr/src/man/man9f/net_getifname.9f b/usr/src/man/man9f/net_getifname.9f new file mode 100644 index 0000000000..c066131336 --- /dev/null +++ b/usr/src/man/man9f/net_getifname.9f @@ -0,0 +1,139 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_getifname 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_getifname \- determine the name given to a network interface +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBint\fR \fBnet_getifname\fR(\fBconst\fR \fBnet_data_t\fR \fInet\fR, \fBconst\fR \fBphy_if_t\fR \fIifp\fR, + \fBchar *\fR\fIbuffer\fR, \fBsize_t\fR \fIbuflen\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 10n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIifp\fR\fR +.ad +.RS 10n +.rt +value returned from a successful call to \fBnet_phylookup\fR(9F) or +\fBnet_phygetnext\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuffer\fR\fR +.ad +.RS 10n +.rt +pointer to the buffer in which to write the interface name. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuflen\fR\fR +.ad +.RS 10n +.rt +size of the buffer in which to store the interface name. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_getifname()\fR function copies the name of the network interface +into the buffer provided. The name will always be null-terminated. If the +buffer is too small to fit both the interface name and the null-terminated +name, the name in the buffer is truncated to fit. See \fBnet_phygetnext\fR(9F) +for an example on how to use this function. +.SH RETURN VALUES +.sp +.LP +The \fBnet_getifname()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB-1\fR +.ad +.RS 6n +.rt +The network protocol does not support this function. +.RE + +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 6n +.rt +Successful completion. +.RE + +.sp +.ne 2 +.mk +.na +\fB1\fR +.ad +.RS 6n +.rt +Unsuccessful. +.RE + +.SH CONTEXT +.sp +.LP +The \fBnet_getifname()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_phygetnext\fR(9F), \fBnet_phylookup\fR(9F), +\fBnet_protocol_lookup\fR(9F) diff --git a/usr/src/man/man9f/net_getlifaddr.9f b/usr/src/man/man9f/net_getlifaddr.9f new file mode 100644 index 0000000000..576a77911d --- /dev/null +++ b/usr/src/man/man9f/net_getlifaddr.9f @@ -0,0 +1,206 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_getlifaddr 9F "13 Oct 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_getlifaddr \- determine a network address for a given interface +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBint\fR \fBnet_getlifaddr\fR(\fBconst\fR \fBnet_data_t\fR \fInet\fR, \fBconst\fR \fBphy_if_t\fR \fIifp\fR, + \fBconst\fR \fBnet_if_t\fR \fIlif\fR, \fBint\fR \fBconst\fR \fItype\fR, + \fBstruct\fR \fBsockaddr*\fR \fIstorage\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 11n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIifp\fR\fR +.ad +.RS 11n +.rt +value returned from a successful call to \fBnet_phylookup\fR(9F) or +\fBnet_phygetnext\fR(9F), indicating which network interface the information +should be returned from. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlif\fR\fR +.ad +.RS 11n +.rt +indicates the logical interface from which to fetch the address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 11n +.rt +indicates what type of address should be returned. See below for more details +on this field. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstorage\fR\fR +.ad +.RS 11n +.rt +pointer to an area of memory to store the address data. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_getlifaddr()\fR function retrieves the address information for each +logical interface. Each call to \fBnet_getlifaddr()\fR requires that the caller +pass a pointer to an array of address information types to retrieve, and an +accompanying pointer to an array of pointers to \fBstruct sockaddr\fR +structures to which to copy the address information. See +\fBnet_lifgetnext\fR(9F) for an example on how to use this function. +.sp +.LP +Each member of the address \fBtype\fR array should be one of the values listed +here. +.sp +.ne 2 +.mk +.na +\fB\fBNA_ADDRESS\fR\fR +.ad +.RS 16n +.rt +Return the network address associated with the logical interface (\fBlif\fR) +that belongs to the network interface (\fBifp\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNA_PEER\fR\fR +.ad +.RS 16n +.rt +Return the address assigned to the remote host for point to point network +interfaces for the given network/logical interface. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNA_BROADCAST\fR\fR +.ad +.RS 16n +.rt +Return the broadcast address assigned to the given network/logical interface +for network interfaces that support broadcast packets. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNA_NETMASK\fR\fR +.ad +.RS 16n +.rt +Return the netmask associated with the given network/logical interface for +network interfaces that support broadcast packets. +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBnet_getlifaddr()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB-1\fR +.ad +.RS 6n +.rt +The network protocol does not support this function. +.RE + +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 6n +.rt +Successful completion. +.RE + +.sp +.ne 2 +.mk +.na +\fB1\fR +.ad +.RS 6n +.rt +Unsuccessful. +.RE + +.SH CONTEXT +.sp +.LP +The \fBnet_getifaddr()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_lifgetnext\fR(9F), \fBnet_phylookup\fR(9F), +\fBnet_phygetnext\fR(9F)\fBnet_protocol_lookup\fR(9F) diff --git a/usr/src/man/man9f/net_getmtu.9f b/usr/src/man/man9f/net_getmtu.9f new file mode 100644 index 0000000000..c222e658e7 --- /dev/null +++ b/usr/src/man/man9f/net_getmtu.9f @@ -0,0 +1,84 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_getmtu 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_getmtu \- determine the MTU of a given network interface +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBint\fR \fBnet_getmtu\fR(\fBconst\fR \fBnet_data_t\fR \fInet\fR, \fBconst\fR \fBphy_if_t\fR \fIifp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 7n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIifp\fR\fR +.ad +.RS 7n +.rt +value returned from a successful call to \fBnet_phylookup\fR(9F) or +\fBnet_phygetnext\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_getmtu()\fR function receives information about the current +\fBMTU\fR of a network interface. The value returned from this function call +should not be cached as the \fBMTU\fR of a network interface since it is not +guaranteed to be constant. +.SH RETURN VALUES +.sp +.LP +The \fBnet_getmtu()\fR function returns -1 if the network protocol does not +support this feature and otherwise returns the current MTU of the network +interface. +.SH CONTEXT +.sp +.LP +The \fBnet_getmtu()\fR function may be called from user, kernel, or interrupt +context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_phygetnext\fR(9F), \fBnet_phylookup\fR(9F), +\fBnet_protocol_lookup\fR(9F) diff --git a/usr/src/man/man9f/net_getnetid.9f b/usr/src/man/man9f/net_getnetid.9f new file mode 100644 index 0000000000..5d4178d41e --- /dev/null +++ b/usr/src/man/man9f/net_getnetid.9f @@ -0,0 +1,67 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_getnetid 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_getnetid \- returns the instance identifier +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBnetid_t\fR \fBnet_getnetid\fR(\fBconst\fR \fBnet_data_t\fR \fInet\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 7n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_getnetid()\fR function returns the instance identifier for the +protocol instance returned via a call to \fBnet_protocol_lookup\fR(9F). +.SH RETURN VALUES +.sp +.LP +The \fBnet_getnetid()\fR function returns the value of the instance identifier. +.SH CONTEXT +.sp +.LP +The \fBnet_getnetid()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_protocol_lookup\fR(9F) diff --git a/usr/src/man/man9f/net_getpmtuenabled.9f b/usr/src/man/man9f/net_getpmtuenabled.9f new file mode 100644 index 0000000000..a9407b966a --- /dev/null +++ b/usr/src/man/man9f/net_getpmtuenabled.9f @@ -0,0 +1,101 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_getpmtuenabled 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_getpmtuenabled \- determine if path MTU discovery is enabled for a network +protocol +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBint\fR \fBnet_getpmtuenabled\fR(\fBconst\fR \fBnet_data_t\fR \fInet\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 7n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_getpmtuenabled()\fR function returns a value to indicate whether or +not path \fBMTU\fR (\fBPMTU\fR) discovery is enabled for this network protocol. +.SH RETURN VALUES +.sp +.LP +The \fBnet_getpmtuenabled()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB-1\fR +.ad +.RS 6n +.rt +The network protocol does not support this function. +.RE + +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 6n +.rt +PATH MTU discovery is disabled. +.RE + +.sp +.ne 2 +.mk +.na +\fB1\fR +.ad +.RS 6n +.rt +PATH MTU discovery is enabled. +.RE + +.SH CONTEXT +.sp +.LP +The \fBnet_getpmtuenabled()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_getmtu\fR(9F), \fBnet_protocol_lookup\fR(9F) diff --git a/usr/src/man/man9f/net_hook_register.9f b/usr/src/man/man9f/net_hook_register.9f new file mode 100644 index 0000000000..69741caa01 --- /dev/null +++ b/usr/src/man/man9f/net_hook_register.9f @@ -0,0 +1,206 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_hook_register 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_hook_register \- add a hook to be called in event processing +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBnet_hook_t\fR \fBnet_hook_register\fR(\fBconst\fR \fBnet_data_t\fR \fInet\fR, \fBhook_t\fR *\fIhook\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 8n +.rt +value returned from a successful call to \fBnet_protocol_register()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhook\fR\fR +.ad +.RS 8n +.rt +pointer to a \fBhook_t\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_hook_register()\fR function uses hooks that allow callbacks to be +registered with events that belong to a network protocol. A successful call to +\fBnet_hook_register()\fR requires that a valid handle for a network protocol +be provided (the \fInet\fR parameter), along with a hook description that +includes a reference to an available event. +.sp +.LP +While it is possible to use the same \fBhook_t\fR structure with multiple calls +to \fBnet_hook_register()\fR, it is not encouraged. +.sp +.LP +The \fBhook_t\fR structure passed in with this function is described by +\fBhook_t\fR(9S). The following describes how this structure is used. +.sp +.ne 2 +.mk +.na +\fB\fBh_func\fR\fR +.ad +.RS 23n +.rt +Must be non-NULL and represent a function that fits the specified interface. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBh_name\fR\fR +.ad +.RS 23n +.rt +Gives the hook a name that represents its owner. No duplication of \fBh_name\fR +among the hooks present for an event is allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBh_flags\fR\fR +.ad +.RS 23n +.rt +Currently unused and must be set to 0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBh_hint, h_hintvalue\fR\fR +.ad +.RS 23n +.rt +Specify a hint to \fBnet_hook_register()\fR on how to insert this hook. If the +hint cannot be specified, then an error is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBh_arg;\fR\fR +.ad +.RS 23n +.rt +May take any value that the consumer wishes to have passed back when the hook +is activated. +.RE + +.SH RETURN VALUES +.sp +.LP +If the \fBnet_hook_register()\fR function succeeds, 0 is returned. Otherwise, +one of the following errors is returned: +.sp +.ne 2 +.mk +.na +\fBENOMEM\fR +.ad +.RS 10n +.rt +The system cannot allocate any more memory to support registering this hook. +.RE + +.sp +.ne 2 +.mk +.na +\fBENXIO\fR +.ad +.RS 10n +.rt +A hook cannot be found among the given family of events. +.RE + +.sp +.ne 2 +.mk +.na +\fBEEXIST\fR +.ad +.RS 10n +.rt +A hook with the given \fBh_name\fR already exists on that event. +.RE + +.sp +.ne 2 +.mk +.na +\fBESRCH\fR +.ad +.RS 10n +.rt +A before or after dependency cannot be satisfied due to the hook with +.RE + +.sp +.ne 2 +.mk +.na +\fBEBUSY\fR +.ad +.RS 10n +.rt +The \fBh_hint\fR field specifies a hint that cannot currently be satisfied +because it conflicts with another hook. An example of this might be specifying +\fBHH_FIRST\fR or \fBHH_LAST\fR when another hook has already been registered +with this value. +.RE + +.SH CONTEXT +.sp +.LP +The \fBnet_hook_register()\fR function may be called from user or kernel +context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_hook_unregister\fR(9F), \fBhook_t\fR(9S) diff --git a/usr/src/man/man9f/net_hook_unregister.9f b/usr/src/man/man9f/net_hook_unregister.9f new file mode 100644 index 0000000000..6a4646121f --- /dev/null +++ b/usr/src/man/man9f/net_hook_unregister.9f @@ -0,0 +1,79 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_hook_unregister 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_hook_unregister \- disable a hook that was called in event processing +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBint\fR \fBnet_hook_unregister\fR(\fBconst\fR \fBnet_data_t\fR \fInet\fR, \fBnethook_t\fR \fIhook\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 8n +.rt +value returned from a successful call to \fBnet_protocol_register()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhook\fR\fR +.ad +.RS 8n +.rt +value returned from a successful call to \fBnet_hook_register\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_hook_unregister()\fR function disables the callback hooks that were +registered with the \fBnet_hook_register()\fR function. +.SH RETURN VALUES +.sp +.LP +If the \fBnet_hook_unregister()\fR function succeeds, 0 is returned. Otherwise, +an error indicating the problem encountered. +.SH CONTEXT +.sp +.LP +The \fBnet_hook_unregister()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_hook_register\fR(9F) diff --git a/usr/src/man/man9f/net_inject.9f b/usr/src/man/man9f/net_inject.9f new file mode 100644 index 0000000000..8748f9f51b --- /dev/null +++ b/usr/src/man/man9f/net_inject.9f @@ -0,0 +1,166 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_inject 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_inject \- determine if a network interface name exists for a network +protocol +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBint\fR \fBnet_inject\fR(\fBconst\fR \fBnet_data_t\fR \fInet\fR, \fBinject_t\fR \fIstyle\fR, + \fBnet_inject_t\fR *\fIpacket\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 10n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstyle\fR\fR +.ad +.RS 10n +.rt +method that determines how this packet is to be injected into the network or +kernel. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpacket\fR\fR +.ad +.RS 10n +.rt +details about the packet to be injected. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_inject()\fR function provides an interface to allow delivery of +network layer (layer 3) packets either into the kernel or onto the network. The +method of delivery is determined by style. +.sp +.LP +If \fBNI_QUEUE_IN\fR is specified, the packet is scheduled for delivery up into +the kernel, imitating its reception by a network interface. In this mode, +\fBpacket->ni_addr\fR is ignored and \fB packet->ni_physical\fR specifies the +interface for which the packet is made to appear as if it arrived on. +.sp +.LP +If \fBNI_QUEUE_OUT\fR is specified, the packet is scheduled for delivery out of +the kernel, as if it were being sent by a raw socket. In this mode, +\fBpacket->ni_addr\fR and \fBpacket->ni_physical\fR are both ignored. +.sp +.LP +Neither \fBNI_QUEUE_IN\fR or \fBNI_QUEUE_OUT\fR cause the packet to be +immediately processed by the kernel. Instead, the packet is added to a list and +a timeout is scheduled (if there are none already pending) to deliver the +packet. The call to \fBnet_inject()\fR returns once the setup has been +completed, and not after the packet has been processed. The packet processing +is completed on a different thread and in a different context to that of the +original packet. Thus, a packet queued up using \fBnet_inject()\fR for either +\fBNI_QUEUE_IN\fR or \fBNI_QUEUE_OUT\fR is presented to the packet event again. +A packet received by a hook from \fBNH_PHYSICAL_IN\fR and then queued up with +\fBNI_QUEUE_IN\fR is seen by the hook as another \fBNH_PHYSICAL_IN\fR packet. +This also applies to both \fBNH_PHYSICAL_OUT\fR and \fBNI_QUEUE_OUT\fR packets. +.sp +.LP +If \fBNI_DIRECT_OUT\fR is specified, an attempt is made to send the packet out +to a network interface immediately. No processing on the packet, aside from +prepending any required layer 2 information, is made. In this instance, +\fBpacket->ni_addr\fR may be used to specify the next hop (for the purpose of +link layer address resolution) and \fBpacket->ni_physical\fR determines which +interface the packet should be sent out. +.sp +.LP +For all three packets, \fBpacket->ni_packet\fR must point to an \fBmblk\fR +structure with the packet to be delivered. +.sp +.LP +See \fBnet_inject_t\fR(9S) for more details on the structure +\fBnet_inject_t\fR. +.SH RETURN VALUES +.sp +.LP +The \fBnet_inject()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB-1\fR +.ad +.RS 6n +.rt +The network protocol does not support this function. +.RE + +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 6n +.rt +The packet is successfully queued or sent. +.RE + +.sp +.ne 2 +.mk +.na +\fB1\fR +.ad +.RS 6n +.rt +The packet could not be queued up or sent out immediately. +.RE + +.SH CONTEXT +.sp +.LP +The \fBnet_inject()\fR function may be called from user, kernel, or interrupt +context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_protocol_lookup\fR(9F), \fBnetinfo\fR(9F), \fBnet_inject_t\fR(9S) diff --git a/usr/src/man/man9f/net_inject_alloc.9f b/usr/src/man/man9f/net_inject_alloc.9f new file mode 100644 index 0000000000..cf1c5c00f3 --- /dev/null +++ b/usr/src/man/man9f/net_inject_alloc.9f @@ -0,0 +1,69 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_inject_alloc 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_inject_alloc \- allocate a net_inject_t structure +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBnet_inject_t *\fR\fBnet_inject_alloc\fR(\fBconst\fR \fBint\fR \fIversion\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIversion\fR\fR +.ad +.RS 11n +.rt +must always be the symbol \fBNETI_VERSION\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_inject_alloc()\fR function allocates a \fBnet_inject_t\fR structure, +returning a pointer for the caller to use. +.SH RETURN VALUES +.sp +.LP +Upon success, \fBnet_inject_alloc()\fR returns a pointer to the allocated +\fInet_inject_t\fR structure. On failure, \fBhook_alloc()\fR returns a +\fINULL\fR pointer. +.SH CONTEXT +.sp +.LP +The \fBnet_inject_alloc()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_inject_free\fR(9F), \fBnet_inject_t\fR(9S) diff --git a/usr/src/man/man9f/net_inject_free.9f b/usr/src/man/man9f/net_inject_free.9f new file mode 100644 index 0000000000..fe072fdbf4 --- /dev/null +++ b/usr/src/man/man9f/net_inject_free.9f @@ -0,0 +1,63 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_inject_free 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_inject_free \- free a net_inject_t structure +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBvoid\fR \fBnet_inject_free\fR(\fBnet_inject_t\fR *\fIinject\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIinject\fR\fR +.ad +.RS 10n +.rt +pointer returned by \fBnet_inject_alloc\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_inject_free()\fR function frees a \fBnet_inject_t\fR structure that +was originally allocated by \fBnet_inject_alloc\fR(9F). +.SH CONTEXT +.sp +.LP +The \fBnet_inject_free()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_inject_alloc\fR(9F), \fBattributes\fR(5), \fBnet_inject_t\fR(9S) diff --git a/usr/src/man/man9f/net_instance_alloc.9f b/usr/src/man/man9f/net_instance_alloc.9f new file mode 100644 index 0000000000..6058b40cb9 --- /dev/null +++ b/usr/src/man/man9f/net_instance_alloc.9f @@ -0,0 +1,68 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_instance_alloc 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_instance_alloc \- allocate a net_instance_t structure +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBnet_instance_t *\fR\fBnet_instance_alloc\fR(\fBconst\fR \fBint\fR \fIversion\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIversion\fR\fR +.ad +.RS 11n +.rt +must always be the symbol \fBNETI_VERSION\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_instance_alloc()\fR function allocates a \fBnet_instance_t\fR +structure, returning a pointer for the caller to use. +.SH RETURN VALUES +.sp +.LP +Upon success, \fBnet_instance_alloc()\fR returns a pointer to the allocated +\fInet_instance_t\fR structure. On failure, it returns a \fINULL\fR pointer. +.SH CONTEXT +.sp +.LP +The \fBnet_instance_alloc()\fR function may be called from user or kernel +context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_instance_free\fR(9F), \fBattributes\fR(5), \fBnet_inject_t\fR(9S) diff --git a/usr/src/man/man9f/net_instance_free.9f b/usr/src/man/man9f/net_instance_free.9f new file mode 100644 index 0000000000..472f88a1e6 --- /dev/null +++ b/usr/src/man/man9f/net_instance_free.9f @@ -0,0 +1,63 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_instance_free 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_instance_free \- free a net_instance_t structure +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBvoid\fR \fBnet_instance_free\fR(\fBnet_instance_t\fR *\fInet_instance\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet_instance\fR\fR +.ad +.RS 16n +.rt +pointer returned by \fBnet_instance_alloc\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_instance_free()\fR function frees a \fBnet_instance_t\fR structure +that was originally allocated by \fBnet_instance_alloc\fR(9F). +.SH CONTEXT +.sp +.LP +The \fBnet_instance_free()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_instance_alloc\fR(9F), \fBattributes\fR(5), \fBnet_instance_t\fR(9S) diff --git a/usr/src/man/man9f/net_instance_notify_register.9f b/usr/src/man/man9f/net_instance_notify_register.9f new file mode 100644 index 0000000000..4e348229b7 --- /dev/null +++ b/usr/src/man/man9f/net_instance_notify_register.9f @@ -0,0 +1,165 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_instance_notify_register 9F "30 Oct 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_instance_notify_register, net_instance_notify_unregister \- add/delete a +function to be called for changes to an instance +.SH SYNOPSIS +.LP +.nf +#include <sys/hook.h> +#include <sys/neti.h> + +\fBint\fR \fBnet_instance_notify_register\fR(\fBnet id_t\fR \fInet_id\fR, + \fBhook_notify_fn_t\fR *\fIcallback\fR, \fBvoid\fR *\fIarg\fR); + +\fBint\fR \fBnet_instance_notify_unregister\fR(\fBnet id_t\fR \fInet_id\fR, + \fBhook_notify_fn_t\fR *\fIcallback\fR); + +\fBtypedef int\fR (* \fBhook_notify_fn_t\fR)(\fBhook_notify_cmd_t command,\fR + \fBvoid\fR *\fIarg\fR, \fBconst char\fR *\fIname1\fR, \fBconst char\fR *\fIname2\fR, \fBconst char\fR + *\fIname3\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInetid\fR\fR +.ad +.RS 12n +.rt +value from either \fIcallback\fR registered with \fBnet_instance_register()\fR +or \fBnet_zoneidtonetid()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 12n +.rt +function to call when a change occurs. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 12n +.rt +pointer to pass into the \fBcallback()\fR function when a change occurs. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_instance_notify_register()\fR function registers a function +represented by the pointer \fIcallback\fR to be called when there is a new +instance added or removed from the given network instance (represented by +\fInetid\fR.) +.sp +.LP +The \fBnet_instance_notify_unregister()\fR function indicates that there is no +longer any desire to receive notification of changes to the instance through +function calls to the specified \fIcallback\fR. +.sp +.LP +Multiple \fIcallback\fR functions may be registered through this interface. The +same set of parameters is passed to each \fIcallback\fR function. The memory +referenced through the pointers passed to the \fIcallback\fR should be treated +as pointing to read-only memory. Changing this data is strictly prohibited. +.sp +.LP +The function that is called must not block any other events. +.sp +.LP +The arguments passed through to the \fBcallback\fR are as follows (the command +is either \fBHN_REGISTER\fR or \fBHN_UNREGISTER\fR): +.sp +.ne 2 +.mk +.na +\fB\fIname1\fR\fR +.ad +.RS 9n +.rt +is the \fInetid\fR represented as a string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname2\fR\fR +.ad +.RS 9n +.rt +is \fBNULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname3\fR\fR +.ad +.RS 9n +.rt +is the name of the instance being added/removed +.RE + +.SH RETURN VALUES +.sp +.LP +If these functions succeed, 0 is returned. Otherwise, the following error is +returned: +.sp +.ne 2 +.mk +.na +\fBEEXIST\fR +.ad +.RS 10n +.rt +the given callback function is already registered. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBnet_instance_register\fR(9F), +\fBnet_instance_unregister\fR(9F), \fBnet_zoneidtonetid\fR(9F) diff --git a/usr/src/man/man9f/net_instance_register.9f b/usr/src/man/man9f/net_instance_register.9f new file mode 100644 index 0000000000..5a716f725d --- /dev/null +++ b/usr/src/man/man9f/net_instance_register.9f @@ -0,0 +1,72 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_instance_register 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_instance_register \- register a set of instances to occur with IP instance +events +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBint\fR \fBnet_instance_register\fR(\fBnet_instance_t\fR *\fIinstances\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIinstances\fR\fR +.ad +.RS 13n +.rt +must be a pointer returned by \fBnet_instance_alloc\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_instance_register()\fR function attempts to record the set of +functions passed by instances that are to be called when an event related to +\fBIP\fR instance maintenance occurs. +.SH RETURN VALUES +.sp +.LP +If the \fBnet_instance_register()\fR function succeeds, \fBDDI_SUCCESS\fR is +returned. Otherwise, \fBDDI_FAILURE\fR is returned to indicate failure due to +the name in the instance already being present. +.SH CONTEXT +.sp +.LP +The \fBnet_instance_register()\fR function may be called from user or kernel +context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_instance_alloc\fR(9F), \fBnet_instance_unregister\fR(9F), +\fBattributes\fR(5), \fBnet_instance_t\fR(9S) diff --git a/usr/src/man/man9f/net_instance_unregister.9f b/usr/src/man/man9f/net_instance_unregister.9f new file mode 100644 index 0000000000..df313105ad --- /dev/null +++ b/usr/src/man/man9f/net_instance_unregister.9f @@ -0,0 +1,69 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_instance_unregister 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_instance_unregister \- disable a set of instances +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBvoid\fR \fBnet_instance_unregister\fR(\fBnet_instance_t\fR *\fBinstances\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIinstances\fR\fR +.ad +.RS 13n +.rt +must be a pointer returned by \fBnet_instance_alloc\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_instance_unregister()\fR function removes the set of instances that +were previously registered with the \fBnet_instance_register()\fR function. +.SH RETURN VALUES +.sp +.LP +If the \fBnet_instance_unregister()\fR function succeeds, 0 is returned. +Otherwise, an error indicating the problem encountered. +.SH CONTEXT +.sp +.LP +The \fBnet_instance_unregister()\fR function may be called from user, kernel, +or interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_instance_alloc\fR(9F), \fBnet_instance_register\fR(9F), +\fBattributes\fR(5), \fBnet_instance_t\fR(9S) diff --git a/usr/src/man/man9f/net_ispartialchecksum.9f b/usr/src/man/man9f/net_ispartialchecksum.9f new file mode 100644 index 0000000000..54a1b2ec10 --- /dev/null +++ b/usr/src/man/man9f/net_ispartialchecksum.9f @@ -0,0 +1,153 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_ispartialchecksum 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_ispartialchecksum \- indicate if a packet is being scheduled for hardware +checksum calculation +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBint\fR \fBnet_ispartialchecksum\fR(\fBconst\fR \fBnet_data_t\fR \fInet\fR, \fBmblk_t\fR *\fImb\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 7n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImb\fR\fR +.ad +.RS 6n +.rt +the \fBmblk\fR structure holding a packet that is the subject of this query. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_ispartialchecksum()\fR function looks at the fields within the +\fBmblk\fR structure to determine if the packet contained inside contains +headers with only partial checksum values. Partial checksum values are stored +inside headers when the calculation of the complete checksum is being handled +by the hardware. +.SH RETURN VALUES +.sp +.LP +The \fBnet_ispartialchecksum()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB-1\fR +.ad +.RS 6n +.rt +The network protocol does not support this function. +.RE + +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 6n +.rt +The packet does not contain partial checksums. +.RE + +.sp +.LP +If a packet is marked for hardware checksum'ing, the following values are +returned: +.sp +.ne 2 +.mk +.na +\fB\fBNET_HCK_L3_FULL\fR\fR +.ad +.RS 19n +.rt +Complete layer 3 checksum calculated +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNET_HCK_L3_PART\fR\fR +.ad +.RS 19n +.rt +Partial layer 3 checksum calculated +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNET_HCK_L4_FULL\fR\fR +.ad +.RS 19n +.rt +Complete layer 4 checksum calculated +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNET_HCK_L4_PART\fR\fR +.ad +.RS 19n +.rt +Partial layer 4 checksum calculated +.RE + +.SH CONTEXT +.sp +.LP +The \fBnet_ispartialchecksum()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_isvalidchecksum\fR(9F), \fBnet_protocol_lookup\fR(9F), +\fBattributes\fR(5) diff --git a/usr/src/man/man9f/net_isvalidchecksum.9f b/usr/src/man/man9f/net_isvalidchecksum.9f new file mode 100644 index 0000000000..a1797cec09 --- /dev/null +++ b/usr/src/man/man9f/net_isvalidchecksum.9f @@ -0,0 +1,119 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_isvalidchecksum 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_isvalidchecksum \- verify layer 3 and layer 4 checksums +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBint\fR \fBnet_isvalidchecksum\fR(\fBconst\fR \fBnet_data_t\fR \fInet\fR, \fBmblk_t\fR *\fImb\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 7n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImb\fR\fR +.ad +.RS 6n +.rt +the \fBmblk\fR structure holding a packet that is the subject of this query. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_isvalidchecksum()\fR function verifies the layer 3 checksum (and, in +some case, the layer 4 checksum) in the packet. If possible, fields that are +used by hardware checksum'ing are examined rather than manually verifying that +the checksums are present for packets received from a network interface. +.sp +.LP +For both \fBIPv4\fR and \fBIPv6\fR, \fBTCP\fR, \fBUDP\fR and \fBICMP\fR +(including \fBICMPV6\fR for \fBIPv6\fR) layer 4 checksums are currently +validated. +.SH RETURN VALUES +.sp +.LP +The \fBnet_isvalidchecksum()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB-1\fR +.ad +.RS 6n +.rt +The network protocol does not support this function. +.RE + +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 6n +.rt +The packet does not contain partial checksums. +.RE + +.sp +.ne 2 +.mk +.na +\fB1\fR +.ad +.RS 6n +.rt +The packet does contain partial checksums. +.RE + +.SH CONTEXT +.sp +.LP +The \fBnet_isvalidchecksum()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_ispartialchecksum\fR(9F), \fBnet_protocol_lookup\fR(9F), +\fBattributes\fR(5) diff --git a/usr/src/man/man9f/net_kstat_create.9f b/usr/src/man/man9f/net_kstat_create.9f new file mode 100644 index 0000000000..1a420a4f42 --- /dev/null +++ b/usr/src/man/man9f/net_kstat_create.9f @@ -0,0 +1,233 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_kstat_create 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_kstat_create \- create and initialize a new kstat for a specific instance +of IP +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kstat.h> +#include <sys/neti.h> + +\fBkstat_t\fR *\fBnet_kstat_create\fR(\fBnetid_t\fR \fInetid\fR, \fBchar\fR *\fImodule\fR, + \fBint\fR \fIinstance\fR, \fBchar\fR *\fIname\fR, \fBchar\fR *\fIclass\fR, \fBuchar_type\fR \fItype\fR, + \fBulong_t\fR \fIndata\fR, \fBuchar_t\fR \fIks_flag\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInetid\fR\fR +.ad +.RS 12n +.rt +\fBIP\fR instance identifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImodule\fR\fR +.ad +.RS 12n +.rt +The name of the provider's module (such as "\fBsd\fR", "\fBesp\fR", ...). The +"\fBcore\fR" kernel uses the name "unix". +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinstance\fR\fR +.ad +.RS 12n +.rt +The provider's instance number, as from \fBddi_get_instance\fR(9F). Modules +which do not have a meaningful instance number should use \fB0\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 12n +.rt +A pointer to a string that uniquely identifies this structure. Only +\fBKSTAT_STRLEN \(mi 1\fR characters are significant. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIclass\fR\fR +.ad +.RS 12n +.rt +The general class that this kstat belongs to. The following classes are +currently in use: \fBdisk\fR, \fBtape\fR, \fBnet\fR, \fBcontroller\fR, +\fBvm\fR, \fBkvm\fR, \fBhat\fR, \fBstreams\fR, \fBkstat\fR, and \fBmisc\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 12n +.rt +The type of \fBkstat\fR to allocate. Valid types are: +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_TYPE_NAMED\fR\fR +.ad +.sp .6 +.RS 4n +Allows more than one data record per \fBkstat\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_TYPE_INTR\fR\fR +.ad +.sp .6 +.RS 4n +Interrupt; only one data record per \fBkstat\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_TYPE_IO\fR\fR +.ad +.sp .6 +.RS 4n +\fBI/O\fR; only one data record per \fBkstat\fR +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIndata\fR\fR +.ad +.RS 12n +.rt +The number of type-specific data records to allocate. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIks_flag\fR\fR +.ad +.RS 12n +.rt +A bit-field of various flags for this \fBkstat\fR. \fIks_flag\fR is some +combination of: +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_FLAG_VIRTUAL\fR\fR +.ad +.sp .6 +.RS 4n +Tells \fBkstat_create()\fR not to allocate memory for the \fBkstat\fR data +section; instead, the driver will set the \fBks_data\fR field to point to the +data it wishes to export. This provides a convenient way to export existing +data structures. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_FLAG_WRITABLE\fR\fR +.ad +.sp .6 +.RS 4n +Makes the \fBkstat\fR data section writable by root. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBKSTAT_FLAG_PERSISTENT\fR\fR +.ad +.sp .6 +.RS 4n +Indicates that this \fBkstat\fR is to be persistent over time. For persistent +\fBkstat\fRs, \fBkstat_delete\fR(9F) simply marks the \fBkstat\fR as dormant; a +subsequent \fBkstat_create()\fR reactivates the kstat. This feature is provided +so that statistics are not lost across driver close/open (such as raw disk +\fBI/O\fR on a disk with no mounted partitions.) Note: Persistent \fBkstat\fRs +cannot be virtual, since \fBks_data\fR points to garbage as soon as the driver +goes away. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_kstat_create()\fR function allocates and initializes a +\fBkstat\fR(9S) structure. See \fBkstat_create\fR(9F) for a complete discussion +of this function. +.SH RETURN VALUES +.sp +.LP +If successful, \fBnet_kstat_create()\fR returns a pointer to the allocated +\fBkstat\fR. \fINULL\fR is returned upon failure. +.SH CONTEXT +.sp +.LP +The \fBnet_kstat_create()\fR function may be called from user or kernel +context. +.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 +\fBddi_get_instance\fR(9F), \fBkstat_create\fR(9F), \fBkstat_delete\fR(9F), +\fBnet_kstat_delete\fR(9F), \fBhook_t\fR(9S), \fBkstat_named\fR(9S) diff --git a/usr/src/man/man9f/net_kstat_delete.9f b/usr/src/man/man9f/net_kstat_delete.9f new file mode 100644 index 0000000000..6b51c722fc --- /dev/null +++ b/usr/src/man/man9f/net_kstat_delete.9f @@ -0,0 +1,84 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_kstat_delete 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_kstat_delete \- remove a kstat for a specific instance of IP from the +system +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/kstat.h> +#include <sys/neti.h> + +\fBvoid\fR \fBnet_kstat_delete\fR(\fBnetid_t\fR \fInetid\fR, \fBkstat_t\fR *\fIksp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInetid\fR\fR +.ad +.RS 9n +.rt +\fBIP\fR instance identifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIksp\fR\fR +.ad +.RS 9n +.rt +Pointer to a currently installed \fBkstat\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_kstat_delete()\fR function removes \fIksp\fR from the \fBkstat\fR +chain and frees all associated system resources. See \fBkstat_delete\fR(9F) for +a complete discussion of this function. +.SH RETURN VALUES +.sp +.LP +If successful, \fBnet_kstat_delete()\fR returns a pointer to the allocated +\fBkstat\fR. \fINULL\fR is returned upon failure. +.SH CONTEXT +.sp +.LP +The \fBnet_kstat_delete()\fR function may be called from user, kernel, or +interrupt context. +.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 +\fBkstat_create\fR(9F), \fBkstat_delete\fR(9F), \fBnet_kstat_create\fR(9F), +\fBhook_t\fR(9S), \fBkstat_named\fR(9S) diff --git a/usr/src/man/man9f/net_lifgetnext.9f b/usr/src/man/man9f/net_lifgetnext.9f new file mode 100644 index 0000000000..1f6c9ff7b4 --- /dev/null +++ b/usr/src/man/man9f/net_lifgetnext.9f @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_lifgetnext 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_lifgetnext \- search through a list of logical network interfaces +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBnet_if_t\fR \fBnet_lifgetnext\fR(\fBconst\fR \fBnet_data_t\fR \fInet\fR, \fBconst\fR \fBphy_if_t\fR \fIifp\fR, + \fBnet_if_t\fR \fIlif\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 7n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIifp\fR\fR +.ad +.RS 7n +.rt +value returned from a successful call to \fBnet_phylookup\fR(9F) or +\fBnet_phygetnext\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlif\fR\fR +.ad +.RS 7n +.rt +value returned from a successful call to this function. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_lifgetnext()\fR function is used to search through all of the +logical interfaces that are associated with a physical network interface. To +start searching through this list, a value of 0 should be passed through as the +value of \fBlif\fR. When 0 is returned by this function, the last of the +interfaces owned by this protocol has been reached. +.sp +.LP +When called successfully, the value returned represents a logical interface +that exists, at the time of the call, within the scope of the network interface +and its assigned network protocol. This value is only guaranteed to be unique +for a name within the scope of the network interface and its assigned protocol. +.SH EXAMPLES +.sp +.in +2 +.nf + net_data_t net; + phy_if_t ifp; + net_if_t lif; + char buffer[32]; + net_ifaddr_t atype[1]; + struct sockaddr_in sin[1]; + + net = net_protocol_lookup("inet"); + + if (net != NULL) { + atype[0] = NA_ADDRESS; + ifp = net_phylookup(net, "hme0"); + for (lif = net_lifgetnext(net, 0); lif != 0; + lif = net_lifgetnext(net, lif)) { + /* Do something with lif */ + if (net_getlifaddr(net, ifp, lif, 1, atype, sin) == 0) + printf("hme0:%d %x0, lif, + ntohl(sin[0].sin_addr.s_addr)); + } + } +.fi +.in -2 +.sp + +.SH RETURN VALUES +.sp +.LP +The \fBnet_lifgetnext()\fR function returns a value of -1 if it is not +supported by the network protocol and a value of 0 if an attempt to go beyond +the last network interface is made. Otherwise, it returns a value representing +a network interface. +.SH CONTEXT +.sp +.LP +The \fBnet_lifgetnext()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_phygetnext\fR(9F), \fBnet_phylookup\fR(9F) diff --git a/usr/src/man/man9f/net_netidtozonid.9f b/usr/src/man/man9f/net_netidtozonid.9f new file mode 100644 index 0000000000..9716a099b0 --- /dev/null +++ b/usr/src/man/man9f/net_netidtozonid.9f @@ -0,0 +1,71 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_netidtozonid 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_netidtozonid \- map a netid_t structure identifier to a zoneid_t structure +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBzoneid_t\fR \fBnet_netidtozonid\fR(\fBconst\fR \fBnetid_t\fR \fInet\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 7n +.rt +valid \fBnetid_t\fR structure that refers to an existing \fBIP\fR instance. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_netidtozonid()\fR function maps the given \fBnetid_t\fR (used to +represent an instance of \fBIP\fR) into the matching \fBzoneid_t\fR structure +that is associated with it. +.SH RETURN VALUES +.sp +.LP +The \fBnet_netidtozonid()\fR function returns -1 if no mapping took place. +Otherwise, it returns the \fBzoneid_t\fR structure currently associated with a +\fBnetid_t\fR structure. For shared stack zones, the \fBzoneid_t\fR structure +for the global zone is returned. +.SH CONTEXT +.sp +.LP +The \fBnet_netidtozonid()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_zoneidtonetid\fR(9F), \fBattributes\fR(5) diff --git a/usr/src/man/man9f/net_phygetnext.9f b/usr/src/man/man9f/net_phygetnext.9f new file mode 100644 index 0000000000..387a4e8bf8 --- /dev/null +++ b/usr/src/man/man9f/net_phygetnext.9f @@ -0,0 +1,113 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_phygetnext 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_phygetnext \- search through the current list of network interfaces +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBphy_if_t\fR \fBnet_phygetnext\fR(\fBconst\fR \fBnet_data_t\fR \fInet\fR, \fBconst\fR \fBphy_if_t\fR \fIifp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 7n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIifp\fR\fR +.ad +.RS 7n +.rt +value returned from a successful call to this function or +\fBnet_phylookup\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_phygetnext()\fR function searches through all of the network +interfaces that a network protocol "owns". To start searching through all of +the interfaces owned by a protocol, a value of 0 should be passed through as +the value of \fBifp\fR. When 0 is returned by this function, the last of the +interfaces owned by this protocol has been reached. +.sp +.LP +When called successfully, the value returned represents a network interface +that exists, at the time of the call, within the scope of the network +interface. This value is only guaranteed to be unique for a name within the +scope of the network protocol. +.SH EXAMPLES +.sp +.in +2 +.nf + net_data_t net; + phy_if_t ifp; + char buffer[32]; + + net = net_protocol_lookup("inet"); + + if (net != NULL) { + for (ifp = net_phygetnext(net, 0); ifp != 0; + ifp = net_phygetnext(net, ifp)) { + /* Do something with ifp */ + if (net_getifname(net, ifp, buffer, + sizeof(buffer) >= 0) + printf("Interface %s0, buffer); + } + } +.fi +.in -2 +.sp + +.SH RETURN VALUES +.sp +.LP +The \fBnet_phygetnext()\fR function returns -1 if it is not supported by the +network protocol or 0 if an attempt to go beyond the last network interface +is made. Otherwise, it returns a value representing a network interface. +.SH CONTEXT +.sp +.LP +The \fBnet_phygetnext()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_phylookup\fR(9F), \fBnet_protocol_lookup\fR(9F), \fBattributes\fR(5) diff --git a/usr/src/man/man9f/net_phylookup.9f b/usr/src/man/man9f/net_phylookup.9f new file mode 100644 index 0000000000..7229cf5708 --- /dev/null +++ b/usr/src/man/man9f/net_phylookup.9f @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_phylookup 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_phylookup \- determine if a network interface name exists for a network +protocol +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBphy_if_t\fR \fBnet_phylookup\fR(\fBconst\fR \fBnet_data_t\fR \fInet\fR, \fBconst\fR \fBchar\fR *\fIname\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 8n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 8n +.rt +name of the network interface to find. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_phylookup()\fR function attempts to resolve the interface name +passed in with the network protocol. +.sp +.LP +When called successfully, the value returned represents a network interface +that exists, at the time of the call, within the scope of the network +interface. This value is only guaranteed to be unique for a name within the +scope of the network protocol. +.SH RETURN VALUES +.sp +.LP +The \fBnet_phylookup()\fR function returns -1 if it is not supported by the +network protocol, and 0 if the named network interface does not exist (or is +otherwise unknown). Otherwise, it returns a value greater than 0 +representing a network interface that currently exists within the scope of this +network protocol. +.SH CONTEXT +.sp +.LP +The \fBnet_phylookup()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_getifname\fR(9F), \fBnet_phygetnext\fR(9F), +\fBnet_protocol_lookup\fR(9F), \fBattributes\fR(5) diff --git a/usr/src/man/man9f/net_protocol_lookup.9f b/usr/src/man/man9f/net_protocol_lookup.9f new file mode 100644 index 0000000000..ee0853942f --- /dev/null +++ b/usr/src/man/man9f/net_protocol_lookup.9f @@ -0,0 +1,89 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_protocol_lookup 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_protocol_lookup \- locate an implementation of a network layer protocol +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBnet_data_t\fR \fBnet_protocol_lookup\fR(\fBnetid_t\fR \fIid\fR, \fBconst\fR \fBchar\fR *\fIprotocol\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIid\fR\fR +.ad +.RS 10n +.rt +network instance identifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfamily\fR\fR +.ad +.RS 10n +.rt +name of the network protocol to find. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_protocol_lookup()\fR function attempts to locate a data structure +that defines what capabilities it is exporting through this interface. The +value returned by this call is guaranteed to be valid until it is passed into a +call to \fBnet_protocol_release\fR(9F), after which it should no longer be +treated as valid. +.sp +.LP +The protocol must be a registered name of a network protocol that has been +registered. The symbols \fBNHF_INET\fR and \fBNHF_INET6\fR should be passed to +\fBnet_protocol_lookup()\fR as the protocol name to gain access to either +\fBIPv4\fR or \fBIPv6\fR respectively. +.SH RETURN VALUES +.sp +.LP +The \fBnet_protocol_lookup()\fR function returns \fBNULL\fR if it does not find +any knowledge about the network protocol referenced. Otherwise, it returns a +value that can be used with other calls in this framework. +.SH CONTEXT +.sp +.LP +The \fBnet_protocol_lookup()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_protocol_release\fR(9F), \fBattributes\fR(5) diff --git a/usr/src/man/man9f/net_protocol_notify_register.9f b/usr/src/man/man9f/net_protocol_notify_register.9f new file mode 100644 index 0000000000..4621b94f66 --- /dev/null +++ b/usr/src/man/man9f/net_protocol_notify_register.9f @@ -0,0 +1,164 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_protocol_notify_register 9F "30 Oct 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_protocol_notify_register, net_instance_protocol_unregister \- add/delete a +function to be called for changes to a protocol +.SH SYNOPSIS +.LP +.nf +#include <sys/hook.h> +#include <sys/neti.h> + +\fBint\fR \fBnet_protocol_notify_register\fR(\fBnet_handle_t\fR \fIfamily\fR, + \fBhook_notify_fn_t\fR *\fIcallback\fR, \fBvoid\fR *\fIarg\fR); + +\fBint\fR \fBnet_protocol_notify_unregister\fR(\fBnet_handle_t\fR \fIfamily\fR, + \fBhook_notify_fn_t\fR *\fIcallback\fR); + +\fBtypedef int\fR (* \fBhook_notify_fn_t\fR)(\fBhook_notify_cmd_t command,\fR + \fBvoid\fR *\fIarg\fR, \fBconst char\fR *\fIname1\fR, \fBconst char\fR *\fIname2\fR, \fBconst char\fR + *\fIname3\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIfamily\fR\fR +.ad +.RS 12n +.rt +value returned from \fBnet_protocol_lookup()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 12n +.rt +function to call when a change occurs. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 12n +.rt +pointer to pass into the \fBcallback()\fR function when a change occurs. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_protocol_notify_register()\fR function registers a function +represented by the pointer \fIcallback\fR to be called when there is a change +to the protocol represented by \fIfamily\fR. The types of changes for which +notifications are available for is currently limited to the addition and +removal of protocols. +.sp +.LP +The \fBnet_protocol_notify_unregister()\fR function removes the function +specified by the pointer \fIcallback\fR from the list of functions to call. +This call may fail if the specified function cannot be found. +.sp +.LP +Multiple \fIcallback\fR functions may be registered through this interface. The +same set of parameters is passed to each \fIcallback\fR function. The memory +referenced through the pointers passed to the \fIcallback\fR should be treated +as pointing to read-only memory. Changing this data is strictly prohibited. +.sp +.LP +The function that is called must not block any other protocols. +.sp +.LP +The arguments passed through to the \fBcallback\fR are as follows (the command +is either \fBHN_REGISTER\fR or \fBHN_UNREGISTER\fR): +.sp +.ne 2 +.mk +.na +\fB\fIname1\fR\fR +.ad +.RS 9n +.rt +is the name of the protocol +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname2\fR\fR +.ad +.RS 9n +.rt +is \fBNULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname3\fR\fR +.ad +.RS 9n +.rt +is the name of the protocol being added/removed +.RE + +.SH RETURN VALUES +.sp +.LP +If these functions succeed, 0 is returned. Otherwise, the following error is +returned: +.sp +.ne 2 +.mk +.na +\fBEEXIST\fR +.ad +.RS 10n +.rt +the given callback function is already registered. +.RE + +.SH CONTEXT +.sp +.LP +These functions may be called from user or kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBnet_protocol_lookup\fR(9F) diff --git a/usr/src/man/man9f/net_protocol_release.9f b/usr/src/man/man9f/net_protocol_release.9f new file mode 100644 index 0000000000..b78483f110 --- /dev/null +++ b/usr/src/man/man9f/net_protocol_release.9f @@ -0,0 +1,102 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_protocol_release 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_protocol_release \- indicate that a reference to a network protocol is no +longer required +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBint\fR \fBnet_protocol_release\fR(\fBnet_data_t\fR *\fInet\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 7n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_protocol_release()\fR function indicates to the network information +framework that the caller is no longer interested in any knowledge about the +network protocol to which the parameter being passed through applies. +.SH RETURN VALUES +.sp +.LP +The \fBnet_protocol_release()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB-1\fR +.ad +.RS 6n +.rt +The value passed in is unknown to this framework. +.RE + +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 6n +.rt +Successful completion. +.RE + +.sp +.ne 2 +.mk +.na +\fB1\fR +.ad +.RS 6n +.rt +Unsuccessful because this function has been called too many times. +.RE + +.SH CONTEXT +.sp +.LP +The \fBnet_protocol_release()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_protocol_lookup\fR(9F), \fBnet_protocol_walk\fR(9F), \fBattributes\fR(5) diff --git a/usr/src/man/man9f/net_protocol_walk.9f b/usr/src/man/man9f/net_protocol_walk.9f new file mode 100644 index 0000000000..4488d8f19d --- /dev/null +++ b/usr/src/man/man9f/net_protocol_walk.9f @@ -0,0 +1,79 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_protocol_walk 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_protocol_walk \- step through the list of registered network protocols +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBnet_data_t\fR *\fBnet_protocol_walk\fR(\fBnet_data_t\fR \fInet\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 7n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_protocol_walk()\fR function walks through all of the network +protocols that have been registered with this interface. The initial call to +\fBnet_protocol_walk()\fR should be made by passing in \fBNULL\fR as the value +for \fInet\fR. When this function returns \fBNULL\fR, the end of the list has +been reached. +.sp +.LP +A caller of \fBnet_protocol_walk()\fR is required to walk through the entire +list of network protocols, until \fBNULL\fR is returned or, when finished with +using the value returned, pass it into a call to +\fBnet_protocol_release\fR(9F). +.SH RETURN VALUES +.sp +.LP +The \fBnet_protocol_walk()\fR function returns \fBNULL\fR when the end of the +list is returned. Otherwise, it returns a non-\fBNULL\fR value as a token for +being passed into other function calls within this interface. +.SH CONTEXT +.sp +.LP +The \fBnet_protocol_walk()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_protocol_lookup\fR(9F), \fBnet_protocol_release\fR(9F), +\fBattributes\fR(5) diff --git a/usr/src/man/man9f/net_routeto.9f b/usr/src/man/man9f/net_routeto.9f new file mode 100644 index 0000000000..789636c0f7 --- /dev/null +++ b/usr/src/man/man9f/net_routeto.9f @@ -0,0 +1,129 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_routeto 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_routeto \- indicate which network interface packets are sent +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBphy_if_t\fR \fBnet_routeto\fR(\fBconst\fR \fBnet_data_t\fR *\fInet\fR, \fBstruct\fR \fBsockaddr\fR *\fIaddress\fR, + \fBstruct\fR \fBsockaddr\fR *\fInexthop\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInet\fR\fR +.ad +.RS 11n +.rt +value returned from a successful call to \fBnet_protocol_lookup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddress\fR\fR +.ad +.RS 11n +.rt +network address to find a path out of the machine for. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInexthop\fR\fR +.ad +.RS 11n +.rt +pointer to the \fBsockaddr\fR structure in which to store the address of the +next hop. If this information is not required, the value \fBNULL\fR may be +passed instead. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_routeto()\fR function indicates which network interface packets +destined for a particular address would be sent out of, according to the +systems network routing tables. If \fBnext\fR is supplied as a non-\fBNULL\fR +pointer, the \fBIP\fR address of the \fBnexthop\fR router to be used is +returned in it. +.SH RETURN VALUES +.sp +.LP +The \fBnet_routeto()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB-1\fR +.ad +.RS 6n +.rt +The network protocol does not support this function. +.RE + +.sp +.ne 2 +.mk +.na +\fB0\fR +.ad +.RS 6n +.rt +This function cannot find a route for the address given. +.RE + +.sp +.ne 2 +.mk +.na +\fB>0\fR +.ad +.RS 6n +.rt +Indicates which network interface can be used to reach the given address. +.RE + +.SH CONTEXT +.sp +.LP +The \fBnet_routeto()\fR function may be called from user, kernel, or interrupt +context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_phygetnext\fR(9F), \fBnet_phylookup\fR(9F), +\fBnet_protocol_lookup\fR(9F), \fBattributes\fR(5) diff --git a/usr/src/man/man9f/net_zoneidtonetid.9f b/usr/src/man/man9f/net_zoneidtonetid.9f new file mode 100644 index 0000000000..901cf51fe7 --- /dev/null +++ b/usr/src/man/man9f/net_zoneidtonetid.9f @@ -0,0 +1,73 @@ +'\" te +.\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH net_zoneidtonetid 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +net_zoneidtonetid \- map a zoneid_t struture identifier to a netid_t structure +.SH SYNOPSIS +.LP +.nf +#include <sys/neti.h> + +\fBnetid_t\fR \fBnet_zoneidtonetid\fR(\fBconst\fR \fBzoneid_t\fR \fIzone\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIzone\fR\fR +.ad +.RS 8n +.rt +valid \fBzoneid_t\fR structure that refers to a running zone. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnet_zoneidtonetid()\fR function maps the given \fBzoneid_t\fR structure +(used to represent a zone that is currently running) into a \fBnetid_t\fR +structure that is associated with the \fBIP\fR instance supporting network +functions for that zone. +.SH RETURN VALUES +.sp +.LP +The \fBnet_zoneidtonetid()\fR function returns -1 if no mapping took place. +Otherwise, it returns the \fBnetid_t\fR structure currently used by the +\fBzoneid_t\fR structure. For zones that are using a shared \fBIP\fR instance, +the \fBnetid_t\fR structure for the instance owned by the global zone is +returned. +.SH CONTEXT +.sp +.LP +The \fBnet_zoneidtonetid()\fR function may be called from user, kernel, or +interrupt context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBnet_netidtozonid\fR(9F), \fBattributes\fR(5) diff --git a/usr/src/man/man9f/netinfo.9f b/usr/src/man/man9f/netinfo.9f new file mode 100644 index 0000000000..6486a7abc9 --- /dev/null +++ b/usr/src/man/man9f/netinfo.9f @@ -0,0 +1,53 @@ +'\" 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 netinfo 9F "1 May 2008" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +netinfo \- interface to network data/functionality +.SH DESCRIPTION +.sp +.LP +The \fBnet_getnetid()\fR interface is designed to provide the framework for +accessing functionality and data within an implementation of a network layer +protocol (OSI layer 3.) A protocol may or may not provide full coverage for +each of the functions that is described within this interface. Where it does +not, it must return an appropriate error condition for that call. Documentation +pertaining to the network protocol, as found in man page section 7pP, must list +which functions provided by this interface are and are not supported. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBhook_alloc\fR(9F), \fBhook_free\fR(9F), +\fBhook_nic_event\fR(9S), \fBhook_pkt_event\fR(9S), \fBhook_t\fR(9S), +\fBnet_getifname\fR(9F), \fBnet_getlifaddr\fR(9F), \fBnet_getmtu\fR(9F), +\fBnet_getnetid\fR(9F), \fBnet_getpmtuenabled\fR(9F), +\fBnet_hook_register\fR(9F), \fBnet_hook_unregister\fR(9F), +\fBnet_inject\fR(9F), \fBnet_inject_alloc\fR(9F), \fBnet_inject_free\fR(9F), +\fBnet_inject_t\fR(9S), \fBnet_instance_alloc\fR(9F), +\fBnet_instance_free\fR(9F), \fBnet_instance_register\fR(9F), +\fBnet_instance_register\fR(9F), \fBnet_inject_t\fR(9S), +\fBnet_ispartialchecksum\fR(9F), \fBnet_isvalidchecksum\fR(9F), +\fBnet_kstat_create\fR(9F), \fBnet_kstat_delete\fR(9F), +\fBnet_lifgetnext\fR(9F), \fBnet_netidtozonid\fR(9F), \fBnet_phygetnext\fR(9F), +\fBnet_phylookup\fR(9F), \fBnet_protocol_lookup\fR(9F), +\fBnet_protocol_release\fR(9F), \fBnet_protocol_walk\fR(9F), +\fBnet_routeto\fR(9F), \fBnet_zoneidtonetid\fR(9F) diff --git a/usr/src/man/man9f/nochpoll.9f b/usr/src/man/man9f/nochpoll.9f new file mode 100644 index 0000000000..1913a4e20d --- /dev/null +++ b/usr/src/man/man9f/nochpoll.9f @@ -0,0 +1,102 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nochpoll 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +nochpoll \- error return function for non-pollable devices +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBnochpoll\fR(\fBdev_t\fR \fIdev\fR, \fBshort\fR \fIevents\fR, \fBint\fR \fIanyyet\fR, \fBshort\fR \fI*reventsp\fR, + \fBstruct pollhead\fR \fI**pollhdrp\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 12n +.rt +Device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevents\fR\fR +.ad +.RS 12n +.rt +Event flags. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIanyyet\fR\fR +.ad +.RS 12n +.rt +Check current events only. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreventsp\fR\fR +.ad +.RS 12n +.rt +Event flag pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpollhdrp\fR\fR +.ad +.RS 12n +.rt +Poll head pointer. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnochpoll()\fR function is a routine that simply returns the value +\fBENXIO\fR. It is intended to be used in the \fBcb_ops\fR(9S) structure of a +device driver for devices that do not support the \fBpoll\fR(2) system call. +.SH RETURN VALUES +.sp +.LP +The \fBnochpoll()\fR function returns \fBENXIO\fR. +.SH CONTEXT +.sp +.LP +The \fBnochpoll()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBpoll\fR(2), \fBchpoll\fR(9E), \fBcb_ops\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/nodev.9f b/usr/src/man/man9f/nodev.9f new file mode 100644 index 0000000000..9e433f21dc --- /dev/null +++ b/usr/src/man/man9f/nodev.9f @@ -0,0 +1,46 @@ +'\" 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 nodev 9F "27 Jan 1993" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +nodev \- error return function +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> + + + +\fBint\fR \fBnodev\fR(\|); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH DESCRIPTION +.sp +.LP +\fBnodev()\fR returns \fBENXIO\fR. It is intended to be used in the +\fBcb_ops\fR(9S) data structure of a device driver for device entry points +which are not supported by the driver. That is, it is an error to attempt to +call such an entry point. +.SH RETURN VALUES +.sp +.LP +\fBnodev()\fR returns \fBENXIO\fR. +.SH CONTEXT +.sp +.LP +\fBnodev()\fR can be only called from user context. +.SH SEE ALSO +.sp +.LP +\fBnulldev\fR(9F), \fBcb_ops\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/noenable.9f b/usr/src/man/man9f/noenable.9f new file mode 100644 index 0000000000..fceac1f991 --- /dev/null +++ b/usr/src/man/man9f/noenable.9f @@ -0,0 +1,59 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH noenable 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +noenable \- prevent a queue from being scheduled +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBnoenable\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 5n +.rt +Pointer to the queue. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnoenable()\fR function prevents the \fIq\fR from being scheduled for +service by \fBinsq\fR(9F), \fBputq\fR(9F) or \fBputbq\fR(9F) when enqueuing an +ordinary priority message. The queue can be re-enabled with the +\fBenableok\fR(9F) function. +.SH CONTEXT +.sp +.LP +The \fBnoenable()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBenableok\fR(9F), \fBinsq\fR(9F), \fBputbq\fR(9F), \fBputq\fR(9F), +\fBqenable\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/nulldev.9f b/usr/src/man/man9f/nulldev.9f new file mode 100644 index 0000000000..780cf15390 --- /dev/null +++ b/usr/src/man/man9f/nulldev.9f @@ -0,0 +1,44 @@ +'\" te +.\" Copyright (c) 1991, 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 nulldev 9F "11 Apr 1991" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +nulldev \- zero return function +.SH SYNOPSIS +.LP +.nf +#include <sys/conf.h> +#include <sys/ddi.h> + + + +\fBint\fR \fBnulldev\fR(\fB);\fR +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (\fBDDI/DKI\fR). +.SH DESCRIPTION +.sp +.LP +\fBnulldev()\fR returns \fB0\fR. It is intended to be used in the +\fBcb_ops\fR(9S) data structure of a device driver for device entry points that +do nothing. +.SH RETURN VALUES +.sp +.LP +\fBnulldev()\fR returns a \fB0\fR. +.SH CONTEXT +.sp +.LP +\fBnulldev()\fR can be called from any context. +.SH SEE ALSO +.sp +.LP +\fBnodev\fR(9F), \fBcb_ops\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/nvlist_add_boolean.9f b/usr/src/man/man9f/nvlist_add_boolean.9f new file mode 100644 index 0000000000..029bb7d8e8 --- /dev/null +++ b/usr/src/man/man9f/nvlist_add_boolean.9f @@ -0,0 +1,299 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nvlist_add_boolean 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +nvlist_add_boolean, nvlist_add_boolean_value, nvlist_add_byte, nvlist_add_int8, +nvlist_add_uint8, nvlist_add_int16, nvlist_add_uint16, nvlist_add_int32, +nvlist_add_uint32, nvlist_add_int64, nvlist_add_uint64, nvlist_add_string, +nvlist_add_nvlist, nvlist_add_nvpair, nvlist_add_boolean_array, +nvlist_add_int8_array, nvlist_add_uint8_array, nvlist_add_nvlist_array, +nvlist_add_byte_array, nvlist_add_int16_array, nvlist_add_uint16_array, +nvlist_add_int32_array, nvlist_add_uint32_array, nvlist_add_int64_array, +nvlist_add_uint64_array, nvlist_add_string_array, nvlist_t \- value pair +functions +.SH SYNOPSIS +.LP +.nf +#include <sys/nvpair.h> + +\fBint\fR \fBnvlist_add_boolean\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_boolean_value\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBboolean_t\fR \fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_byte\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBuchar_t\fR \fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_int8\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBint8_t\fR \fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_uint8\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBuint8_t\fR \fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_int16\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBint16_t\fR \fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_uint16\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBuint16_t\fR \fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_int32\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBint32_t\fR \fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_uint32\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBuint32_t\fR \fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_int64\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBint64_t\fR \fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_uint64\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBuint64_t\fR \fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_string\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBchar *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_nvlist\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBnvlist_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_nvpair\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvpair_t *\fR\fInvp\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_boolean_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBboolean_t *\fR\fIval\fR, \fBuint_t\fR \fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_byte_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBuchar_t *\fR\fIval\fR, + \fBuint_t\fR \fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_int8_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBint8_t *\fR\fIval\fR, + \fBuint_t\fR \fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_uint8_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBuint8_t *\fR\fIval\fR uint_t nelem); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_int16_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBint16_t *\fR\fIval\fR, + \fBuint_t\fR \fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_uint16_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBuint16_t *\fR\fIval\fR, + \fBuint_t\fR \fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_int32_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBint32_t *\fR\fIval\fR, + \fBuint_t\fR \fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_uint32_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBuint32_t *\fR\fIval\fR, + \fBuint_t\fR \fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_int64_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBint64_t *\fR\fIval\fR, + \fBuint_t\fR \fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_uint64_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBuint64_t *\fR\fIval\fR, + \fBuint_t\fR \fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_string_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBconst *char *\fR\fIval\fR, \fBuint_t\fR \fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_add_nvlist_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBnvlist_t **\fR\fIval\fR, \fBuint_t\fR \fInelem\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInvl\fR\fR +.ad +.RS 9n +.rt +The \fBnvlist_t\fR to be processed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInvp\fR\fR +.ad +.RS 9n +.rt +The \fBnvpair_t\fR (name-value pair) to be processed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 9n +.rt +Name of the name-value pair (\fBnvpair\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInelem\fR\fR +.ad +.RS 9n +.rt +Number of elements in value (that is, array size). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIval\fR\fR +.ad +.RS 9n +.rt +Value or starting address of the array value. +.RE + +.SH DESCRIPTION +.sp +.LP +These functions add a new name-value pair to an \fBnvlist_t\fR. The memory +allocation policy follows that specified in \fBnvlist_alloc()\fR, +\fBnvlist_unpack()\fR, or \fBnvlist_dup()\fR. See \fBnvlist_alloc\fR(9F). The +uniqueness of \fBnvpair\fR name and data types follows the \fInvflag\fR +argument specified in \fBnvlist_alloc()\fR. +.sp +.LP +If \fBNV_UNIQUE_NAME\fR was specified for \fInvflag\fR, existing \fBnvpair\fRs +with matching names are removed before the new \fBnvpair\fR is added. +.sp +.LP +If \fBNV_UNIQUE_NAME_TYPE\fR was specified for \fInvflag\fR, existing +\fBnvpair\fRs with matching names and data types are removed before the new +\fBnvpair\fR is added. +.sp +.LP +If neither was specified for \fInvflag\fR, the new \fBnvpair\fR is +unconditionally added at the end of the list. The library preserves the order +of the name-value pairs across packing, unpacking, and duplication. +.sp +.LP +Multiple threads can simultaneously read the same nvlist_t, but only one thread +may actively change a given nvlist_t at a time. The caller is responsible for +the synchronization. +.sp +.LP +The \fBnvlist_add_boolean()\fR function is deprecated and the +\fBnvlist_add_boolean_value()\fR function is used instead. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 10n +.rt +success +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +invalid argument +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +insufficient memory +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from interrupt context only if (1) the default +allocator is used and the \fBKM_NOSLEEP\fR flag is set, or (2) the specified +allocator did not sleep for free memory (for example, if it uses a +pre-allocated buffer for memory allocations). +.sp +.LP +See \fBnvlist_alloc\fR(9F) for a description of pluggable allocators and +KM_NOSLEEP. These functions can be called from user or kernel context in all +cases. diff --git a/usr/src/man/man9f/nvlist_alloc.9f b/usr/src/man/man9f/nvlist_alloc.9f new file mode 100644 index 0000000000..b0ae50ccd4 --- /dev/null +++ b/usr/src/man/man9f/nvlist_alloc.9f @@ -0,0 +1,704 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nvlist_alloc 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack, nvlist_dup, +nv_alloc_init, nv_alloc_fini, nvlist_xalloc, nvlist_xpack, nvlist_xunpack, +nvlist_xdup, nvlist_merge \- Manage a name-value pair list +.SH SYNOPSIS +.LP +.nf +#include <sys/nvpair.h> + +List Manipulation: + +\fBint\fR \fBnvlist_alloc\fR(\fBnvlist_t **\fR\fInvlp\fR, \fBuint_t\fR \fInvflag\fR, + \fBint\fR \fIkmflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_xalloc\fR(\fBnvlist_t **\fR\fInvlp\fR, \fBuint_t\fR \fInvflag\fR, \fBnv_alloc_t *\fR\fInva\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBnvlist_free\fR(\fBnvlist_t *\fR\fInvl\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_size\fR(\fBnvlist_t *\fR\fInvl\fR, \fBsize_t *\fR\fIsize\fR, \fBint\fR \fIencoding\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_pack\fR(\fBnvlist_t *\fR\fInvl\fR, \fBchar **\fR\fIbufp\fR, \fBsize_t *\fR\fIbuflen\fR, \fBint\fR \fIencoding\fR, + \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_xpack\fR(\fBnvlist_t *\fR\fInvl\fR, \fBchar **\fR\fIbufp\fR, \fBsize_t *\fR\fIbuflen\fR, \fBint\fR \fIencoding\fR, + \fBnv_alloc_t *\fR\fInva\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_unpack\fR(\fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR, \fBnvlist_t **\fR\fInvlp\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_xunpack\fR(\fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR, \fBnvlist_t **\fR\fInvlp\fR, + \fBnv_alloc_t *\fR\fInva\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_dup\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvlist_t **\fR\fInvlp\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_xdup\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvlist_t **\fR\fInvlp\fR, \fBnv_alloc_t *\fR\fInva\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_merge\fR(\fBnvlist_t *\fR\fIdst\fR, \fBnvlist_t *\fR\fInvl\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +Pluggable Allocator Configuration: + +\fBnv_alloc_t *\fR\fBnvlist_lookup_nv_alloc\fR(\fBnvlist_t *);\fR +.fi + +.LP +.nf +\fBint\fR \fBnv_alloc_init\fR(\fBnv_alloc_t *\fR\fInva\fR, + \fBconst nv_alloc_ops_t *\fR \fInvo,\fR/* args */ ...); +.fi + +.LP +.nf +\fBvoid\fR \fBnv_alloc_reset\fR(\fBnv_alloc_t *\fR\fInva\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBnv_alloc_fini\fR(\fBnv_alloc_t *\fR\fInva\fR); +.fi + +.LP +.nf +Pluggable Allocation Initialization with Fixed Allocator: + +\fBint\fR \fBnv_alloc_init\fR(\fBnv_alloc_t *\fR\fInva\fR, + \fBnv_fixed_ops\fR, \fBvoid *\fR \fIbufptr\fR, \fBsize_t\fR sz); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInvlp\fR\fR +.ad +.RS 12n +.rt +Address of a pointer to list of name-value pairs (\fBnvlist_t\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInvflag\fR\fR +.ad +.RS 12n +.rt +Specify bit fields defining \fBnvlist_t\fR properties: +.sp +.ne 2 +.mk +.na +\fB\fBNV_UNIQUE_NAME\fR\fR +.ad +.RS 23n +.rt +\fBnvpair\fR names are unique. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNV_UNIQUE_NAME_TYPE\fR\fR +.ad +.RS 23n +.rt +Name-data type combination is unique +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIkmflag\fR\fR +.ad +.RS 12n +.rt +Kernel memory allocation policy, either \fBKM_SLEEP\fR or \fBKM_NOSLEEP\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInvl\fR\fR +.ad +.RS 12n +.rt +\fBnvlist_t\fR to be processed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdst\fR\fR +.ad +.RS 12n +.rt +Destination \fBnvlist_t\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 12n +.rt +Pointer to buffer to contain the encoded size. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbufp\fR\fR +.ad +.RS 12n +.rt +Address of buffer to pack \fBnvlist\fR into. Must be 8-byte aligned. If NULL, +library will allocate memory. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuf\fR\fR +.ad +.RS 12n +.rt +Buffer containing packed \fBnvlist_t\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuflen\fR\fR +.ad +.RS 12n +.rt +Size of buffer \fIbufp\fR or \fIbuf\fR points to. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIencoding\fR\fR +.ad +.RS 12n +.rt +Encoding method for packing. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInvo\fR\fR +.ad +.RS 12n +.rt +Pluggable allocator operations pointer (nv_alloc_ops_t). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInva\fR\fR +.ad +.RS 12n +.rt +Points to a nv_alloc_t structure to be used for the specified \fBnvlist_t\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +List Manipulation: +.sp +.LP +The \fBnvlist_alloc()\fR function allocates a new name-value pair list and +updates \fInvlp\fR to point to the handle. The argument \fInvflag\fR specifies +\fBnvlist_t\fR properties to remain persistent across packing, unpacking, and +duplication. +.sp +.LP +If \fBNV_UNIQUE_NAME\fR is specified for nvflag, existing nvpairs with matching +names are removed before the new nvpair is added. If \fBNV_UNIQUE_NAME_TYPE\fR +is specified for nvflag, existing nvpairs with matching names and data types +are removed before the new nvpair is added. See \fBnvlist_add_byte\fR(9F) for +more details. +.sp +.LP +The \fBnvlist_xalloc()\fR function differs from \fBnvlist_alloc()\fR in that +\fBnvlist_xalloc()\fR can use a different allocator, as described in the +Pluggable Allocators section. +.sp +.LP +The \fBnvlist_free()\fR function frees a name-value pair list. +.sp +.LP +The \fBnvlist_size()\fR function returns the minimum size of a contiguous +buffer large enough to pack \fInvl\fR. The \fIencoding\fR parameter specifies +the method of encoding when packing \fInvl\fR. Supported encoding methods are: +.sp +.ne 2 +.mk +.na +\fB\fBNV_ENCODE_NATIVE\fR\fR +.ad +.RS 20n +.rt +Straight \fBbcopy()\fR as described in \fBbcopy\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBNV_ENCODE_XDR\fR\fR +.ad +.RS 20n +.rt +Use XDR encoding, suitable for sending to another host. +.RE + +.sp +.LP +The \fBnvlist_pack()\fR function packs \fInvl\fR into contiguous memory +starting at *\fIbufp\fR. The \fIencoding\fR parameter specifies the method of +encoding (see above). +.RS +4 +.TP +.ie t \(bu +.el o +If *\fIbufp\fR is not NULL, *\fIbufp\fR is expected to be a caller-allocated +buffer of size *\fIbuflen\fR. The \fIkmflag\fR argument is ignored. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If *\fIbufp\fR is NULL, the library allocates memory and updates *\fIbufp\fR to +point to the memory and updates *\fIbuflen\fR to contain the size of the +allocated memory. The value of \fIkmflag\fR indicates the memory allocation +policy +.RE +.sp +.LP +The \fBnvlist_xpack()\fR function differs from \fBnvlist_pack()\fR in that +\fBnvlist_xpack()\fR can use a different allocator. +.sp +.LP +The \fBnvlist_unpack()\fR function takes a buffer with a packed \fBnvlist_t\fR +and unpacks it into a searchable \fBnvlist_t\fR. The library allocates memory +for \fBnvlist_t\fR. The caller is responsible for freeing the memory by calling +\fBnvlist_free()\fR. +.sp +.LP +The \fBnvlist_xunpack()\fR function differs from \fBnvlist_unpack()\fR in that +\fBnvlist_xunpack()\fR can use a different allocator. +.sp +.LP +The \fBnvlist_dup()\fR function makes a copy of \fInvl\fR and updates +\fInvlp\fR to point to the copy. +.sp +.LP +The \fBnvlist_xdup()\fR function differs from \fBnvlist_dup()\fR in that +\fBnvlist_xdup()\fR can use a different allocator. +.sp +.LP +The \fBnvlist_merge()\fR function adds copies of all name-value pairs from +\fBnvlist_t\fR \fInvl\fR to \fBnvlist_t dst\fR. Name-value pairs in dst are +replaced with name-value pairs from \fBnvl\fR which have identical names (if +dst has the type \fBNV_UNIQUE_NAME\fR), or identical names and types (if dst +has the type \fBNV_UNIQUE_NAME_TYPE\fR). +.sp +.LP +The \fBnvlist_lookup_nv_alloc()\fR function retrieves the pointer to the +allocator used when manipulating a name-value pair list. +.SS "PLUGGABLE ALLOCATORS" +.sp +.LP +Using Pluggable Allocators: +.sp +.LP +The \fBnv_alloc_init()\fR, \fBnv_alloc_reset()\fR and \fBnv_alloc_fini()\fR +functions provide an interface that specifies the allocator to be used when +manipulating a name-value pair list. +.sp +.LP +The \fBnv_alloc_init()\fR determines allocator properties and puts them into +the \fInva\fR argument. You need to specify the \fInv_arg\fR argument, the +\fInvo\fR argument and an optional variable argument list. The optional +arguments are passed to the (*\fBnv_ao_init()\fR) function. +.sp +.LP +The \fInva\fR argument must be passed to \fBnvlist_xalloc()\fR, +\fBnvlist_xpack()\fR, \fBnvlist_xunpack()\fR and \fBnvlist_xdup()\fR. +.sp +.LP +The \fBnv_alloc_reset()\fR function resets the allocator properties to the data +specified by \fBnv_alloc_init()\fR. When no (*\fBnv_ao_reset()\fR) function is +specified, \fBnv_alloc_reset()\fR is without effect. +.sp +.LP +The \fBnv_alloc_fini()\fR destroys the allocator properties determined by +\fBnv_alloc_init()\fR. When a (*\fBnv_ao_fini()\fR) routine is specified, it is +called from \fBnv_alloc_fini()\fR. +.sp +.LP +The disposition of the allocated objects and the memory used to store them is +left to the allocator implementation. +.sp +.LP +The `nv_alloc_sleep' and `nv_alloc_nosleep' nv_alloc_t pointers may be used +with nvlist_xalloc to mimic the behavior of nvlist_alloc with KM_SLEEP and +KM_NOSLEEP, respectively. +.sp +.in +2 +.nf +o nv_alloc_nosleep +o nv_alloc_sleep +.fi +.in -2 + +.sp +.LP +The nvpair framework provides a fixed-buffer allocator, accessible via +nv_fixed_ops. +.sp +.in +2 +.nf +o nv_fixed_ops +.fi +.in -2 + +.sp +.LP +Given a buffer size and address, the fixed-buffer allocator allows for the +creation of nvlists in contexts where malloc or kmem_alloc services may not be +available. The fixed-buffer allocator is designed primarily to support the +creation of nvlists. +.sp +.LP +Memory freed using \fBnvlist_free()\fR, pair-removal, or similar routines is +not reclaimed. +.sp +.LP +When used to initialize the fixed-buffer allocator, nv_alloc_init should be +called as follows: +.sp +.in +2 +.nf +int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo, + void *bufptr, size_t sz); +.fi +.in -2 + +.sp +.LP +When invoked on a fixed-buffer, the \fBnv_alloc_reset()\fR function resets the +fixed buffer and prepares it for re-use. The framework consumer is responsible +for freeing the buffer passed to \fBnv_alloc_init()\fR. +.SS "CREATING PLUGGABLE ALLOCATORS" +.sp +.LP +Any producer of name-value pairs may possibily specify his own allocator +routines. You must provide the following pluggable allocator operations in the +allocator implementation. +.sp +.in +2 +.nf +int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist); +void (*nv_ao_fini)(nv_alloc_t *nva); +void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz); +void (*nv_ao_reset)(nv_alloc_t *nva); +void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz); +.fi +.in -2 + +.sp +.LP +The \fInva\fR argument of the allocator implementation is always the first +argument. +.sp +.LP +The optional (*\fBnv_ao_init()\fR ) function is responsible for filling the +data specified by \fBnv_alloc_init()\fR into the \fBnva_arg()\fR argument. The +(*\fBnv_ao_init()\fR) function is called only when \fBnv_alloc_init()\fR is +executed. +.sp +.LP +The optional (*\fBnv_ao_fini()\fR) function is responsible for the cleanup of +the allocator implementation. It is called by \fBnv_alloc_fini()\fR. +.sp +.LP +The required (*\fBnv_ao_alloc()\fR) function is used in the nvpair allocation +framework for memory allocation. The sz argument specifies the size of the +requested buffer. +.sp +.LP +The optional (*\fBnv_ao_reset()\fR) function is responsible for resetting the +nva_arg argument to the data specified by \fBnv_alloc_init()\fR. +.sp +.LP +The required (*\fBnv_ao_free()\fR) function is used in the nvpair allocator +framework for memory de-allocation. The argument buf is a pointer to a block +previously allocated by (*\fBnv_ao_alloc()\fR) function. The size argument sz +must exactly match the original allocation. +.sp +.LP +The disposition of the allocated objects and the memory used to store them is +left to the allocator implementation. +.SH RETURN VALUES +.sp +.LP +For \fBnvlist_alloc()\fR, \fBnvlist_dup()\fR, \fBnvlist_xalloc()\fR, and +\fBnvlist_xdup()\fR: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 10n +.rt +success +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +invalid argument +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +insufficient memory +.RE + +.sp +.LP +For \fBnvlist_pack()\fR, \fBnvlist_unpack()\fR, \fBnvlist_xpack()\fR, and +\fBnvlist_xunpack()\fR: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 11n +.rt +success +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +invalid argument +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 11n +.rt +insufficient memory +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEFAULT\fR\fR +.ad +.RS 11n +.rt +encode/decode error +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSUP\fR\fR +.ad +.RS 11n +.rt +encode/decode method not supported +.RE + +.sp +.LP +For \fBnvlist_size()\fR: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 10n +.rt +success +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +invalid argument +.RE + +.sp +.LP +For \fBnvlist_lookup_nv_alloc()\fR: +.sp +.LP +pointer to the allocator +.SH USAGE +.sp +.LP +The fixed-buffer allocator is very simple allocator. It uses a pre-allocated +buffer for memory allocations and it can be used in interrupt context. You are +responsible for allocation and de-allocation for the pre-allocated buffer. +.SH EXAMPLES +.sp +.in +2 +.nf + /* + * using the fixed-buffer allocator. + */ + #include <sys/nvpair.h> + + /* initialize the nvpair allocator framework */ + static nv_alloc_t * + init(char *buf, size_t size) + { + nv_alloc_t *nvap; + + if ((nvap = kmem_alloc(sizeof(nv_alloc_t), KM_SLEEP)) == NULL) + return (NULL); + + if (nv_alloc_init(nvap, nv_fixed_ops, buf, size) == 0) + return (nvap); + + return (NULL); + } + + static void + fini(nv_alloc_t *nvap) + { + nv_alloc_fini(nvap); + kmem_free(nvap, sizeof(nv_alloc_t)); + } + static int + interrupt_context(nv_alloc_t *nva) + { + nvlist_t *nvl; + int error; + + if ((error = nvlist_xalloc(&nvl, NV_UNIQUE_NAME, nva)) != 0) + return (-1); + + if ((error = nvlist_add_int32(nvl, "name", 1234)) == 0) + error = send_nvl(nvl); + + nvlist_free(nvl); + return (error); + } +.fi +.in -2 + +.SH CONTEXT +.sp +.LP +The \fBnvlist_alloc()\fR, \fBnvlist_pack()\fR, \fBnvlist_unpack()\fR, and +\fBnvlist_dup()\fR functions can be called from interrupt context only if the +\fBKM_NOSLEEP\fR flag is set. They can be called from user context with any +valid flag. +.sp +.LP +The \fBnvlist_xalloc()\fR, \fBnvlist_xpack()\fR, \fBnvlist_xunpack()\fR, and +\fBnvlist_xdup()\fR functions can be called from interrupt context only if (1) +the default allocator is used and the \fBKM_NOSLEEP\fR flag is set or (2) the +specified allocator did not sleep for free memory (for example, it uses a +pre-allocated buffer for memory allocations). +.sp +.LP +These functions can be called from user or kernel context with any valid flag. diff --git a/usr/src/man/man9f/nvlist_lookup_boolean.9f b/usr/src/man/man9f/nvlist_lookup_boolean.9f new file mode 100644 index 0000000000..c28f6bc3ff --- /dev/null +++ b/usr/src/man/man9f/nvlist_lookup_boolean.9f @@ -0,0 +1,412 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nvlist_lookup_boolean 9F "20 May 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +nvlist_lookup_boolean, nvlist_lookup_boolean_value, nvlist_lookup_byte, +nvlist_lookup_int8, nvlist_lookup_int16, nvlist_lookup_int32, +nvlist_lookup_int64, nvlist_lookup_uint8, nvlist_lookup_uint16, +nvlist_lookup_uint32, nvlist_lookup_uint64, nvlist_lookup_string, +nvlist_lookup_nvlist, nvlist_lookup_boolean_array, nvlist_lookup_byte_array, +nvlist_lookup_int8_array, nvlist_lookup_int16_array, nvlist_lookup_int32_array, +nvlist_lookup_int64_array, nvlist_lookup_uint8_array, +nvlist_lookup_uint16_array, nvlist_lookup_uint32_array, +nvlist_lookup_uint64_array, nvlist_lookup_string_array, +nvlist_lookup_nvlist_array, nvlist_lookup_pairs \- match name and type +indicated by the interface name and retrieve data value +.SH SYNOPSIS +.LP +.nf +#include <sys/nvpair.h> + +\fBint\fR \fBnvlist_lookup_boolean\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_boolean_value\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBboolean_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_byte\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBuchar_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_int8\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBint8_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_uint8\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBuint8_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_int16\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBint16_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_uint16\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBuint16_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_int32\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBint32_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_uint32\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBuint32_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_int64\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBint64_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_uint64\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBuint64_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_string\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBchar **\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_nvlist\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBnvlist_t **\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_boolean_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBboolean_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_byte_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBuchar_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_int8_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBint8_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_uint8_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBuint8_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_int16_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBint16_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_uint16_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBuint16_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_int32_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBint32_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_uint32_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBuint32_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_int64_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBint64_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_uint64_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBuint64_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_string_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBchar ***\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_nvlist_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + \fBnvlist_t ***\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_lookup_pairs\fR(\fBnvlist_t *\fR\fInvl\fR, \fBint\fR \fIflag, ...\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInvl\fR\fR +.ad +.RS 9n +.rt +The list of name-value pairs (\fBnvlist_t\fR) to be processed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 9n +.rt +Name of the name-value pair (\fBnvpair\fR) to search. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInelem\fR\fR +.ad +.RS 9n +.rt +Address to store the number of elements in value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIval\fR\fR +.ad +.RS 9n +.rt +Address to store the value or starting address of the array value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 9n +.rt +Specify bit fields defining lookup behavior: +.sp +.ne 2 +.mk +.na +\fBNV_FLAG_NOENTOK\fR +.ad +.RS 19n +.rt +The retrival function will not fail if no matching name-value pair is found. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +These functions find the \fBnvpair\fR that matches the name and type as +indicated by the interface name. If one is found, \fInelem\fR and \fIval\fR are +modified to contain the number of elements in value and the starting address of +data, respectively. +.sp +.LP +These interfaces work for \fBnvlist_t\fR allocated with \fBNV_UNIQUE_NAME\fR or +\fBNV_UNIQUE_NAME_TYPE\fR specified in \fBnvlist_alloc()\fR. See +\fBnvlist_alloc\fR(9F). If this is not the case, the interface will return +\fBENOTSUP\fR because the list potentially contains multiple \fBnvpair\fRs with +the same name and type. +.sp +.LP +Multiple threads can simultaneously read the same \fBnvlist_t\fR but only one +thread should actively change a given \fBnvlist_t\fR at a time. The caller is +responsible for the synchronization. +.sp +.LP +All memory required for storing the array elements, including string values, +are managed by the library. References to such data remain valid until +\fBnvlist_free()\fR is called on \fInvl\fR. +.sp +.LP +The \fBnvlist_lookup_pairs()\fR function retrieves a set of \fBnvpair\fRs. The +arguments are a null-terminated list of pairs (data type +\fBDATA_TYPE_BOOLEAN\fR), triples (non-array data types) or quads (array data +types). As shown below, the interpretation of the arguments depends on the +value of \fItype\fR. See \fBnvpair_type\fR(9F). +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 9n +.rt +Name of the name-value pair to search. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 9n +.rt +Data type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIval\fR\fR +.ad +.RS 9n +.rt +Address to store the starting address of the value. When using data type +\fBDATA_TYPE_BOOLEAN\fR, the \fIval\fR argument is ignored. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInelem\fR\fR +.ad +.RS 9n +.rt +Address to store the number of elements in value. Non-array data types have +only one argument and \fInelem\fR is ignored. +.RE + +.sp +.LP +The argument order is \fIname\fR, \fItype\fR, [\fIval\fR], [\fInelem\fR]. +.sp +.LP +When using \fBNV_FLAG_NOENTOK\fR and no matching name-value pair is found, the +memory pointed to by \fIval\fR and \fInelem\fR is not touched. +.sp +.LP +These functions return \fB0\fR on success and an error value on failure. +.SH ERRORS +.sp +.LP +These functions fail under the following conditions. +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 11n +.rt +Success +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +Invalid argument +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 11n +.rt +No matching name-value pair found +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSUP\fR\fR +.ad +.RS 11n +.rt +Encode/decode method not supported +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.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 +\fBnvlist_alloc\fR(9F), \fBnvpair_type\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/nvlist_lookup_nvpair.9f b/usr/src/man/man9f/nvlist_lookup_nvpair.9f new file mode 100644 index 0000000000..395a83039e --- /dev/null +++ b/usr/src/man/man9f/nvlist_lookup_nvpair.9f @@ -0,0 +1,100 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nvlist_lookup_nvpair 9F "24 Oct 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +nvlist_lookup_nvpair, nvlist_exists \- lookup named pairs +.SH SYNOPSIS +.LP +.nf +#include <libnvpair.h> + +\fBint\fR \fBnvlist_lookup_nvpair\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, + nvpair_t **\fInvp\fR); +.fi + +.LP +.nf +\fBboolean_t\fR \fBnvlist_exists\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBnvlist_lookup_nvpair()\fR function returns the nvpair with the matching +name, regardless of type. It is valid only for lists allocated with +\fBNV_UNIQUE_NAME\fR. See \fBnvlist_alloc\fR(9F). +.sp +.LP +The \fBnvlist_exists()\fR function returns success if any nvpair exists with +the given name. It is valid for all types of lists. +.SH RETURN VALUES +.sp +.LP +The \fBnvlist_lookup_nvpair()\fR function returns 0 on success and an error +value on failure. +.sp +.LP +The \fBnvlist_exists()\fR function returns \fBB_TRUE\fR if an nvpair with the +given name exists and \fBB_FALSE\fR otherwise. +.SH ERRORS +.sp +.LP +The \fBnvlist_lookup_nvpair()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +There is an invalid argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOENT\fR\fR +.ad +.RS 11n +.rt +No matching name-value pair is found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSUP\fR\fR +.ad +.RS 11n +.rt +The list was not allocated with \fBNV_UNIQUE_NAME\fR. +.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 +\fBnvlist_lookup_nvpair\fR(3NVPAIR), \fBnvlist_alloc\fR(9F), +\fBattributes\fR(5) diff --git a/usr/src/man/man9f/nvlist_next_nvpair.9f b/usr/src/man/man9f/nvlist_next_nvpair.9f new file mode 100644 index 0000000000..7da393b7aa --- /dev/null +++ b/usr/src/man/man9f/nvlist_next_nvpair.9f @@ -0,0 +1,121 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nvlist_next_nvpair 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +nvlist_next_nvpair, nvpair_name, nvpair_type \- return data regarding +name-value pairs +.SH SYNOPSIS +.LP +.nf +#include <sys/nvpair.h> + +\fBnvpair_t *\fR\fBnvlist_next_nvpair\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvpair_t *\fR\fInvpair\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBnvpair_name\fR(\fBnvpair_t *\fR\fInvpair\fR); +.fi + +.LP +.nf +\fBdata_type_t\fR \fBnvpair_type\fR(\fBnvpair_t *\fR\fInvpair\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInvl\fR\fR +.ad +.RS 10n +.rt +The list of name-value pairs (\fBnvlist_t\fR) to be processed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInvpair\fR\fR +.ad +.RS 10n +.rt +Handle to a name-value pair. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnvlist_next_nvpair()\fR function returns a handle to the next name-value +pair (\fBnvpair\fR) in the list following \fInvpair\fR. If \fInvpair\fR is +NULL, the first pair is returned. If \fInvpair\fR is the last pair in the +\fBnvlist_t\fR, NULL is returned. +.sp +.LP +The \fBnvpair_name()\fR function returns a string containing the name of +\fInvpair\fR. +.sp +.LP +The \fBnvpair_type()\fR function retrieves the value of the \fInvpair\fR in the +form of enumerated type \fBdata_type_t\fR. This is used to determine the +appropriate \fBnvpair_*()\fR function to call for retrieving the value. +.SH RETURN VALUES +.sp +.LP +For \fBnvpair_name()\fR: a string containing the name. +.sp +.LP +For \fBnvpair_type()\fR: an enumerated data type \fBdata_type_t\fR. Possible +values for \fBdata_type_t\fR are: +.sp +.in +2 +.nf +DATA_TYPE_BOOLEAN +DATA_TYPE_BOOLEAN_VALUE +DATA_TYPE_BYTE +DATA_TYPE_INT8 +DATA_TYPE_UINT8 +DATA_TYPE_INT16 +DATA_TYPE_UINT16 +DATA_TYPE_INT32 +DATA_TYPE_UINT32 +DATA_TYPE_INT64 +DATA_TYPE_UINT64 +DATA_TYPE_STRING +DATA_TYPE_NVLIST +DATA_TYPE_BOOLEAN_ARRAY +DATA_TYPE_BYTE_ARRAY +DATA_TYPE_INT8_ARRAY +DATA_TYPE_UINT8_ARRAY +DATA_TYPE_INT16_ARRAY +DATA_TYPE_UINT16_ARRAY +DATA_TYPE_INT32_ARRAY +DATA_TYPE_UINT32_ARRAY +DATA_TYPE_INT64_ARRAY +DATA_TYPE_UINT64_ARRAY +DATA_TYPE_STRING_ARRAY +DATA_TYPE_NVLIST_ARRAY +.fi +.in -2 +.sp + +.sp +.LP +After nvpairs is removed from or replaced in an nvlist, it cannot be +manipulated. This includes \fBnvlist_next_nvpair()\fR, \fBnvpair_name()\fR and +\fBnvpair_type()\fR. Replacement can happen during pair addition on nvlists +created with NV_UNIQUE_NAME_TYPE and NV_UNIQUE_NAME. See \fBnvlist_alloc\fR(9F) +for more details. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. diff --git a/usr/src/man/man9f/nvlist_remove.9f b/usr/src/man/man9f/nvlist_remove.9f new file mode 100644 index 0000000000..9d90db06ae --- /dev/null +++ b/usr/src/man/man9f/nvlist_remove.9f @@ -0,0 +1,106 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nvlist_remove 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +nvlist_remove, nvlist_remove_all \- remove name-value pairs +.SH SYNOPSIS +.LP +.nf +#include <sys/nvpair.h> + +\fBint\fR \fBnvlist_remove\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR, \fBdata_type_t\fR \fItype\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvlist_remove_all\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInvl\fR\fR +.ad +.RS 8n +.rt +The list of name-value pairs (\fBnvlist_t\fR) to be processed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 8n +.rt +Name of the name-value pair (\fBnvpair\fR) to be removed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 8n +.rt +Data type of the \fBnvpair\fR to be removed. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBnvlist_remove()\fR function removes the first occurrence of \fInvpair\fR +that matches the name and the type. +.sp +.LP +The \fBnvlist_remove_all()\fR function removes all occurrences of \fInvpair\fR +that match the name, regardless of type. +.sp +.LP +Multiple threads can simultaneously read the same \fBnvlist_t\fR but only one +thread may actively change a given \fBnvlist_t\fR at a time. The caller is +responsible for the synchronization. +.SH RETURN VALUES +.sp +.LP +These functions return \fB0\fR on success and an error value on failure. +.SH CONTEXT +.sp +.LP +The \fBnvlist_remove()\fR and \fBnvlist_remove_all()\fR functions can be called +from user, interrupt, or kernel context. +.SH ERRORS +.sp +.ne 2 +.mk +.na +\fBEINVAL\fR +.ad +.RS 10n +.rt +There is an invalid argument. +.RE + +.sp +.ne 2 +.mk +.na +\fBENOENT\fR +.ad +.RS 10n +.rt +No name-value pairs were found to match the criteria specified by name and +type. +.RE + diff --git a/usr/src/man/man9f/nvpair_value_byte.9f b/usr/src/man/man9f/nvpair_value_byte.9f new file mode 100644 index 0000000000..9a42e78b65 --- /dev/null +++ b/usr/src/man/man9f/nvpair_value_byte.9f @@ -0,0 +1,238 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH nvpair_value_byte 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +nvpair_value_byte, nvpair_value_nvlist, nvpair_value_int8, nvpair_value_int16, +nvpair_value_int32, nvpair_value_int64, nvpair_value_uint8, +nvpair_value_uint16, nvpair_value_uint32, nvpair_value_uint64, +nvpair_value_string, nvpair_value_boolean_array, nvpair_value_byte_array, +nvpair_value_nvlist_array, nvpair_value_int8_array, nvpair_value_int16_array, +nvpair_value_int32_array, nvpair_value_int64_array, nvpair_value_uint8_array, +nvpair_value_uint16_array, nvpair_value_uint32_array, +nvpair_value_uint64_array, nvpair_value_string_array \- retrieve value from a +name-value pair +.SH SYNOPSIS +.LP +.nf +#include <sys/nvpair.h> + +\fBint\fR \fBnvpair_value_boolean_value\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBboolean_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_byte\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBuchar_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_int8\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBint8_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_uint8\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBuint8_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_int16\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBint16_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_uint16\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBuint16_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_int32\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBint32_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_uint32\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBuint32_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_int64\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBint64_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_uint64\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBuint64_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_string\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBchar **\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_nvlist\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBnvlist_t **\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_boolean_array\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBboolean_t **\fR\fIval\fR, + \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_byte_array\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBuchar_t **\fR\fIval\fR, + \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_int8_array\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBint8_t **\fR\fIval\fR, + \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_uint8_array\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBuint8_t **\fR\fIval\fR, + \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_int16_array\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBint16_t **\fR\fIval\fR, + \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_uint16_array\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBuint16_t **\fR\fIval\fR, + \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_int32_array\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBint32_t **\fR\fIval\fR, + \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_uint32_array\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBuint32_t **\fR\fIval\fR, + \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_int64_array\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBint64_t **\fR\fIval\fR, + \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_uint64_array\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBuint64_t **\fR\fIval\fR, + \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_string_array\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBchar ***\fR\fIval\fR, + \fBuint_t *\fR\fInelem\fR); +.fi + +.LP +.nf +\fBint\fR \fBnvpair_value_nvlist_array\fR(\fBnvpair_t *\fR\fInvpair\fR, \fBnvlist_t ***\fR\fIval\fR, + \fBuint_t *\fR\fInelem\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInvpair\fR\fR +.ad +.RS 10n +.rt +Name-value pair (\fBnvpair\fR) to be processed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInelem\fR\fR +.ad +.RS 10n +.rt +Address to store the number of elements in value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIval\fR\fR +.ad +.RS 10n +.rt +Address to store the value or starting address of array value. +.RE + +.SH DESCRIPTION +.sp +.LP +These functions retrieve the value of \fInvpair\fR. The data type of +\fInvpair\fR must match the function name for the call to be successful. +.sp +.LP +There is no \fBnvpair_value_boolean()\fR; the existence of the name implies the +value is true. +.sp +.LP +For array data types, including string, the memory containing the data is +managed by the library and references to the value remains valid until +\fBnvlist_free()\fR is called on the \fBnvlist_t\fR from which \fInvpair\fR is +obtained. See \fBnvlist_free\fR(9F) +.sp +.LP +The value of an nvpair may not be retrieved after the nvpair having been +removed from or replaced in an nvlist. Replacement can happen during pair +addition on nvlists created with NV_UNIQUE_NAME_TYPE and NV_UNIQUE_NAME. See +\fBnvlist_alloc(9F)\fR for more details. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 10n +.rt +Success +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Either one of the arguments is \fINULL\fR or type of \fInvpair\fR does not +match the interface name. +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. diff --git a/usr/src/man/man9f/outb.9f b/usr/src/man/man9f/outb.9f new file mode 100644 index 0000000000..60b21775d1 --- /dev/null +++ b/usr/src/man/man9f/outb.9f @@ -0,0 +1,144 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All RIghts Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH outb 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +outb, outw, outl, repoutsb, repoutsw, repoutsd \- write to an I/O port +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBvoid\fR \fBoutb\fR(\fBint\fR \fIport\fR, \fBunsigned char\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBoutw\fR(\fBint\fR \fIport\fR, \fBunsigned short\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBoutl\fR(\fBint\fR \fIport\fR, \fBunsigned long\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrepoutsb\fR(\fBint\fR \fIport\fR, \fBunsigned char *\fR\fIaddr\fR, \fBint\fR \fIcount\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrepoutsw\fR(\fBint\fR \fIport\fR, \fBunsigned short *\fR\fIaddr\fR, \fBint\fR \fIcount\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrepoutsd\fR(\fBint\fR \fIport\fR, \fBunsigned long *\fR\fIaddr\fR, \fBint\fR \fIcount\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +The functions described here are obsolete. For the \fBoutb()\fR, \fBoutw()\fR, +and \fBoutl()\fR functions use, respectively, \fBddi_put8\fR(9F), +\fBddi_put8\fR(9F), and \fBddi_put8\fR(9F) instead. For \fBrepoutsb()\fR, +\fBrepoutsw()\fR, and\fBrepoutsl()\fR, use, respectively, +\fBddi_rep_put8\fR(9F), \fBddi_rep_put8\fR(9F), and \fBddi_rep_put8\fR(9F) +instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIport\fR\fR +.ad +.RS 9n +.rt +A valid \fBI/O\fR port address. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvalue\fR\fR +.ad +.RS 9n +.rt +The data to be written to the \fBI/O\fR port. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR\fR +.ad +.RS 9n +.rt +The address of a buffer from which the values will be fetched. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcount\fR\fR +.ad +.RS 9n +.rt +The number of values to be written to the \fBI/O\fR port. +.RE + +.SH DESCRIPTION +.sp +.LP +These routines write data of various sizes to the \fBI/O\fR port with the +address specified by \fIport\fR. +.sp +.LP +The \fBoutb()\fR, \fBoutw()\fR, and \fBoutl()\fR functions write 8 bits, 16 +bits, and 32 bits of data respectively, writing the data specified by +\fIvalue\fR. +.sp +.LP +The \fBrepoutsb()\fR, \fBrepoutsw()\fR, and \fBrepoutsd()\fR functions write +multiple 8-bit, 16-bit, and 32-bit values, respectively. \fIcount\fR specifies +the number of values to be written. \fIaddr\fR is a pointer to a buffer from +which the output values are fetched. +.SH CONTEXT +.sp +.LP +These functions may be called from user, interrupt, or kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Architecturex86 +_ +Interface Stability Obsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBisa\fR(4), \fBattributes\fR(5), \fBddi_put8\fR(9F), \fBddi_put8\fR(9F), +\fBddi_put8\fR(9F), \fBddi_rep_put8\fR(9F), \fBddi_rep_put8\fR(9F), +\fBddi_rep_put8\fR(9F), \fBinb\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/pci_config_get8.9f b/usr/src/man/man9f/pci_config_get8.9f new file mode 100644 index 0000000000..3c730030c0 --- /dev/null +++ b/usr/src/man/man9f/pci_config_get8.9f @@ -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 pci_config_get8 9F "1 Nov 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +pci_config_get8, pci_config_get16, pci_config_get32, pci_config_get64, +pci_config_put8, pci_config_put16, pci_config_put32, pci_config_put64, +pci_config_getb, pci_config_getl, pci_config_getll, pci_config_getw, +pci_config_putb, pci_config_putl, pci_config_putll, pci_config_putw \- read or +write single datum of various sizes to the PCI Local Bus Configuration space +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBuint8_t\fR \fBpci_config_get8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBoff_t\fR \fIoffset\fR); +.fi + +.LP +.nf +\fBuint16_t\fR \fBpci_config_get16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBoff_t\fR \fIoffset\fR); +.fi + +.LP +.nf +\fBuint32_t\fR \fBpci_config_get32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBoff_t\fR \fIoffset\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBpci_config_get64\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBoff_t\fR \fIoffset\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpci_config_put8\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBoff_t\fR \fIoffset\fR, + \fBuint8_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpci_config_put16\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBoff_t\fR \fIoffset\fR, + \fBuint16_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpci_config_put32\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBoff_t\fR \fIoffset\fR, + \fBuint32_t\fR \fIvalue\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpci_config_put64\fR(\fBddi_acc_handle_t\fR \fIhandle\fR, \fBoff_t\fR \fIoffset\fR, + \fBuint64_t\fR \fIvalue\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBpci_config_getb()\fR, +\fBpci_config_getl()\fR, \fBpci_config_getll()\fR, \fBpci_config_getw()\fR, +\fBpci_config_putb()\fR, \fBpci_config_putl()\fR, \fBpci_config_putll()\fR, and +\fBpci_config_putw()\fR functions are obsolete. The \fBpci_config_get8()\fR +function replaces \fBpci_config_getb()\fR. The \fBpci_config_get32()\fR +function replaces \fBpci_config_getl()\fR. The \fBpci_config_get64()\fR +function replaces \fBpci_config_getll()\fR. The \fBpci_config_get16()\fR +function replaces \fBpci_config_getw()\fR. The \fBpci_config_put8()\fR function +replaces \fBpci_config_putb()\fR. The \fBpci_config_put32()\fR function +replaces \fBpci_config_putl()\fR. The \fBpci_config_put64()\fR function +replaces \fBpci_config_putll()\fR. The \fBpci_config_put16()\fR function +replaces \fBpci_config_putw()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 10n +.rt +The data access handle returned from \fBpci_config_setup\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoffset\fR\fR +.ad +.RS 10n +.rt +Byte offset from the beginning of the \fBPCI \fRConfiguration space. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvalue\fR\fR +.ad +.RS 10n +.rt +Output data. +.RE + +.SH DESCRIPTION +.sp +.LP +These routines read or write a single datum of various sizes from or to the +\fBPCI \fRLocal Bus Configuration space. The \fBpci_config_get8()\fR, +\fBpci_config_get16()\fR, \fBpci_config_get32()\fR, and +\fBpci_config_get64()\fR functions read 8 bits, 16 bits, 32 bits, and 64 bits +of data, respectively. The \fBpci_config_put8()\fR, \fBpci_config_put16()\fR, +\fBpci_config_put32()\fR, and \fBpci_config_put64()\fR functions write 8 bits, +16 bits, 32 bits, and 64 bits of data, respectively. The \fIoffset\fR argument +must be a multiple of the datum size. +.sp +.LP +Since th \fBPCI \fRLocal Bus Configuration space is represented in little +endian data format, these functions translate the data from or to native host +format to or from little endian format. +.sp +.LP +\fBpci_config_setup\fR(9F) must be called before invoking these functions. +.SH RETURN VALUES +.sp +.LP +\fBpci_config_get8()\fR, \fBpci_config_get16()\fR, \fBpci_config_get32()\fR, +and \fBpci_config_get64()\fR return the value read from the \fBPCI \fRLocal +Bus Configuration space. +.SH CONTEXT +.sp +.LP +These routines can be called from user, kernel, or interrupt context. +.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 StabilityT{ +\fBpci_config_getb()\fR, \fBpci_config_getl()\fR, \fBpci_config_getll()\fR, \fBpci_config_getw()\fR, \fBpci_config_putb()\fR, \fBpci_config_putl()\fR, \fBpci_config_putll()\fR, \fBpci_config_putw()\fR are Obsolete \fBpci_config_get8()\fR, \fBpci_config_get16()\fR, \fBpci_config_get32()\fR, \fBpci_config_get64()\fR, \fBpci_config_put8()\fR, \fBpci_config_put16()\fR, \fBpci_config_put32()\fR, \fBpci_config_put64()\fR are Committed +T} +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBpci_config_setup\fR(9F), \fBpci_config_teardown\fR(9F) diff --git a/usr/src/man/man9f/pci_config_setup.9f b/usr/src/man/man9f/pci_config_setup.9f new file mode 100644 index 0000000000..8d432bd26a --- /dev/null +++ b/usr/src/man/man9f/pci_config_setup.9f @@ -0,0 +1,120 @@ +'\" 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 pci_config_setup 9F "1 Jan 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +pci_config_setup, pci_config_teardown \- setup or tear down the resources for +enabling accesses to the PCI Local Bus Configuration space +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> + #include <sys/sunddi.h> + + + +\fBint\fR \fBpci_config_setup\fR(\fBdev_info_t\fR \fI*dip\fR, \fBddi_acc_handle_t\fR \fI*handle\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpci_config_teardown\fR(\fBddi_acc_handle_t\fR \fI*handle\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 11n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR \fR +.ad +.RS 11n +.rt +Pointer to a data access handle. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBpci_config_setup()\fR sets up the necessary resources for enabling +subsequent data accesses to the \fBPCI \fRLocal Bus Configuration space. +\fBpci_config_teardown()\fR reclaims and removes those resources represented +by the data access handle returned from \fBpci_config_setup()\fR. +.SH RETURN VALUES +.sp +.LP +\fBpci_config_setup()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR \fR +.ad +.RS 16n +.rt +Successfully setup the resources. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR \fR +.ad +.RS 16n +.rt +Unable to allocate resources for setup. +.RE + +.SH CONTEXT +.sp +.LP +\fBpci_config_setup()\fR must be called from user or kernel context. +\fBpci_config_teardown()\fR can be called from any context. +.SH NOTES +.sp +.LP +These functions are specific to \fBPCI \fRbus device drivers. For drivers using +these functions, a single source to support devices with multiple bus versions +may not be easy to maintain. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI Local Bus +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5) +.sp +.LP +\fIIEEE 1275 PCI Bus Binding\fR diff --git a/usr/src/man/man9f/pci_ereport_setup.9f b/usr/src/man/man9f/pci_ereport_setup.9f new file mode 100644 index 0000000000..a4475f2f01 --- /dev/null +++ b/usr/src/man/man9f/pci_ereport_setup.9f @@ -0,0 +1,311 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pci_ereport_setup 9F "10 May 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +pci_ereport_setup, pci_ereport_teardown, pci_ereport_post \- post error reports +for the generic PCI errors logged in the PCI Configuration Status register. +.SH SYNOPSIS +.LP +.nf +#include <sys/sunddi.h> + +\fBvoid\fR \fBpci_ereport_setup\fR(\fBdev_info_t\fR *\fIdip\fR, \fBint\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpci_ereport_teardown\fR(\fBdev_info_t\fR *\fIdip\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpci_ereport_post\fR(\fBdev_info_t\fR *\fIdip\fR, \fBddi_fm_error_t\fR *\fIdep\fR, + \fBuin16_t\fR *\fIstatus\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 10n +.rt +Pointer to the \fBdev_info\fR structure of the devices +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdep\fR\fR +.ad +.RS 10n +.rt +Pointer to DDI error status +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstatus\fR\fR +.ad +.RS 10n +.rt +Pointer to status bit storage location +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpci_ereport_setup()\fR function initializes support for error report +generation and sets up the resources for subsequent access to \fBPCI\fR, +\fBPCI/X\fR or \fBPCI Express Configuration\fR space. The caller must have +established a fault management capability level of at least +\fBDDI_FM_EREPORT_CAPABLE\fR with a previous call to \fBddi_fm_init()\fR for +\fIdip\fR. +.sp +.LP +The \fBpci_ereport_teardown()\fR function releases any resources allocated and +set up by \fBpci_ereport_setup()\fR and associated with \fIdip\fR. +.sp +.LP +The \fBpci_ereport_post()\fR function is called to scan for and post any +\fBPCI\fR, \fBPCI/X\fR or \fBPCI Express Bus\fR errors. On a \fBPCI\fR bus, for +example, the errors detected include: +.RS +4 +.TP +.ie t \(bu +.el o +Detected Parity Error +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Master Data Parity Error +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Target Abort +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Master Abort +.RE +.RS +4 +.TP +.ie t \(bu +.el o +System Error +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Discard Timeout +.RE +.sp +.LP +The \fBpci_ereport_post()\fR function must be called only from a driver's error +handler callback function. See \fBddi_fm_handler_register\fR(9F). The +\fIerror_status\fR argument to the error handler callback function should be +passed through as the \fIdep\fR argument to \fBpci_ereport_post()\fR as it may +contain bus specific information that might be useful for handling any errors +that are discovered. +.sp +.LP +The \fBfme_flag\fR in the \fBerror_status\fR argument to the error handler +callback function will contain one of the following: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_ERR_UNEXPECTED()\fR\fR +.ad +.RS 27n +.rt +Any errors discovered are unexpected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_ERR_EXPECTED()\fR\fR +.ad +.RS 25n +.rt +Errors discovered were the result of a \fBDDI_ACC_CAUTIOUS\fR operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_ERR_POKE()\fR\fR +.ad +.RS 25n +.rt +Errors discovered are the result of a \fBddi_poke\fR(9F) operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_ERR_PEEK()\fR\fR +.ad +.RS 25n +.rt +Errors discovered are the result of a \fBddi_peek\fR(9F) operation. +.RE + +.sp +.LP +Error report events are generated automatically if \fBfme_flag\fR is set to +\fBDDI_FM_ERR_UNEXPECTED\fR and the corresponding error bits are set in the +various \fBPCI\fR, \fBPCI/X\fR or \fBPCI Express Bus\fR error registers of the +device associated with \fIdip\fR. The generated error report events are posted +to the Solaris Fault Manager, \fBfmd\fR(1M), for diagnosis. +.sp +.LP +If the status argument is non-null, \fBpci_ereport_post()\fR saves the contents +of the \fBPCI Configuration Status Register\fR to \fB*status\fR. If it is not +possible to read the \fBPCI Configuration Status Register\fR, \fB-1\fR is +returned in \fB*status\fR instead. +.sp +.LP +On return from the call to \fBpci_ereport_post()\fR, the \fBddi_fm_error_t\fR +structure pointed at by \fIdep\fR will have been updated, and the +\fBfme_status\fR field contains one of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_OK\fR\fR +.ad +.RS 19n +.rt +No errors were detected which might affect this device instance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_FATAL\fR\fR +.ad +.RS 19n +.rt +An error which is considered fatal to the operational state of the system was +detected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_NONFATAL\fR\fR +.ad +.RS 19n +.rt +An error which is not considered fatal to the operational state of the system +was detected. The \fBfme_acc_handle\fR or \fBfme_dma_handle\fR fields in the +returned \fBddi_fm_error_t\fR structure will typically reference a handle that +belongs to the device instance that has been affected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FM_UNKNOWN\fR\fR +.ad +.RS 19n +.rt +An error was detected, but the call was unable to determine the impact of the +error on the operational state of the system. This is treated the same way as +\fBDDI_FM_FATAL\fR unless some other device is able to evaluate the fault to be +\fBDDI_FM_NONFATAL\fR. +.RE + +.SH CONTEXT +.sp +.LP +The \fBpci_ereport_setup()\fR and \fBpci_ereport_teardown()\fR functions must +be called from user or kernel context. +.sp +.LP +The \fBpci_ereport_post()\fR function can be called in any context. +.SH EXAMPLES +.sp +.in +2 +.nf +int xxx_fmcap = DDI_FM_EREPORT_CAPABLE | DDI_FM_ERRCB_CAPABLE; + +xxx_attach(dev_info_t *dip, ddi_attach_cmd_t cmd) { + + ddi_fm_init(dip, &xxx_fmcap, &xxx_ibc); + if (xxx_fmcap & DDI_FM_ERRCB_CAPABLE) + ddi_fm_handler_register(dip, xxx_err_cb); + if (xxx_fmcap & DDI_FM_EREPORT_CAPABLE) + pci_ereport_setup(dip); + +} + +xxx_err_cb(dev_info_t *dip, ddi_fm_error_t *errp) { +uint16_t status; + + pci_ereport_post(dip, errp, &status); +return (errp->fme_status); +} + +xxx_detach(dev_info_t *dip, ddi_attach_cmd_t cmd) { + + if (xxx_fmcap & DDI_FM_EREPORT_CAPABLE) + pci_ereport_teardown(dip); + if (xxx_fmcap & DDI_FM_ERRCB_CAPABLE) + ddi_fm_handler_unregister(dip); +ddi_fm_fini(dip); + +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBfmd\fR(1M), \fBattributes\fR(5), \fBddi_fm_handler_register\fR(9F), +\fBddi_fm_init\fR(9F), \fBddi_peek\fR(9F), \fBddi_poke\fR(9F), +\fBddi_fm_error\fR(9S) diff --git a/usr/src/man/man9f/pci_report_pmcap.9f b/usr/src/man/man9f/pci_report_pmcap.9f new file mode 100644 index 0000000000..f09bcea26a --- /dev/null +++ b/usr/src/man/man9f/pci_report_pmcap.9f @@ -0,0 +1,194 @@ +'\" 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 pci_report_pmcap 9F "13 August 1999" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +pci_report_pmcap \- Report Power Management capability of a PCI device +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBpci_report_pmcap\fR(\fBdev_info_t *\fR\fIdip\fR, int \fIcap,\fR void *\fIarg\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 +Pointer to the device's \fBdev_info\fR structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcap\fR\fR +.ad +.RS 7n +.rt +Power management capability +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 7n +.rt +Argument for the capability +.RE + +.SH DESCRIPTION +.sp +.LP +Some PCI devices provide power management capabilities in addition to those +provided by the PCI Power Management Specification. The +\fBpci_report_pmcap()\fR function reports those Power Management capabilities +of the PCI device to the framework. Framework supports dynamic changing of the +capability by allowing \fBpci_report_pmcap()\fR to be called multiple times. +Following are the supported capabilities as indicated by the \fBcap\fR: +.sp +.LP +\fBPCI_PM_IDLESPEED\fR \(em The \fBPCI_PM_IDLESPEED\fR value indicates the +lowest PCI clock speed that a device can tolerate when idle, and is applicable +only to 33 MHz PCI bus. \fBarg\fR represents the lowest possible idle speed in +KHz (1 KHz is 1000 Hz). The integer value representing the speed should be cast +to \fB(void *)\fRbefore passing as \fBarg\fR to \fBpci_report_pmcap()\fR. +.sp +.LP +The special values of \fBarg\fR are: +.sp +.ne 2 +.mk +.na +\fB\fBPCI_PM_IDLESPEED_ANY\fR\fR +.ad +.RS 25n +.rt +The device can tolerate any idle clock speed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPCI_PM_IDLESPEED_NONE\fR\fR +.ad +.RS 25n +.rt +The device cannot tolerate slowing down of PCI clock even when idle. +.RE + +.sp +.LP +If the driver doesn't make this call, \fBPCI_PM_IDLESPEED_NONE\fR is assumed. +In this case, one offending device can keep the entire bus from being power +managed. +.SH RETURN VALUES +.sp +.LP +The \fBpci_report_pmcap()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Successful reporting of the capability +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Failure to report capability because of invalid argument(s) +.RE + +.SH CONTEXT +.sp +.LP +The \fBpci_report_pmcap()\fR function can be called from user, kernel and +interrupt context. +.SH EXAMPLES +.sp +.LP +1. A device driver knows that the device it controls works with any clock +between DC and 33 MHz as specified in \fISection 4.2.3.1: Clock Specification +\fR of the \fIPCI Bus Specification Revision 2.1\fR. The device driver makes +the following call from its \fBattach\fR(9E): +.sp +.in +2 +.nf +if (pci_report_pmcap(dip, PCI_PM_IDLESPEED, PCI_PM_IDLESPEED_ANY) != + DDI_SUCCESS) + cmn_err(CE_WARN, "%s%d: pci_report_pmcap failed\fB\en\fR", + ddi_driver_name(dip), ddi_get_instance(dip)); +.fi +.in -2 + +.sp +.LP +2. A device driver controls a 10/100 Mb Ethernet device which runs the device +state machine on the chip from the PCI clock. For the device state machine to +receive packets at 100 Mb, the PCI clock cannot drop below 4 MHz. The driver +makes the following call whenever it negotiates a 100 Mb Ethernet connection: +.sp +.in +2 +.nf +if (pci_report_pmcap(dip, PCI_PM_IDLESPEED, (void *)4000) != + DDI_SUCCESS) + cmn_err(CE_WARN, "%s%d: pci_report_pmcap failed\fB\en\fR", + ddi_driver_name(dip), ddi_get_instance(dip)); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fIPCI Bus Power Management Interface Specification Version 1.1\fR +.sp +.LP +\fIPCI Bus Specification Revision 2.1\fR diff --git a/usr/src/man/man9f/pci_save_config_regs.9f b/usr/src/man/man9f/pci_save_config_regs.9f new file mode 100644 index 0000000000..14886cd362 --- /dev/null +++ b/usr/src/man/man9f/pci_save_config_regs.9f @@ -0,0 +1,167 @@ +'\" 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 pci_save_config_regs 9F "02 June 2000" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +pci_save_config_regs, pci_restore_config_regs \- save and restore the PCI +configuration registers +.SH SYNOPSIS +.LP +.nf +\fB#include <sys/ddi.h>\fR +\fB#include <sys/sunddi.h>\fR + + + +\fBint\fR \fBpci_save_config_regs\fR(\fBdev_info_t *\fR\fIdip\fR); +.fi + +.LP +.nf +\fBint\fR \fBpci_restore_config_regs\fR(\fBdev_info_t *\fR\fIdip\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI-specific (Solaris DDI). +.SH ARGUMENTS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 7n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBpci_save_config_regs()\fR saves the current configuration registers on +persistent system memory. \fBpci_restore_config_regs()\fR restores +configuration registers previously saved by \fBpci_save_config_regs()\fR. +.sp +.LP +\fBpci_save_config_regs()\fR should be called by the driver's \fBpower()\fR +entry point before powering a device off (to PCI state D3). Likewise, +\fBpci_restore_config_regs()\fR should be called after powering a device on +(from PCI state D3), but before accessing the device. See \fBpower\fR(9E). +.SH RETURN VALUES +.sp +.LP +\fBpci_save_config_regs()\fR and \fBpci_restore_config_regs()\fR return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Operation completed successfully. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Operation failed to complete successfully. +.RE + +.SH CONTEXT +.sp +.LP +Both these functions can be called from user or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRInvoking the save and restore functions +.sp +.in +2 +.nf +static int +xx_power(dev_info_t *dip, int component, int level) { + struct xx *xx; + int rval = DDI_SUCCESS; + + xx = ddi_get_soft_state(xx_softstate, ddi_get_instance(dip)); + if (xx == NULL) { + return (DDI_FAILURE); + } + + mutex_enter(&xx\(mi>x_mutex); + + switch (level) { + case PM_LEVEL_D0: + XX_POWER_ON(xx); + if (pci_restore_config_regs(dip) == DDI_FAILURE) { + /* + * appropriate error path handling here + */ + ... + rval = DDI_FAILURE; + } + break; + + case PM_LEVEL_D3: + if (pci_save_config_regs(dip) == DDI_FAILURE) { + /* + * appropriate error path handling here + */ + ... + rval = DDI_FAILURE; + } + else { + XX_POWER_OFF(xx); + } + break; + + default: + rval = DDI_FAILURE; + break; + } + + mutex_exit(&xx\(mi>x_mutex); + return (rval); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBpower\fR(9E) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fIPCI Bus Power Management Interface Specification Version 1.1\fR +.sp +.LP +\fIPCI Bus Specification Revision 2.1\fR diff --git a/usr/src/man/man9f/physio.9f b/usr/src/man/man9f/physio.9f new file mode 100644 index 0000000000..24599602dc --- /dev/null +++ b/usr/src/man/man9f/physio.9f @@ -0,0 +1,186 @@ +'\" 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 physio 9F "2 Apr 1993" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +physio, minphys \- perform physical I/O +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/buf.h> +#include <sys/uio.h> + + + +\fBint\fR \fBphysio\fR(\fBint\fR(\fI*strat\fR)(\fIstruct buf *\fR), \fBstruct buf\fR \fI*bp\fR, \fBdev_t\fR \fIdev\fR, + \fBint\fR \fIrw\fR, \fBvoid\fR (\fI*mincnt\fR)(\fIstruct buf *\fR), \fBstruct uio\fR \fI*uio\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBminphys\fR(\fBstruct buf\fR \fI*bp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.SS "\fBphysio()\fR" +.sp +.ne 2 +.mk +.na +\fB\fIstrat\fR \fR +.ad +.RS 11n +.rt +Pointer to device strategy routine. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR \fR +.ad +.RS 11n +.rt +Pointer to a \fBbuf\fR(9S) structure describing the transfer. If \fIbp\fR is +set to \fINULL\fR then \fBphysio()\fR allocates one which is automatically +released upon completion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev\fR \fR +.ad +.RS 11n +.rt +The device number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrw\fR \fR +.ad +.RS 11n +.rt +Read/write flag. This is either \fBB_READ\fR when reading from the device, or +\fBB_WRITE\fR when writing to the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImincnt\fR \fR +.ad +.RS 11n +.rt +Routine which bounds the maximum transfer unit size. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuio\fR \fR +.ad +.RS 11n +.rt +Pointer to the \fBuio\fR structure which describes the user \fBI/O\fR request. +.RE + +.SS "\fBminphys()\fR" +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR \fR +.ad +.RS 7n +.rt +Pointer to a \fBbuf\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBphysio()\fR performs unbuffered \fBI/O\fR operations between the device +\fIdev\fR and the address space described in the \fBuio\fR structure. +.sp +.LP +Prior to the start of the transfer \fBphysio()\fR verifies the requested +operation is valid by checking the protection of the address space specified in +the \fBuio\fR structure. It then locks the pages involved in the \fBI/O\fR +transfer so they can not be paged out. The device strategy routine, +\fBstrat()\fR, is then called one or more times to perform the physical +\fBI/O\fR operations. \fBphysio()\fR uses \fBbiowait\fR(9F) to block until +\fBstrat()\fR has completed each transfer. Upon completion, or detection of an +error, \fBphysio()\fR unlocks the pages and returns the error status. +.sp +.LP +\fBphysio()\fR uses \fBmincnt()\fR to bound the maximum transfer unit size to +the system, or device, maximum length. \fBminphys()\fR is the system +\fBmincnt()\fR routine for use with \fBphysio()\fR operations. Drivers which do +not provide their own local \fBmincnt()\fR routines should call \fBphysio()\fR +with \fBminphys()\fR. +.sp +.LP +\fBminphys()\fR limits the value of \fIbp\fR\fB->b_bcount\fR to a sensible +default for the capabilities of the system. Drivers that provide their own +\fBmincnt()\fR routine should also call \fBminphys()\fR to make sure they do +not exceed the system limit. +.SH RETURN VALUES +.sp +.LP +\fBphysio()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR \fR +.ad +.RS 12n +.rt +Upon success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnon-zero\fR\fR +.ad +.RS 12n +.rt +Upon failure. +.RE + +.SH CONTEXT +.sp +.LP +\fBphysio()\fR can be called from user context only. +.SH SEE ALSO +.sp +.LP +\fBstrategy\fR(9E), \fBbiodone\fR(9F), \fBbiowait\fR(9F), \fBbuf\fR(9S), +\fBuio\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +Since \fBphysio()\fR calls \fBbiowait()\fR to block until each buf transfer is +complete, it is the drivers responsibility to call \fBbiodone\fR(9F) when the +transfer is complete, or \fBphysio()\fR will block forever. diff --git a/usr/src/man/man9f/pm_busy_component.9f b/usr/src/man/man9f/pm_busy_component.9f new file mode 100644 index 0000000000..cad2833872 --- /dev/null +++ b/usr/src/man/man9f/pm_busy_component.9f @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pm_busy_component 9F "21 July 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +pm_busy_component, pm_idle_component \- control device component availability +for Power Management +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBint\fR \fBpm_busy_component\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint\fR \fIcomponent\fR); +.fi + +.LP +.nf +\fBint\fR \fBpm_idle_component\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint\fR \fIcomponent\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 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 +The number of the component to be power-managed. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpm_busy_component()\fR function sets \fIcomponent\fR of \fIdip\fR to be +busy. Calls to \fBpm_busy_component()\fR are stacked, requiring a corresponding +number of calls to \fBpm_idle_component()\fR to make the component idle again. +When a device is busy it will not be power-managed by the system. +.sp +.LP +The \fBpm_idle_component()\fR function marks \fIcomponent\fR idle, recording +the time that \fIcomponent\fR went idle. This function must be called once for +each call to \fBpm_busy_component()\fR. A component which is idle is available +to be power-managed by the system. The \fBpm_idle_component()\fR function has +no effect if the component is already idle, except to update the system's +notion of when the device went idle. +.sp +.LP +If these functions are called as a result of entry into the driver's +\fBattach\fR(9E), \fBdetach\fR(9E) or \fBpower\fR(9E) entry point, these +functions must be called from the same thread which entered \fBattach\fR(9E), +\fBdetach\fR(9E) or \fBpower\fR(9E). +.SH RETURN VALUES +.sp +.LP +The \fBpm_busy_component()\fR and \fBpm_idle_component()\fR functions return: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +Successfully set the indicated component busy or idle. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Invalid component number \fIcomponent\fR or the device has no components. +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from user or kernel context. These functions may +also be called from interrupt context, providing they are not the first Power +Management function called by the driver. +.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 +\fBpower.conf\fR(4), \fBpm\fR(7D), \fBattach\fR(9E), \fBdetach\fR(9E), +\fBpower\fR(9E), \fBpm_raise_power\fR(9F), \fBpm\fR(9P), +\fBpm-components\fR(9P) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/pm_power_has_changed.9f b/usr/src/man/man9f/pm_power_has_changed.9f new file mode 100644 index 0000000000..5a441c8d78 --- /dev/null +++ b/usr/src/man/man9f/pm_power_has_changed.9f @@ -0,0 +1,202 @@ +'\" 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 pm_power_has_changed 9F "22 July 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +pm_power_has_changed \- Notify Power Management framework of autonomous power +level change +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBpm_power_has_changed\fR(\fBdev_info_t *\fR\fIdip,\fR int \fIcomponent\fR, int \fIlevel\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 +Pointer to the device \fBdev_info\fR structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcomponent\fR\fR +.ad +.RS 13n +.rt +Number of the component that has changed power level +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlevel\fR\fR +.ad +.RS 9n +.rt +Power level to which the indicated component has changed +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpm_power_has_changed\fR(9) function notifies the Power Management +framework that the power level of component of \fIdip \fR has changed to +\fIlevel\fR. +.sp +.LP +Normally power level changes are initiated by the Power Management framework +due to device idleness, or through a request to the framework from the driver +via \fBpm_raise_power\fR(9F) or \fBpm_lower_power\fR(9F), but some devices may +change power levels on their own. For the framework to track the power level of +the device under these circumstances, the framework must be notified of +autonomous power level changes by a call to \fBpm_power_has_changed()\fR. +.sp +.LP +Because of the asynchronous nature of these events, the Power Management +framework might have called \fBpower\fR(9E) between the device's autonomous +power level change and the driver calling \fBpm_power_has_changed()\fR, or the +framework may be in the process of changing the power level when +\fBpm_power_has_changed()\fR is called. To handle these situations correctly, +the driver should verify that the device is indeed at the level or set the +device to the level if it doesn't support inquirying of power levels, before +calling \fBpm_power_has_changed()\fR. In addition, the driver should prevent a +\fBpower\fR(9E) entry point from running in parallel with +\fBpm_power_has_changed()\fR. +.LP +Note - +.sp +.RS 2 +If this function is called as a result of entry into the driver's +\fBattach\fR(9E), \fBdetach\fR(9E) or \fBpower\fR(9E) entry point, this +function must be called from the same thread which entered \fBattach\fR(9E), +\fBdetach\fR(9E) or \fBpower\fR(9E). +.RE +.SH RETURN VALUES +.sp +.LP +The \fBpm_power_has_changed()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +The power level of component was successfully updated to \fIlevel\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +Invalid component \fIcomponent\fR or power level \fIlevel\fR. +.RE + +.SH CONTEXT +.sp +.LP +This function can be called from user or kernel context. This function can also +be called from interrupt context, providing that it is not the first Power +Management function called by the driver. +.SH EXAMPLES +.sp +.LP +A hypothetical driver might include this code to handle +\fBpm_power_has_changed\fR(9): +.sp +.in +2 +.nf +static int +xxusb_intr(struct buf *bp) +{ + + ... + + + /* + * At this point the device has informed us that it has + * changed power level on its own. Inform this to framework. + * We need to take care of the case when framework has + * already called power() entry point and changed power level + * before we were able to inform framework of this change. + * Handle this by comparing the informed power level with + * the actual power level and only doing the call if they + * are same. In addition, make sure that power() doesn't get + * run in parallel with this code by holding the mutex. + */ + ASSERT(mutex_owned(&xsp->lock)); + if (level_informed == *(xsp->level_reg_addr)) { + if (pm_power_has_changed(xsp->dip, XXUSB_COMPONENT, + level_informed) != DDI_SUCCESS) { + mutex_exit( &xsp->lock); + return(DDI_INTR_UNCLAIMED); + } + } + + .... + +} + + +xxdisk_power(dev_info *dip, int comp, int level) +{ + mutex_enter( xsp->lock); + + ... + + ... + +} +.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) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBpower.conf\fR(4), \fBpm\fR(7D), \fBattach\fR(9E), \fBdetach\fR(9E), +\fBpower\fR(9E), \fBpm_busy_component\fR(9F), \fBpm_idle_component\fR(9F), +\fBpm_raise_power\fR(9F), \fBpm_lower_power\fR(9F), \fBpm\fR(9P), +\fBpm-components\fR(9P) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/pm_raise_power.9f b/usr/src/man/man9f/pm_raise_power.9f new file mode 100644 index 0000000000..c551b02aec --- /dev/null +++ b/usr/src/man/man9f/pm_raise_power.9f @@ -0,0 +1,318 @@ +'\" 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 pm_raise_power 9F "22 March 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +pm_raise_power, pm_lower_power \- Raise or lower power of components +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + +\fBint\fR \fBpm_raise_power\fR(\fBdev_info_t *\fR\fIdip,\fR int \fIcomponent\fR, int \fIlevel\fR); +.fi + +.LP +.nf +\fBint\fR \fBpm_lower_power\fR(\fBdev_info_t *\fR\fIdip,\fR int \fIcomponent\fR, int \fIlevel\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.SS "pm_raise_power" +.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 +The number of the \fIcomponent\fR for which a power level change is desired +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlevel\fR\fR +.ad +.RS 13n +.rt +The power level to which the indicated \fIcomponent\fR will be raised +.RE + +.SS "pm_lower_power" +.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 +Number of the \fIcomponent\fR for which a power level change is desired +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlevel\fR\fR +.ad +.RS 13n +.rt +Power level to which the indicated \fIcomponent\fR will be lowered +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpm_raise_power\fR(9F) function requests the Power Management framework +to raise the power level of \fIcomponent \fRof \fIdip\fR to at least \fIlevel. +\fR +.sp +.LP +The state of the device should be examined before each physical access. The +\fBpm_raise_power\fR(9F) function should be called to set a \fIcomponent \fR to +the required power level if the operation to be performed requires the +\fIcomponent \fR to be at a power level higher than its current power level. +.sp +.LP +When \fBpm_raise_power\fR(9F) returns with success, the \fIcomponent \fR is +guaranteed to be at least at the requested power level. All devices that depend +on this will be at their full power level. Since the actual device power level +may be higher than requested by the driver, the driver should not make any +assumption about the absolute power level on successful return from +\fBpm_raise_power\fR(9F). +.sp +.LP +The \fBpm_raise_power\fR(9F) function may cause re-entry of the driver +\fBpower\fR(9E) to raise the power level. Deadlock may result if the driver +locks are held across the call to \fBpm_raise_power\fR(9F). +.sp +.LP +The \fBpm_lower_power\fR(9F) function requests the Power Management framework +to lower the power level of \fIcomponent \fRof \fIdip\fR to at most +\fIlevel\fR. +.sp +.LP +Normally, transitions to lower power levels are initiated by the Power +Management framework based on \fIcomponent\fR idleness. However, when +detaching, the driver should also initiate reduced power levels by setting the +power level of all device components to their lowest levels. The +\fBpm_lower_power\fR(9F) function is intended for this use only, and will +return \fBDDI_FAILURE\fR if the driver is not detaching at the time of the +call. +.sp +.LP +If automatic Power Management is disabled (see \fBdtpower\fR(1M) and +\fBpower.conf\fR(4)), \fBpm_lower_power\fR(9F) returns \fBDDI_SUCCESS\fR +without changing the power level of the component. Otherwise, when +\fBpm_lower_power\fR(9F) returns with success, the \fIcomponent \fR is +guaranteed to be at most at the requested power level. Since the actual device +power level may be lower than requested by the driver, the driver should not +make any assumption about the absolute power level on successful return from +\fBpm_lower_power\fR(9F). +.sp +.LP +The \fBpm_lower_power\fR(9F) function may cause re-entry of the driver +\fBpower\fR(9E) to lower the power level. Deadlock may result if the driver +locks are held across the call to \fBpm_lower_power\fR(9F). +.LP +Note - +.sp +.RS 2 +If these functions are called as a result of entry into the driver's +\fBattach\fR(9E), \fBdetach\fR(9E) or \fBpower\fR(9E) entry point, these +functions must be called from the same thread which entered \fBattach\fR(9E), +\fBdetach\fR(9E) or \fBpower\fR(9E). +.RE +.SH RETURN VALUES +.sp +.LP +The \fBpm_raise_power\fR(9F) function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +\fIComponent\fR is now at the requested power level or higher. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +\fIComponent \fRor \fIlevel\fR is out of range, or the framework was unable to +raise the power level of the component to the requested level. +.RE + +.sp +.LP +The \fBpm_lower_power\fR(9F) function returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +\fI Component \fR is now at the requested power level or lower, or automatic +Power Management is disabled. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +\fI Component \fR or \fIlevel\fR is out of range, or the framework was unable +to lower the power level of the component to the requested level, or the device +is not detaching. +.RE + +.SH EXAMPLES +.sp +.LP +A hypothetical disk driver might include this code to handle +\fBpm_raise_power\fR(9F): +.sp +.in +2 +.nf +static int +xxdisk_strategy(struct buf *bp) +{ + + ... + + /* + * At this point we have determined that we need to raise the + * power level of the device. Since we have to drop the + * mutex, we need to take care of case where framework is + * lowering power at the same time we are raising power. + * We resolve this by marking the device busy and failing + * lower power in power() entry point when device is busy. + */ + + ASSERT(mutex_owned(xsp->lock)); + if (xsp->pm_busycnt < 1) { + /* + * Component is not already marked busy + */ + if (pm_busy_component(xsp->dip, + XXDISK_COMPONENT) != DDI_SUCCESS) { + bioerror(bp,EIO); + biodone(bp); + return (0); + } + xsp->pm_busycnt++; + } + mutex_exit(xsp->lock); + if (pm_raise_power(xsp->dip, + XXDISK_COMPONENT, XXPOWER_SPUN_UP) != DDI_SUCCESS) { + bioerror(bp,EIO); + biodone(bp); + return (0); + } + mutex_enter(xsp->lock); + + .... + +} + + +xxdisk_power(dev_info *dip, int comp, int level) +{ + +\&... + + /* + * We fail the power() entry point if the device is busy and + * request is to lower the power level. + +*/ + + ASSERT(mutex_owned( xsp->lock)); + if (xsp->pm_busycnt >= 1) { + if (level < xsp->cur_level) { + mutex_exit( xsp->lock); + return (DDI_FAILURE); + } + } + +\&... + +} +.fi +.in -2 + +.SH CONTEXT +.sp +.LP +These functions can be called from user or kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for a description of the following attribute: +.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 +\fBpower.conf\fR(4), \fBpm\fR(7D), \fBattach\fR(9E), \fBdetach\fR(9E), +\fBpower\fR(9E), \fBpm_busy_component\fR(9F), \fBpm_idle_component\fR(9F), +\fBpm\fR(9P), \fBpm-components\fR(9P) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/pm_trans_check.9f b/usr/src/man/man9f/pm_trans_check.9f new file mode 100644 index 0000000000..621bf63074 --- /dev/null +++ b/usr/src/man/man9f/pm_trans_check.9f @@ -0,0 +1,162 @@ +'\" 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 pm_trans_check 9F "16 Jul 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +pm_trans_check \- Device power cycle advisory check +.SH SYNOPSIS +.LP +.nf +#include <sys/sunddi.h> + +\fBint\fR \fBpm_trans_check\fR(\fBstruct pm_trans_data *\fR\fIdatap,\fR time_t *\fIintervalp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdatap\fR\fR +.ad +.RS 9n +.rt +Pointer to a \fBpm_trans_data\fR structure +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIintervalp\fR\fR +.ad +.RS 13n +.rt +Pointer to time difference when next power cycle will be advised +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpm_trans_check()\fR function checks if a power-cycle is currently +advised based on data in the \fBpm_trans_data\fR structure. This function is +provided to prevent damage to devices from excess power cycles; drivers for +devices that are sensitive to the number of power cycles should call +\fBpm_trans_check()\fR from their \fBpower\fR(9E) function before powering-off +a device. If \fBpm_trans_check()\fR indicates that the device should not be +power cycled, the driver should not attempt to power cycle the device and +should fail the call to \fBpower\fR(9E) entry point. +.sp +.LP +If \fBpm_trans_check()\fR returns that it is not advised to power cycle the +device, it attempts to calculate when the next power cycle is advised, based +on the supplied parameters. In such case, \fIintervalp\fR returns the time +difference (in seconds) from the current time to when the next power cycle is +advised. If the time for the next power cycle cannot be determined, +\fIintervalp\fR indicates \fB0\fR. +.sp +.LP +To avoid excessive calls to the \fBpower\fR(9E) entry point during a period +when power cycling is not advised, the driver should mark the corresponding +device component busy for the \fIintervalp\fR time period (if interval is not +0). Conveniently, the driver can utilize the fact that calls to +\fBpm_busy_component\fR(9F) are stacked. If power cycling is not advised, the +driver can call \fBpm_busy_component\fR(9F) and issue a \fBtimeout\fR(9F) for +the \fIintervalp\fR time. The \fBtimeout()\fR handler can issue the +corresponding \fBpm_idle_component\fR(9F) call. +.sp +.LP +The format field of \fBpm_trans_data\fR accepts either \fBDC_SCSI_FORMAT\fR or +\fBDC_SMART_FORMAT\fR. If the caller provides information from a SCSI Log Page, +it should set the format field to \fBDC_SCSI_FORMAT\fR, and provide valid data +in \fIsvc_date\fR[], \fIlifemax\fR, \fIncycles\fR and \fIflag\fR in the +\fBpm_scsi_cycles\fR structure. If the caller provides information from a SMART +feature attribute, it should set the format field to \fBDC_SMART_FORMAT\fR and +provide valid data in \fIallowed\fR, \fIusedup\fR and \fIflag\fR in the +\fBpm_smart_count\fR structure, where \fIallowed\fR indicates the normalized +cycle count before reaching the borderline threshold cycle count, and +\fIusedup\fR indicates the normalized consumed cycle count. +.sp +.LP +The \fIflag\fR field in both \fBpm_scsi_cycles\fR and \fBpm_smart_count\fR +structures is reserved for future use and must be set to 0. +.sp +.in +2 +.nf +struct pm_trans_data { + int format; /* data format */ + union { + struct pm_scsi_cycles scsi_cycles; + struct pm_smart_count smart_count; + } un; +}; +.fi +.in -2 + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 6n +.rt +Power cycle is advised. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 6n +.rt +Power cycle is not advised. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB-1\fR\fR +.ad +.RS 6n +.rt +Error due to invalid argument. +.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 +\fBpower.conf\fR(4), \fBattributes\fR(5), \fBpower\fR(9E) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fIUsing Power Management\fR diff --git a/usr/src/man/man9f/pollwakeup.9f b/usr/src/man/man9f/pollwakeup.9f new file mode 100644 index 0000000000..c3ca1eb818 --- /dev/null +++ b/usr/src/man/man9f/pollwakeup.9f @@ -0,0 +1,70 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pollwakeup 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +pollwakeup \- inform a process that an event has occurred +.SH SYNOPSIS +.LP +.nf +#include <sys/poll.h> + + + +\fBvoid\fR \fBpollwakeup\fR(\fBstruct pollhead *\fR\fIphp\fR, \fBshort\fR \fIevent\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIphp\fR\fR +.ad +.RS 9n +.rt +Pointer to a \fBpollhead\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIevent\fR\fR +.ad +.RS 9n +.rt +Event to notify the process about. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpollwakeup()\fR function wakes a process waiting on the occurrence of an +event. It should be called from a driver for each occurrence of an event. The +\fBpollhead\fR structure will usually be associated with the driver's private +data structure associated with the particular minor device where the event has +occurred. See \fBchpoll\fR(9E) and \fBpoll\fR(2) for more detail. +.SH CONTEXT +.sp +.LP +The \fBpollwakeup()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBpoll\fR(2), \fBchpoll\fR(9E) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Driver defined locks should not be held across calls to this function. diff --git a/usr/src/man/man9f/priv_getbyname.9f b/usr/src/man/man9f/priv_getbyname.9f new file mode 100644 index 0000000000..a7dd1a9700 --- /dev/null +++ b/usr/src/man/man9f/priv_getbyname.9f @@ -0,0 +1,154 @@ +'\" 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 priv_getbyname 9F "11 Mar 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +priv_getbyname \- map a privilege name to a number +.SH SYNOPSIS +.LP +.nf +#include <sys/cred.h> + + + +\fBint\fR \fBpriv_getbyname\fR(\fBconst char *\fR\fIpriv\fR, \fBint\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpriv\fR\fR +.ad +.RS 9n +.rt +name of the privilege +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 9n +.rt +flags, must be zero or \fBPRIV_ALLOC\fR +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpriv_getbyname()\fR function maps a privilege name to a privilege number +for use with the \fBpriv_*()\fR kernel interfaces. +.sp +.LP +If \fBPRIV_ALLOC\fR is passed as a flag parameter, an attempt is made to +allocate a privilege if it is not yet defined. The newly allocated privilege +number is returned. +.sp +.LP +Privilege names can be specified with an optional \fBpriv_\fR prefix, which is +stripped. +.sp +.LP +Privilege names are case insensitive but allocated privileges preserve case. +.sp +.LP +Allocated privileges can be at most \fB{PRIVNAME_MAX}\fR characters long and +can contain only alphanumeric characters and the underscore character. +.SH RETURN VALUES +.sp +.LP +This function returns the privilege number, which is greater than or equal to +0, if it succeeds. It returns a negative error number if an error occurs. +.SH ERRORS +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +This might be caused by any of the following +.RS +4 +.TP +.ie t \(bu +.el o +The \fIflags\fR parameter is invalid. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The specified privilege does not exist. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fIpriv\fR parameter contains invalid characters. +.RE +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 16n +.rt +There is no room to allocate another privilege. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +An attempt was made to allocate a privilege that was longer than +\fB{PRIVNAME_MAX}\fR characters. +.RE + +.SH CONTEXT +.sp +.LP +This functions can be called from user and kernel contexts. +.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 +_ +ArchitectureAll +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBprivileges\fR(5) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/priv_policy.9f b/usr/src/man/man9f/priv_policy.9f new file mode 100644 index 0000000000..19e66bf565 --- /dev/null +++ b/usr/src/man/man9f/priv_policy.9f @@ -0,0 +1,207 @@ +'\" 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 priv_policy 9F "3 Apr 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +priv_policy, priv_policy_only, priv_policy_choice \- check, report, and audit +privileges +.SH SYNOPSIS +.LP +.nf +#include <sys/policy.h> + +\fBint\fR \fBpriv_policy\fR(\fBconst cred_t *\fR\fIcr\fR, \fBint\fR \fIpriv\fR, \fBint\fR \fIerr\fR, + \fBboolean_t\fR \fIflag\fR, \fBconst char *\fR\fImsg\fR); +.fi + +.LP +.nf +\fBboolean_t\fR \fBpriv_policy_only\fR(\fBconst cred_t *\fR\fIcr\fR, \fBint\fR \fIpriv\fR, + \fBboolean_t\fR \fIflag\fR); +.fi + +.LP +.nf +\fBboolean_t\fR \fBpriv_policy_choice\fR(\fBconst cred_t *\fR\fIcr\fR, \fBint\fR \fIpriv\fR, + \fBboolean_t\fR \fIflag\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcr\fR\fR +.ad +.RS 8n +.rt +The credential to be checked. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpriv\fR\fR +.ad +.RS 8n +.rt +The integer value of the privilege to test. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 8n +.rt +All zone privileges flag. Set to \fBB_FALSE\fR for most tests or \fBB_TRUE\fR +if the operation requires the caller to have all available privileges in the +zone. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerr\fR\fR +.ad +.RS 8n +.rt +The error code to return. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImsg\fR\fR +.ad +.RS 8n +.rt +String that is added to the privilege debugging message if one is generated. +NULL if no additional information is needed. Because the function name is +included in the output, NULL is usually the best value to pass as a parameter. +.RE + +.SH DESCRIPTION +.sp +.LP +These functions aid in privilege checking and privilege debugging. +.sp +.LP +The \fBpriv_policy()\fR, \fBpriv_policy_only()\fR, and +\fBpriv_policy_choice()\fR functions all check whether \fIpriv\fR is asserted +in the effective set of the credential. The special value \fBPRIV_ALL\fR tests +for all privileges. +.sp +.LP +The \fBpriv_policy()\fR function updates the ASU accounting flag and records +the privilege used on success in the audit trail if the required privilege was +not a basic privilege. +.sp +.LP +The \fBpriv_policy_only()\fR function checks whether a privilege is asserted +and has no side effects. +.sp +.LP +The \fBpriv_policy_choice()\fR function behaves like \fBpriv_policy_only()\fR +but records the successfully used non-basic privileges in the audit trail. +.SH RETURN VALUES +.sp +.LP +On success, \fBpriv_policy()\fR return 0. On failure it returns its parameter +\fIerr\fR. +.sp +.LP +On success, \fBpriv_policy_choice()\fR and \fBpriv_policy_only()\fR return 1, +on failure both return 0. +.SH ERRORS +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 16n +.rt +This might be caused by any of the following: +.RS +4 +.TP +.ie t \(bu +.el o +The \fIflags\fR parameter is invalid. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The specified privilege does not exist. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fIpriv\fR parameter contains invalid characters. +.RE +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 16n +.rt +There is no room to allocate another privilege. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENAMETOOLONG\fR\fR +.ad +.RS 16n +.rt +An attempt was made to allocate a privilege that was longer than +\fB{PRIVNAME_MAX}\fR characters. +.RE + +.SH CONTEXT +.sp +.LP +This functions can be called from user, interrupt, or kernel context. +.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 +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBacct\fR(3HEAD), \fBattributes\fR(5), \fBprivileges\fR(5) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/proc_signal.9f b/usr/src/man/man9f/proc_signal.9f new file mode 100644 index 0000000000..469b75ee52 --- /dev/null +++ b/usr/src/man/man9f/proc_signal.9f @@ -0,0 +1,211 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH proc_signal 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +proc_signal, proc_ref, proc_unref \- send a signal to a process +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> +#include <sys/signal.h> + + + +\fBvoid *\fR\fBproc_ref\fR(void) +.fi + +.LP +.nf +\fBvoid\fR\fBproc_unref\fR(\fBvoid\fR \fI*pref\fR); +.fi + +.LP +.nf +\fBint\fR \fBproc_signal\fR(\fBvoid\fR \fI*pref\fR, \fBint\fR \fIsig\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpref\fR\fR +.ad +.RS 8n +.rt +A handle for the process to be signalled. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsig\fR\fR +.ad +.RS 8n +.rt +Signal number to be sent to the process. +.RE + +.SH DESCRIPTION +.sp +.LP +This set of routines allows a driver to send a signal to a process. The routine +\fBproc_ref()\fR is used to retrieve an unambiguous reference to the process +for signalling purposes. The return value can be used as a unique handle on the +process, even if the process dies. Because system resources are committed to a +process reference, \fBproc_unref()\fR should be used to remove it as soon as it +is no longer needed.\fBproc_signal()\fR is used to send signal \fIsig\fR to the +referenced process. The following set of signals may be sent to a process from +a driver: +.sp +.ne 2 +.mk +.na +\fB\fBSIGHUP\fR\fR +.ad +.RS 12n +.rt +The device has been disconnected. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGINT\fR\fR +.ad +.RS 12n +.rt +The interrupt character has been received. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGQUIT\fR\fR +.ad +.RS 12n +.rt +The quit character has been received. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGPOLL\fR\fR +.ad +.RS 12n +.rt +A pollable event has occurred. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGKILL\fR\fR +.ad +.RS 12n +.rt +Kill the process (cannot be caught or ignored). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGWINCH\fR\fR +.ad +.RS 12n +.rt +Window size change. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSIGURG\fR\fR +.ad +.RS 12n +.rt +Urgent data are available. +.RE + +.sp +.LP +See \fBsignal.h\fR(3HEAD) for more details on the meaning of these signals. +.sp +.LP +If the process has exited at the time the signal was sent, \fBproc_signal()\fR +returns an error code; the caller should remove the reference on the process by +calling \fBproc_unref()\fR. +.sp +.LP +The driver writer must ensure that for each call made to \fBproc_ref()\fR, +there is exactly one corresponding call to \fBproc_unref()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBproc_ref()\fR returns the following: +.sp +.ne 2 +.mk +.na +\fB\fIpref\fR\fR +.ad +.RS 8n +.rt +An opaque handle used to refer to the current process. +.RE + +.sp +.LP +The \fBproc_signal()\fR returns the following: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 6n +.rt +The process existed before the signal was sent. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB-1\fR\fR +.ad +.RS 6n +.rt +The process no longer exists; no signal was sent. +.RE + +.SH CONTEXT +.sp +.LP +The \fBproc_unref()\fR and \fBproc_signal()\fR functions can be called from +user, interrupt, or kernel context. The \fBproc_ref()\fR function should be +called only from user context. +.SH SEE ALSO +.sp +.LP +\fBsignal.h\fR(3HEAD), \fBputnextctl1\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ptob.9f b/usr/src/man/man9f/ptob.9f new file mode 100644 index 0000000000..c15b0ff50b --- /dev/null +++ b/usr/src/man/man9f/ptob.9f @@ -0,0 +1,61 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ptob 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ptob \- convert size in pages to size in bytes +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> + + + +\fBunsigned long\fR \fBptob\fR(\fBunsigned long\fR \fInumpages\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fInumpages\fR\fR +.ad +.RS 12n +.rt +Size in number of pages to convert to size in bytes. +.RE + +.SH DESCRIPTION +.sp +.LP +This function returns the number of bytes that are contained in the specified +number of pages. For example, if the page size is 2048, then \fBptob(2)\fR +returns \fB4096\fR. \fBptob(0)\fR returns \fB0\fR. +.SH RETURN VALUES +.sp +.LP +The return value is always the number of bytes in the specified number of +pages. There are no invalid input values, and no checking will be performed for +overflow in the case of a page count whose corresponding byte count cannot be +represented by an \fBunsigned long\fR. Rather, the higher order bits will be +ignored. +.SH CONTEXT +.sp +.LP +The \fBptob()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBbtop\fR(9F), \fBbtopr\fR(9F), \fBddi_ptob\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/pullupmsg.9f b/usr/src/man/man9f/pullupmsg.9f new file mode 100644 index 0000000000..86a8522e2e --- /dev/null +++ b/usr/src/man/man9f/pullupmsg.9f @@ -0,0 +1,130 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pullupmsg 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +pullupmsg \- concatenate bytes in a message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBpullupmsg\fR(\fBmblk_t *\fR\fImp\fR, \fBssize_t\fR \fIlen\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 7n +.rt +Pointer to the message whose blocks are to be concatenated. \fBmblk_t\fR is an +instance of the \fBmsgb\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 7n +.rt +Number of bytes to concatenate. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpullupmsg()\fR function tries to combine multiple data blocks into a +single block. \fBpullupmsg()\fR concatenates and aligns the first \fIlen\fR +data bytes of the message pointed to by \fImp\fR. If \fIlen\fR equals \fB-1\fR, +all data are concatenated. If \fIlen\fR bytes of the same message type cannot +be found, \fBpullupmsg()\fR fails and returns \fB0\fR. +.SH RETURN VALUES +.sp +.LP +On success, \fB1\fR is returned; on failure, \fB0\fR is returned. +.SH CONTEXT +.sp +.LP +The \fBpullupmsg()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBpullupmsg()\fR +.sp +.LP +This is a driver write \fBsrv\fR(9E) (service) routine for a device that does +not support scatter/gather \fBDMA\fR. For all \fBM_DATA\fR messages, the data +will be transferred to the device with \fBDMA\fR. First, try to pull up the +message into one message block with the \fBpullupmsg()\fR function (line 12). +If successful, the transfer can be accomplished in one \fBDMA \fRjob. +Otherwise, it must be done one message block at a time (lines 19-22). After the +data has been transferred to the device, free the message and continue +processing messages on the queue. + +.sp +.in +2 +.nf + + 1 xxxwsrv(q) + 2 queue_t *q; + 3 { + 4 mblk_t *mp; + 5 mblk_t *tmp; + 6 caddr_t dma_addr; + 7 ssize_t dma_len; + 8 + 9 while ((mp = getq(q)) != NULL) { +10 switch (mp->b_datap->db_type) { +11 case M_DATA: +12 if (pullupmsg(mp, -1)) { +13 dma_addr = vtop(mp->b_rptr); +14 dma_len = mp->b_wptr - mp->b_rptr; +15 xxx_do_dma(dma_addr, dma_len); +16 freemsg(mp); +17 break; +18 } +19 for (tmp = mp; tmp; tmp = tmp->b_cont) { +20 dma_addr = vtop(tmp->b_rptr); +21 dma_len = tmp->b_wptr - tmp->b_rptr; +22 xxx_do_dma(dma_addr, dma_len); +23 } +24 freemsg(mp); +25 break; + . . . +26 } +27 } +28 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBsrv\fR(9E), \fBallocb\fR(9F), \fBmsgpullup\fR(9F), \fBmsgb\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH NOTES +.sp +.LP +The \fBpullupmsg()\fR function is not included in the \fBDKI\fR and will be +removed from the system in a future release. Device driver writers are strongly +encouraged to use \fBmsgpullup\fR(9F) instead of \fBpullupmsg()\fR. diff --git a/usr/src/man/man9f/put.9f b/usr/src/man/man9f/put.9f new file mode 100644 index 0000000000..416223c2ec --- /dev/null +++ b/usr/src/man/man9f/put.9f @@ -0,0 +1,96 @@ +'\" 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 put 9F "28 Apr 1992" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +put \- call a STREAMS put procedure +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBput\fR(\fBqueue_t *\fR\fIq\fR, \fBmblk_t *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR \fR +.ad +.RS 7n +.rt +Pointer to a STREAMS queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR \fR +.ad +.RS 7n +.rt +Pointer to message block being passed into queue. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBput()\fR calls the put procedure ( \fBput\fR(9E) entry point) for the +STREAMS queue specified by \fIq\fR, passing it the message block referred to by +\fImp\fR. It is typically used by a driver or module to call its own put +procedure. +.SH CONTEXT +.sp +.LP +\fBput()\fR can be called from a STREAMS module or driver put or service +routine, or from an associated interrupt handler, timeout, bufcall, or esballoc +call-back. In the latter cases, the calling code must guarantee the validity of +the \fIq\fR argument. +.sp +.LP +Since \fBput()\fR may cause re-entry of the module (as it is intended to do), +mutexes or other locks should not be held across calls to it, due to the risk +of single-party deadlock (\fBput\fR(9E), \fBputnext\fR(9F), \fBputctl\fR(9F), +\fBqreply\fR(9F)). This function is provided as a DDI/DKI conforming +replacement for a direct call to a put procedure. +.SH SEE ALSO +.sp +.LP +\fBput\fR(9E), \fBfreezestr\fR(9F), \fBputctl\fR(9F), \fBputctl1\fR(9F), +\fBputnext\fR(9F), \fBputnextctl\fR(9F), \fBputnextctl1\fR(9F), +\fBqprocson\fR(9F), \fBqreply\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP + \fISTREAMS Programming Guide\fR +.SH NOTES +.sp +.LP +The caller cannot have the stream frozen when calling this function. See +\fBfreezestr\fR(9F). +.sp +.LP +DDI/DKI conforming modules and drivers are no longer permitted to call put +procedures directly, but must call through the appropriate STREAMS utility +function, for example, \fBput\fR(9E), \fBputnext\fR(9F), \fBputctl\fR(9F), and +\fBqreply\fR(9F). This function is provided as a DDI/DKI conforming replacement +for a direct call to a put procedure. +.sp +.LP +The \fBput()\fR and \fBputnext()\fR functions should be called only after +\fBqprocson()\fR is finished. diff --git a/usr/src/man/man9f/putbq.9f b/usr/src/man/man9f/putbq.9f new file mode 100644 index 0000000000..f33df268d5 --- /dev/null +++ b/usr/src/man/man9f/putbq.9f @@ -0,0 +1,93 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH putbq 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +putbq \- place a message at the head of a queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBputbq\fR(\fBqueue_t *\fR\fIq\fR, \fBmblk_t *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 6n +.rt +Pointer to the queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +Pointer to the message block. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBputbq()\fR function places a message at the beginning of the appropriate +section of the message queue. There are always sections for high priority and +ordinary messages. If other priority bands are used, each will have its own +section of the queue, in priority band order, after high priority messages and +before ordinary messages. \fBputbq()\fR can be used for ordinary, priority +band, and high priority messages. However, unless precautions are taken, using +\fBputbq()\fR with a high priority message is likely to lead to an infinite +loop of putting the message back on the queue, being rescheduled, pulling it +off, and putting it back on. +.sp +.LP +This function is usually called when \fBbcanput\fR(9F) or \fBcanput\fR(9F) +determines that the message cannot be passed on to the next stream component. +The flow control parameters are updated to reflect the change in the queue's +status. If \fBQNOENB\fR is not set, the service routine is enabled. +.SH RETURN VALUES +.sp +.LP +The \fBputbq()\fR function returns \fB1\fR upon success and \fB0\fR upon +failure. +.sp +.LP +Upon failure, the caller should call \fBfreemsg\fR(9F) to free the pointer to +the message block. +.SH CONTEXT +.sp +.LP +The \fBputbq()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +See the \fBbufcall\fR(9F) function page for an example of \fBputbq()\fR. +.SH SEE ALSO +.sp +.LP +\fBbcanput\fR(9F), \fBbufcall\fR(9F), \fBcanput\fR(9F), \fBgetq\fR(9F), +\fBputq\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/putctl.9f b/usr/src/man/man9f/putctl.9f new file mode 100644 index 0000000000..09f80eb4e6 --- /dev/null +++ b/usr/src/man/man9f/putctl.9f @@ -0,0 +1,119 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH putctl 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +putctl \- send a control message to a queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBputctl\fR(\fBqueue_t *\fR\fIq\fR, \fBint\fR \fItype\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 8n +.rt +Queue to which the message is to be sent. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 8n +.rt +Message type (must be control, not data type). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBputctl()\fR function tests the \fItype\fR argument to make sure a data +type has not been specified, and then attempts to allocate a message block. +\fBputctl()\fR fails if \fItype\fR is \fBM_DATA\fR, \fBM_PROTO\fR, or +\fBM_PCPROTO\fR, or if a message block cannot be allocated. If successful, +\fBputctl()\fR calls the \fBput\fR(9E) routine of the queue pointed to by +\fIq\fR with the newly allocated and initialized messages. +.SH RETURN VALUES +.sp +.LP +On success, \fB1\fR is returned. If \fItype\fR is a data type, or if a message +block cannot be allocated, \fB0\fR is returned. +.SH CONTEXT +.sp +.LP +The \fBputctl()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBputctl()\fR +.sp +.LP +The \fBsend_ctl()\fR routine is used to pass control messages downstream. +\fBM_BREAK\fR messages are handled with \fBputctl()\fR (line 11). +\fBputctl1\fR(9F) (line 16) is used for \fBM_DELAY\fR messages, so that +\fIparm\fR can be used to specify the length of the delay. In either case, if a +message block cannot be allocated a variable recording the number of allocation +failures is incremented (lines 12, 17). If an invalid message type is detected, +\fBcmn_err\fR(9F) panics the system (line 21). + +.sp +.in +2 +.nf +1 void + 2 send_ctl(wrq, type, parm) + 3 queue_t *wrq; + 4 uchar_t type; + 5 uchar_t parm; + 6 { + 7 extern int num_alloc_fail; + 8 + 9 switch (type) { +10 case M_BREAK: +11 if (!putctl(wrq->q_next, M_BREAK)) +12 num_alloc_fail++; +13 break; +14 +15 case M_DELAY: +16 if (!putctl1(wrq->q_next, M_DELAY, parm)) +17 num_alloc_fail++; +18 break; +19 +20 default: +21 cmn_err(CE_PANIC, "send_ctl: bad message type passed"); +22 break; +23 } +24 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBput\fR(9E), \fBcmn_err\fR(9F), \fBdatamsg\fR(9F), \fBputctl1\fR(9F), +\fBputnextctl\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/putctl1.9f b/usr/src/man/man9f/putctl1.9f new file mode 100644 index 0000000000..0caceb0131 --- /dev/null +++ b/usr/src/man/man9f/putctl1.9f @@ -0,0 +1,94 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH putctl1 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +putctl1 \- send a control message with a one-byte parameter to a queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBputctl1\fR(\fBqueue_t *\fR\fIq\fR, \fBint\fR \fItype\fR, \fBint\fR \fIp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 8n +.rt +Queue to which the message is to be sent. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 8n +.rt +Type of message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIp\fR\fR +.ad +.RS 8n +.rt +One-byte parameter. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBputctl1()\fR function, like \fBputctl\fR(9F), tests the \fItype\fR +argument to make sure a data type has not been specified, and attempts to +allocate a message block. The \fIp\fR parameter can be used, for example, to +specify how long the delay will be when an \fBM_DELAY\fR message is being sent. +\fBputctl1()\fR fails if \fItype\fR is \fBM_DATA\fR, \fBM_PROTO\fR, or +\fBM_PCPROTO\fR, or if a message block cannot be allocated. If successful, +\fBputctl1()\fR calls the \fBput\fR(9E) routine of the queue pointed to by +\fIq\fR with the newly allocated and initialized message. +.SH RETURN VALUES +.sp +.LP +On success, \fB1\fR is returned. \fB0\fR is returned if \fItype\fR is a data +type, or if a message block cannot be allocated. +.SH CONTEXT +.sp +.LP +The \fBputctl1()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +See the \fBputctl\fR(9F) function page for an example of \fBputctl1()\fR. +.SH SEE ALSO +.sp +.LP +\fBput\fR(9E), \fBallocb\fR(9F), \fBdatamsg\fR(9F), \fBputctl\fR(9F), +\fBputnextctl1\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/putnext.9f b/usr/src/man/man9f/putnext.9f new file mode 100644 index 0000000000..74adb334bd --- /dev/null +++ b/usr/src/man/man9f/putnext.9f @@ -0,0 +1,80 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH putnext 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +putnext \- send a message to the next queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBputnext\fR(\fBqueue_t *\fR\fIq\fR, \fBmblk_t *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 6n +.rt +Pointer to the queue from which the message \fImp\fR will be sent. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 6n +.rt +Message to be passed. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBputnext()\fR function is used to pass a message to the \fBput\fR(9E) +routine of the next queue in the stream. +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +The \fBputnext()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +See \fBallocb\fR(9F) for an example of using \fBputnext()\fR. +.SH SEE ALSO +.sp +.LP +\fBput\fR(9E), \fBallocb\fR(9F), \fBput\fR(9F), \fBqprocson\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH NOTES +.sp +.LP +The \fBput()\fR and \fBputnext()\fR functions should be called only after +\fBqprocson()\fR is finished. diff --git a/usr/src/man/man9f/putnextctl.9f b/usr/src/man/man9f/putnextctl.9f new file mode 100644 index 0000000000..24b595a838 --- /dev/null +++ b/usr/src/man/man9f/putnextctl.9f @@ -0,0 +1,123 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH putnextctl 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +putnextctl \- send a control message to a queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBputnextctl\fR(\fBqueue_t *\fR\fIq\fR, \fBint\fR \fItype\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 8n +.rt +Queue to which the message is to be sent. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 8n +.rt +Message type (must be control, not data type). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBputnextctl()\fR function tests the \fItype\fR argument to make sure a +data type has not been specified, and then attempts to allocate a message +block. \fBputnextctl()\fR fails if \fItype\fR is \fBM_DATA\fR, \fBM_PROTO\fR, +or \fBM_PCPROTO\fR, or if a message block cannot be allocated. If successful, +\fBputnextctl()\fR calls the \fBput\fR(9E) routine of the queue pointed to by +\fIq\fR with the newly allocated and initialized messages. +.sp +.LP +A call to \fBputnextctl(\fR\fIq\fR\fB,\fR\fItype\fR\fB)\fR is an atomic +equivalent of \fBputctl(\fR\fIq\fR\fB->q_next\fR,\fItype\fR\fI).\fR The STREAMS +framework provides whatever mutual exclusion is necessary to insure that +dereferencing \fIq\fR through its \fBq_next\fR field and then invoking +\fBputctl\fR(9F) proceeds without interference from other threads. +.sp +.LP +The \fBputnextctl()\fR function should always be used in preference to +\fBputctl\fR(9F) +.SH RETURN VALUES +.sp +.LP +On success, \fB1\fR is returned. If \fItype\fR is a data type, or if a message +block cannot be allocated, \fB0\fR is returned. +.SH CONTEXT +.sp +.LP +The \fBputnextctl()\fR function can be user, interrupt, or kernel context. +.SH EXAMPLES +.sp +.LP +The \fBsend_ctl\fR routine is used to pass control messages downstream. +\fBM_BREAK\fR messages are handled with \fBputnextctl\fR(\|) (line 8). +\fBputnextctl1\fR(9F) (line 13) is used for \fBM_DELAY\fR messages, so that +\fIparm\fR can be used to specify the length of the delay. In either case, if a +message block cannot be allocated a variable recording the number of +allocation failures is incremented (lines 9, 14). If an invalid message type +is detected, \fBcmn_err\fR(9F) panics the system (line 18). +.sp +.in +2 +.nf +1 void + 2 send_ctl(queue_t *wrq, uchar_t type, uchar_t parm) + 3 { + 4 extern int num_alloc_fail; + 5 + 6 switch (type) { + 7 case M_BREAK: + 8 if (!putnextctl(wrq, M_BREAK)) + 9 num_alloc_fail++; +10 break; +11 +12 case M_DELAY: +13 if (!putnextctl1(wrq, M_DELAY, parm)) +14 num_alloc_fail++; +15 break; +16 +17 default: +18 cmn_err(CE_PANIC, "send_ctl: bad message type passed"); +19 break; +20 } +21 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBput\fR(9E), \fBcmn_err\fR(9F), \fBdatamsg\fR(9F), \fBputctl\fR(9F), +\fBputnextctl1\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/putnextctl1.9f b/usr/src/man/man9f/putnextctl1.9f new file mode 100644 index 0000000000..b0cc02d915 --- /dev/null +++ b/usr/src/man/man9f/putnextctl1.9f @@ -0,0 +1,106 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH putnextctl1 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +putnextctl1 \- send a control message with a one-byte parameter to a queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBputnextctl1\fR(\fBqueue_t *\fR\fIq\fR, \fBint\fR \fItype\fR, \fBint\fR \fIp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 8n +.rt +Queue to which the message is to be sent. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 8n +.rt +Type of message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIp\fR\fR +.ad +.RS 8n +.rt +One-byte parameter. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBputnextctl1()\fR function, like \fBputctl1\fR(9F), tests the \fItype\fR +argument to make sure a data type has not been specified, and attempts to +allocate a message block. The \fIp\fR parameter can be used, for example, to +specify how long the delay will be when an \fBM_DELAY\fR message is being sent. +\fBputnextctl1()\fR fails if \fItype\fR is \fBM_DATA\fR, \fBM_PROTO\fR, or +\fBM_PCPROTO\fR, or if a message block cannot be allocated. If successful, +\fBputnextctl1()\fR calls the \fBput\fR(9E) routine of the queue pointed to by +\fIq\fR with the newly allocated and initialized message. +.sp +.LP +A call to \fBputnextctl1(\fR\fIq\fR,\fItype, p\fR\fB)\fR is an atomic +equivalent of \fBputctl1(\fR\fIq\fR\fB->q_next,\fR \fItype, p\fR\fB).\fR The +STREAMS framework provides whatever mutual exclusion is necessary to insure +that dereferencing \fIq\fR through its \fBq_next\fR field and then invoking +\fBputctl1\fR(9F) proceeds without interference from other threads. +.sp +.LP +The \fBputnextctl1()\fR function should always be used in preference to +\fBputctl1\fR(9F) +.SH RETURN VALUES +.sp +.LP +On success, \fB1\fR is returned. \fB0\fR is returned if \fItype\fR is a data +type, or if a message block cannot be allocated. +.SH CONTEXT +.sp +.LP +The \fBputnextctl1()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +See the \fBputnextctl\fR(9F) function page for an example of +\fBputnextctl1()\fR. +.SH SEE ALSO +.sp +.LP +\fBput\fR(9E), \fBallocb\fR(9F), \fBdatamsg\fR(9F), \fBputctl1\fR(9F), +\fBputnextctl\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/putq.9f b/usr/src/man/man9f/putq.9f new file mode 100644 index 0000000000..01dd68f5ec --- /dev/null +++ b/usr/src/man/man9f/putq.9f @@ -0,0 +1,81 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH putq 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +putq \- put a message on a queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBputq\fR(\fBqueue_t *\fR\fIq\fR, \fBmblk_t *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 6n +.rt +Pointer to the queue to which the message is to be added. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +Message to be put on the queue. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBputq()\fR function is used to put messages on a driver's queue after the +module's put routine has finished processing the message. The message is placed +after any other messages of the same priority, and flow control parameters are +updated. If \fBQNOENB\fR is not set, the service routine is enabled. If no +other processing is done, \fBputq()\fR can be used as the module's put routine. +.SH RETURN VALUES +.sp +.LP +The \fBputq()\fR function returns \fB1\fR on success and \fB0\fR on failure. +.sp +.LP +Upon failure, the caller should call \fBfreemsg\fR(9F) to free the pointer to +the message block. +.SH CONTEXT +.sp +.LP +The \fBputq()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +See the \fBdatamsg\fR(9F) function page for an example of \fBputq()\fR. +.SH SEE ALSO +.sp +.LP +\fBdatamsg\fR(9F), \fBputbq\fR(9F), \fBqenable\fR(9F), \fBrmvq\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/qassociate.9f b/usr/src/man/man9f/qassociate.9f new file mode 100644 index 0000000000..7ec16c581a --- /dev/null +++ b/usr/src/man/man9f/qassociate.9f @@ -0,0 +1,156 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH qassociate 9F "01 Feb 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +qassociate \- associate STREAMS queue with driver instance +.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\fR \fBqassociate\fR(\fBqueue_t *\fR\fIq\fR, \fBint\fR \fIinstance\fR +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fBqueue_t *\fIq\fR\fR +.ad +.RS 16n +.rt +Pointer to a \fBqueue\fR(9S) structure. Either the read or write queue can be +used. +.RE + +.sp +.ne 2 +.mk +.na +\fBint \fIinstance\fR\fR +.ad +.RS 16n +.rt +Driver instance number or -1. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBqassociate()\fR function must be used by \fBDLPI\fR style 2 device +drivers to manage the association between STREAMS queues and device instances. +The \fBgld\fR(7D) does this automatically on behalf of drivers based on it. It +is recommended that the \fBgld\fR(7D) be used for network device drivers +whenever possible. +.sp +.LP +The \fBqassociate()\fR function associates the specified STREAMS queue with the +specified instance of the bottom driver in the queue. Upon successful return, +the stream is associated with the instance with any prior association +dissolved. +.sp +.LP +A DLPI style 2 driver calls \fBqassociate()\fR while processing the +\fBDL_ATTACH_REQ\fR message. The driver is also expected to call this interface +while performing stream associations through other means, such as \fBndd\fR(1M) +ioctl commands. +.sp +.LP +If \fIinstance\fR is -1, the stream is left unassociated with any hardware +instance. +.sp +.LP +If the interface returns failure, the stream is not associated with the +specified instance. Any prior association is left untouched. +.sp +.LP +The interface typically fails because of failure to locate and attach the +device instance. The interface never fails if the specified instance is -1. +.SH CONTEXT +.sp +.LP +The \fBqassociate()\fR function can be called from the stream's \fBput\fR(9E) +entry point. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 6n +.rt +Success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB-1\fR\fR +.ad +.RS 6n +.rt +Failure. +.RE + +.SH EXAMPLES +.sp +.LP +DLPI style 2 network driver \fBDL_ATTACH_REQ\fR code specifies: +.sp +.in +2 +.nf +if (qassociate(q, instance) != 0) + goto fail; +.fi +.in -2 + +.sp +.LP +The association prevents Dynamic Reconfiguration (DR) from detaching the +instance. +.sp +.LP +DLPI style 2 network driver \fBDL_DETACH\fR code specifies: +.sp +.in +2 +.nf +(void) qassociate(q, -1); +.fi +.in -2 + +.sp +.LP +This dissolves the queue's association with any device instance. +.sp +.LP +DLPI style 2 network driver \fBopen\fR(9E) code must call: +.sp +.in +2 +.nf +qassociate(q, -1); +.fi +.in -2 + +.sp +.LP +This informs the framework that this driver has been modified to be +DDI-compliant. +.SH SEE ALSO +.sp +.LP +\fBdlpi\fR(7P), \fBgld\fR(7D), \fBopen\fR(9E), \fBput\fR(9E), +\fBddi_no_info\fR(9F), \fBqueue\fR(9S) diff --git a/usr/src/man/man9f/qbufcall.9f b/usr/src/man/man9f/qbufcall.9f new file mode 100644 index 0000000000..1d6fd0d2a5 --- /dev/null +++ b/usr/src/man/man9f/qbufcall.9f @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (c) 2006, 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 qbufcall 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +qbufcall \- call a function when a buffer becomes available +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBbufcall_id_t\fR \fBqbufcall\fR(\fBqueue_t *\fR\fIq\fR, \fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR, + \fBvoid\fR(\fI*func\fR)(\fBvoid\fR \fI*arg\fR), \fBvoid\fR \fI*arg\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 8n +.rt +Pointer to \fBSTREAMS \fRqueue structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 8n +.rt +Number of bytes required for the buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpri\fR\fR +.ad +.RS 8n +.rt +Priority of the \fBallocb\fR(9F) allocation request (not used). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfunc\fR\fR +.ad +.RS 8n +.rt +Function or driver routine to be called when a buffer becomes available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 8n +.rt +Argument to the function to be called when a buffer becomes available. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBqbufcall()\fR function serves as a \fBqtimeout\fR(9F) call of +indeterminate length. When a buffer allocation request fails, \fBqbufcall()\fR +can be used to schedule the routine \fIfunc\fR to be called with the argument +\fIarg\fR when a buffer becomes available. \fIfunc\fR may call \fBallocb()\fR +or it may do something else. +.sp +.LP +The \fBqbufcall()\fR function is tailored to be used with the enhanced +\fBSTREAMS \fRframework interface, which is based on the concept of perimeters. +(See \fBmt-streams\fR(9F).) \fBqbufcall()\fR schedules the specified function +to execute after entering the perimeters associated with the queue passed in as +the first parameter to \fBqbufcall()\fR. All outstanding timeouts and bufcalls +must be cancelled (using, respectively, \fBquntimeout\fR(9F) and +\fBqunbufcall\fR(9F)) before a driver close routine can block and before the +close routine calls \fBqprocsoff\fR(9F). +.sp +.LP +\fBqprocson\fR(9F) must be called before calling either \fBqbufcall()\fR or +\fBqtimeout\fR(9F). +.SH RETURN VALUES +.sp +.LP +If successful, the \fBqbufcall()\fR function returns a \fBqbufcall\fR \fBID\fR +that can be used in a call to \fBqunbufcall\fR(9F) to cancel the request. If +the \fBqbufcall()\fR scheduling fails, \fIfunc\fR is never called and \fB0\fR +is returned. +.SH CONTEXT +.sp +.LP +The \fBqbufcall()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBallocb\fR(9F), \fBmt-streams\fR(9F), \fBqprocson\fR(9F), \fBqtimeout\fR(9F), +\fBqunbufcall\fR(9F), \fBquntimeout\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH WARNINGS +.sp +.LP +Even when \fIfunc\fR is called by \fBqbufcall()\fR, \fBallocb\fR(9F) can fail +if another module or driver had allocated the memory before \fIfunc\fR was able +to call \fBallocb\fR(9F). diff --git a/usr/src/man/man9f/qenable.9f b/usr/src/man/man9f/qenable.9f new file mode 100644 index 0000000000..40926a81cd --- /dev/null +++ b/usr/src/man/man9f/qenable.9f @@ -0,0 +1,61 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH qenable 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +qenable \- enable a queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBqenable\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 5n +.rt +Pointer to the queue to be enabled. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBqenable()\fR function adds the queue pointed to by \fIq\fR to the list +of queues whose service routines are ready to be called by the STREAMS +scheduler. +.SH CONTEXT +.sp +.LP +The \fBqenable()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +See the \fBdupb\fR(9F) function page for an example of the \fBqenable()\fR. +.SH SEE ALSO +.sp +.LP +\fBdupb\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/qprocson.9f b/usr/src/man/man9f/qprocson.9f new file mode 100644 index 0000000000..a890db7568 --- /dev/null +++ b/usr/src/man/man9f/qprocson.9f @@ -0,0 +1,87 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH qprocson 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +qprocson, qprocsoff \- enable, disable put and service routines +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + +\fBvoid\fR \fBqprocson\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBqprocsoff\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 5n +.rt +Pointer to the \fBRD\fR side of a streams queue pair. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBqprocson()\fR enables the put and service routines of the driver or +module whose read queue is pointed to by \fIq\fR. Threads cannot enter the +module instance through the put and service routines while they are disabled. +.sp +.LP +The \fBqprocson()\fR function must be called by the open routine of a driver or +module before returning, and after any initialization necessary for the proper +functioning of the put and service routines. +.sp +.LP +The \fBqprocson()\fR function must be called before calling \fBput\fR(9F), +\fBputnext\fR(9F), \fBqbufcall\fR(9F), \fBqtimeout\fR(9F), \fBqwait\fR(9F), or +\fBqwait_sig\fR(9F). +.sp +.LP +The \fBqprocsoff()\fR function must be called by the close routine of a driver +or module before returning, and before deallocating any resources necessary for +the proper functioning of the put and service routines. It also removes the +queue's service routines from the service queue, and blocks until any pending +service processing completes. +.sp +.LP +The module or driver instance is guaranteed to be single-threaded before +\fBqprocson()\fR is called and after \fBqprocsoff()\fR is called, except for +threads executing asynchronous events such as interrupt handlers and callbacks, +which must be handled separately. +.SH CONTEXT +.sp +.LP +These routines can be called from user, interrupt, or kernel context. +.SH SEE ALSO +.sp +.LP +\fBclose\fR(9E), \fBopen\fR(9E), \fBput\fR(9E), \fBsrv\fR(9E), \fBput\fR(9F), +\fBputnext\fR(9F), \fBqbufcall\fR(9F), \fBqtimeout\fR(9F), \fBqwait\fR(9F), +\fBqwait_sig\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH NOTES +.sp +.LP +The caller may not have the stream frozen during either of these calls. diff --git a/usr/src/man/man9f/qreply.9f b/usr/src/man/man9f/qreply.9f new file mode 100644 index 0000000000..57a48cb770 --- /dev/null +++ b/usr/src/man/man9f/qreply.9f @@ -0,0 +1,110 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH qreply 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +qreply \- send a message on a stream in the reverse direction +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBvoid\fR \fBqreply\fR(\fBqueue_t *\fR\fIq\fR, \fBmblk_t *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 6n +.rt +Pointer to the queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 6n +.rt +Pointer to the message to be sent in the opposite direction. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBqreply()\fR function sends messages in the reverse direction of normal +flow. That is, \fBqreply(\fR\fIq\fR\fB,\fR \fImp\fR\fB)\fR is equivalent to +\fBputnext(OTHERQ(\fR\fIq\fR\fB),\fR \fImp\fR\fB)\fR. +.SH CONTEXT +.sp +.LP +The \fBqreply()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRCanonical Flushing Code for STREAMS Drivers. +.sp +.LP +This example depicts the canonical flushing code for STREAMS drivers. Assume +that the driver has service procedures so that there may be messages on its +queues. See \fBsrv\fR(9E). Its write-side put procedure handles \fBM_FLUSH\fR +messages by first checking the \fBFLUSHW\fR bit in the first byte of the +message, then the write queue is flushed (line 8) and the \fBFLUSHW\fR bit is +turned off (line 9). See \fBput\fR(9E). If the \fBFLUSHR\fR bit is on, then the +read queue is flushed (line 12) and the message is sent back up the read side +of the stream with the \fBqreply()\fR function (line 13). If the \fBFLUSHR\fR +bit is off, then the message is freed (line 15). See the example for +\fBflushq\fR(9F) for the canonical flushing code for modules. + +.sp +.in +2 +.nf +1 xxxwput(q, mp) + 2 queue_t *q; + 3 mblk_t *mp; + 4 { + 5 switch(mp->b_datap->db_type) { + 6 case M_FLUSH: + 7 if (*mp->b_rptr & FLUSHW) { + 8 flushq(q, FLUSHALL); + 9 *mp->b_rptr &= ~FLUSHW; +10 } +11 if (*mp->b_rptr & FLUSHR) { +12 flushq(RD(q), FLUSHALL); +13 qreply(q, mp); +14 } else { +15 freemsg(mp); +16 } +17 break; + . . . +18 } +19 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBput\fR(9E), \fBsrv\fR(9E), \fBflushq\fR(9F), \fBOTHERQ\fR(9F), +\fBputnext\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/qsize.9f b/usr/src/man/man9f/qsize.9f new file mode 100644 index 0000000000..e5125c48a9 --- /dev/null +++ b/usr/src/man/man9f/qsize.9f @@ -0,0 +1,57 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH qsize 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +qsize \- find the number of messages on a queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBqsize\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 5n +.rt +Queue to be evaluated. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBqsize()\fR function evaluates the queue \fIq\fR and returns the number +of messages it contains. +.SH RETURN VALUES +.sp +.LP +If there are no message on the queue, \fBqsize()\fR returns \fB0\fR. Otherwise, +it returns the integer representing the number of messages on the queue. +.SH CONTEXT +.sp +.LP +The \fBqsize()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/qtimeout.9f b/usr/src/man/man9f/qtimeout.9f new file mode 100644 index 0000000000..276689735f --- /dev/null +++ b/usr/src/man/man9f/qtimeout.9f @@ -0,0 +1,115 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH qtimeout 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +qtimeout \- execute a function after a specified length of time +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + +\fBtimeout_id_t\fR \fBqtimeout\fR(\fBqueue_t *\fR\fIq\fR, \fBvoid\fR (\fI*func\fR)(\fIvoid *\fR), + \fBvoid\fR \fI*arg\fR, \fBclock_t\fR \fIticks\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 9n +.rt +Pointer to \fBSTREAMS\fR queue structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfunc\fR\fR +.ad +.RS 9n +.rt +Kernel function to invoke when the time increment expires. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 9n +.rt +Argument to the function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIticks\fR\fR +.ad +.RS 9n +.rt +Number of clock ticks to wait before the function is called. Use +\fBdrv_usectohz\fR(9F) to convert microseconds to clock ticks. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBqtimeout()\fR function schedules the specified function \fIfunc\fR to be +called after a specified time interval. \fIfunc\fR is called with \fIarg\fR as +a parameter. Control is immediately returned to the caller. This is useful when +an event is known to occur within a specific time frame, or when you want to +wait for I/O processes when an interrupt is not available or might cause +problems. The exact time interval over which the timeout takes effect cannot be +guaranteed, but the value given is a close approximation. +.sp +.LP +The \fBqtimeout()\fR function is tailored to be used with the enhanced +\fBSTREAMS \fRframework interface which is based on the concept of perimeters. +(See \fBmt-streams\fR(9F).) \fBqtimeout()\fR schedules the specified function +to execute after entering the perimeters associated with the queue passed in as +the first parameter to \fBqtimeout()\fR. All outstanding timeouts and bufcalls +must be cancelled (using, respectively, \fBquntimeout\fR(9F) and +\fBqunbufcall\fR(9F)) before a driver close routine can block and before the +close routine calls \fBqprocsoff\fR(9F). +.sp +.LP +The \fBqprocson\fR(9F) function must be called before calling \fBqtimeout()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBqtimeout()\fR function returns an opaque non-zero \fBtimeout\fR +identifier that can be passed to \fBquntimeout\fR(9F) to cancel the request. +Note: No value is returned from the called function. +.SH CONTEXT +.sp +.LP +The \fBqtimeout()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBdrv_usectohz\fR(9F), \fBmt-streams\fR(9F), \fBqbufcall\fR(9F), +\fBqprocson\fR(9F), \fBqunbufcall\fR(9F), \fBquntimeout\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/qunbufcall.9f b/usr/src/man/man9f/qunbufcall.9f new file mode 100644 index 0000000000..13165f5ace --- /dev/null +++ b/usr/src/man/man9f/qunbufcall.9f @@ -0,0 +1,77 @@ +'\" te +.\" Copyright 2006 Sun Microsystems. +.\" 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 qunbufcall 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +qunbufcall \- cancel a pending qbufcall request +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + #include <sys/ddi.h> + + +\fBvoid\fR \fBqunbufcall\fR(\fBqueue_t *\fR\fIq\fR, \fBbufcall_id_t\fR \fIid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 6n +.rt +Pointer to \fBSTREAMS\fR queue_t structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIid\fR\fR +.ad +.RS 6n +.rt +Identifier returned from \fBqbufcall\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBqunbufcall()\fR function cancels a pending \fBqbufcall()\fR request. The +argument \fIid\fR is a non-zero identifier of the request to be cancelled. +\fIid\fR is returned from the \fBqbufcall()\fR function used to issue the +cancel request. +.sp +.LP +The \fBqunbufcall()\fR function is tailored to be used with the enhanced +\fBSTREAMS \fRframework interface which is based on the concept of perimeters. +(See \fBmt-streams\fR(9F).) \fBqunbufcall()\fR returns when the bufcall has +been cancelled or finished executing. The bufcall will be cancelled even if it +is blocked at the perimeters associated with the queue. All outstanding +timeouts and bufcalls must be cancelled before a driver close routine can block +and before the close routine calls \fBqprocsoff\fR(9F). +.SH CONTEXT +.sp +.LP +The \fBqunbufcall()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBmt-streams\fR(9F), \fBqbufcall\fR(9F), \fBqtimeout\fR(9F), +\fBquntimeout\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/quntimeout.9f b/usr/src/man/man9f/quntimeout.9f new file mode 100644 index 0000000000..29a27d34ab --- /dev/null +++ b/usr/src/man/man9f/quntimeout.9f @@ -0,0 +1,80 @@ +'\" te +.\" Copyright 2006 Sun Microsystems. +.\" 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 quntimeout 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +quntimeout \- cancel previous qtimeout function call +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBclock_t\fR \fBquntimeout\fR(\fBqueue_t\fR \fI*q\fR, \fBtimeout_id_t\fR \fIid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 6n +.rt +Pointer to a \fBSTREAMS \fRqueue structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIid\fR\fR +.ad +.RS 6n +.rt +Opaque timeout \fBID\fR a previous \fBqtimeout\fR(9F) call. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBquntimeout()\fR function cancels a pending \fBqtimeout\fR(9F) request. +The \fBquntimeout()\fR function is tailored to be used with the enhanced +\fBSTREAMS\fR framework interface, which is based on the concept of perimeters. +(See \fBmt-streams\fR(9F).) \fBquntimeout()\fR returns when the timeout has +been cancelled or finished executing. The timeout will be cancelled even if it +is blocked at the perimeters associated with the queue. \fBquntimeout()\fR +should be executed for all outstanding timeouts before a driver or module close +returns. All outstanding timeouts and bufcalls must be cancelled before a +driver close routine can block and before the close routine calls +\fBqprocsoff\fR(9F). +.SH RETURN VALUES +.sp +.LP +The \fBquntimeout()\fR function returns \fB-1\fR if the \fBid\fR is not found. +Otherwise, \fBquntimeout()\fR returns a \fB0\fR or positive value. +.SH CONTEXT +.sp +.LP +The \fBquntimeout()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBmt-streams\fR(9F), \fBqbufcall\fR(9F), \fBqtimeout\fR(9F), +\fBqunbufcall\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/qwait.9f b/usr/src/man/man9f/qwait.9f new file mode 100644 index 0000000000..7dbc01f954 --- /dev/null +++ b/usr/src/man/man9f/qwait.9f @@ -0,0 +1,161 @@ +'\" 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 qwait 9F "15 Dec 2003" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +qwait, qwait_sig \- STREAMS wait routines +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBqwait\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.LP +.nf +\fBint\fR \fBqwait_sig\fR(\fBqueue_t *\fR\fIq\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIqp\fR\fR +.ad +.RS 6n +.rt +Pointer to the queue that is being opened or closed. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBqwait()\fR and \fBqwait_sig()\fR are used to wait for a message to arrive to +the \fBput\fR(9E) or \fBsrv\fR(9E) procedures. \fBqwait()\fR and +\fBqwait_sig()\fR can also be used to wait for \fBqbufcall\fR(9F) or +\fBqtimeout\fR(9F) callback procedures to execute. These routines can be used +in the \fBopen\fR(9E) and \fBclose\fR(9E) procedures in a STREAMS driver or +module. +.sp +.LP +The thread that calls \fBclose()\fR does not necessarily have the ability to +receive signals, particularly when called by \fBexit\fR(2). In this case, +\fBqwait_sig()\fR behaves exactly as \fBqwait()\fR. Driver writers may use +\fBddi_can_receive_sig\fR(9F) to determine when this is the case, and, if so, +arrange some means to avoid blocking indefinitely (for example, by using +\fBqtimeout\fR(9F). +.sp +.LP +\fBqwait()\fR and \fBqwait_sig()\fR atomically exit the inner and outer +perimeters associated with the queue, and wait for a thread to leave the +module's \fBput\fR(9E), \fBsrv\fR(9E), or \fBqbufcall\fR(9F) / +\fBqtimeout\fR(9F) callback procedures. Upon return they re-enter the inner and +outer perimeters. +.sp +.LP +This can be viewed as there being an implicit wakeup when a thread leaves a +\fBput\fR(9E) or \fBsrv\fR(9E) procedure or after a \fBqtimeout\fR(9F) or +\fBqbufcall\fR(9F) callback procedure has been run in the same perimeter. +.sp +.LP +\fBqprocson\fR(9F) must be called before calling \fBqwait()\fR or +\fBqwait_sig()\fR. +.sp +.LP +\fBqwait()\fR is not interrupted by a signal, whereas \fBqwait_sig()\fR is +interrupted by a signal. \fBqwait_sig()\fR normally returns non-zero, and +returns zero when the waiting was interrupted by a signal. +.sp +.LP +\fBqwait()\fR and \fBqwait_sig()\fR are similar to \fBcv_wait()\fR and +\fBcv_wait_sig()\fR except that the mutex is replaced by the inner and outer +perimeters and the signalling is implicit when a thread leaves the inner +perimeter. See \fBcondvar\fR(9F). +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +For \fBqwait_sig()\fR, indicates that the condition was not necessarily +signaled, and the function returned because a signal was pending. +.RE + +.SH CONTEXT +.sp +.LP +These functions can only be called from an \fBopen\fR(9E) or \fBclose\fR(9E) +routine. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBqwait()\fR +.sp +.LP +The open routine sends down a \fBT_INFO_REQ\fR message and waits for the +\fBT_INFO_ACK\fR. The arrival of the \fBT_INFO_ACK\fR is recorded by resetting +a flag in the unit structure (\fBWAIT_INFO_ACK\fR). The example assumes that +the module is \fBD_MTQPAIR\fR or \fBD_MTPERMOD\fR. + +.sp +.in +2 +.nf +xxopen(qp, .\|.\|.) + queue_t *qp; +{ + struct xxdata *xx; + /* Allocate xxdata structure */ + qprocson(qp); + /* Format T_INFO_ACK in mp */ + putnext(qp, mp); + xx->xx_flags |= WAIT_INFO_ACK; + while (xx->xx_flags & WAIT_INFO_ACK) + qwait(qp); + return (0); +} +xxrput(qp, mp) + queue_t *qp; + mblk_t *mp; +{ + struct xxdata *xx = (struct xxdata *)q->q_ptr; + + ... + + case T_INFO_ACK: + if (xx->xx_flags & WAIT_INFO_ACK) { + /* Record information from info ack */ + xx->xx_flags &= ~WAIT_INFO_ACK; + freemsg(mp); + return; + } + + ... +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBclose\fR(9E), \fBopen\fR(9E), \fBput\fR(9E), \fBsrv\fR(9E), +\fBcondvar\fR(9F), \fBddi_can_receive_sig\fR(9F), \fBmt-streams\fR(9F), +\fBqbufcall\fR(9F), \fBqprocson\fR(9F), \fBqtimeout\fR(9F) +.sp +.LP +\fISTREAMS Programming Guide\fR +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/qwriter.9f b/usr/src/man/man9f/qwriter.9f new file mode 100644 index 0000000000..50d0189aff --- /dev/null +++ b/usr/src/man/man9f/qwriter.9f @@ -0,0 +1,116 @@ +'\" 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 qwriter 9F "1 Mar 1993" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +qwriter \- asynchronous STREAMS perimeter upgrade +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBqwriter\fR(\fBqueue_t *\fR\fIqp\fR, \fBmblk_t *\fR\fImp\fR, \fBvoid (*\fR\fIfunc\fR)(), \fBint\fR \fIperimeter\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIqp\fR \fR +.ad +.RS 14n +.rt +Pointer to the queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR \fR +.ad +.RS 14n +.rt +Pointer to a message that will be passed in to the callback function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfunc\fR \fR +.ad +.RS 14n +.rt +A function that will be called when exclusive (writer) access has been acquired +at the specified perimeter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIperimeter\fR \fR +.ad +.RS 14n +.rt +Either \fBPERIM_INNER\fR or \fBPERIM_OUTER\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBqwriter()\fR is used to upgrade the access at either the inner or the outer +perimeter from shared to exclusive and call the specified callback function +when the upgrade has succeeded. See \fBmt-streams\fR(9F). The callback function +is called as: +.sp +.in +2 +.nf +\fB(*func)(queue_t *\fR\fIqp\fR\fB, mblk_t *\fR\fImp\fR\fB);\fR +.fi +.in -2 + +.sp +.LP +\fBqwriter()\fR will acquire exclusive access immediately if possible, in which +case the specified callback function will be executed before \fBqwriter()\fR +returns. If this is not possible, \fBqwriter()\fR will defer the upgrade until +later and return before the callback function has been executed. Modules should +not assume that the callback function has been executed when \fBqwriter()\fR +returns. One way to avoid dependencies on the execution of the callback +function is to immediately return after calling \fBqwriter()\fR and let the +callback function finish the processing of the message. +.sp +.LP +When \fBqwriter()\fR defers calling the callback function, the STREAMS +framework will prevent other messages from entering the inner perimeter +associated with the queue until the upgrade has completed and the callback +function has finished executing. +.SH CONTEXT +.sp +.LP +\fBqwriter()\fR can only be called from an \fBput\fR(9E) or \fBsrv\fR(9E) +routine, or from a \fBqwriter()\fR, \fBqtimeout\fR(9F), or \fBqbufcall\fR(9F) +callback function. +.SH SEE ALSO +.sp +.LP +\fBput\fR(9E), \fBsrv\fR(9E), \fBmt-streams\fR(9F), \fBqbufcall\fR(9F), +\fBqtimeout\fR(9F) +.sp +.LP +\fISTREAMS Programming Guide\fR +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/rmalloc.9f b/usr/src/man/man9f/rmalloc.9f new file mode 100644 index 0000000000..85f9767401 --- /dev/null +++ b/usr/src/man/man9f/rmalloc.9f @@ -0,0 +1,264 @@ +'\" te +.\" Copyright (c) 2006, 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 rmalloc 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +rmalloc \- allocate space from a resource map +.SH SYNOPSIS +.LP +.nf +#include <sys/map.h> +#include <sys/ddi.h> + + + +\fBunsigned long\fR \fBrmalloc\fR(\fBstruct map *\fR\fImp\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (\fBDDI/DKI\fR). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 8n +.rt +Resource map from where the resource is drawn. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 8n +.rt +Number of units of the resource. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBrmalloc()\fR function is used by a driver to allocate space from a +previously defined and initialized resource map. The map itself is allocated by +calling the function \fBrmallocmap\fR(9F). \fBrmalloc()\fR is one of five +functions used for resource map management. The other functions include: +.sp +.ne 2 +.mk +.na +\fB\fBrmalloc_wait\fR(9F)\fR +.ad +.RS 20n +.rt +Allocate space from a resource map, wait if necessary. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrmfree\fR(9F)\fR +.ad +.RS 20n +.rt +Return previously allocated space to a map. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrmallocmap\fR(9F)\fR +.ad +.RS 20n +.rt +Allocate a resource map and initialize it. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBrmfreemap\fR(9F)\fR +.ad +.RS 20n +.rt +Deallocate a resource map. +.RE + +.sp +.LP +The \fBrmalloc()\fR function allocates space from a resource map in terms of +arbitrary units. The system maintains the resource map by size and index, +computed in units appropriate for the resource. For example, units may be byte +addresses, pages of memory, or blocks. The normal return value is an +\fBunsigned long\fR set to the value of the index where sufficient free space +in the resource was found. +.SH RETURN VALUES +.sp +.LP +Under normal conditions, \fBrmalloc()\fR returns the base index of the +allocated space. Otherwise, \fBrmalloc()\fR returns a \fB0\fR if all resource +map entries are already allocated. +.SH CONTEXT +.sp +.LP +The \fBrmalloc()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRIllustrating the principles of map management +.sp +.LP +The following example is a simple memory map, but it illustrates the principles +of map management. A driver allocates and initializes the map by calling both +the \fBrmallocmap\fR(9F) and \fBrmfree\fR(9F) functions. \fBrmallocmap\fR(9F) +is called to establish the number of slots or entries in the map, and +\fBrmfree\fR(9F) to initialize the resource area the map is to manage. The +following example is a fragment from a hypothetical \fBstart\fR routine and +illustrates the following procedures: + +.RS +4 +.TP +.ie t \(bu +.el o +Panics the system if the required amount of memory can not be allocated (lines +11-15). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Uses \fBrmallocmap\fR(9F) to configure the total number of entries in the map, +and \fBrmfree\fR(9F) to initialize the total resource area. +.RE +.sp +.in +2 +.nf +1 #define XX_MAPSIZE 12 +2 #define XX_BUFSIZE 2560 +3 static struct map *xx_mp; /* Private buffer space map */ + .\|.\|. +4 xxstart(\|) +5 /* +6 * Allocate private buffer. If insufficient memory, +7 * display message and halt system. +8 */ +9 { +10 register caddr_t bp; + .\|.\|. +11 if ((bp = kmem_alloc(XX_BUFSIZE, KM_NOSLEEP) == 0) { +12 +13 cmn_err(CE_PANIC, "xxstart: kmem_alloc failed before %d buffer" +14 "allocation", XX_BUFSIZE); +15 } +16 +17 /* +18 * Initialize the resource map with number +19 * of slots in map. +20 */ +21 xx_mp = rmallocmap(XX_MAPSIZE); +22 +24 /* +25 * Initialize space management map with total +26 * buffer area it is to manage. +27 */ +28 rmfree(xx_mp, XX_BUFSIZE, bp); + .\|.\|.\fI\fR +.fi +.in -2 + +.LP +\fBExample 2 \fRAllocating buffers +.sp +.LP +The \fBrmalloc()\fR function is then used by the driver's \fBread\fR or +\fBwrite\fR routine to allocate buffers for specific data transfers. The +\fBuiomove\fR(9F) function is used to move the data between user space and +local driver memory. The device then moves data between itself and local driver +memory through \fBDMA\fR. + +.sp +.LP +The next example illustrates the following procedures: + +.RS +4 +.TP +.ie t \(bu +.el o +The size of the \fBI/O\fR request is calculated and stored in the \fIsize\fR +variable (line 10). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Buffers are allocated through the \fBrmalloc()\fR function using the \fIsize\fR +value (line 15). If the allocation fails the system will panic. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +The \fBuiomove\fR(9F) function is used to move data to the allocated buffer +(line 23). +.RE +.RS +4 +.TP +.ie t \(bu +.el o +If the address passed to \fBuiomove\fR(9F) is invalid, \fBrmfree\fR(9F) is +called to release the previously allocated buffer, and an \fBEFAULT\fR error is +returned. +.RE +.sp +.in +2 +.nf +1 #define XX_BUFSIZE 2560 +2 #define XX_MAXSIZE (XX_BUFSIZE / 4) +3 +4 static struct map *xx_mp; /* Private buffer space map */ + ... +5 xxread(dev_t dev, uio_t *uiop, cred_t *credp) +6 { +7 +8 register caddr_t addr; +9 register int size; +10 size = min(COUNT, XX_MAXSIZE); /* Break large I/O */ +11 /* request into small ones */ +12 /* +13 * Get buffer. +14 */ +15 if ((addr = (caddr_t)rmalloc(xx_mp, size)) == 0) +16 cmn_err(CE_PANIC, "read: rmalloc failed allocation of size %d", +17 size); +18 +19 /* +20 * Move data to buffer. If invalid address is found, +21 * return buffer to map and return error code. +22 */ +23 if (uiomove(addr, size, UIO_READ, uiop) == -1) { +24 rmfree(xx_mp, size, addr); +25 return(EFAULT); +26 } +27 }\fI\fR +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBkmem_alloc\fR(9F), \fBrmalloc_wait\fR(9F), \fBrmallocmap\fR(9F), +\fBrmfree\fR(9F), \fBrmfreemap\fR(9F), \fBuiomove\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/rmalloc_wait.9f b/usr/src/man/man9f/rmalloc_wait.9f new file mode 100644 index 0000000000..87eba9f3cd --- /dev/null +++ b/usr/src/man/man9f/rmalloc_wait.9f @@ -0,0 +1,70 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rmalloc_wait 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +rmalloc_wait \- allocate space from a resource map, wait if necessary +.SH SYNOPSIS +.LP +.nf +#include <sys/map.h> +#include <sys/ddi.h> + + + +\fBunsigned long\fR \fBrmalloc_wait\fR(\fBstruct map *\fR\fImp\fR, \fBsize_t\fR \fIsize\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (\fBDDI/DKI\fR). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 8n +.rt +Pointer to the resource map from which space is to be allocated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 8n +.rt +Number of units of space to allocate. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBrmalloc_wait()\fR function requests an allocation of space from a +resource map. \fBrmalloc_wait()\fR is similar to the \fBrmalloc\fR(9F) function +with the exception that it will wait for space to become available if +necessary. +.SH RETURN VALUES +.sp +.LP +The \fBrmalloc_wait()\fR function returns the base of the allocated space. +.SH CONTEXT +.sp +.LP +This function can be called from user, interrupt, or kernel context. However, +in most cases \fBrmalloc_wait()\fR should not be called from interrupt context. +.SH SEE ALSO +.sp +.LP +\fBrmalloc\fR(9F), \fBrmallocmap\fR(9F), \fBrmfree\fR(9F), \fBrmfreemap\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/rmallocmap.9f b/usr/src/man/man9f/rmallocmap.9f new file mode 100644 index 0000000000..96e204078b --- /dev/null +++ b/usr/src/man/man9f/rmallocmap.9f @@ -0,0 +1,109 @@ +'\" 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 rmallocmap 9F "20 Nov 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +rmallocmap, rmallocmap_wait, rmfreemap \- allocate and free resource maps +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> +#include <sys/sunddi.h> + + + +\fBstruct map *\fR\fBrmallocmap\fR(\fBsize_t\fR \fImapsize\fR); +.fi + +.LP +.nf +\fBstruct map *\fR\fBrmallocmap_wait\fR(\fBsize_t\fR \fImapsize\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrmfreemap\fR(\fBstruct map *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (\fBDDI/DKI\fR). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImapsize\fR \fR +.ad +.RS 12n +.rt +Number of entries for the map. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR \fR +.ad +.RS 12n +.rt +A pointer to the map structure to be deallocated. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBrmallocmap()\fR dynamically allocates a resource map structure. The argument +\fImapsize\fR defines the total number of entries in the map. In particular, +it is the total number of allocations that can be outstanding at any one time. +.sp +.LP +\fBrmallocmap()\fR initializes the map but does not associate it with the +actual resource. In order to associate the map with the actual resource, a +call to \fBrmfree\fR(9F) is used to make the entirety of the actual resource +available for allocation, starting from the first index into the resource. +Typically, the call to \fBrmallocmap()\fR is followed by a call to +\fBrmfree\fR(9F), passing the address of the map returned from +\fBrmallocmap()\fR, the total size of the resource, and the first index into +the actual resource. +.sp +.LP +The resource map allocated by \fBrmallocmap()\fR can be used to describe an +arbitrary resource in whatever allocation units are appropriate, such as +blocks, pages, or data structures. This resource can then be managed by the +system by subsequent calls to \fBrmalloc\fR(9F), \fBrmalloc_wait\fR(9F), and +\fBrmfree\fR(9F). +.sp +.LP +\fBrmallocmap_wait()\fR is similar to \fBrmallocmap()\fR, with the exception +that it will wait for space to become available if necessary. +.sp +.LP +\fBrmfreemap()\fR deallocates a resource map structure previously allocated by +\fBrmallocmap()\fR or \fBrmallocmap_wait()\fR. The argument \fImp\fR is a +pointer to the map structure to be deallocated. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBrmallocmap()\fR and \fBrmallocmap_wait()\fR +return a pointer to the newly allocated map structure. Upon failure, +\fBrmallocmap()\fR returns a \fBNULL\fR pointer. +.SH CONTEXT +.sp +.LP +\fBrmallocmap()\fR and \fBrmfreemap()\fR can be called from user, kernel, or +interrupt context. +.sp +.LP +\fBrmallocmap_wait()\fR can only be called from user or kernel context. +.SH SEE ALSO +.sp +.LP +\fBrmalloc\fR(9F), \fBrmalloc_wait\fR(9F), \fBrmfree\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/rmfree.9f b/usr/src/man/man9f/rmfree.9f new file mode 100644 index 0000000000..df9e4d1a10 --- /dev/null +++ b/usr/src/man/man9f/rmfree.9f @@ -0,0 +1,93 @@ +'\" te +.\" Copyright (c) 2006, 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 rmfree 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +rmfree \- free space back into a resource map +.SH SYNOPSIS +.LP +.nf +#include <sys/map.h> +#include <sys/ddi.h> + + + +\fBvoid\fR \fBrmfree\fR(\fBstruct map *\fR\fImp\fR, \fBsize_t\fR \fIsize\fR, \fBulong_t\fR \fIindex\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 9n +.rt +Pointer to the map structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 9n +.rt +Number of units being freed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIindex\fR\fR +.ad +.RS 9n +.rt +Index of the first unit of the allocated resource. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBrmfree()\fR function releases space back into a resource map. It is the +opposite of \fBrmalloc\fR(9F), which allocates space that is controlled by a +resource map structure. +.sp +.LP +When releasing resources using \fBrmfree()\fR the size and index passed to +\fBrmfree()\fR must exactly match the size and index values passed to and +returned from a previous call to \fBrmalloc()\fR. Resources cannot be returned +piecemeal. +.sp +.LP +Drivers may define resource maps for resource allocation, in terms of arbitrary +units, using the \fBrmallocmap\fR(9F) function. The system maintains the +resource map structure by size and index, computed in units appropriate for the +resource. For example, units may be byte addresses, pages of memory, or blocks. +\fBrmfree()\fR frees up unallocated space for re-use. +.sp +.LP +The \fBrmfree()\fR function can also be used to initialize a resource map, in +which case the size and index should cover the entire resource area. +.SH CONTEXT +.sp +.LP +The \fBrmfree()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBrmalloc\fR(9F), \fBrmalloc_wait\fR(9F), \fBrmallocmap\fR(9F), +\fBrmfreemap\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/rmvb.9f b/usr/src/man/man9f/rmvb.9f new file mode 100644 index 0000000000..81bce80cbf --- /dev/null +++ b/usr/src/man/man9f/rmvb.9f @@ -0,0 +1,109 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rmvb 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +rmvb \- remove a message block from a message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBmblk_t *\fR\fBrmvb\fR(\fBmblk_t *\fR\fImp\fR, \fBmblk_t *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 6n +.rt +Message from which a block is to be removed. \fBmblk_t\fR is an instance of the +\fBmsgb\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +Message block to be removed. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBrmvb()\fR function removes a message block (\fIbp\fR) from a message +(\fImp\fR), and returns a pointer to the altered message. The message block is +not freed, merely removed from the message. It is the module or driver's +responsibility to free the message block. +.SH RETURN VALUES +.sp +.LP +If successful, a pointer to the message (minus the removed block) is returned. +The pointer is \fBNULL\fR if \fIbp\fR was the only block of the message before +\fBrmvb()\fR was called. If the designated message block (\fIbp\fR) does not +exist, \fB-1\fR is returned. +.SH CONTEXT +.sp +.LP +The \fBrmvb()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +This routine removes all zero-length \fBM_DATA\fR message blocks from the given +message. For each message block in the message, save the next message block +(line 10). If the current message block is of type \fBM_DATA\fR and has no data +in its buffer (line 11), then remove it from the message (line 12) and free it +(line 13). In either case, continue with the next message block in the message +(line 16). +.sp +.in +2 +.nf +1 void + 2 xxclean(mp) + 3 mblk_t *mp; + 4 { + 5 mblk_t *tmp; + 6 mblk_t *nmp; + 7 + 8 tmp = mp; + 9 while (tmp) { +10 nmp = tmp->b_cont; +11 if ((tmp->b_datap->db_type == M_DATA) && + (tmp->b_rptr == tmp->b_wptr)) { +12 (void) rmvb(mp, tmp); +13 freeb(tmp); +14 } +15 tmp = nmp; +16 } +17 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBfreeb\fR(9F), \fBmsgb\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/rmvq.9f b/usr/src/man/man9f/rmvq.9f new file mode 100644 index 0000000000..ef5f43dfda --- /dev/null +++ b/usr/src/man/man9f/rmvq.9f @@ -0,0 +1,115 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rmvq 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +rmvq \- remove a message from a queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBvoid\fR \fBrmvq\fR(\fBqueue_t *\fR\fIq\fR, \fBmblk_t *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 6n +.rt +Queue containing the message to be removed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 6n +.rt +Message to remove. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBrmvq()\fR function removes a message from a queue. A message can be +removed from anywhere on a queue. To prevent modules and drivers from having to +deal with the internals of message linkage on a queue, either \fBrmvq()\fR or +\fBgetq\fR(9F) should be used to remove a message from a queue. +.SH CONTEXT +.sp +.LP +The \fBrmvq()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +This code fragment illustrates how one may flush one type of message from a +queue. In this case, only \fBM_PROTO T_DATA_IND\fR messages are flushed. For +each message on the queue, if it is an \fBM_PROTO\fR message (line 8) of type +\fBT_DATA_IND\fR (line 10), save a pointer to the next message (line 11), +remove the \fBT_DATA_IND\fR message (line 12) and free it (line 13). Continue +with the next message in the list (line 19). +.sp +.in +2 +.nf +1 mblk_t *mp, *nmp; +2 queue_t *q; +3 union T_primitives *tp; +4 +5 /* Insert code here to protect queue and message block */ +6 mp = q->q_first; +7 while (mp) { +8 if (mp->b_datap->db_type == M_PROTO) { +9 tp = (union T_primitives *)mp->b_rptr; +10 if (tp->type == T_DATA_IND) { +11 nmp = mp->b_next; +12 rmvq(q, mp); +13 freemsg(mp); +14 mp = nmp; +15 } else { +16 mp = mp->b_next; +17 } +18 } else { +19 mp = mp->b_next; +20 } +21 } +22 /* End of region that must be protected */ +.fi +.in -2 + +.sp +.LP +When using \fBrmvq()\fR, you must ensure that the queue and the message block +is not modified by another thread at the same time. You can achieve this either +by using STREAMS functions or by implementing your own locking. +.SH SEE ALSO +.sp +.LP +\fBfreemsg\fR(9F), \fBgetq\fR(9F), \fBinsq\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH WARNINGS +.sp +.LP +Make sure that the message \fImp\fR is linked onto \fIq\fR to avoid a possible +system panic. diff --git a/usr/src/man/man9f/rwlock.9f b/usr/src/man/man9f/rwlock.9f new file mode 100644 index 0000000000..64bfeed4f4 --- /dev/null +++ b/usr/src/man/man9f/rwlock.9f @@ -0,0 +1,264 @@ +'\" te +.\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH rwlock 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +rwlock, rw_init, rw_destroy, rw_enter, rw_exit, rw_tryenter, rw_downgrade, +rw_tryupgrade, rw_read_locked \- readers/writer lock functions +.SH SYNOPSIS +.LP +.nf +#include <sys/ksynch.h> + + + +\fBvoid\fR \fBrw_init\fR(\fBkrwlock_t *\fR\fIrwlp\fR, \fBchar *\fR\fIname\fR, \fBkrw_type_t\fR \fItype\fR, \fBvoid *\fR\fIarg\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrw_destroy\fR(\fBkrwlock_t *\fR\fIrwlp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrw_enter\fR(\fBkrwlock_t *\fR\fIrwlp\fR, \fBkrw_t\fR \fIenter_type\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrw_exit\fR(\fBkrwlock_t *\fR\fIrwlp\fR); +.fi + +.LP +.nf +\fBint\fR \fBrw_tryenter\fR(\fBkrwlock_t *\fR\fIrwlp\fR, \fBkrw_t\fR \fIenter_type\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBrw_downgrade\fR(\fBkrwlock_t *\fR\fIrwlp\fR); +.fi + +.LP +.nf +\fBint\fR \fBrw_tryupgrade\fR(\fBkrwlock_t *\fR\fIrwlp\fR); +.fi + +.LP +.nf +\fBint\fR \fBrw_read_locked\fR(\fBkrwlock_t *\fR\fIrwlp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIrwlp\fR\fR +.ad +.RS 14n +.rt +Pointer to a \fBkrwlock_t\fR readers/writer lock. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 14n +.rt +Descriptive string. This is obsolete and should be \fBNULL\fR. (Non-null +strings are legal, but they're a waste of kernel memory.) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 14n +.rt +Type of readers/writer lock. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 14n +.rt +Type-specific argument for initialization function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIenter_type\fR\fR +.ad +.RS 14n +.rt +One of the values \fBRW_READER\fR or \fBRW_WRITER\fR, indicating whether the +lock is to be acquired non-exclusively (\fBRW_READER\fR) or exclusively +(\fBRW_WRITER\fR). +.RE + +.SH DESCRIPTION +.sp +.LP +A multiple-readers, single-writer lock is represented by the \fBkrwlock_t\fR +data type. This type of lock will allow many threads to have simultaneous +read-only access to an object. Only one thread may have write access at any one +time. An object which is searched more frequently than it is changed is a good +candidate for a readers/writer lock. +.sp +.LP +Readers/writer locks are slightly more expensive than mutex locks, and the +advantage of multiple read access may not occur if the lock will only be held +for a short time. +.sp +.LP +The \fBrw_init()\fR function initializes a readers/writer lock. It is an error +to initialize a lock more than once. The \fItype\fR argument should be set to +\fBRW_DRIVER\fR. If the lock is used by the interrupt handler, the +type-specific argument, \fIarg\fR, should be the interrupt priority returned +from \fBddi_intr_get_pri\fR(9F) or \fBddi_intr_get_softint_pri\fR(9F). Note +that arg should be the value of the interrupt priority cast by calling the +\fBDDI_INTR_PRI\fR macro. If the lock is not used by any interrupt handler, the +argument should be \fINULL.\fR +.sp +.LP +The \fBrw_destroy()\fR function releases any resources that might have been +allocated by \fBrw_init()\fR. It should be called before freeing the memory +containing the lock. The lock must not be held by any thread when it is +destroyed. +.sp +.LP +The \fBrw_enter()\fR function acquires the lock, and blocks if necessary. If +\fIenter_type\fR is \fBRW_READER\fR, the caller blocks if there is a writer or +a thread attempting to enter for writing. If \fIenter_type\fR is +\fBRW_WRITER\fR, the caller blocks if any thread holds the lock. +.sp +.LP +NOTE: It is a programming error for any thread to acquire an rwlock it already +holds, even as a reader. Doing so can deadlock the system: if thread R acquires +the lock as a reader, then thread W tries to acquire the lock as a writer, W +will set write-wanted and block. When R tries to get its second read hold on +the lock, it will honor the write-wanted bit and block waiting for W; but W +cannot run until R drops the lock. Thus threads R and W deadlock. +.sp +.LP +The \fBrw_exit()\fR function releases the lock and may wake up one or more +threads waiting on the lock. +.sp +.LP +The \fBrw_tryenter()\fR function attempts to enter the lock, like +\fBrw_enter()\fR, but never blocks. It returns a non-zero value if the lock was +successfully entered, and zero otherwise. +.sp +.LP +A thread which holds the lock exclusively (entered with \fBRW_WRITER\fR), may +call \fBrw_downgrade()\fR to convert to holding the lock non-exclusively (as if +entered with \fBRW_READER\fR). One or more waiting readers may be unblocked. +.sp +.LP +The \fBrw_tryupgrade()\fR function can be called by a thread which holds the +lock for reading to attempt to convert to holding it for writing. This upgrade +can only succeed if no other thread is holding the lock and no other thread is +blocked waiting to acquire the lock for writing. +.sp +.LP +The \fBrw_read_locked()\fR function returns non-zero if the calling thread +holds the lock for read, and zero if the caller holds the lock for write. The +caller must hold the lock. The system may panic if \fBrw_read_locked()\fR is +called for a lock that isn't held by the caller. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 12n +.rt +\fBrw_tryenter()\fR could not obtain the lock without blocking. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 12n +.rt +\fBrw_tryupgrade()\fR was unable to perform the upgrade because of other +threads holding or waiting to hold the lock. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 12n +.rt +\fBrw_read_locked()\fR returns \fB0\fR if the lock is held by the caller for +write. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnon-zero\fR\fR +.ad +.RS 12n +.rt +from \fBrw_read_locked()\fR if the lock is held by the caller for read. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBnon-zero\fR\fR +.ad +.RS 12n +.rt +successful return from \fBrw_tryenter()\fR or \fBrw_tryupgrade()\fR. +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context, except +for \fBrw_init()\fR and \fBrw_destroy()\fR, which can be called from user +context only. +.SH SEE ALSO +.sp +.LP +\fBcondvar\fR(9F), \fBddi_intr_alloc\fR(9F), \fBddi_intr_add_handler\fR(9F), +\fBddi_intr_get_pri\fR(9F), \fBddi_intr_get_softint_pri\fR(9F), +\fBmutex\fR(9F), \fBsemaphore\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Compiling with \fB_LOCKTEST\fR or \fB_MPSTATS\fR defined no longer has any +effect. To gather lock statistics, see \fBlockstat\fR(1M). diff --git a/usr/src/man/man9f/scsi_abort.9f b/usr/src/man/man9f/scsi_abort.9f new file mode 100644 index 0000000000..ea73d7b063 --- /dev/null +++ b/usr/src/man/man9f/scsi_abort.9f @@ -0,0 +1,103 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_abort 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_abort \- abort a SCSI command +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint\fR\fBscsi_abort\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBstruct scsi_pkt *\fR\fIpkt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBscsi_address\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_abort()\fR function terminates a command that has been transported +to the host adapter driver. A \fINULL\fR \fIpkt\fR causes all outstanding +packets to be aborted. On a successful abort, the \fBpkt_reason\fR is set to +\fBCMD_ABORTED\fR and \fBpkt_statistics\fR is \fBOR\fR'ed with +\fBSTAT_ABORTED\fR. +.SH RETURN VALUES +.sp +.LP +The \fBscsi_abort()\fR function returns: +.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 CONTEXT +.sp +.LP +The \fBscsi_abort()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRTerminating a command. +.sp +.in +2 +.nf +\fBif (scsi_abort(&devp->sd_address, pkt) == 0) { + (void) scsi_reset(&devp->sd_address, RESET_ALL); +}\fR +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBtran_abort\fR(9E), \fBscsi_reset\fR(9F), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_alloc_consistent_buf.9f b/usr/src/man/man9f/scsi_alloc_consistent_buf.9f new file mode 100644 index 0000000000..18bfc97aa1 --- /dev/null +++ b/usr/src/man/man9f/scsi_alloc_consistent_buf.9f @@ -0,0 +1,207 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_alloc_consistent_buf 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_alloc_consistent_buf \- allocate an I/O buffer for SCSI DMA +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBstruct buf *\fR\fBscsi_alloc_consistent_buf\fR(\fBstructscsi_address*\fR\fIap\fR, + \fBstruct buf *\fR\fIbp\fR, \fBsize_t\fR \fIdatalen\fR, \fBuint_t\fR \fIbflags\fR, + \fBint (*\fR\fIcallback\fR)(caddr_t), \fBcaddr_t\fR \fIarg\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR\fR +.ad +.RS 12n +.rt +Pointer to the \fBscsi_address\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 12n +.rt +Pointer to the \fBbuf\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdatalen\fR\fR +.ad +.RS 12n +.rt +Number of bytes for the data buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbflags\fR\fR +.ad +.RS 12n +.rt +Flags setting for the allocated buffer header. This should either be +\fBB_READ\fR or \fBB_WRITE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 12n +.rt +A pointer to a callback function, \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 12n +.rt +The callback function argument. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_alloc_consistent_buf()\fR function returns allocates a buffer +header and the associated data buffer for direct memory access (DMA) transfer. +This buffer is allocated from the \fBiobp\fR space, which is considered +consistent memory. For more details, see \fBddi_dma_mem_alloc\fR(9F) and +\fBddi_dma_sync\fR(9F). +.sp +.LP +For buffers allocated via \fBscsi_alloc_consistent_buf()\fR, and marked with +the \fBPKT_CONSISTENT\fR flag via \fBscsi_init_pkt\fR(9F), the HBA driver must +ensure that the data transfer for the command is correctly synchronized before +the target driver's command completion callback is performed. +.sp +.LP +If \fIbp\fR is \fINULL\fR, a new buffer header will be allocated using +\fBgetrbuf\fR(9F). In addition, if \fIdatalen\fR is non-zero, a new buffer will +be allocated using \fBddi_dma_mem_alloc\fR(9F). +.sp +.LP +\fIcallback\fR indicates what the allocator routines should do when direct +memory access \fB(DMA)\fR resources are not available; the valid values are: +.sp +.ne 2 +.mk +.na +\fB\fBNULL_FUNC\fR\fR +.ad +.RS 16n +.rt +Do not wait for resources. Return a \fINULL\fR pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSLEEP_FUNC\fR\fR +.ad +.RS 16n +.rt +Wait indefinitely for resources. +.RE + +.sp +.ne 2 +.mk +.na +\fBOther Values\fR +.ad +.RS 16n +.rt +\fIcallback\fR points to a function that is called when resources may become +available. \fIcallback\fR must return either \fB0\fR (indicating that it +attempted to allocate resources but failed to do so), in which case it is put +back on a list to be called again later, or \fB1\fR indicating either success +in allocating resources or indicating that it no longer cares for a retry. The +last argument \fIarg\fR is supplied to the \fIcallback\fR function when it is +invoked. +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBscsi_alloc_consistent_buf()\fR function returns a pointer to a +\fBbuf\fR(9S) structure on success. It returns \fBNULL\fR if resources are not +available even if \fIwaitfunc\fR was not \fBSLEEP_FUNC\fR. +.SH CONTEXT +.sp +.LP +If \fIcallback\fR is \fBSLEEP_FUNC\fR, then this routine may be called only +from user-level code. Otherwise, it may be called fromuser, interrupt, or +kernel context. The \fIcallback\fR function may not block or call routines that +block. +.SH EXAMPLES +.LP +\fBExample 1 \fRAllocate a request sense packet with consistent DMA resources +attached. +.sp +.in +2 +.nf + bp = scsi_alloc_consistent_buf(&devp->sd_address, NULL, + SENSE_LENGTH, B_READ, SLEEP_FUNC, NULL); + rqpkt = scsi_init_pkt(&devp->sd_address, + NULL, bp, CDB_GROUP0, 1, 0, + PKT_CONSISTENT, SLEEP_FUNC, NULL); +.fi +.in -2 + +.LP +\fBExample 2 \fRAllocate an inquiry packet with consistent DMA resources +attached. +.sp +.in +2 +.nf + bp = scsi_alloc_consistent_buf(&devp->sd_address, NULL, + SUN_INQSIZE, B_READ, canwait, NULL); + if (bp) { + pkt = scsi_init_pkt(&devp->sd_address, NULL, bp, + CDB_GROUP0, 1, PP_LEN, PKT_CONSISTENT, + canwait, NULL); + } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBddi_dma_mem_alloc\fR(9F), \fBddi_dma_sync\fR(9F), \fBgetrbuf\fR(9F), +\fBscsi_destroy_pkt\fR(9F), \fBscsi_init_pkt\fR(9F), +\fBscsi_free_consistent_buf\fR(9F), \fBbuf\fR(9S), \fBscsi_address\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_cname.9f b/usr/src/man/man9f/scsi_cname.9f new file mode 100644 index 0000000000..c2fcef31be --- /dev/null +++ b/usr/src/man/man9f/scsi_cname.9f @@ -0,0 +1,172 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_cname 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_cname, scsi_dname, scsi_mname, scsi_rname, scsi_sname \- decode a SCSI +name +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBchar *\fR\fBscsi_cname\fR(\fBuchar_t\fR \fIcmd\fR, \fBchar **\fR\fIcmdvec\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBscsi_dname\fR(\fBint\fR \fIdtype\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBscsi_mname\fR(\fBuchar_t\fR \fImsg\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBscsi_rname\fR(\fBuchar_t\fR \fIreason\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBscsi_sname\fR(\fBuchar_t\fR \fIsense_key\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcmd\fR\fR +.ad +.RS 13n +.rt +A \fBSCSI\fR command value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmdvec\fR\fR +.ad +.RS 13n +.rt +Pointer to an array of command strings. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdtype\fR\fR +.ad +.RS 13n +.rt +Device type. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImsg\fR\fR +.ad +.RS 13n +.rt +A message value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreason\fR\fR +.ad +.RS 13n +.rt +A packet reason value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsense_key\fR\fR +.ad +.RS 13n +.rt +A \fBSCSI\fR sense key value. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_cname()\fR function decodes \fBSCSI\fR commands. \fIcmdvec\fR is a +pointer to an array of strings. The first byte of the string is the command +value, and the remainder is the name of the command. +.sp +.LP +The \fBscsi_dname()\fR function decodes the peripheral device type (for +example, direct access or sequential access) in the inquiry data. +.sp +.LP +The \fBscsi_mname()\fR function decodes \fBSCSI \fRmessages. +.sp +.LP +The \fBscsi_rname()\fR function decodes packet completion reasons. +.sp +.LP +The \fBscsi_sname()\fR function decodes \fBSCSI\fR sense keys. +.SH RETURN VALUES +.sp +.LP +These functions return a pointer to a string. If an argument is invalid, they +return a string to that effect. +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRDecoding SCSI tape commands. +.sp +.LP +The \fBscsi_cname()\fR function decodes \fBSCSI \fRtape commands as follows: + +.sp +.in +2 +.nf +static char *st_cmds[] = { + "\e000test unit ready", + "\e001rewind", + "\e003request sense", + "\e010read", + "\e012write", + "\e020write file mark", + "\e021space", + "\e022inquiry", + "\e025mode select", + "\e031erase tape", + "\e032mode sense", + "\e033load tape", + NULL + }; + .. + cmn_err(CE_CONT, "st: cmd=%s", scsi_cname(cmd, st_cmds)); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_destroy_pkt.9f b/usr/src/man/man9f/scsi_destroy_pkt.9f new file mode 100644 index 0000000000..73f24ad2e1 --- /dev/null +++ b/usr/src/man/man9f/scsi_destroy_pkt.9f @@ -0,0 +1,62 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_destroy_pkt 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_destroy_pkt \- free an allocated SCSI packet and its DMA resource +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBvoid\fR \fBscsi_destroy_pkt\fR(\fBstruct scsi_pkt *\fR\fIpktp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpktp\fR\fR +.ad +.RS 8n +.rt +Pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_destroy_pkt()\fR function releases all necessary resources, +typically at the end of an I/O transfer. The data is synchronized to memory, +then the \fBDMA\fR resources are deallocated and \fIpktp\fR is freed. +.SH CONTEXT +.sp +.LP +The \fBscsi_destroy_pkt()\fR function may be called from user, interrupt, or +kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRReleasing resources +.sp +.in +2 +.nf +scsi_destroy_pkt(un->un_rqs); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBtran_destroy_pkt\fR(9E), \fBscsi_init_pkt\fR(9F), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_dmaget.9f b/usr/src/man/man9f/scsi_dmaget.9f new file mode 100644 index 0000000000..6b313a8739 --- /dev/null +++ b/usr/src/man/man9f/scsi_dmaget.9f @@ -0,0 +1,171 @@ +'\" te +.\" Copyright (c) 2006, 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 scsi_dmaget 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_dmaget, scsi_dmafree \- SCSI dma utility routines +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBstruct scsi_pkt *\fR\fBscsi_dmaget\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR, + \fBopaque_t\fR \fIdmatoken\fR, \fBint\fR\fB(*\fRcallback\fB)(void)\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBscsi_dmafree\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +These interfaces are obsolete. Use \fBscsi_init_pkt\fR(9F) instead of +\fBscsi_dmaget()\fR. Use \fBscsi_destroy_pkt\fR(9F) instead of +\fBscsi_dmafree()\fR. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR\fR +.ad +.RS 12n +.rt +A pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdmatoken\fR\fR +.ad +.RS 12n +.rt +Pointer to an implementation dependent object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 12n +.rt +Pointer to a callback function, or \fBNULL_FUNC\fR or \fBSLEEP_FUNC.\fR +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_dmaget()\fR function allocates \fBDMA\fR resources for an already +allocated \fBSCSI\fR packet. \fIpkt\fR is a pointer to the previously allocated +\fBSCSI\fR packet (see \fBscsi_pktalloc\fR(9F)). +.sp +.LP +The \fIdmatoken\fR parameter is a pointer to an implementation dependent object +which defines the length, direction, and address of the data transfer +associated with this \fBSCSI \fRpacket (command). The \fIdmatoken\fR must be a +pointer to a \fBbuf\fR(9S) structure. If \fIdmatoken\fR is \fINULL\fR, no +resources are allocated. +.sp +.LP +The \fIcallback\fR parameter indicates what \fBscsi_dmaget()\fR should do when +resources are not available: +.sp +.ne 2 +.mk +.na +\fB\fBNULL_FUNC\fR\fR +.ad +.RS 16n +.rt +Do not wait for resources. Return a \fINULL\fR pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSLEEP_FUNC\fR\fR +.ad +.RS 16n +.rt +Wait indefinitely for resources. +.RE + +.sp +.ne 2 +.mk +.na +\fBOther Values\fR +.ad +.RS 16n +.rt +\fIcallback\fR points to a function which is called when resources may have +become available. \fIcallback\fR must return either \fB0\fR (indicating that it +attempted to allocate resources but failed to do so again), in which case it is +put back on a list to be called again later, or \fB1\fR indicating either +success in allocating resources or indicating that it no longer cares for a +retry. +.RE + +.sp +.LP +The \fBscsi_dmafree()\fR function frees the \fBDMA\fR resources associated with +the \fBSCSI\fR packet. The packet itself remains allocated. +.SH RETURN VALUES +.sp +.LP +The \fBscsi_dmaget()\fR function returns a pointer to a \fBscsi_pkt\fR on +success. It returns \fBNULL\fR if resources are not available. +.SH CONTEXT +.sp +.LP +If \fIcallback\fR is \fBSLEEP_FUNC\fR, then this routine may only be called +from user or kernel context. Otherwise, it may be called from user, kernel, or +interrupt context. The \fIcallback\fR function may not block or call routines +that block. +.sp +.LP +The \fBscsi_dmafree()\fR function can be called from user, interrupt, or kernel +context. +.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 +\fBattributes\fR(5), \fBscsi_pktalloc\fR(9F), \fBscsi_pktfree\fR(9F), +\fBscsi_resalloc\fR(9F), \fBscsi_resfree\fR(9F), \fBbuf\fR(9S), +\fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The \fBscsi_dmaget()\fR and \fBscsi_dmafree()\fR functions are obsolete and +will be discontinued in a future release. These functions have been replaced +by, respectively, \fBscsi_init_pkt\fR(9F) and \fBscsi_destroy_pkt\fR(9F). diff --git a/usr/src/man/man9f/scsi_errmsg.9f b/usr/src/man/man9f/scsi_errmsg.9f new file mode 100644 index 0000000000..3dd95aee07 --- /dev/null +++ b/usr/src/man/man9f/scsi_errmsg.9f @@ -0,0 +1,246 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_errmsg 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_errmsg \- display a SCSI request sense message +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBvoid\fR \fBscsi_errmsg\fR(\fBstruct scsi_device *\fR\fIdevp\fR, \fBstruct scsi_pkt *\fR\fIpktp\fR, + \fBchar *\fR\fIdrv_name\fR, \fBint\fR \fIseverity\fR, \fBdaddr_t\fR \fIblkno\fR, \fBdaddr_t\fR \fIerr_blkno\fR, + \fBstruct scsi_key_strings *\fR\fIcmdlist\fR, \fBstruct scsi_extended_sense *\fR\fIsensep\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdevp\fR\fR +.ad +.RS 13n +.rt +Pointer to the \fBscsi_device\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpktp\fR\fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdrv_name\fR\fR +.ad +.RS 13n +.rt +String used by \fBscsi_log\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIseverity\fR\fR +.ad +.RS 13n +.rt +Error severity level, maps to severity strings below. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIblkno\fR\fR +.ad +.RS 13n +.rt +Requested block number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerr_blkno\fR\fR +.ad +.RS 13n +.rt +Error block number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmdlist\fR\fR +.ad +.RS 13n +.rt +An array of \fBSCSI \fRcommand description strings. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsensep\fR\fR +.ad +.RS 13n +.rt +A pointer to a \fBscsi_extended_sense\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_errmsg()\fR function interprets the request sense information in +the \fIsensep\fR pointer and generates a standard message that is displayed +using \fBscsi_log\fR(9F). The first line of the message is always a +\fBCE_WARN\fR, with the continuation lines being \fBCE_CONT\fR. \fIsensep\fR +may be \fINULL\fR, in which case no sense key or vendor information is +displayed. +.sp +.LP +The driver should make the determination as to when to call this function based +on the severity of the failure and the severity level that the driver wants to +report. +.sp +.LP +The \fBscsi_device\fR(9S) structure denoted by \fIdevp\fR supplies the +identification of the device that requested the display. \fIseverity\fR selects +which string is used in the "Error Level:" reporting, according to the +following table: +.sp + +.sp +.TS +tab(); +cw(2.68i) cw(2.76i) cw(.06i) +lw(2.68i) lw(2.76i) lw(.06i) +. +\fBSeverity Value:\fR\fBString:\fR +\fBSCSI_ERR_ALL\fR\fBAll\fR +\fBSCSI_ERR_UNKNOWN\fR\fBUnknown\fR +\fBSCSI_ERR_INFO\fR\fBInformational\fR +\fBSCSI_ERR_RECOVERE\fR\fBRecovered\fR +\fBSCSI_ERR_RETRYABL\fR\fBRetryable\fR +\fBSCSI_ERR_FATAL\fR\fBFatal\fR +.TE + +.sp +.LP +\fIblkno\fR is the block number of the original request that generated the +error. \fIerr_blkno\fR is the block number where the error occurred. +\fIcmdlist\fR is a mapping table for translating the \fBSCSI \fRcommand code in +\fIpktp\fR to the actual command string. +.sp +.LP +The \fIcmdlist\fR is described in the structure below: +.sp +.in +2 +.nf +struct scsi_key_strings { + int key; + char *message; +}; +.fi +.in -2 + +.sp +.LP +For a basic \fBSCSI\fR disk, the following list is appropriate: +.sp +.in +2 +.nf +static struct scsi_key_strings scsi_cmds[] = { + 0x00, "test unit ready", + 0x01, "rezero/rewind", + 0x03, "request sense", + 0x04, "format", + 0x07, "reassign", + 0x08, "read", + 0x0a, "write", + 0x0b, "seek", + 0x12, "inquiry", + 0x15, "mode select", + 0x16, "reserve", + 0x17, "release", + 0x18, "copy", + 0x1a, "mode sense", + 0x1b, "start/stop", + 0x1e, "door lock", + 0x28, "read(10)", + 0x2a, "write(10)", + 0x2f, "verify", + 0x37, "read defect data", + 0x3b, "write buffer", + -1, NULL +}; +.fi +.in -2 + +.SH CONTEXT +.sp +.LP +The \fBscsi_errmsg()\fR function may be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRGenerating error information. +.sp +.LP +This entry: + +.sp +.in +2 +.nf +scsi_errmsg(devp, pkt, "sd", SCSI_ERR_INFO, bp->b_blkno, + err_blkno, sd_cmds, rqsense); +.fi +.in -2 + +.sp +.LP +Generates: + +.sp +.in +2 +.nf +\fBWARNING: /sbus@1,f8000000/esp@0,800000/sd@1,0 (sd1): +Error for Command: read Error Level: Informational +Requested Block: 23936 Error Block: 23936 +Vendor: QUANTUM Serial Number: 123456 +Sense Key: Unit Attention +ASC: 0x29 (reset), ASCQ: 0x0, FRU: 0x0\fR +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBcmn_err\fR(9F), \fBscsi_log\fR(9F), \fBscsi_device\fR(9S), +\fBscsi_extended_sense\fR(9S), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_ext_sense_fields.9f b/usr/src/man/man9f/scsi_ext_sense_fields.9f new file mode 100644 index 0000000000..3578929e64 --- /dev/null +++ b/usr/src/man/man9f/scsi_ext_sense_fields.9f @@ -0,0 +1,188 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_ext_sense_fields 9F "29 Jun 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_ext_sense_fields, scsi_sense_info_uint64, scsi_sense_cmdspecific_uint64 \- +retrieve fields from SCSI sense data +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBvoid\fR \fBscsi_ext_sense_fields\fR(\fBuint8_t *\fR\fIsense_buffer\fR, \fBint *\fR\fIsense_buf_len\fR, + \fBuint8_t **\fR\fIinformation\fR, \fBuint8_t **\fR\fIcmd_spec_info\fR, \fBuint8_t **\fR\fIfru_code\fR, + \fBuint8_t **\fR\fIsk_specific\fR, \fBuint8_t **\fR\fIstream_flags\fR); +.fi + +.LP +.nf +\fBboolean_t\fR \fBscsi_sense_info_uint64\fR(\fBuint8_t *\fR\fIsense_buffer\fR, \fBint\fR \fIsense_buf_len\fR, + \fBuint64_t *\fR\fIinformation\fR); +.fi + +.LP +.nf +\fBboolean_t\fR \fBscsi_sense_cmdspecific_uint64\fR(\fBuint8_t *\fR\fIsense_buffer\fR, + \fBint\fR \fIsense_buf_len\fR, \fBuint64_t *\fR\fIcmd_spec_info\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsense_buffer\fR\fR +.ad +.RS 17n +.rt +Pointer to a buffer containing \fBSCSI\fR sense data. The sense data is +expected in wire format starting at the response code. It can be in either a +fixed or descriptor format. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinformation\fR\fR +.ad +.RS 17n +.rt +For \fBscsi_ext_sense_fields()\fR, this is a call-by-reference pointer to +\fBuint8_t\fR. A pointer to the \fBINFORMATION\fR field in the sense data may +be returned in this parameter. +.sp +The \fBscsi_sense_info_uint64()\fR function requires a pointer to +\fBuint64_t\fR. The data in the information field is returned as a 64 bit +integer. If the sense data information field is 32 bits, fixed format, the most +significant 32-bits are \fB\fR0. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmd_spec_info\fR\fR +.ad +.RS 17n +.rt +For \fBscsi_ext_sense_fields()\fR, this is a call-by-reference pointer to +\fBuint8_t\fR. A pointer to the \fBCOMMAND_SPECIFIC INFORMATION\fR field in the +sense data can be returned in this parameter. +.sp +The \fBscsi_sense_cmdspecific_uint64()\fR function requires a pointer to +\fBuint64_t\fR. The data in the command specific information field is returned +as a 64 bit integer. If the sense data command specific information field is 32 +bits, fixed format, the most significant 32-bits are \fB0\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfru_code\fR\fR +.ad +.RS 17n +.rt +Call-by-reference pointer to \fBuint8_t\fR. A pointer to the \fBFIELD +REPLACEABLE UNIT CODE\fR field in the sense data can be returned in this +parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsk_specific\fR\fR +.ad +.RS 17n +.rt +Call-by-reference pointer to \fBuint8_t\fR. A pointer to the \fBSENSE KEY +SPECIFIC\fR field in the sense data can be returned in this parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstream_flags\fR\fR +.ad +.RS 17n +.rt +Call-by-reference pointer to \fBuint8_t\fR. A pointer to the byte containing +the \fBILI\fR, \fBEOM\fR, and \fBFILEMARK\fR flags can be returned in this +parameter. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_ext_sense_fields()\fR function can be used to retrieve any of the +extended sense data fields from a sense data buffer, regardless of whether the +sense data is in fixed format or in descriptor format. +.sp +.LP +The \fIinformation\fR, \fIcmd_spec_info\fR, \fIfru_code\fR, \fIsk_specific\fR, +and \fIstream_specific\fR parameters are all call-by-reference output +parameters. Each parameter corresponds to one or more of the extended sense +data fields. Any of these parameters can be passed as \fINULL\fR if the caller +is not interested in the associated data. +.sp +.LP +If the requested data is present and valid for each output parameter, the +pointer passed in is set to point to the relevant location in the sense buffer. +If the data is not present or invalid, the pointer is set to \fINULL\fR. For +example, a caller that requests a pointer to the information field would get +\fINULL\fR when an information descriptor is not present for descriptor format +sense data or when the valid bit is not set for fixed format sense data. +.sp +.LP +The information and command specific information fields can be 4 bytes or 8 +bytes in length, depending on whether the sense data is in fixed or descriptor +format respectively. Drivers can use \fBscsi_validate_sense\fR(9F) to determine +the sense data format and, by extension, the length of the information and +command specific information fields. +.sp +.LP +A driver can determine whether integer data is included in the information or +command specific information fields based on the \fBasc\fR and \fBascq\fR sense +keys, such as the \fBLBA\fR of a failed disk request. The +\fBscsi_sense_info_uint64()\fR function retrieves the contents of the +information field as a 64 bit integer and the +\fBscsi_sense_cmdspecific_uint64()\fR retrieves the command specific +information field as a 64 bit integer. +.sp +.LP +Drivers should use \fBscsi_validate_sense\fR(9F) to ensure that the sense +buffer contains valid sense data. +.SH RETURN VALUES +.sp +.LP +The \fBscsi_sense_info_uint64()\fR function returns \fBTRUE\fR if the +information field is present and valid. Otherwise it returns \fBFALSE\fR. +.sp +.LP +The \fBscsi_sense_cmdspecific_uint64()\fR function returns \fBTRUE\fR if the +command specific information field is present and valid. Otherwise it returns +\fBFALSE\fR. +.SH CONTEXT +.sp +.LP +The \fBscsi_ext_sense_fields()\fR, \fBscsi_sense_info_uint64()\fR and +\fBscsi_sense_cmdspecific_uint64()()\fR functions can be called from user or +interrupt context. +.SH SEE ALSO +.sp +.LP +\fBscsi_find_sense_descr\fR(9F), \fBscsi_sense_asc\fR(9F), +\fBscsi_sense_ascq\fR(9F), \fBscsi_sense_key\fR(9F), +\fBscsi_validate_sense\fR(9F) diff --git a/usr/src/man/man9f/scsi_find_sense_descr.9f b/usr/src/man/man9f/scsi_find_sense_descr.9f new file mode 100644 index 0000000000..9670babe74 --- /dev/null +++ b/usr/src/man/man9f/scsi_find_sense_descr.9f @@ -0,0 +1,108 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_find_sense_descr 9F "30 Jun 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_find_sense_descr \- find descriptor in SCSI sense data +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBuint8_t *\fR\fBscsi_find_sense_descr\fR(\fBuint8_t *\fR\fIsense_buffer\fR, \fBint\fR \fIsense_buf_len\fR, + \fBint\fR \fIreq_descr_type\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsense_buffer\fR\fR +.ad +.RS 18n +.rt +Pointer to a buffer containing \fBSCSI\fR descriptor sense data. The data is +expected in wire format starting at the response code. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsense_buf_len\fR\fR +.ad +.RS 18n +.rt +Integer that contains the length of sense buffer in bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreq_descr_type\fR\fR +.ad +.RS 18n +.rt +Integer that contains the descriptor type value for the desired sense +descriptor. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_find_sense_descr()\fR function is used to obtain a pointer to a +specific descriptor type, specified by \fIreq_descr_type\fR, within a +descriptor sense buffer. Before returning the pointer, +\fBscsi_find_sense_descr()\fR verifies that the entire descriptor is present +based on the length provided in \fIsense_buf_len\fR. +.sp +.LP +Any value for \fIreq_descr_type\fR can be requested. The following descriptor +types are already defined: +.sp +.in +2 +.nf +#define DESCR_INFORMATION 0x00 +#define DESCR_COMMAND_SPECIFIC 0x01 +#define DESCR_SENSE_KEY_SPECIFIC 0x02 +#define DESCR_FRU 0x03 +#define DESCR_STREAM_COMMANDS 0x04 +#define DESCR_BLOCK_COMMANDS 0x05 +#define DESCR_OSD_OID 0x06 +#define DESCR_OSD_RESP_INTEGRITY 0x07 +#define DESCR_OSD_ATTR_ID 0x08 +.fi +.in -2 + +.sp +.LP +Drivers should use \fBscsi_validate_sense\fR(9F) to ensure that the sense +buffer contains valid descriptor sense data. +.SH RETURN VALUES +.sp +.LP +The \fBscsi_find_sense_descr()\fR function returns a pointer to a sense +descriptor of the requested type if a descriptor of that type exists. If no +such descriptor exists, \fBscsi_find_sense_descr()\fR returns \fINULL\fR. +.SH CONTEXT +.sp +.LP +The \fBscsi_find_sense_descr()\fR function can be called from user or interrupt +context. +.SH SEE ALSO +.sp +.LP +\fBscsi_ext_sense_fields\fR(9F), \fBscsi_sense_asc\fR(9F), +\fBscsi_sense_ascq\fR(9F), \fBscsi_sense_cmdspecific_uint64\fR(9F), +\fBscsi_sense_info_uint64\fR(9F), \fBscsi_sense_key\fR(9F), +\fBscsi_validate_sense\fR(9F) diff --git a/usr/src/man/man9f/scsi_free_consistent_buf.9f b/usr/src/man/man9f/scsi_free_consistent_buf.9f new file mode 100644 index 0000000000..8ab3ad0176 --- /dev/null +++ b/usr/src/man/man9f/scsi_free_consistent_buf.9f @@ -0,0 +1,63 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_free_consistent_buf 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_free_consistent_buf \- free a previously allocated SCSI DMA I/O buffer +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBvoid\fR \fBscsi_free_consistent_buf\fR(\fBstruct buf *\fR\fIbp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.RS 6n +.rt +Pointer to the \fBbuf\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_free_consistent_buf()\fR function frees a buffer header and +consistent data buffer that was previously allocated using +\fBscsi_alloc_consistent_buf\fR(9F). +.SH CONTEXT +.sp +.LP +The \fBscsi_free_consistent_buf()\fR function can be called from user, +interrupt, or kernel context. +.SH SEE ALSO +.sp +.LP +\fBfreerbuf\fR(9F), \fBscsi_alloc_consistent_buf\fR(9F), \fBbuf\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNING +.sp +.LP +The \fBscsi_free_consistent_buf()\fR function will call \fBfreerbuf\fR(9F) to +free the \fBbuf\fR(9S) that was allocated before or during the call to +\fBscsi_alloc_consistent_buf\fR(9F). +.sp +.LP +If consistent memory is bound to a \fBscsi_pkt\fR(9S), the pkt should be +destroyed before freeing the consistent memory. diff --git a/usr/src/man/man9f/scsi_get_device_type_scsi_options.9f b/usr/src/man/man9f/scsi_get_device_type_scsi_options.9f new file mode 100644 index 0000000000..d15813ed2a --- /dev/null +++ b/usr/src/man/man9f/scsi_get_device_type_scsi_options.9f @@ -0,0 +1,141 @@ +'\" 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 scsi_get_device_type_scsi_options 9F "19 Nov 2001" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_get_device_type_scsi_options \- look up per-device-type scsi-options +property +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint\fR \fBscsi_get_device_type_scsi_options\fR(\fBdev_info_t *\fR\fIdip\fR, + \fBstruct scsi_device *\fR\fIdevp\fR, \fBint\fR \fIdefault_scsi_options\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 24n +.rt +Pointer to the device info node for this HBA driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdevp\fR\fR +.ad +.RS 24n +.rt +Pointer to a \fBscsi_device\fR(9S) structure of the target. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdefault_scsi_options\fR\fR +.ad +.RS 24n +.rt +Value returned if no match is found. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_get_device_type_scsi_options()\fR function looks up the property +\fBdevice-type-scsi-options-list\fR, which can be specified in the HBA's +\fBdriver.conf\fR(4) file. This property allows specification of +\fBscsi-options\fR on a per-device-type basis. +.sp +.LP +The formal syntax is: +.sp +.in +2 +.nf +device-type-scsi-options-list = \fI<duplet>\fR [, \fI<duplet>\fR *]; +.fi +.in -2 +.sp + +.sp +.LP +where: +.sp +.in +2 +.nf +\fI<duplet>\fR := \fI<vid+pid>\fR, \fI<scsi-options-property-name>\fR +.fi +.in -2 +.sp + +.sp +.LP +and: +.sp +.in +2 +.nf +\fI<scsi-options-property-name>\fR = \fI<value>\fR; +.fi +.in -2 +.sp + +.sp +.LP +The string \fI<vid+pid>\fR is returned by the device on a SCSI inquiry command. +This string can contain any character in the range 0x20-0x7e. Characters such +as double quote (\fB"\fR) or single quote (\fB\&'\fR), which are not permitted +in property value strings, are represented by their octal equivalent (for +example, \e042 and \e047). Trailing spaces can be truncated. +.sp +.LP +For example: +.sp +.in +2 +.nf +device-type-scsi-options-list= + "SEAGATE ST32550W", "seagate-options", + "EXABYTE EXB-2501". "exabyte-options", + "IBM OEM DFHSS4S", "ibm-options"; + +seagate-options = 0x78; +exabyte-options = 0x58; +ibm-options = 0x378; +.fi +.in -2 +.sp + +.sp +.LP +The \fBscsi_get_device_type_scsi_options()\fR function searches the list of +duplets for a matching \fBINQUIRY\fR string. If a match is found, +\fBscsi_get_device_type_scsi_options()\fR returns the corresponding value. +.SH RETURN VALUES +.sp +.LP +\fBscsi_get_device_type_scsi_options()\fR returns the \fBscsi-options\fR value +found, or if no match is found the \fBdefault_scsi_options\fR value passed in. +.SH CONTEXT +.sp +.LP +This function can be called from kernel or interrupt context. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_get_device_type_string.9f b/usr/src/man/man9f/scsi_get_device_type_string.9f new file mode 100644 index 0000000000..4c0e24c91f --- /dev/null +++ b/usr/src/man/man9f/scsi_get_device_type_string.9f @@ -0,0 +1,140 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_get_device_type_string 9F "12 Jul 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_get_device_type_string \- look up per-device-type, returning matching +information string +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBchar\fR \fB*scsi_get_device_type_string\fR(\fBchar *prop_name, + dev_info_t *\fR\fIdip\fR, \fBstruct scsi_device *\fR\fIdevp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIprop_name\fR\fR +.ad +.RS 13n +.rt +Name of string array property that contains a list of paired device-type +information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 13n +.rt +Pointer to the device info node for this HBA driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdevp\fR \fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_device\fR(9S) structure of the target. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_get_device_type_string()\fR function looks up the \fIprop_name\fR +property, which can be specified in the HBA's \fBdriver.conf\fR(4)file. This +property allows specification of per-device-type information. The syntax for +\fIprop_name\fR in a \fBdriver.conf\fR(4) file is: +.sp +.LP +The formal syntax is: +.sp +.in +2 +.nf +prop_name = \fI<duplet>\fR [, \fI<duplet>\fR *]; +.fi +.in -2 +.sp + +.sp +.LP +where: +.sp +.in +2 +.nf +\fI<duplet>\fR := \fI"<vid+pid>"\fR, \fI"<information"\fR +.fi +.in -2 +.sp + +.sp +.LP +The string \fI<vid+pid>\fR is returned by the device on a SCSI inquiry command. +This string can contain any character in the range 0x20-0x7e. Characters such +as double quote (") or single quote ('), which are not permitted in property +value strings, are represented by their octal equivalent (for example, \e042 +and \e047). Trailing spaces can be truncated. +.sp +.LP +For example: +.sp +.in +2 +.nf +scsi_vhci_failover_override = + "STK FLEXLINE 400", "f_asym_lsi", + "SUN T4", "f_tpgs";; +.fi +.in -2 +.sp + +.sp +.LP +The \fBscsi_get_device_type_string\fR() function searches the list of duplets +for a matching INQUIRY string. If a match is found, +\fBscsi_get_device_type_string\fR returns a copy of the <\fIinformation\fR> +string. The meaning of the returned <\fIinformation\fR> string is determined by +the caller. +.SH RETURN VALUES +.sp +.LP +\fBscsi_get_device_type_string()\fR returns a copy of the matching +<\fIinformation\fR> string, or if no match is found, \fBNULL\fR is returned. +When a non-NULL value is returned, the caller is responsible for freeing the +<\fIinformation\fR> string via: +.sp +.in +2 +.nf +kmem_free(info, strlen(info) + 1); +.fi +.in -2 + +.SH CONTEXT +.sp +.LP +This function can be called from kernel or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBdriver.conf\fR(4) +.sp +.LP +\fIWriting Device Drivers \fR diff --git a/usr/src/man/man9f/scsi_hba_attach_setup.9f b/usr/src/man/man9f/scsi_hba_attach_setup.9f new file mode 100644 index 0000000000..4204ffa346 --- /dev/null +++ b/usr/src/man/man9f/scsi_hba_attach_setup.9f @@ -0,0 +1,357 @@ +'\" te +.\" Copyright (c) 2006 Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_hba_attach_setup 9F "30 May 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_hba_attach_setup, scsi_hba_attach, scsi_hba_detach \- SCSI HBA attach and +detach routines +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint\fR \fBscsi_hba_attach_setup\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_attr_t *\fR\fIhba_dma_attr\fR, + \fBscsi_hba_tran_t *\fR\fIhba_tran\fR, \fBint\fR \fIhba_flags\fR); +.fi + +.LP +.nf +\fBint\fR \fBscsi_hba_attach\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_dma_lim_t *\fR\fIhba_lim\fR, + \fBscsi_hba_tran_t *\fR\fIhba_tran\fR, \fBint\fR \fIhba_flags\fR, \fBvoid *\fR\fIhba_options\fR); +.fi + +.LP +.nf +\fBint\fR \fBscsi_hba_detach\fR(\fBdev_info_t *\fR\fIdip\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 16n +.rt +Pointer to the \fBdev_info_t\fR structure that refers to the instance of the +HBA device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhba_lim\fR\fR +.ad +.RS 16n +.rt +Pointer to a \fBddi_dma_lim\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhba_tran\fR\fR +.ad +.RS 16n +.rt +Pointer to a \fBscsi_hba_tran\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhba_flags\fR\fR +.ad +.RS 16n +.rt +Flag modifiers. The defined flag values are \fBSCSI_HBA_TRAN_CLONE\fR, +\fBSCSI_HBA_TRAN_SCB\fR, and \fBSCSI_HBA_TRAN_CDB\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhba_options\fR\fR +.ad +.RS 16n +.rt +Optional features provided by the HBA driver for future extensions; must be +\fINULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhba_dma_attr\fR\fR +.ad +.RS 16n +.rt +Pointer to a \fBddi_dma_attr\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_hba_attach_setup()\fR function is the recommended interface over +the \fBscsi_hba_attach()\fR function. +.SS "scsi_hba_attach_setup(\|) scsi_hba_attach(\|)" +.sp +.LP +The \fBscsi_hba_attach()\fR function registers the \fIhba_lim\fR DMA limits and +the \fIhba_tran\fR transport vectors of each instance of the HBA device defined +by \fIdip\fR. The \fBscsi_hba_attach_setup()\fR function registers the +\fIhba_dma_attr\fR DMA attributes and the \fIhba_tran\fR transport vectors of +each instance of the HBA device defined by \fIdip\fR. The HBA driver can pass +different DMA limits or DMA attributes and the transport vectors for each +instance of the device to support any constraints imposed by the HBA itself. +.sp +.LP +The \fBscsi_hba_attach()\fR and \fBscsi_hba_attach_setup()\fR functions use the +\fBdev_bus_ops\fR field in the \fBdev_ops\fR(9S) structure. The HBA driver +should initialize this field to \fINULL\fR before calling +\fBscsi_hba_attach()\fR or \fBscsi_hba_attach_setup()\fR. +.sp +.LP +If \fBSCSI_HBA_TRAN_CLONE\fR is requested in \fIhba_flags\fR, the +\fBhba_tran\fR structure is cloned once for each target that is attached to the +HBA. The structure is cloned before the \fBtran_tgt_init\fR(9E) entry point is +called to initialize a target. At all subsequent HBA entry points, including +\fBtran_tgt_init\fR(9E), the \fBscsi_hba_tran_t\fR structure passed as an +argument or found in a \fBscsi_address\fR structure is the cloned +\fBscsi_hba_tran_t\fR structure,which allows the HBA to use the +\fBtran_tgt_private\fR field in the \fBscsi_hba_tran_t\fR structure to point to +per-target data. The HBA should free only the same \fBscsi_hba_tran_t\fR +structure allocated when the HBA detaches. All cloned \fBscsi_hba_tran_t\fR +structures that are allocated by the system are freed by the system. +.sp +.LP +The flags \fBSCSI_HBA_TRAN_CDB\fR and \fBSCSI_HBA_TRAN_SCB\fR are only valid +when \fBtran_setup_pkt()\fR is used. See \fBtran_setup_pkt\fR(9E) for +information on using these flags. +.sp +.LP +The \fBscsi_hba_attach()\fR and \fBscsi_hba_attach_setup()\fR functions attach +a number of integer-valued properties to \fIdip\fR, unless properties of the +same name are already attached to the node. An HBA driver should retrieve these +configuration parameters via \fBddi_prop_get_int\fR(9F), and respect any +settings for features provided the HBA. +.sp +.ne 2 +.mk +.na +\fB\fBscsi-options\fR\fR +.ad +.RS 26n +.rt +\fBOptional\fR \fBSCSI\fR \fBconfiguration bits\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_OPTIONS_DR\fR\fR +.ad +.RS 26n +.rt +If not set, the HBA should not grant Disconnect privileges to target devices. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_OPTIONS_TAG\fR\fR +.ad +.RS 26n +.rt +If not set, the HBA should not operate in Command Tagged Queueing mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_OPTIONS_PARITY\fR\fR +.ad +.RS 26n +.rt +If not set, the HBA should not operate in parity mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_OPTIONS_QAS\fR\fR +.ad +.RS 26n +.rt +If not set, the HBA should not make use of the Quick Arbitration Select +feature. Consult your Sun hardware documentation to determine whether your +machine supports QAS. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_OPTIONS_FAST\fR\fR +.ad +.RS 26n +.rt +If not set, the HBA should not operate the bus in FAST SCSI mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_OPTIONS_FAST20\fR\fR +.ad +.RS 26n +.rt +If not set, the HBA should not operate the bus in FAST20 SCSI mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_OPTIONS_FAST40\fR\fR +.ad +.RS 26n +.rt +If not set, the HBA should not operate the bus in FAST40 SCSI mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_OPTIONS_FAST80\fR\fR +.ad +.RS 26n +.rt +If not set, the HBA should not operate the bus in FAST80 SCSI mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_OPTIONS_FAST160\fR\fR +.ad +.RS 26n +.rt +If not set, the HBA should not operate the bus in FAST160 SCSI mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_OPTIONS_FAST320\fR\fR +.ad +.RS 26n +.rt +If not set, the HBA should not operate the bus in FAST320 SCSI mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_OPTIONS_WIDE\fR\fR +.ad +.RS 26n +.rt +If not set, the HBA should not operate the bus in WIDE SCSI mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_OPTIONS_SYNC\fR\fR +.ad +.RS 26n +.rt +If not set, the HBA should not operate the bus in synchronous transfer mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBscsi-reset-delay\fR\fR +.ad +.RS 26n +.rt +SCSI bus or device reset recovery time, in milliseconds. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBscsi-selection-timeout\fR\fR +.ad +.RS 26n +.rt +Default SCSI selection phase timeout value, in milliseconds. Please refer to +individual HBA man pages for any HBA-specific information +.RE + +.SS "scsi_hba_detach(\|)" +.sp +.LP +The \fBscsi_hba_detach()\fR function removes the reference to the DMA limits or +attributes structure and the transport vector for the given instance of an HBA +driver. +.SH RETURN VALUES +.sp +.LP +The \fBscsi_hba_attach()\fR, \fBscsi_hba_attach_setup()\fR, and +\fBscsi_hba_detach()\fR functions return \fBDDI_SUCCESS\fR if the function call +succeeds, and return \fBDDI_FAILURE\fR on failure. +.SH CONTEXT +.sp +.LP +The \fBscsi_hba_attach()\fR and \fBscsi_hba_attach_setup()\fR functions should +be called from \fBattach\fR(9E). The \fBscsi_hba_detach()\fR function should be +called from \fBdetach\fR(9E). +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBdetach\fR(9E), \fBtran_setup_pkt\fR(9E), +\fBtran_tgt_init\fR(9E), \fBddi_prop_get_int\fR(9F), \fBddi_dma_attr\fR(9S), +\fBddi_dma_lim\fR(9S), \fBdev_ops\fR(9S), \fBscsi_address\fR(9S), +\fBscsi_hba_tran\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +It is the HBA driver's responsibility to ensure that no more transport requests +will be taken on behalf of any SCSI target device driver after +\fBscsi_hba_detach()\fR is called. +.sp +.LP +The \fBscsi_hba_attach()\fR function is obsolete and will be discontinued in a +future release. This function is replaced by \fBscsi_hba_attach_setup()\fR. diff --git a/usr/src/man/man9f/scsi_hba_init.9f b/usr/src/man/man9f/scsi_hba_init.9f new file mode 100644 index 0000000000..1ba98d5927 --- /dev/null +++ b/usr/src/man/man9f/scsi_hba_init.9f @@ -0,0 +1,85 @@ +'\" 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 scsi_hba_init 9F "1 Nov 1993" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_hba_init, scsi_hba_fini \- SCSI Host Bus Adapter system initialization and +completion routines +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint\fR \fBscsi_hba_init\fR(\fBstruct modlinkage *\fR\fImodlp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBscsi_hba_fini\fR(\fBstruct modlinkage *\fR\fImodlp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImodlp\fR \fR +.ad +.RS 10n +.rt +Pointer to the Host Bus Adapters module linkage structure. +.RE + +.SH DESCRIPTION +.SS "\fBscsi_hba_init()\fR" +.sp +.LP +\fBscsi_hba_init()\fR is the system-provided initialization routine for +\fBSCSI\fR \fBHBA\fR drivers. The \fBscsi_hba_init()\fR function registers the +\fBHBA\fR in the system and allows the driver to accept configuration requests +on behalf of \fBSCSI\fR target drivers. The \fBscsi_hba_init()\fR routine must +be called in the \fBHBA\fR's \fB_init\fR(9E) routine before +\fBmod_install\fR(9F) is called. If \fBmod_install\fR(9F) fails, the +\fBHBA\fR's \fB_init\fR(9E) should call \fBscsi_hba_fini()\fR before returning +failure. +.SS "\fBscsi_hba_fini()\fR" +.sp +.LP +\fBscsi_hba_fini()\fR is the system provided completion routine for \fBSCSI\fR +\fBHBA\fR drivers. \fBscsi_hba_fini()\fR removes all of the system references +for the \fBHBA\fR that were created in \fBscsi_hba_init()\fR. The +\fBscsi_hba_fini()\fR routine should be called in the \fBHBA\fR's +\fB_fini\fR(9E) routine if \fBmod_remove\fR(9F) is successful. +.SH RETURN VALUES +.sp +.LP +\fBscsi_hba_init()\fR returns \fB0\fR if successful, and a non-zero value +otherwise. If \fBscsi_hba_init()\fR fails, the HBA's \fB_init()\fR entry point +should return the value returned by \fBscsi_hba_init()\fR. +.SH CONTEXT +.sp +.LP +\fBscsi_hba_init()\fR and \fBscsi_hba_fini()\fR should be called from +\fB_init\fR(9E) or \fB_fini\fR(9E), respectively. +.SH SEE ALSO +.sp +.LP +\fB_fini\fR(9E), \fB_init\fR(9E), \fBmod_install\fR(9F), \fBmod_remove\fR(9F), +\fBscsi_pktalloc\fR(9F), \fBscsi_pktfree\fR(9F), \fBscsi_hba_tran\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The \fBHBA\fR is responsible for ensuring that no \fBDDI\fR request routines +are called on behalf of its \fBSCSI\fR target drivers once +\fBscsi_hba_fini()\fR is called. diff --git a/usr/src/man/man9f/scsi_hba_lookup_capstr.9f b/usr/src/man/man9f/scsi_hba_lookup_capstr.9f new file mode 100644 index 0000000000..71676a4015 --- /dev/null +++ b/usr/src/man/man9f/scsi_hba_lookup_capstr.9f @@ -0,0 +1,288 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_hba_lookup_capstr 9F "13 May 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_hba_lookup_capstr \- return index matching capability string +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint\fR \fBscsi_hba_lookup_capstr\fR(\fBchar *\fR\fIcapstr\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcapstr\fR\fR +.ad +.RS 10n +.rt +Pointer to a string +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_hba_lookup_capstr()\fR function attempts to match \fIcapstr\fR +against a known set of capability strings. If found, the defined index for the +matched capability is returned. +.sp +.LP +The following indices are defined for the capability strings listed below. +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_DMA_MAX\fR\fR +.ad +.sp .6 +.RS 4n +"\fBdma-max\fR" or "\fBdma_max\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_MSG_OUT\fR\fR +.ad +.sp .6 +.RS 4n +"\fBmsg-out\fR" or "\fBmsg_out\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_DISCONNECT\fR\fR +.ad +.sp .6 +.RS 4n +"\fBdisconnect\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_SYNCHRONOUS\fR\fR +.ad +.sp .6 +.RS 4n +"\fBsynchronous\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_WIDE_XFER\fR\fR +.ad +.sp .6 +.RS 4n +"\fBwide-xfer\fR" or "\fBwide_xfer\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_PARITY\fR\fR +.ad +.sp .6 +.RS 4n +"\fBparity\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_INITIATOR_ID\fR\fR +.ad +.sp .6 +.RS 4n +"\fBinitiator-id\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_UNTAGGED_QING\fR\fR +.ad +.sp .6 +.RS 4n +"\fBuntagged-qing\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_TAGGED_QING\fR\fR +.ad +.sp .6 +.RS 4n +"\fBtagged-qing\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_ARQ\fR\fR +.ad +.sp .6 +.RS 4n +"\fBauto-rqsense\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_LINKED_CMDS\fR\fR +.ad +.sp .6 +.RS 4n +"\fBlinked-cmds\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_SECTOR_SIZE\fR\fR +.ad +.sp .6 +.RS 4n +"\fBsector-size\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_TOTAL_SECTORS\fR\fR +.ad +.sp .6 +.RS 4n +"\fBtotal-sectors\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_GEOMETRY\fR\fR +.ad +.sp .6 +.RS 4n +"\fBgeometry\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_RESET_NOTIFICATION\fR\fR +.ad +.sp .6 +.RS 4n +"\fBreset-notification\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_QFULL_RETRIES\fR\fR +.ad +.sp .6 +.RS 4n +"\fBqfull-retries\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_QFULL_RETRY_INTERVAL\fR\fR +.ad +.sp .6 +.RS 4n +"\fBqfull-retry-interval\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_LUN_RESET\fR\fR +.ad +.sp .6 +.RS 4n +"\fBlun-reset\fR" +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_CAP_CDB_LEN\fR\fR +.ad +.sp .6 +.RS 4n +"\fBmax-cdb-length\fR" +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBscsi_hba_lookup_capstr()\fR function returns a non-negative index value +that corresponds to the capability string. If the string does not match a known +capability, \fB-1\fR is returned. +.SH CONTEXT +.sp +.LP +The \fBscsi_hba_lookup_capstr()\fR function can be called from user, interrupt, +or kernel context. +.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 +\fBtran_getcap\fR(9E), \fBtran_setcap\fR(9E), \fBscsi_ifgetcap\fR(9F), +\fBscsi_ifsetcap\fR(9F), \fBscsi_reset_notify\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_hba_pkt_alloc.9f b/usr/src/man/man9f/scsi_hba_pkt_alloc.9f new file mode 100644 index 0000000000..c549da395b --- /dev/null +++ b/usr/src/man/man9f/scsi_hba_pkt_alloc.9f @@ -0,0 +1,255 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_hba_pkt_alloc 9F "11 Dec 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_hba_pkt_alloc, scsi_hba_pkt_free \- allocate and free a scsi_pkt structure +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBstruct scsi_pkt *\fR\fBscsi_hba_pkt_alloc\fR(\fBdev_info_t *\fR\fIdip\fR, + \fBstruct scsi_address *\fR\fIap\fR, \fBint\fR \fIcmdlen\fR, \fBint\fR \fIstatuslen\fR, + \fBint\fR \fItgtlen\fR, \fBint\fR \fIhbalen\fR, + \fBint\fR (*\fIcallback\fR)(\fBcaddr_t\fR \fIarg\fR), \fBcaddr_t\fR \fIarg\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBscsi_hba_pkt_free\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\fIdip\fR\fR +.ad +.RS 13n +.rt +Pointer to a \fBdev_info_t\fR structure, defining the \fBHBA\fR driver +instance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIap\fR\fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_address\fR(9S) structure, defining the target instance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmdlen\fR\fR +.ad +.RS 13n +.rt +Length in bytes to be allocated for the \fBSCSI\fR command descriptor block +(\fBCDB\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstatuslen\fR\fR +.ad +.RS 13n +.rt +Length in bytes to be allocated for the \fBSCSI\fR status completion block +(\fBSCB\fR). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItgtlen\fR\fR +.ad +.RS 13n +.rt +Length in bytes to be allocated for a private data area for the target driver's +exclusive use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhbalen\fR\fR +.ad +.RS 13n +.rt +Length in bytes to be allocated for a private data area for the \fBHBA\fR +driver's exclusive use. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 13n +.rt +Indicates what \fBscsi_hba_pkt_alloc()\fR 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 + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 13n +.rt +Must be \fINULL.\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR\fR +.ad +.RS 13n +.rt +A pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +For \fBscsi_hba_pkt_alloc()\fR: +.sp +.LP +The \fBscsi_hba_pkt_alloc()\fR function allocates space for a \fBscsi_pkt\fR +structure. \fBHBA\fR drivers must use this interface when allocating a +\fBscsi_pkt\fR from their \fBtran_init_pkt\fR(9E) entry point. +.sp +.LP +If \fIcallback\fR is \fBNULL_FUNC\fR, \fBscsi_hba_pkt_alloc()\fR may not sleep +when allocating resources, and callers should be prepared to deal with +allocation failures. +.sp +.LP +The \fBscsi_hba_pkt_alloc()\fR function copies the \fBscsi_address\fR(9S) +structure pointed to by \fIap\fR to the \fBpkt_address\fR field in the +\fBscsi_pkt\fR(9S). +.sp +.LP +The \fBscsi_hba_pkt_alloc()\fR function also allocates memory for these +\fBscsi_pkt\fR(9S) data areas, and sets these fields to point to the allocated +memory: +.sp +.ne 2 +.mk +.na +\fB\fBpkt_ha_private\fR\fR +.ad +.RS 18n +.rt +\fBHBA\fR private data area. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_private\fR\fR +.ad +.RS 18n +.rt +Target driver private data area. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_scbp\fR\fR +.ad +.RS 18n +.rt +\fBSCSI\fR status completion block. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBpkt_cdbp\fR\fR +.ad +.RS 18n +.rt +\fBSCSI\fR command descriptor block. +.RE + +.sp +.LP +For \fBscsi_hba_pkt_free()\fR: +.sp +.LP +The \fBscsi_hba_pkt_free()\fR function frees the space allocated for the +\fBscsi_pkt\fR(9S) structure. +.SH RETURN VALUES +.sp +.LP +The \fBscsi_hba_pkt_alloc()\fR function returns a pointer to the \fBscsi_pkt\fR +structure, or \fINULL\fR if no space is available. +.SH CONTEXT +.sp +.LP +The \fBscsi_hba_pkt_alloc()\fR function can be called from user, interrupt, or +kernel context. Drivers must not allow \fBscsi_hba_pkt_alloc()\fR to sleep if +called from an interrupt routine. +.sp +.LP +The \fBscsi_hba_pkt_free()\fR function can be called from user, interrupt, or +kernel context. +.SH SEE ALSO +.sp +.LP +\fBtran_init_pkt\fR(9E), \fBscsi_address\fR(9S), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_hba_pkt_comp.9f b/usr/src/man/man9f/scsi_hba_pkt_comp.9f new file mode 100644 index 0000000000..8aef18209c --- /dev/null +++ b/usr/src/man/man9f/scsi_hba_pkt_comp.9f @@ -0,0 +1,82 @@ +'\" te +.\" Copyright (c) 2009, Sun Microsystems Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_hba_pkt_comp 9F "29 Jan 2009" "SunOS 5.11" "" +.SH NAME +scsi_hba_pkt_comp \- scsi_pkt completion routine +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + +\fBvoid\fR \fBscsi_hba_pkt_comp\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +After filling in \fBscsi_pkt\fR(9S) fields with packet completion information, +an HBA driver should call the \fBscsi_hba_pkt_comp()\fR function. This function +is the recommended way for an HBA driver to signal completion of a +\fBscsi_pkt\fR structure. Use is mandatory for HBA drivers that use +\fBtran_setup_pkt\fR(9E). +.sp +.LP +Calling the \fBscsi_hba_pkt_comp()\fR function allows SCSA to observe, and +possibly react to, the completion of a \fBscsi_pkt\fR request. +.sp +.LP +A call to the \fBscsi_hba_pkt_comp()\fR function will always result in a call +to the \fIpkt_comp\fR() callback function defined in \fBscsi_pkt\fR(9S). This +\fIpkt_comp\fR() callback may, however, occur after return from +\fBscsi_hba_pkt_comp()\fR, and may occur from a different thread executing on a +different CPU. +.SH CONTEXT +.sp +.LP +The \fBscsi_hba_pkt_comp()\fR function can be called from user, interrupt, or +kernel context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBtran_setup_pkt\fR(9E), \fBscsi_pkt\fR(9S) +.SH NOTES +.sp +.LP +HBA driver calls \fBscsi_hba_pkt_comp()\fR instead of calling +\fBscsi_pkt\fR(9S) \fIpkt_comp\fR directly. diff --git a/usr/src/man/man9f/scsi_hba_probe.9f b/usr/src/man/man9f/scsi_hba_probe.9f new file mode 100644 index 0000000000..fdba95c158 --- /dev/null +++ b/usr/src/man/man9f/scsi_hba_probe.9f @@ -0,0 +1,69 @@ +'\" 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 scsi_hba_probe 9F "30 Aug 1995" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_hba_probe \- default SCSI HBA probe function +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint\fR \fBscsi_hba_probe\fR(\fBstruct scsi_device *\fR\fIsd\fR, \fBint\fR\fB(*\fRwaitfunc\fB)(void)\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 describing the target. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwaitfunc\fR \fR +.ad +.RS 13n +.rt +\fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBscsi_hba_probe()\fR is a function providing the semantics of +\fBscsi_probe\fR(9F). An \fBHBA\fR driver may call \fBscsi_hba_probe()\fR from +its \fBtran_tgt_probe\fR(9E) entry point, to probe for the existence of a +target on the \fBSCSI\fR bus, or the \fBHBA\fR may set \fBtran_tgt_probe\fR(9E) +to point to \fBscsi_hba_probe\fR directly. +.SH RETURN VALUES +.sp +.LP +See \fBscsi_probe\fR(9F) for the return values from \fBscsi_hba_probe()\fR. +.SH CONTEXT +.sp +.LP +\fBscsi_hba_probe()\fR should only be called from the \fBHBA\fR's +\fBtran_tgt_probe\fR(9E) entry point. +.SH SEE ALSO +.sp +.LP +\fBtran_tgt_probe\fR(9E), \fBscsi_probe\fR(9F), \fBscsi_device\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_hba_tran_alloc.9f b/usr/src/man/man9f/scsi_hba_tran_alloc.9f new file mode 100644 index 0000000000..a7584ae037 --- /dev/null +++ b/usr/src/man/man9f/scsi_hba_tran_alloc.9f @@ -0,0 +1,107 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_hba_tran_alloc 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_hba_tran_alloc, scsi_hba_tran_free \- allocate and free transport +structures +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBscsi_hba_tran_t *\fR\fBscsi_hba_tran_alloc\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBscsi_hba_tran_free\fR(\fBscsi_hba_tran_t *\fR\fIhba_tran\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris architecture specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 12n +.rt +Pointer to a \fBdev_info\fR structure, defining the \fBHBA\fR driver instance. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 12n +.rt +Flag modifiers. The only possible flag value is \fBSCSI_HBA_CANSLEEP\fR (memory +allocation may sleep). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhba_tran\fR\fR +.ad +.RS 12n +.rt +Pointer to a \fBscsi_hba_tran\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +For \fBscsi_hba_tran_alloc()\fR: +.sp +.LP +The \fBscsi_hba_tran_alloc()\fR function allocates a \fBscsi_hba_tran\fR(9S) +structure for a \fBHBA\fR driver. The \fBHBA\fR must use this structure to +register its transport vectors with the system by using +\fBscsi_hba_attach_setup\fR(9F). +.sp +.LP +If the flag \fBSCSI_HBA_CANSLEEP\fR is set in \fIflags\fR, +\fBscsi_hba_tran_alloc()\fR may sleep when allocating resources; otherwise it +may not sleep, and callers should be prepared to deal with allocation failures. +.sp +.LP +For \fBscsi_hba_tran_free()\fR: +.sp +.LP +The \fBscsi_hba_tran_free()\fR function is used to free the +\fBscsi_hba_tran\fR(9S) structure allocated by \fBscsi_hba_tran_alloc()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBscsi_hba_tran_alloc()\fR function returns a pointer to the allocated +transport structure, or \fBNULL\fR if no space is available. +.SH CONTEXT +.sp +.LP +The \fBscsi_hba_tran_alloc()\fR function can be called from user, interrupt, or +kernel context. Drivers must not allow \fBscsi_hba_tran_alloc()\fR to sleep if +called from an interrupt routine. +.sp +.LP +The \fBscsi_hba_tran_free()\fR function can be called from user, interrupt, or +kernel context context. +.SH SEE ALSO +.sp +.LP +\fBscsi_hba_attach_setup\fR(9F), \fBscsi_hba_tran\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_ifgetcap.9f b/usr/src/man/man9f/scsi_ifgetcap.9f new file mode 100644 index 0000000000..dfcfea0447 --- /dev/null +++ b/usr/src/man/man9f/scsi_ifgetcap.9f @@ -0,0 +1,494 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_ifgetcap 9F "16 Oct 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_ifgetcap, scsi_ifsetcap \- get/set SCSI transport capability +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint\fR \fBscsi_ifgetcap\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBchar *\fR\fIcap\fR, \fBint\fR \fIwhom\fR); +.fi + +.LP +.nf +\fBint\fR \fBscsi_ifsetcap\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 DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR\fR +.ad +.RS 9n +.rt +Pointer to the \fBscsi_address\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcap\fR\fR +.ad +.RS 9n +.rt +Pointer to the string capability identifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvalue\fR\fR +.ad +.RS 9n +.rt +Defines the new state of the capability. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwhom\fR\fR +.ad +.RS 9n +.rt +Determines if all targets or only the specified target is affected. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_ifsetcap()\fR function is used by target drivers to set the +capabilities of the host adapter driver. The \fIcap\fR pointer is a name-value +pair identified by a null-terminated character string and the integer value of +the \fIcap\fR. The current value of the capability can be retrieved with the +\fBscsi_ifgetcap()\fR function. If the \fIwhom\fR value is \fB0\fR, all target +drivers are affected. Otherwise, the \fBscsi_address\fR structure pointed to by +\fIap\fR is the only target that is affected. +.sp +.LP +The driver should confirm that \fBscsi_ifsetcap()\fR and \fBscsi_ifsetcap()\fR +functions are called with a \fIcap\fR that points to a capability which is +supported by the device. +.sp +.LP +The following capabilities have been defined: +.sp +.ne 2 +.mk +.na +\fB\fBdma-max\fR\fR +.ad +.RS 24n +.rt +Maximum \fBdma\fR transfer size that is supported by the host adapter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdma-max-arch\fR\fR +.ad +.RS 24n +.rt +Maximum \fBdma\fR transfer size that is supported by system. Takes the host +adapter and system architecture into account. This is useful for target drivers +which do not support partial \fBDMA\fRs on systems which do not have an +\fBIOMMU\fR. In this case, the \fBDMA\fR can also be limited by the host +adapters "scatter/gather" list constraints. +.sp +The "\fBdma-max-arch\fR" capability can not be set. It is implemented with this +command and does not rely on a \fBtran_getcap\fR(9E) response from the HBA. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBmsg-out\fR\fR +.ad +.RS 24n +.rt +Message out capability that is supported by the host adapter: \fB0\fR disables, +\fB1\fR enables. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBdisconnect\fR\fR +.ad +.RS 24n +.rt +Disconnect capability that is supported by the host adapter: \fB0\fR disables, +\fB1\fR enables. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsynchronous\fR\fR +.ad +.RS 24n +.rt +Synchronous data transfer capability that is supported by the host adapter: +\fB0\fR disables, \fB1\fR enables. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBwide-xfer\fR\fR +.ad +.RS 24n +.rt +Wide transfer capability that is supported by the host adapter: \fB0\fR +disables, \fB1\fR enables. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBparity\fR\fR +.ad +.RS 24n +.rt +Parity checking capability that is supported by host adapter: \fB0\fR disables, +\fB1\fR enables. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBinitiator-id\fR\fR +.ad +.RS 24n +.rt +Host bus address that is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBuntagged-qing\fR\fR +.ad +.RS 24n +.rt +Host adapter capability that supports internal queueing of commands without +tagged queueing: \fB0\fR disables, \fB1\fR enables. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtagged-qing\fR\fR +.ad +.RS 24n +.rt +Host adapter capability that supports queuing: \fB0\fR disables, \fB1\fR +enables. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBauto-rqsense\fR\fR +.ad +.RS 24n +.rt +Host adapter capability that supports auto request sense on check conditions: +\fB0\fR disables, \fB1\fR enables. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsector-size\fR\fR +.ad +.RS 24n +.rt +Capability that is set by the target driver to inform the \fBHBA\fR of the +granularity, in bytes, of the \fBDMA\fR breakup. The \fBHBA\fR \fBDMA\fR limit +structure is set to reflect the byte total of this setting. See +\fBddi_dma_lim_sparc\fR(9S) or \fBddi_dma_lim_x86\fR(9S). The \fBsector-size\fR +should be set to the size of the physical disk sector. The capability defaults +to 512 bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBtotal-sectors\fR\fR +.ad +.RS 24n +.rt +Capability that is set by the target driver to inform the \fBHBA\fR of the +total number of sectors on the device returned by the \fBSCSI\fR \fBget +capacity\fR command. This capability must be set before the target driver +``gets'' the \fBgeometry\fR capability. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBgeometry\fR\fR +.ad +.RS 24n +.rt +Capability that returns the \fBHBA\fR geometry of a target disk. The target +driver sets the \fBtotal-sectors\fR capability before ``getting'' the geometry +capability. The geometry is returned as a 32-bit value. The upper 16 bits +represent the number of heads per cylinder. The lower 16 bits represent the +number of sectors per track. The geometry capability cannot be ``set''. +.sp +If geometry is not relevant or appropriate for the target disk, +\fBscsi_ifgetcap()\fR can return \fB-1\fR to indicate that the geometry is not +defined. For example, if the \fBHBA\fR BIOS supports Logical Block Addressing +for the target disk, \fBscsi_ifgetcap()\fR returns \fB-1\fR. Attempts to +retreive the "virtual geometry" from the target driver, such as the +\fBDKIOCG_VIRTGEOM\fR ioctl, will fail. See \fBdkio\fR(7I) for more information +about \fBDKIOCG_VIRTGEOM\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBreset-notification\fR\fR +.ad +.RS 24n +.rt +Host adapter capability that supports bus reset notification: \fB0\fR disables, +\fB1\fR enables. See \fBscsi_reset_notify\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBlinked-cmds\fR\fR +.ad +.RS 24n +.rt +Host adapter capability that supports linked commands: \fB0\fR disables, +\fB1\fR enables. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBqfull-retries\fR\fR +.ad +.RS 24n +.rt +Capability that enables or disables \fBQUEUE\fR \fBFULL\fR handling. If +\fB0\fR, the \fBHBA\fR will not retry a command when a \fBQUEUE\fR \fBFULL\fR +status is returned. If the value is greater than \fB0\fR, the \fBHBA\fR driver +retries the command a specified number of times at an interval determined by +the \fBqfull-retry-interval\fR. The range for \fBqfull-retries\fR is +\fB0-255\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBqfull-retry-interval\fR\fR +.ad +.RS 24n +.rt +Capability that sets the retry interval in milliseconds (\fBms\fR) for commands +completed with a \fBQUEUE\fR \fBFULL\fR status. The range for +\fBqfull-retry-intervals\fR is \fB0-1000\fR \fBms\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBlun-reset\fR\fR +.ad +.RS 24n +.rt +Capability that is created with a value of zero by \fBHBA\fR drivers that +support the \fBRESET_LUN\fR flag in the \fBtran_reset\fR(9E) function. If it +exists, the \fBlun-reset\fR value can be set to \fB1\fR by target drivers to +allow the use of \fBLOGICAL UNIT RESET\fR on a specific target instance. If +\fBlun-reset\fR does not exist or has a value of zero, \fBscsi_reset\fR(9F) is +prevented from passing the \fBRESET_LUN\fR flag to \fBtran_reset()\fR function +of the \fBHBA\fR driver. If \fBlun-reset\fR exists and has a value of \fB1\fR, +the \fBtran_reset()\fR function of the \fBHBA\fR driver can be called with the +\fBRESET_LUN\fR flag. +.RE + +.sp +.ne 2 +.mk +.na +\fBinterconnect-type\fR +.ad +.RS 24n +.rt +Capability held in the \fBtran_interconnect_type\fR element of struct +\fBscsi_hba_tran\fR that indicates the \fBHBA\fR transport interconnect type . +The integer value of the interconnect type of the transport is defined in the +\fBservices.h\fR header file. +.RE + +.sp +.ne 2 +.mk +.na +\fBmax-cdb-length\fR +.ad +.RS 24n +.rt +Host adapter capability of the maximum supported \fBCDB\fR (Command Descriptor +Block) length. The target driver asks for the capability at attach time. If the +\fBHBA\fR driver supports the capability, the maximum length of the \fBCDB\fR +is returned in bytes. The target driver can then use that value to determine +which \fBCDB\fR is used for the \fBHBA\fR. +.sp +If the \fBHBA\fR driver does not support the \fBmax-cdb-length\fR capability, +the default value of the target driver is used for the \fBCDB\fR determination. +.RE + +.SH RETURN VALUES +.sp +.LP +The \fBscsi_ifsetcap()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 9n +.rt +If the capability was successfully set to the new value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 9n +.rt +If the capability is not variable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB\(mi1\fR\fR +.ad +.RS 9n +.rt +If the capability was not defined, or setting the capability to a new value +failed. +.RE + +.sp +.LP +The \fBscsi_ifgetcap()\fR function returns the current value of a capability, +or: +.sp +.ne 2 +.mk +.na +\fB\fB\(mi1\fR\fR +.ad +.RS 9n +.rt +If the capability was not defined. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBscsi_ifgetcap()\fR +.sp +.in +2 +.nf +if (scsi_ifgetcap(&sd->sd_address, "auto-rqsense", 1) == 1) { + un->un_arq_enabled = 1; +} else { + un->un_arq_enabled = + ((scsi_ifsetcap(&sd->sd_address, "auto-rqsense", 1, 1) == 1) ? + 1 : 0); +} + +if (scsi_ifsetcap(&devp->sd_address, "tagged-qing", 1, 1) == 1) { + un->un_dp->options |= SD_QUEUEING; + un->un_throttle = MAX_THROTTLE; +} else if (scsi_ifgetcap(&devp->sd_address, "untagged-qing", 0) == 1) { + un->un_dp->options |= SD_QUEUEING; + un->un_throttle = 3; +} else { + un->un_dp->options &= ~SD_QUEUEING; + un->un_throttle = 1; +} +.fi +.in -2 + +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context. +.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 +\fBtran_reset\fR(9E), \fBscsi_hba_lookup_capstr\fR(9F), \fBscsi_reset\fR(9F), +\fBscsi_reset_notify\fR(9F), \fBddi_dma_lim_sparc\fR(9S), +\fBddi_dma_lim_x86\fR(9S), \fBscsi_address\fR(9S), \fBscsi_arq_status\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_init_pkt.9f b/usr/src/man/man9f/scsi_init_pkt.9f new file mode 100644 index 0000000000..fb02ca6dd2 --- /dev/null +++ b/usr/src/man/man9f/scsi_init_pkt.9f @@ -0,0 +1,409 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_init_pkt 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_init_pkt \- prepare a complete SCSI packet +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBstruct scsi_pkt *\fR\fBscsi_init_pkt\fR(\fBstruct scsi_address *\fR\fIap\fR, + \fBstruct scsi_pkt *\fR\fIpktp\fR, \fBstruct buf *\fR\fIbp\fR, \fBint\fR \fIcmdlen\fR, \fBint\fR \fIstatuslen\fR, + \fBint\fR \fIprivatelen\fR, \fBint\fR \fIflags\fR, \fBint\fR \fB(*\fRcallback\fB)(caddr_t)\fR, \fBcaddr_t\fR \fIarg\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR\fR +.ad +.sp .6 +.RS 4n +Pointer to a \fBscsi_address\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpktp\fR\fR +.ad +.sp .6 +.RS 4n +A pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbp\fR\fR +.ad +.sp .6 +.RS 4n +Pointer to a \fBbuf\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmdlen\fR\fR +.ad +.sp .6 +.RS 4n +The required length for the \fBSCSI \fRcommand descriptor block (\fBCDB\fR) in +bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstatuslen\fR\fR +.ad +.sp .6 +.RS 4n +The required length for the \fBSCSI \fRstatus completion block (\fBSCB\fR) in +bytes. Valid values are: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.sp .6 +.RS 4n +No status back. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.sp .6 +.RS 4n +Return SCSI status byte. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBsizeof(scsi_arq_status)\fR\fR +.ad +.sp .6 +.RS 4n +Return status information in a \fBscsi_arq_status\fR structure. This will +include up to 20 bytes of sense data. Please refer to \fBscsi_arq_status\fR(9S) +for more information. +.sp +For extra sense packets (\fBPKT_XARQ\fR flag asserted), set \fIstatuslen\fR to +be a greater number like, (\fIN\fR + \fBsizeof(struct scsi_arq_status)\fR) +where \fIN\fR is the number of extra bytes beyond the default 20. For example, +\fIN\fR=1 requests 21 bytes of sense, \fIN\fR=235 asks for 255 bytes. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprivatelen\fR\fR +.ad +.sp .6 +.RS 4n +The required length for the \fIpkt_private\fR area. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.sp .6 +.RS 4n +Flags modifier. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.sp .6 +.RS 4n +A pointer to a callback function, \fBNULL_FUNC\fR, or \fBSLEEP_FUNC\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.sp .6 +.RS 4n +The \fIcallback\fR function argument. +.RE + +.SH DESCRIPTION +.sp +.LP +Target drivers use \fBscsi_init_pkt()\fR to request the transport layer to +allocate and initialize a packet for a \fBSCSI\fR command which possibly +includes a data transfer. If \fIpktp\fR is \fINULL,\fR a new \fBscsi_pkt\fR(9S) +is allocated using the \fBHBA\fR driver's packet allocator. The \fIbp\fR is a +pointer to a \fBbuf\fR(9S) structure. If \fIbp\fR is non-\fINULL\fR and +contains a valid byte count, the \fBbuf\fR(9S) structure is also set up for +\fBDMA \fRtransfer using the \fBHBA\fR driver \fBDMA\fR resources allocator. +When \fIbp\fR is allocated by \fBscsi_alloc_consistent_buf\fR(9F), the +\fBPKT_CONSISTENT\fR bit must be set in the \fIflags\fR argument to ensure +proper operation. If \fIprivatelen\fR is non-zero then additional space is +allocated for the \fIpkt_private\fR area of the \fBscsi_pkt\fR(9S). On return +\fIpkt_private\fR points to this additional space. Otherwise \fIpkt_private\fR +is a pointer that is typically used to store the \fIbp\fR during execution of +the command. In this case \fIpkt_private\fR is \fINULL\fR on return. +.sp +.LP +The \fIflags\fR argument is a set of bit flags. Possible bits include: +.sp +.ne 2 +.mk +.na +\fB\fBPKT_CONSISTENT\fR\fR +.ad +.sp .6 +.RS 4n +This must be set if the \fBDMA\fR buffer was allocated using +\fBscsi_alloc_consistent_buf\fR(9F). In this case, the \fBHBA\fR driver will +guarantee that the data transfer is properly synchronized before performing the +target driver's command completion callback. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPKT_DMA_PARTIAL\fR\fR +.ad +.sp .6 +.RS 4n +This may be set if the driver can accept a partial \fBDMA\fR mapping. If set, +\fBscsi_init_pkt()\fR will allocate \fBDMA\fR resources with the +\fBDDI_DMA_PARTIAL\fR bit set in the \fBdmar_flag\fR element of the +\fBddi_dma_req\fR(9S) structure. The \fBpkt_resid\fR field of the +\fBscsi_pkt\fR(9S) structure may be returned with a non-zero value, which +indicates the number of bytes for which \fBscsi_init_pkt()\fR was unable to +allocate DMA resources. In this case, a subsequent call to +\fBscsi_init_pkt()\fR may be made for the same \fIpktp\fR and \fIbp\fR to +adjust the DMA resources to the next portion of the transfer. This sequence +should be repeated until the \fBpkt_resid\fR field is returned with a zero +value, which indicates that with transport of this final portion the entire +original request will have been satisfied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPKT_XARQ\fR\fR +.ad +.sp .6 +.RS 4n +Setting this flag requests that the \fBHBA\fR return extra sense data for this +\fBscsi_pkt\fR(9S). The default auto request sense mechanism returns up to 20 +bytes. More than 20 bytes of sense data can be requested by setting this flag +and setting the \fIstatuslen\fR correctly. Set the \fIstatuslen\fR to be the +\fBsizeof(struct scsi_arq_status)\fR plus the number of sense bytes needed +beyond 20. For example, set statuslen to be \fB(sizeof(struct scsi_arq_status) ++ 5)\fR for 25 bytes of sense. +.RE + +.sp +.LP +When calling \fBscsi_init_pkt()\fR to move already-allocated \fBDMA\fR +resources, the \fIcmdlen\fR, \fIstatuslen\fR, and \fIprivatelen\fR fields are +ignored. +.sp +.LP +The last argument \fIarg\fR is supplied to the \fIcallback\fR function when it +is invoked. +.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 16n +.rt +Do not wait for resources. Return a \fINULL\fR pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSLEEP_FUNC\fR\fR +.ad +.RS 16n +.rt +Wait indefinitely for resources. +.RE + +.sp +.ne 2 +.mk +.na +\fBOther Values\fR +.ad +.RS 16n +.rt +\fIcallback\fR points to a function which is called when resources may have +become available. \fIcallback\fR must return either \fB0\fR (indicating that it +attempted to allocate resources but again failed to do so), in which case it is +put back on a list to be called again later, or \fB1\fR indicating either +success in allocating resources or indicating that it no longer cares for a +retry. +.RE + +.sp +.LP +When allocating \fBDMA\fR resources, \fBscsi_init_pkt()\fR returns the +\fBscsi_pkt\fR field \fBpkt_resid\fR as the number of residual bytes for which +the system was unable to allocate \fBDMA\fR resources. A \fBpkt_resid\fR of +\fB0\fR means that all necessary \fBDMA\fR resources were allocated. +.SH RETURN VALUES +.sp +.LP +The \fBscsi_init_pkt()\fR function returns \fINULL\fR if the packet or +\fBDMA\fR resources could not be allocated. Otherwise, it returns a pointer to +an initialized \fBscsi_pkt\fR(9S). If \fIpktp\fR was not \fINULL\fR the return +value will be \fIpktp\fR on successful initialization of the packet. +.SH CONTEXT +.sp +.LP +If \fIcallback\fR is \fBSLEEP_FUNC\fR, then this routine can be called only +from user-level code. Otherwise, it can be called from user, interrupt, or +kernel context. The \fIcallback\fR function may not block or call routines that +block. +.SH EXAMPLES +.LP +\fBExample 1 \fRAllocating a Packet Without \fBDMA\fR Resources Attached +.sp +.LP +To allocate a packet without \fBDMA\fR resources attached, use: + +.sp +.in +2 +.nf +pkt = scsi_init_pkt(&devp->sd_address, NULL, NULL, CDB_GROUP1, + 1, sizeof (struct my_pkt_private *), 0, + sd_runout, sd_unit); +.fi +.in -2 + +.LP +\fBExample 2 \fRAllocating a Packet With \fBDMA\fR Resources Attached +.sp +.LP +To allocate a packet with \fBDMA\fR resources attached use: + +.sp +.in +2 +.nf +pkt = scsi_init_pkt(&devp->sd_address, NULL, bp, CDB_GROUP1, + sizeof(struct scsi_arq_status), 0, 0, NULL_FUNC, NULL); +.fi +.in -2 + +.LP +\fBExample 3 \fRAttaching \fBDMA\fR Resources to a Preallocated Packet +.sp +.LP +To attach \fBDMA\fR resources to a preallocated packet, use: + +.sp +.in +2 +.nf +pkt = scsi_init_pkt(&devp->sd_address, old_pkt, bp, 0, + 0, 0, 0, sd_runout, (caddr_t) sd_unit); +.fi +.in -2 + +.LP +\fBExample 4 \fRAllocating a Packet with Consistent \fBDMA\fR Resources +Attached +.sp +.LP +Since the packet is already allocated, the \fIcmdlen\fR, \fIstatuslen\fR and +\fIprivatelen\fR are \fB0\fR. To allocate a packet with consistent \fBDMA\fR +resources attached, use: + +.sp +.in +2 +.nf +bp = scsi_alloc_consistent_buf(&devp->sd_address, NULL, + SENSE_LENGTH, B_READ, SLEEP_FUNC, NULL); + pkt = scsi_init_pkt(&devp->sd_address, NULL, bp, CDB_GROUP0, + sizeof(struct scsi_arq_status), sizeof (struct my_pkt_private *), + PKT_CONSISTENT, SLEEP_FUNC, NULL); +.fi +.in -2 + +.LP +\fBExample 5 \fRAllocating a Packet with Partial \fBDMA\fR Resources Attached +.sp +.LP +To allocate a packet with partial \fBDMA\fR resources attached, use: + +.sp +.in +2 +.nf +my_pkt = scsi_init_pkt(&devp->sd_address, NULL, bp, CDB_GROUP0, + 1, sizeof (struct buf *), PKT_DMA_PARTIAL, + SLEEP_FUNC, NULL); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBscsi_alloc_consistent_buf\fR(9F), \fBscsi_destroy_pkt\fR(9F), +\fBscsi_dmaget\fR(9F), \fBscsi_pktalloc\fR(9F), \fBbuf\fR(9S), +\fBddi_dma_req\fR(9S), \fBscsi_address\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, the +\fBB_ERROR\fR flag will be set in \fIbp\fR, and the \fBb_error\fR field will be +set to \fBEFAULT\fR. +.sp +.LP +If a \fBDMA\fR allocation request fails with \fBDDI_DMA_TOOBIG\fR, the +\fBB_ERROR\fR flag will be set in \fIbp\fR, and the \fBb_error\fR field will be +set to \fBEINVAL\fR. diff --git a/usr/src/man/man9f/scsi_log.9f b/usr/src/man/man9f/scsi_log.9f new file mode 100644 index 0000000000..2d728b4b33 --- /dev/null +++ b/usr/src/man/man9f/scsi_log.9f @@ -0,0 +1,120 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_log 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_log \- display a SCSI-device-related message +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + #include <sys/cmn_err.h> + + + +\fBvoid\fR \fBscsi_log\fR(\fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIdrv_name\fR, \fBuint_t\fR \fIlevel\fR, + \fBconst char *\fR\fIfmt\fR\fB, ...\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 12n +.rt +Pointer to the \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdrv_name\fR\fR +.ad +.RS 12n +.rt +String naming the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlevel\fR\fR +.ad +.RS 12n +.rt +Error level. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfmt\fR\fR +.ad +.RS 12n +.rt +Display format. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_log()\fR function is a utility function that displays a message via +the \fBcmn_err\fR(9F) routine. The error levels that can be passed in to this +function are \fBCE_PANIC\fR, \fBCE_WARN\fR, \fBCE_NOTE\fR, \fBCE_CONT\fR, and +\fBSCSI_DEBUG\fR. The last level is used to assist in displaying debug messages +to the console only. \fIdrv_name\fR is the short name by which this device is +known; example disk driver names are \fBsd\fR and \fBcmdk\fR. If the +\fIdev_info_t\fR pointer is \fINULL\fR, then the \fIdrv_name\fR will be used +with no unit or long name. +.sp +.LP +If the first character in \fIformat\fR is: +.RS +4 +.TP +.ie t \(bu +.el o +An exclamation mark (\fB!\fR), the message goes only to the system buffer. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A caret (\fB^\fR), the message goes only to the console. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +A question mark (\fB?\fR) and \fIlevel\fR is \fBCE_CONT\fR, the message is +always sent to the system buffer, but is written to the console only when the +system has been booted in verbose mode. See \fBkernel\fR(1M). If neither +condition is met, the \fB?\fR character has no effect and is simply ignored. +.RE +.sp +.LP +All formatting conversions in use by \fBcmn_err()\fR also work with +\fBscsi_log()\fR. +.SH CONTEXT +.sp +.LP +The \fBscsi_log()\fR function may be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBkernel\fR(1M), \fBsd\fR(7D), \fBcmn_err\fR(9F), \fBscsi_errmsg\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_pktalloc.9f b/usr/src/man/man9f/scsi_pktalloc.9f new file mode 100644 index 0000000000..4b0eb8d31b --- /dev/null +++ b/usr/src/man/man9f/scsi_pktalloc.9f @@ -0,0 +1,241 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_pktalloc 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_pktalloc, scsi_resalloc, scsi_pktfree, scsi_resfree \- SCSI packet utility +routines +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + +\fBstruct scsi_pkt *\fR\fBscsi_pktalloc\fR (\fBstruct scsi_address*\fR \fIap\fR, \fBint\fR \fIcmdlen\fR, + \fBint\fR \fIstatuslen\fR, \fBint\fR (\fI*callback\fR)(\fIvoid\fR)); +.fi + +.LP +.nf +\fBstruct scsi_pkt *\fR\fBscsi_resalloc\fR (\fBstruct scsi_address*\fR \fIap\fR, \fBint\fR \fIcmdlen\fR, + \fBint\fR \fIstatuslen\fR, \fBopaque_t\fR \fIdmatoken\fR, \fBint\fR (\fI*callback\fR)(\fIvoid\fR)); +.fi + +.LP +.nf +\fBvoid\fR \fBscsi_pktfree\fR (\fBstruct scsi_pkt*\fR \fIpkt\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBscsi_resfree\fR (\fBstruct scsi_pkt*\fR \fIpkt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +The \fBscsi_pktalloc()\fR, \fBscsi_pktfree()\fR, \fBscsi_resalloc()\fR, and +\fBscsi_resfree()\fR functions are obsolete. The \fBscsi_pktalloc()\fR and +\fBscsi_resalloc()\fR functions have been replaced by \fBscsi_init_pkt\fR(9F). +The \fBscsi_pktfree()\fR and \fBscsi_resfree()\fR functions have been replaced +by \fBscsi_destroy_pkt\fR(9F). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR\fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_address\fR structure. +.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\fR status completion block (\fBSCB\fR) in +bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdmatoken\fR\fR +.ad +.RS 13n +.rt +Pointer to an implementation-dependent object. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 13n +.rt +A pointer to a callback function, or \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR\fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_pktalloc()\fR function requests the host adapter driver to allocate +a command packet. For commands that have a data transfer associated with them, +\fBscsi_resalloc()\fR should be used. +.sp +.LP +\fIap\fR is a pointer to a \fBscsi_address\fR structure. Allocator routines use +it to determine the associated host adapter. +.sp +.LP +The \fIcmdlen\fR parameter is the required length for the \fBSCSI \fRcommand +descriptor block. This block is allocated such that a kernel virtual address is +established in the \fBpkt_cdbp\fR field of the allocated \fBscsi_pkt\fR +structure. +.sp +.LP +\fIstatuslen\fR is the required length for the \fBSCSI \fRstatus completion +block. The address of the allocated block is placed into the \fBpkt_scbp\fR +field of the \fBscsi_pkt\fR structure. +.sp +.LP +The \fIdmatoken\fR parameter is a pointer to an implementation dependent object +which defines the length, direction, and address of the data transfer +associated with this \fBSCSI\fR packet (command). The \fIdmatoken\fR must be a +pointer to a \fBbuf\fR(9S) structure. If \fIdmatoken\fR is \fINULL\fR, no +\fBDMA\fR resources are required by this \fBSCSI\fR command, so none are +allocated. Only one transfer direction is allowed per command. If there is an +unexpected data transfer phase (either no data transfer phase expected, or the +wrong direction encountered), the command is terminated with the +\fBpkt_reason\fR set to \fBCMD_DMA_DERR\fR. \fIdmatoken\fR provides the +information to determine if the transfer count is correct. +.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 16n +.rt +Do not wait for resources. Return a \fINULL\fR pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSLEEP_FUNC\fR\fR +.ad +.RS 16n +.rt +Wait indefinitely for resources. +.RE + +.sp +.ne 2 +.mk +.na +\fBOther Values\fR +.ad +.RS 16n +.rt +\fIcallback\fR points to a function which is called when resources may have +become available. \fIcallback\fR must return either \fB0\fR (indicating that it +attempted to allocate resources but again failed to do so), in which case it is +put back on a list to be called again later, or \fB1\fR indicating either +success in allocating resources or indicating that it no longer cares for a +retry. +.RE + +.sp +.LP +The \fBscsi_pktfree()\fR function frees the packet. +.sp +.LP +The \fBscsi_resfree()\fR function free all resources held by the packet and the +packet itself. +.SH RETURN VALUES +.sp +.LP +Both allocation routines return a pointer to a \fBscsi_pkt\fR structure on +success, or \fINULL\fR on failure. +.SH CONTEXT +.sp +.LP +If \fIcallback\fR is \fBSLEEP_FUNC\fR, then this routine can be called only +from user or kernel context. Otherwise, it can be called from user, kernel, or +interrupt context. The \fIcallback\fR function may not block or call routines +that block. Both deallocation routines can be called from user, kernel, or +interrupt context. +.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 +\fBattributes\fR(5), \fBscsi_dmafree\fR(9F), \fBscsi_dmaget\fR(9F), +\fBbuf\fR(9S), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The \fBscsi_pktalloc()\fR, \fBscsi_pktfree()\fR, \fBscsi_resalloc()\fR, and +\fBscsi_resfree()\fR functions are obsolete and will be discontinued in a +future release. The \fBscsi_pktalloc()\fR and \fBscsi_resalloc()\fR functions +have been replaced by \fBscsi_init_pkt\fR(9F). The \fBscsi_pktfree()\fR and +\fBscsi_resfree()\fR functions have been replaced by +\fBscsi_destroy_pkt\fR(9F). diff --git a/usr/src/man/man9f/scsi_poll.9f b/usr/src/man/man9f/scsi_poll.9f new file mode 100644 index 0000000000..f522f454e1 --- /dev/null +++ b/usr/src/man/man9f/scsi_poll.9f @@ -0,0 +1,88 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_poll 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_poll \- run a polled SCSI command on behalf of a target driver +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint\fR \fBscsi_poll\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR\fR +.ad +.RS 7n +.rt +Pointer to the \fBscsi_pkt\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_poll()\fR function requests the host adapter driver to run a polled +command. Unlike \fBscsi_transport\fR(9F) which runs commands asynchronously, +\fBscsi_poll()\fR runs commands to completion before returning. If the +\fBpkt_time\fR member of \fIpkt\fR is \fB0\fR, the value of \fBpkt_time\fR is +defaulted to \fBSCSI_POLL_TIMEOUT\fR to prevent an indefinite hang of the +system. +.SH RETURN VALUES +.sp +.LP +The \fBscsi_poll()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 6n +.rt +command completed successfully. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB-1\fR\fR +.ad +.RS 6n +.rt +command failed. +.RE + +.SH CONTEXT +.sp +.LP +The \fBscsi_poll()\fR function can be called from user, interrupt, or kernel +context. This function should not be called when the caller is executing +\fBtimeout\fR(9F) in the context of a thread. +.SH SEE ALSO +.sp +.LP +\fBmakecom\fR(9F), \fBscsi_transport\fR(9F), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +Since \fBscsi_poll()\fR runs commands to completion before returning, it may +require more time than is desirable when called from interrupt context. +Therefore, calling \fBscsi_poll\fR from interrupt context is not recommended. diff --git a/usr/src/man/man9f/scsi_probe.9f b/usr/src/man/man9f/scsi_probe.9f new file mode 100644 index 0000000000..8797336527 --- /dev/null +++ b/usr/src/man/man9f/scsi_probe.9f @@ -0,0 +1,229 @@ +'\" te +.\" Copyright (c) 2002, 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 scsi_probe 9F "26 Feb 2002" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_probe \- utility for probing a scsi device +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint\fR \fBscsi_probe\fR(\fBstruct scsi_device *\fR\fIdevp\fR, \fBint (*\fR\fIwaitfunc\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdevp\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 +\fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR +.RE + +.SH DESCRIPTION +.sp +.LP +\fBscsi_probe()\fR determines whether a \fBtarget/lun\fR is present and sets up +the \fBscsi_device\fR structure with inquiry data. +.sp +.LP +\fBscsi_probe()\fR uses the SCSI Inquiry command to test if the device exists. +It can retry the Inquiry command as appropriate. If \fBscsi_probe()\fR is +successful, it will allocate space for the \fBscsi_inquiry\fR structure and +assign the address to the \fBsd_inq\fR member of the \fBscsi_device\fR(9S) +structure. \fBscsi_probe()\fR will then fill in this \fBscsi_inquiry\fR(9S) +structure and return \fBSCSIPROBE_EXISTS\fR. If \fBscsi_probe()\fR is +unsuccessful, it returns \fBSCSIPROBE_NOMEM\fR in spite of callback set to +\fBSLEEP_FUNC\fR. +.sp +.LP +\fBscsi_unprobe\fR(9F) is used to undo the effect of \fBscsi_probe()\fR. +.sp +.LP +If the target is a non-CCS device, \fBSCSIPROBE_NONCCS\fR will be returned. +.sp +.LP +\fIwaitfunc\fR indicates what the allocator routines should do when resources +are not available; the valid values are: +.sp +.ne 2 +.mk +.na +\fB\fBNULL_FUNC\fR \fR +.ad +.RS 15n +.rt +Do not wait for resources. Return \fBSCSIPROBE_NOMEM\fR or +\fBSCSIPROBE_FAILURE\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSLEEP_FUNC\fR \fR +.ad +.RS 15n +.rt +Wait indefinitely for resources. +.RE + +.SH RETURN VALUES +.sp +.LP +\fBscsi_probe()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBSCSIPROBE_BUSY\fR \fR +.ad +.RS 23n +.rt +Device exists but is currently busy. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSIPROBE_EXISTS\fR \fR +.ad +.RS 23n +.rt +Device exists and inquiry data is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSIPROBE_FAILURE\fR \fR +.ad +.RS 23n +.rt +Polled command failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSIPROBE_NOMEM\fR \fR +.ad +.RS 23n +.rt +No space available for structures. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSIPROBE_NOMEM_CB\fR \fR +.ad +.RS 23n +.rt +No space available for structures but callback request has been queued. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSIPROBE_NONCCS\fR \fR +.ad +.RS 23n +.rt +Device exists but inquiry data is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSIPROBE_NORESP\fR \fR +.ad +.RS 23n +.rt +Device does not respond to an INQUIRY. +.RE + +.SH CONTEXT +.sp +.LP +\fBscsi_probe()\fR is normally called from the target driver's \fBprobe\fR(9E) +or \fBattach\fR(9E) routine. In any case, this routine should not be called +from interrupt context, because it can sleep waiting for memory to be +allocated. +.SH EXAMPLES +.LP +\fBExample 1 \fR Using \fBscsi_probe()\fR +.sp +.in +2 +.nf + switch (scsi_probe(devp, NULL_FUNC)) { + default: + case SCSIPROBE_NORESP: + case SCSIPROBE_NONCCS: + case SCSIPROBE_NOMEM: + case SCSIPROBE_FAILURE: + case SCSIPROBE_BUSY: + break; + case SCSIPROBE_EXISTS: + switch (devp->sd_inq->inq_dtype) { + case DTYPE_DIRECT: + rval = DDI_PROBE_SUCCESS; + break; + case DTYPE_RODIRECT: + rval = DDI_PROBE_SUCCESS; + break; + case DTYPE_NOTPRESENT: + default: + break; + } + } + scsi_unprobe(devp); +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBattach\fR(9E), \fBprobe\fR(9E), \fBscsi_slave\fR(9F), +\fBscsi_unprobe\fR(9F), \fBscsi_unslave\fR(9F), \fBscsi_device\fR(9S), +\fBscsi_inquiry\fR(9S) +.sp +.LP +\fIANSI Small Computer System Interface-2 (SCSI-2)\fR +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +A \fIwaitfunc\fR function other than \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR is not +supported and may have unexpected results. diff --git a/usr/src/man/man9f/scsi_reset.9f b/usr/src/man/man9f/scsi_reset.9f new file mode 100644 index 0000000000..56215dd537 --- /dev/null +++ b/usr/src/man/man9f/scsi_reset.9f @@ -0,0 +1,121 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_reset 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_reset \- reset a SCSI bus or target +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint\fR \fBscsi_reset\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBint\fR \fIlevel\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR\fR +.ad +.RS 9n +.rt +Pointer to the \fBscsi_address\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlevel\fR\fR +.ad +.RS 9n +.rt +The level of reset required. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_reset()\fR function asks the host adapter driver to reset the +\fBSCSI \fRbus or a \fBSCSI \fRtarget as specified by \fIlevel\fR. If +\fIlevel\fR equals \fBRESET_ALL\fR, the \fBSCSI\fR bus is reset. If it equals +\fBRESET_TARGET\fR, \fIap\fR is used to determine the target to be reset. If it +equals \fBRESET_LUN\fR, \fIap\fR is used to determine the logical unit to be +reset. +.sp +.LP +When given the \fBRESET_LUN\fR level, \fBscsi_reset()\fR can return failure if +the \fBLOGICAL UNIT RESET\fR message is not supported by the target device, or +if the underlying HBA driver does not implement the ability to issue a +\fBLOGICAL UNIT RESET\fR message. +.sp +.LP +Note that, at the point when \fBscsi_reset()\fR resets the logical unit (case +\fBRESET_LUN\fR), or the target (case \fBRESET_TARGET\fR), or the bus (case +\fBRESET_ALL\fR), there might be one or more command packets outstanding. That +is, packets have been passed to \fBscsi_transport()\fR, and queued or possibly +transported, but the commands have not been completed and the target completion +routine has not been called for those packets. +.sp +.LP +The successful call to \fBscsi_reset()\fR has the side effect that any such +commands currently outstanding are aborted, at which point the packets are +marked with \fBpkt_reason\fR set to \fBCMD_RESET\fR, and the appropriate bit -- +either \fBSTAT_BUS_RESET\fR or \fBSTAT_DEV_RESET\fR -- is set in +\fBpkt_statistics\fR. Once thus appropriately marked, the aborted command +packets are passed to the target driver command completion routine. +.sp +.LP +Also note that, at the moment that a thread executing \fBscsi_reset()\fR +actually resets the target or the bus, it is possible that a second thread may +have already called \fBscsi_transport()\fR, but not yet queued or transported +its command. In this case the HBA will not yet have received the second +thread's packet and this packet will not be aborted. +.SH RETURN VALUES +.sp +.LP +The \fBscsi_reset()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 5n +.rt +Upon success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +Upon failure. +.RE + +.SH CONTEXT +.sp +.LP +The \fBscsi_reset()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBtran_reset\fR(9E), \fBtran_reset_notify\fR(9E), \fBscsi_abort\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_reset_notify.9f b/usr/src/man/man9f/scsi_reset_notify.9f new file mode 100644 index 0000000000..170f85f3c4 --- /dev/null +++ b/usr/src/man/man9f/scsi_reset_notify.9f @@ -0,0 +1,172 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_reset_notify 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_reset_notify \- notify target driver of bus resets +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBvoid\fR \fBscsi_reset_notify\fR(\fBstruct scsi_address *\fR\fIap\fR, \fBint\fR \fIflag\fR, + \fBvoid\fR (*\fIcallback)(caddr_t)\fR, \fBcaddr_t\fR \fIarg\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIap\fR\fR +.ad +.RS 12n +.rt +Pointer to the \fBscsi_address\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 12n +.rt +A flag indicating registration or cancellation of the notification request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 12n +.rt +A pointer to the target driver's reset notification function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 12n +.rt +The callback function argument. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_reset_notify()\fR function is used by a target driver when it needs +to be notified of a bus reset. The bus reset could be issued by the transport +layer (e.g. the host bus adapter (\fBHBA)\fR driver or controller) or by +another initiator. +.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 21n +.rt +Register \fIcallback\fR as the reset notification function for the target +driver. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSI_RESET_CANCEL\fR\fR +.ad +.RS 21n +.rt +Cancel the reset notification request. +.RE + +.sp +.LP +Target drivers can find out whether the \fBHBA\fR driver and controller support +reset notification by checking the \fBreset-notification\fR capability using +the \fBscsi_ifgetcap\fR(9F) function. +.SH RETURN VALUES +.sp +.LP +If \fIflag\fR is \fBSCSI_RESET_NOTIFY\fR, \fBscsi_reset_notify()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +The notification request has been accepted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +The transport layer does not support reset notification or could not accept +this request. +.RE + +.sp +.LP +If \fIflag\fR is \fBSCSI_RESET_CANCEL\fR, \fBscsi_reset_notify()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBDDI_SUCCESS\fR\fR +.ad +.RS 15n +.rt +The notification request has been canceled. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBDDI_FAILURE\fR\fR +.ad +.RS 15n +.rt +No notification request was registered. +.RE + +.SH CONTEXT +.sp +.LP +The \fBscsi_reset_notify()\fR function can be called from user, interrupt, or +kernel context. +.SH SEE ALSO +.sp +.LP +\fBscsi_address\fR(9S), \fBscsi_ifgetcap\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_sense_key.9f b/usr/src/man/man9f/scsi_sense_key.9f new file mode 100644 index 0000000000..5015913744 --- /dev/null +++ b/usr/src/man/man9f/scsi_sense_key.9f @@ -0,0 +1,87 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_sense_key 9F "28 Jun 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_sense_key, scsi_sense_asc, scsi_sense_ascq \- retrieve fields from SCSI +sense data +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBuint8_t\fR \fBscsi_sense_key\fR(\fBuint8_t *\fR\fIsense_buffer\fR); +.fi + +.LP +.nf +\fBuint8_t\fR \fBscsi_sense_asc\fR(\fBuint8_t *\fR\fIsense_buffer\fR); +.fi + +.LP +.nf +\fBuint8_t\fR \fBscsi_sense_ascq\fR(\fBuint8_t *\fR\fIsense_buffer\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsense_buffer\fR\fR +.ad +.RS 16n +.rt +Pointer to a buffer containing \fBSCSI\fR sense data. The sense data is +expected in wire format starting at the response code. It can be in either +fixed or descriptor format. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_sense_key()\fR function returns the sense key value from the sense +data contained in the sense_buffer. +.sp +.LP +The \fBscsi_sense_asc()\fR function returns the additional sense code +(\fBASC\fR) value from the sense data contained in the sense_buffer. +.sp +.LP +The \fBscsi_sense_ascq()\fR function returns the additional sense code +qualifier (\fBASCQ\fR) value from the sense data contained in the sense_buffer. +.sp +.LP +The \fBscsi_sense_key()\fR, \fBscsi_sense_asc()\fR, and \fBscsi_sense_ascq()\fR +functions are used to retrieve values from \fBSCSI\fR sense data, regardles of +whether the sense data is in fixed format or descriptor format. +.sp +.LP +Drivers should use \fBscsi_validate_sense\fR(9F) to ensure that valid sense +key, \fBasc\fR, and \fBascq\fR values are present in the sense data. +.SH RETURN VALUES +.sp +.LP +The \fBscsi_sense_key()\fR function returns the sense key value from the sense +buffer. The \fBscsi_sense_asc()\fR function returns the additional sense code +(\fBASC\fR) from the sense buffer and the \fBscsi_sense_ascq()\fR function +returns the additional sense code qualifier (\fBASCQ\fR) from the sense buffer. +.SH CONTEXT +.sp +.LP +The \fBscsi_sense_key()\fR, \fBscsi_sense_asc()\fR, and \fBscsi_sense_ascq()\fR +functions can be called from user or interrupt context. +.SH SEE ALSO +.sp +.LP +\fBscsi_ext_sense_fields\fR(9F), \fBscsi_find_sense_descr\fR(9F), +\fBscsi_sense_cmdspecific_uint64\fR(9F), \fBscsi_sense_info_uint64\fR(9F), +\fBscsi_validate_sense\fR(9F) diff --git a/usr/src/man/man9f/scsi_setup_cdb.9f b/usr/src/man/man9f/scsi_setup_cdb.9f new file mode 100644 index 0000000000..0d460f0f30 --- /dev/null +++ b/usr/src/man/man9f/scsi_setup_cdb.9f @@ -0,0 +1,137 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. , All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_setup_cdb 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_setup_cdb \- setup SCSI command descriptor block (CDB) +.SH SYNOPSIS +.LP +.nf +\fBint\fR \fBscsi_setup_cdb\fR(\fBunion scsi_cdb\fR \fI*cdbp\fR, \fBuchar_t\fR \fIcmd\fR, \fBuint_t\fR \fIaddr\fR, + \fBuint_t\fR \fIcnt\fR, \fBuint_t\fR \fIothr_cdb_data\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIcdbp\fR\fR +.ad +.RS 17n +.rt +Pointer to command descriptor block. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmd\fR\fR +.ad +.RS 17n +.rt +The first byte of the \fBSCSI\fR group 0, 1, 2, 4, or 5 \fBCDB\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIaddr\fR\fR +.ad +.RS 17n +.rt +Pointer to the location of the data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcnt\fR\fR +.ad +.RS 17n +.rt +Data transfer length in units defined by the SCSI device type. For sequential +devices \fIcnt\fR is the number of bytes. For block devices, \fIcnt\fR is the +number of blocks. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIothr_cdb_data\fR\fR +.ad +.RS 17n +.rt +Additional \fBCDB\fR data. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_setup_cdb()\fR function initializes a group 0, 1, 2, 4, or 5 type +of command descriptor block pointed to by \fIcdbp\fR using \fIcmd\fR, +\fIaddr\fR, \fIcnt\fR, \fIothr_cdb_data\fR. +.sp +.LP +\fIaddr\fR should be set to 0 for commands having no addressing information +(for example, group 0 READ command for sequential access devices). +\fIothr_cdb_data\fR should be additional \fBCDB\fR data for Group 4 commands; +otherwise, it should be set to 0. +.sp +.LP +The \fBscsi_setup_cdb()\fR function does not set the \fBLUN\fR bits in +\fBCDB\fR[1] as the \fBmakecom\fR(9F) functions do. Also, the fixed bit for +sequential access device commands is not set. +.SH RETURN VALUES +.sp +.LP +The \fBscsi_setup_cdb()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 5n +.rt +Upon success. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +Upon failure. +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from a user, interrupt, or kernel context. +.SH SEE ALSO +.sp +.LP +\fBmakecom\fR(9F), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fIAmerican National Standard Small Computer System Interface-2 (SCSI-2)\fR +.sp +.LP +\fIAmerican National Standard SCSI-3 Primary Commands (SPC)\fR diff --git a/usr/src/man/man9f/scsi_slave.9f b/usr/src/man/man9f/scsi_slave.9f new file mode 100644 index 0000000000..7b7c6c86a5 --- /dev/null +++ b/usr/src/man/man9f/scsi_slave.9f @@ -0,0 +1,199 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_slave 9F "27 Sep 2002" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_slave \- utility for SCSI target drivers to establish the presence of a +target +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint\fR \fBscsi_slave\fR(\fBstruct scsi_device *\fR\fIdevp\fR, \fBint\fR \fB(*\fRcallback\fB)(void)\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +The \fBscsi_slave()\fR function is obsolete. This function has been replaced by +\fBscsi_probe\fR(9F). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdevp\fR \fR +.ad +.RS 13n +.rt +Pointer to a \fBscsi_device\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR \fR +.ad +.RS 13n +.rt +Pointer to a callback function, \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBscsi_slave()\fR checks for the presence of a \fBSCSI\fR device. Target +drivers may use this function in their \fBprobe\fR(9E) routines. +\fBscsi_slave()\fR determines if the device is present by using a Test Unit +Ready command followed by an Inquiry command. If \fBscsi_slave()\fR is +successful, it will fill in the \fBscsi_inquiry\fR structure, which is the +\fBsd_inq\fR member of the \fBscsi_device\fR(9S) structure, and return +\fBSCSI_PROBE_EXISTS\fR. This information can be used to determine if the +target driver has probed the correct SCSI device type. \fIcallback\fR indicates +what the allocator routines should do when \fBDMA \fRresources are not +available: +.sp +.ne 2 +.mk +.na +\fB\fBNULL_FUNC\fR \fR +.ad +.RS 16n +.rt +Do not wait for resources. Return a \fINULL\fR pointer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSLEEP_FUNC\fR \fR +.ad +.RS 16n +.rt +Wait indefinitely for resources. +.RE + +.sp +.ne 2 +.mk +.na +\fBOther Values\fR +.ad +.RS 16n +.rt +\fIcallback\fR points to a function which is called when resources may have +become available. \fIcallback\fR \fBmust\fR return either \fB0\fR (indicating +that it attempted to allocate resources but again failed to do so), in which +case it is put back on a list to be called again later, or \fB1\fR indicating +either success in allocating resources or indicating that it no longer cares +for a retry. +.RE + +.SH RETURN VALUES +.sp +.LP +\fBscsi_slave()\fR returns: +.sp +.ne 2 +.mk +.na +\fB\fBSCSIPROBE_NOMEM\fR \fR +.ad +.RS 22n +.rt +No space available for structures. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSIPROBE_EXISTS\fR \fR +.ad +.RS 22n +.rt +Device exists and inquiry data is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSIPROBE_NONCCS\fR \fR +.ad +.RS 22n +.rt +Device exists but inquiry data is not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSIPROBE_FAILURE\fR \fR +.ad +.RS 22n +.rt +Polled command failure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSCSIPROBE_NORESP\fR \fR +.ad +.RS 22n +.rt +No response to \fBTEST UNIT READY\fR. +.RE + +.SH CONTEXT +.sp +.LP +\fBscsi_slave()\fR is normally called from the target driver's \fBprobe\fR(9E) +or \fBattach\fR(9E) routine. In any case, this routine should not be called +from interrupt context, because it can sleep waiting for memory to be +allocated. +.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 +\fBattributes\fR(5), \fBattach\fR(9E), \fBprobe\fR(9E), +\fBddi_iopb_alloc\fR(9F), \fBmakecom\fR(9F), \fBscsi_dmaget\fR(9F), +\fBscsi_ifgetcap\fR(9F), \fBscsi_pktalloc\fR(9F), \fBscsi_poll\fR(9F), +\fBscsi_probe\fR(9F), \fBscsi_device\fR(9S) +.sp +.LP + \fIANSI Small Computer System Interface-2 (SCSI-2)\fR +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The \fBscsi_slave()\fR function is obsolete and will be discontinued in a +future release. This function has been replaced by \fBscsi_probe\fR(9F). diff --git a/usr/src/man/man9f/scsi_sync_pkt.9f b/usr/src/man/man9f/scsi_sync_pkt.9f new file mode 100644 index 0000000000..972835ded0 --- /dev/null +++ b/usr/src/man/man9f/scsi_sync_pkt.9f @@ -0,0 +1,70 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_sync_pkt 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_sync_pkt \- synchronize CPU and I/O views of memory +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBvoid\fR \fBscsi_sync_pkt\fR(\fBstruct scsi_pkt *\fR\fIpktp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpktp\fR\fR +.ad +.RS 8n +.rt +Pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_sync_pkt()\fR function is used to selectively synchronize a +\fBCPU\fR's or device's view of the data associated with the \fBSCSI\fR packet +that has been mapped for \fBI/O\fR. This may involve operations such as flushes +of \fBCPU\fR or \fBI/O\fR caches, as well as other more complex operations such +as stalling until hardware write buffers have drained. +.sp +.LP +This function need only be called under certain circumstances. When a +\fBSCSI\fR packet is mapped for \fBI/O\fR using \fBscsi_init_pkt\fR(9F) and +destroyed using \fBscsi_destroy_pkt\fR(9F), then an implicit +\fBscsi_sync_pkt()\fR will be performed. However, if the memory object has been +modified by either the device or a \fBCPU\fR after the mapping by +\fBscsi_init_pkt\fR(9F), then a call to \fBscsi_sync_pkt()\fR is required. +.sp +.LP +If the same scsi_pkt is reused for a data transfer from memory to a device, +then \fBscsi_sync_pkt()\fR must be called before calling +\fBscsi_transport\fR(9F). If the same packet is reused for a data transfer from +a device to memory \fBscsi_sync_pkt()\fR must be called after the completion of +the packet but before accessing the data in memory. +.SH CONTEXT +.sp +.LP +The \fBscsi_sync_pkt()\fR function may be called from user, interrupt, or +kernel context. +.SH SEE ALSO +.sp +.LP +\fBtran_sync_pkt\fR(9E), \fBddi_dma_sync\fR(9F), \fBscsi_destroy_pkt\fR(9F), +\fBscsi_init_pkt\fR(9F), \fBscsi_transport\fR(9F), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_transport.9f b/usr/src/man/man9f/scsi_transport.9f new file mode 100644 index 0000000000..83701a8f40 --- /dev/null +++ b/usr/src/man/man9f/scsi_transport.9f @@ -0,0 +1,124 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_transport 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_transport \- request by a SCSI target driver to start a command +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint\fR \fBscsi_transport\fR(\fBstruct scsi_pkt *\fR\fIpkt\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpkt\fR\fR +.ad +.RS 7n +.rt +Pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +Target drivers use \fBscsi_transport()\fR to request the host adapter driver to +transport a command to the \fBSCSI \fRtarget device specified by \fIpkt\fR. The +target driver must obtain resources for the packet using +\fBscsi_init_pkt\fR(9F) prior to calling this function. The packet may be +initialized using one of the \fBmakecom\fR(9F) functions. +\fBscsi_transport()\fR does not wait for the \fBSCSI\fR command to complete. +See \fBscsi_poll\fR(9F) for a description of polled \fBSCSI\fR commands. Upon +completion of the \fBSCSI\fR command the host adapter calls the completion +routine provided by the target driver in the \fBpkt_comp\fR member of the +\fBscsi_pkt\fR pointed to by \fIpkt\fR. +.SH RETURN VALUES +.sp +.LP +The \fBscsi_transport()\fR function returns: +.sp +.ne 2 +.mk +.na +\fB\fBTRAN_ACCEPT\fR\fR +.ad +.RS 20n +.rt +The packet was accepted by the transport layer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTRAN_BUSY\fR\fR +.ad +.RS 20n +.rt +The packet could not be accepted because there was already a packet in progress +for this target/lun, the host adapter queue was full, or the target device +queue was full. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTRAN_BADPKT\fR\fR +.ad +.RS 20n +.rt +The \fBDMA\fR count in the packet exceeded the \fBDMA\fR engine's maximum +\fBDMA\fR size. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBTRAN_FATAL_ERROR\fR\fR +.ad +.RS 20n +.rt +A fatal error has occurred in the transport layer. +.RE + +.SH CONTEXT +.sp +.LP +The \fBscsi_transport()\fR function can be called from user, interrupt, or +kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBscsi_transport()\fR +.sp +.in +2 +.nf +if ((status = scsi_transport(rqpkt)) != TRAN_ACCEPT) { + scsi_log(devp, sd_label, CE_WARN, + "transport of request sense pkt fails (0x%x)\en", status); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBtran_start\fR(9E), \fBmakecom\fR(9F), \fBscsi_init_pkt\fR(9F), +\fBscsi_pktalloc\fR(9F), \fBscsi_poll\fR(9F), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/scsi_unprobe.9f b/usr/src/man/man9f/scsi_unprobe.9f new file mode 100644 index 0000000000..ca64b35c7e --- /dev/null +++ b/usr/src/man/man9f/scsi_unprobe.9f @@ -0,0 +1,63 @@ +'\" te +.\" Copyright (c) 2002, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_unprobe 9F "27 Sep 2002" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_unprobe, scsi_unslave \- free resources allocated during initial probing +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBvoid\fR \fBscsi_unslave\fR(\fBstruct scsi_device *\fR\fIdevp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBscsi_unprobe\fR(\fBstruct scsi_device *\fR\fIdevp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). The \fBscsi_unslave()\fR interface is +obsolete. Use \fBscsi_unprobe()\fR instead. +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdevp\fR \fR +.ad +.RS 9n +.rt +Pointer to a \fBscsi_device\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBscsi_unprobe()\fR and \fBscsi_unslave()\fR are used to free any resources +that were allocated on the driver's behalf during \fBscsi_slave\fR(9F) and +\fBscsi_probe\fR(9F) activity. +.SH CONTEXT +.sp +.LP +\fBscsi_unprobe()\fR and \fBscsi_unslave()\fR must not be called from an +interrupt context. +.SH SEE ALSO +.sp +.LP +\fBscsi_probe\fR(9F), \fBscsi_slave\fR(9F), \fBscsi_device\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The \fBscsi_unslave()\fR function is obsolete and will be discontinued in a +future release. This function has been replaced by \fBscsi_unprobe()\fR. diff --git a/usr/src/man/man9f/scsi_validate_sense.9f b/usr/src/man/man9f/scsi_validate_sense.9f new file mode 100644 index 0000000000..f2ecabd2af --- /dev/null +++ b/usr/src/man/man9f/scsi_validate_sense.9f @@ -0,0 +1,143 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_validate_sense 9F "29 Jun 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_validate_sense \- find descriptor in SCSI sense data +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBint\fR \fBscsi_validate_sense\fR(\fBuint8_t *\fR\fIsense_buffer\fR, \fBint\fR \fIsense_buf_len\fR, + \fBint *\fR\fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsense_buffer\fR\fR +.ad +.RS 17n +.rt +Pointer to a buffer containing \fBSCSI\fR sense data. The sense data is +expected in wire format starting at the response code. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsense_buf_len\fR\fR +.ad +.RS 17n +.rt +Length of sense buffer in bytes. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 17n +.rt +Returns additional properties of the sense data. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBscsi_validate_sense()\fR function returns the format of the sense data +contained in the provided sense buffer. If the response code field in the sense +data is not recognized or if there is not enough sense data to include sense +key, asc, and ascq then \fBscsi_validate_sense()\fR returns +\fBSENSE_UNUSABLE\fR. If the buffer contains usable sense data in fixed format, +the function returns \fBSENSE_FIXED_FORMAT\fR. If the buffer contains usable +sense data in descriptor format, the function returns \fBSENSE_DESCR_FORMAT\fR. +.sp +.LP +The following flags may be set as appropriate depending on the sense data: +.sp +.ne 2 +.mk +.na +\fB\fBSNS_BUF_OVERFLOW\fR\fR +.ad +.RS 20n +.rt +The sense data buffer provided for the request is too small to hold all the +sense data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSNS_BUF_DEFERRED\fR\fR +.ad +.RS 20n +.rt +The sense data contained in the buffer relates to an error that has occurred +during the processing of a successfully completed command, such as a cached +write that could not be commited to the media. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fBSENSE_UNUSABLE\fR\fR +.ad +.RS 22n +.rt +The response code from the sense data is unrecognized or not enough sense data +present to provide the \fBsense key\fR, \fBasc\fR, and \fBascq\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSENSE_FIXED_FORMAT\fR\fR +.ad +.RS 22n +.rt +The sense data in the buffer is in "fixed format". +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSENSE_DESCR_FORMAT\fR\fR +.ad +.RS 22n +.rt +The sense data in the buffer is in "descriptor format". +.RE + +.SH CONTEXT +.sp +.LP +The \fBscsi_validate_sense()\fR function can be called from user or interrupt +context. +.SH SEE ALSO +.sp +.LP +\fBscsi_ext_sense_fields\fR(9F), \fBscsi_find_sense_descr\fR(9F), +\fBscsi_sense_asc\fR(9F), \fBscsi_sense_ascq\fR(9F), +\fBscsi_sense_cmdspecific_uint64\fR(9F), \fBscsi_sense_info_uint64\fR(9F), +\fBscsi_sense_key\fR(9F) diff --git a/usr/src/man/man9f/scsi_vu_errmsg.9f b/usr/src/man/man9f/scsi_vu_errmsg.9f new file mode 100644 index 0000000000..0d8fc4ec08 --- /dev/null +++ b/usr/src/man/man9f/scsi_vu_errmsg.9f @@ -0,0 +1,291 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH scsi_vu_errmsg 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +scsi_vu_errmsg \- display a SCSI request sense message +.SH SYNOPSIS +.LP +.nf +#include <sys/scsi/scsi.h> + + + +\fBvoid\fR \fBscsi_vu_errmsg\fR(\fBstruct scsi_pkt\fR \fI*pktp\fR, \fBchar\fR \fI*drv_name\fR, \fBint severity,\fR + \fBint err_blkno,\fR \fBstruct scsi_key_strings\fR \fI*cmdlist\fR, + \fBstruct scsi_extended_sense\fR \fI*sensep\fR, + \fBstruct scsi_asq_key_strings\fR \fI*asc_list\fR, + \fBchar **decode_fru struct scsi_device\fR\fI*\fR, char \fI*\fR, int, char); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.LP +The following parameters are supported: +.sp +.ne 2 +.mk +.na +\fB\fIdevp\fR\fR +.ad +.RS 14n +.rt +Pointer to the \fBscsi_device\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpktp\fR\fR +.ad +.RS 14n +.rt +Pointer to a \fBscsi_pkt\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdrv_name\fR\fR +.ad +.RS 14n +.rt +String used by \fBscsi_log\fR(9F). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIseverity\fR\fR +.ad +.RS 14n +.rt +Error severity level, maps to severity strings below. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIblkno\fR\fR +.ad +.RS 14n +.rt +Requested block number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerr_blkno\fR\fR +.ad +.RS 14n +.rt +Error block number. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmdlist\fR\fR +.ad +.RS 14n +.rt +An array of SCSI command description strings. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsensep\fR\fR +.ad +.RS 14n +.rt +A pointer to a \fBscsi_extended_sense\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIasc_list\fR\fR +.ad +.RS 14n +.rt +A pointer to a array of asc and ascq message list.The list must be terminated +with \fB-1\fR asc value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdecode_fru\fR\fR +.ad +.RS 14n +.rt +This is a function pointer that will be called after the entire sense +information has been decoded. The parameters will be the scsi_device structure +to identify the device. Second argument will be a pointer to a buffer of length +specified by third argument. The fourth argument will be the FRU byte. +\fIdecode_fru\fR might be \fINULL\fR if no special decoding is required. +\fIdecode_fru\fR is expected to return pointer to a char string if decoding +possible and \fINULL\fR if no decoding is possible. +.RE + +.SH DESCRIPTION +.sp +.LP +This function is very similar to \fBscsi_errmsg\fR(9F) but allows decoding of +vendor-unique ASC/ASCQ and FRU information. +.sp +.LP +The \fBscsi_vu_errmsg()\fR function interprets the request sense information in +the \fIsensep\fR pointer and generates a standard message that is displayed +using \fBscsi_log\fR(9F). It first searches the list array for a matching +vendor unique code if supplied. If it does not find one in the list then the +standard list is searched. The first line of the message is always a +\fBCE_WARN\fR, with the continuation lines being \fBCE_CONT\fR. \fIsensep\fR +may be \fINULL\fR, in which case no sense key or vendor information is +displayed. +.sp +.LP +The driver should make the determination as to when to call this function based +on the severity of the failure and the severity level that the driver wants to +report. +.sp +.LP +The \fBscsi_device\fR(9S) structure denoted by \fIdevp\fR supplies the +identification of the device that requested the display. \fIseverity\fR selects +which string is used in the Error Level: reporting, according to the table +below: +.sp +.in +2 +.nf + Severity Value: String: + SCSI_ERR_ALL All + SCSI_ERR_UNKNOWN Unknown + SCSI_ERR_INFO Information + SCSI_ERR_RECOVERED Recovered + SCSI_ERR_RETRYABLE Retryable + SCSI_ERR_FATAL Fatal +.fi +.in -2 + +.sp +.LP +\fIblkno\fR is the block number of the original request that generated the +error. \fIerr_blkno\fR is the block number where the error occurred. +\fIcmdlist\fR is a mapping table for translating the SCSI command code in pktp +to the actual command string. +.sp +.LP +The \fIcmdlist\fR is described in the structure below: +.sp +.in +2 +.nf +struct scsi_key_strings { + int key; + char *message; +}; +.fi +.in -2 + +.sp +.LP +For a basic SCSI disk, the following list is appropriate: +.sp +.in +2 +.nf + static struct scsi_key_strings scsi_cmds[] = { + 0x00, "test unit ready", + 0x01, "rezero/rewind", + 0x03, "request sense", + 0x04, "format", + 0x07, "reassign", + 0x08, "read", + 0x0a, "write", + 0x0b, "seek", + 0x12, "inquiry", + 0x15, "mode select", + 0x16, "reserve", + 0x17, "release", + 0x18, "copy", + 0x1a, "mode sense", + 0x1b, "start/stop", + 0x1e, "door lock", + 0x28, "read(10)", + 0x2a, "write(10)", + 0x2f, "verify", + 0x37, "read defect data", + 0x3b, "write buffer", + -1, NULL + }; +.fi +.in -2 + +.SH CONTEXT +.sp +.LP +The \fBscsi_vu_errmsg()\fR function may be called from user, interrupt, or +kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBscsi_vu_errmsg()\fR +.sp +.in +2 +.nf + struct scsi_asq_key_strings cd_slist[] = { + 0x81, 0, "Logical Unit is inaccessable", + -1, 0, NULL, + }; + + + scsi_vu_errmsg(devp, pkt, "sd", + SCSI_ERR_INFO, bp->b_blkno, err_blkno, + sd_cmds, rqsense, cd_list, + my_decode_fru); +.fi +.in -2 + +.sp +.LP +This generates the following console warning: + +.sp +.in +2 +.nf +WARNING: /sbus@1,f8000000/esp@0,800000/sd@1,0 (sd1): + Error for Command: read Error Level: Informational + Requested Block: 23936 Error Block: 23936 + Vendor: XYZ Serial Number: 123456 + Sense Key: Unit Attention + ASC: 0x81 (Logical Unit is inaccessable), ASCQ: 0x0 + FRU: 0x11 (replace LUN 1, located in slot 1) +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBcmn_err\fR(9F), \fBscsi_errmsg\fR(9F), \fBscsi_log\fR(9F), +\fBscsi_errmsg\fR(9F), \fBscsi_asc_key_strings\fR(9S), \fBscsi_device\fR(9S), +\fBscsi_extended_sense\fR(9S), \fBscsi_pkt\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/semaphore.9f b/usr/src/man/man9f/semaphore.9f new file mode 100644 index 0000000000..9c960ec09c --- /dev/null +++ b/usr/src/man/man9f/semaphore.9f @@ -0,0 +1,185 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH semaphore 9F "7 May 1997" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +semaphore, sema_init, sema_destroy, sema_p, sema_p_sig, sema_v, sema_tryp \- +semaphore functions +.SH SYNOPSIS +.LP +.nf +#include <sys/ksynch.h> + + + +\fBvoid\fR \fBsema_init\fR(\fBksema_t *\fR\fIsp\fR, \fBuint_t\fR \fIval\fR, \fBchar *\fR\fIname\fR, \fBksema_type_t\fR \fItype\fR, + \fBvoid *\fR\fIarg\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsema_destroy\fR(\fBksema_t *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsema_p\fR(\fBksema_t *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBsema_v\fR(\fBksema_t *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBsema_p_sig\fR(\fBksema_t *\fR\fIsp\fR); +.fi + +.LP +.nf +\fBint\fR \fBsema_tryp\fR(\fBksema_t *\fR\fIsp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris \fBDDI\fR specific (Solaris \fBDDI\fR). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsp\fR\fR +.ad +.RS 8n +.rt +A pointer to a semaphore, type \fBksema_t\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIval\fR\fR +.ad +.RS 8n +.rt +Initial value for semaphore. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 8n +.rt +Descriptive string. This is obsolete and should be \fINULL\fR. (Non-\fINULL\fR +strings are legal, but they are a waste of kernel memory.) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 8n +.rt +Variant type of the semaphore. Currently, only \fBSEMA_DRIVER\fR is supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 8n +.rt +Type-specific argument; should be \fINULL\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +These functions implement counting semaphores as described by Dijkstra. A +semaphore has a value which is atomically decremented by \fBsema_p()\fR and +atomically incremented by \fBsema_v()\fR. The value must always be greater than +or equal to zero. If \fBsema_p()\fR is called and the value is zero, the +calling thread is blocked until another thread performs a \fBsema_v()\fR +operation on the semaphore. +.sp +.LP +Semaphores are initialized by calling \fBsema_init()\fR. The argument, +\fBval\fR, gives the initial value for the semaphore. The semaphore storage is +provided by the caller but more may be dynamically allocated, if necessary, by +\fBsema_init()\fR. For this reason, \fBsema_destroy()\fR should be called +before deallocating the storage containing the semaphore. +.sp +.LP +The \fBsema_p_sig()\fR function decrements the semaphore, as does +\fBsema_p()\fR. However, if the semaphore value is zero, \fBsema_p_sig()\fR +will return without decrementing the value if a signal (that is, from +\fBkill\fR(2)) is pending for the thread. +.sp +.LP +The \fBsema_tryp()\fR function will decrement the semaphore value only if it is +greater than zero, and will not block. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fB\fB0\fR\fR +.ad +.RS 5n +.rt +\fBsema_tryp()\fR could not decrement the semaphore value because it was zero. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB1\fR\fR +.ad +.RS 5n +.rt +\fBsema_p_sig()\fR was not able to decrement the semaphore value and detected a +pending signal. +.RE + +.SH CONTEXT +.sp +.LP +These functions can be called from user, interrupt, or kernel context, except +for \fBsema_init()\fR and \fBsema_destroy()\fR, which can be called from user +or kernel context only. None of these functions can be called from a high-level +interrupt context. In most cases, \fBsema_v()\fR and \fBsema_p()\fR should not +be called from any interrupt context. +.sp +.LP +If \fBsema_p()\fR is used from interrupt context, lower-priority interrupts +will not be serviced during the wait. This means that if the thread that will +eventually perform the \fBsema_v()\fR becomes blocked on anything that requires +the lower-priority interrupt, the system will hang. +.sp +.LP +For example, the thread that will perform the \fBsema_v()\fR may need to first +allocate memory. This memory allocation may require waiting for paging +\fBI/O\fR to complete, which may require a lower-priority disk or network +interrupt to be serviced. In general, situations like this are hard to predict, +so it is advisable to avoid waiting on semaphores or condition variables in an +interrupt context. +.SH SEE ALSO +.sp +.LP +\fBkill\fR(2), \fBcondvar\fR(9F), \fBmutex\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/stoi.9f b/usr/src/man/man9f/stoi.9f new file mode 100644 index 0000000000..8b54833ae4 --- /dev/null +++ b/usr/src/man/man9f/stoi.9f @@ -0,0 +1,90 @@ +'\" te +.\" Copyright (c) 2006, 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 stoi 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +stoi, numtos \- convert between an integer and a decimal string +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> + +\fBint\fR \fBstoi\fR(\fBchar\fR \fI**str\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBnumtos\fR(\fBunsigned long\fR \fInum\fR, \fBchar *\fR\fIs\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIstr\fR\fR +.ad +.RS 7n +.rt +Pointer to a character string to be converted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInum\fR\fR +.ad +.RS 7n +.rt +Decimal number to be converted to a character string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIs\fR\fR +.ad +.RS 7n +.rt +Character buffer to hold converted decimal number. +.RE + +.SH DESCRIPTION +.SS "\fBstoi()\fR" +.sp +.LP +The \fBstoi()\fR function returns the integer value of a string of decimal +numeric characters beginning at \fI**str\fR. No overflow checking is done. +\fI*str\fR is updated to point at the last character examined. +.SS "\fBnumtos()\fR" +.sp +.LP +The \fBnumtos()\fR function converts a \fBlong\fR into a null-terminated +character string. No bounds checking is done. The caller must ensure there is +enough space to hold the result. +.SH RETURN VALUES +.sp +.LP +The \fBstoi()\fR function returns the integer value of the string \fIstr\fR. +.SH CONTEXT +.sp +.LP +The \fBstoi()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +The \fBstoi()\fR function handles only positive integers; it does not handle +leading minus signs. diff --git a/usr/src/man/man9f/string.9f b/usr/src/man/man9f/string.9f new file mode 100644 index 0000000000..eaaab44a1d --- /dev/null +++ b/usr/src/man/man9f/string.9f @@ -0,0 +1,278 @@ +'\" 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 string 9F "27 Feb 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +string, strcasecmp, strncasecmp, strncat, strlcat, strchr, strrchr, strcmp, +strncmp, strcpy, strncpy, strlcpy, strfree, strspn, strdup, ddi_strdup, strlen, +strnlen \- string operations +.SH SYNOPSIS +.LP +.nf +#include <sys/ddi.h> + +\fBint\fR \fBstrcasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.LP +.nf +\fBint\fR \fBstrncasecmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrncat\fR(\fBchar *\fR \fIs1\fR, \fBconst char *\fR \fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBstrlcat\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrchr\fR(\fBconst char *\fR\fIstr\fR, \fBint\fR \fIchr\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrrchr\fR(\fBconst char *\fR\fIstr\fR, \fBint\fR \fIchr\fR); +.fi + +.LP +.nf +\fBint\fR \fBstrcmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.LP +.nf +\fBint\fR \fBstrncmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrcpy\fR(\fBchar *\fR \fIdst\fR, \fBconst char *\fR \fIsrc\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrncpy\fR(\fBchar *\fR \fIdst\fR, \fBconst char *\fR \fIsrc\fR, \fBsize_t\fR \fIn\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBstrlcpy\fR(\fBchar *\fR\fIdst\fR, \fBconst char *\fR\fIsrc\fR, \fBsize_t\fR \fIdstsize\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBstrfree\fR(\fBchar *\fR\fIs\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBstrspn\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBstrdup\fR(\fBconst char *\fR\fIs1\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBddi_strdup\fR(\fBconst char *\fR\fIs1\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBstrlen\fR(\fBconst char *\fR\fIs\fR); +.fi + +.LP +.nf +\fBsize_t\fR \fBstrnlen\fR(\fBconst char *\fR\fIs\fR, \fBsize_t\fR \fIn\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH DESCRIPTION +.sp +.LP +The arguments \fIs\fR, \fIs1\fR, and \fIs2\fR point to strings (arrays of +characters terminated by a null character). The \fBstrcat()\fR, +\fBstrncat()\fR, \fBstrlcat()\fR, \fBstrcpy()\fR, \fBstrncpy()\fR, +\fBstrlcpy()\fR, and \fBstrfree()\fR functions all alter their first argument. +Additionally, the \fBstrcpy()\fR function does not check for overflow of the +array. +.SS "\fBstrcasecmp()\fR, \fBstrncasecmp()\fR" +.sp +.LP +The \fBstrcasecmp()\fR and \fBstrncasecmp()\fR functions are case-insensitive +versions of \fBstrcmp()\fR and \fBstrncmp()\fR respectively, described below. +They assume the \fBASCII\fR character set and ignore differences in case when +comparing lower and upper case characters. +.SS "\fBstrncat()\fR, \fBstrlcat()\fR" +.sp +.LP +The \fBstrncat()\fR function appends at most \fIn\fR characters of string +\fIs2\fR, including the terminating null character, to the end of string +\fIs1\fR. It returns a pointer to the null-terminated result. The initial +character of \fIs2\fR overrides the null character at the end of \fIs1\fR. If +copying takes place between objects that overlap, the behavior of +\fBstrncat()\fRand \fBstrlcat()\fR is undefined. +.sp +.LP +The \fBstrlcat()\fR function appends at most +(\fIdstsize\fR-\fBstrlen\fR(\fIdst\fR)-1) characters of \fIsrc\fR to \fIdst\fR +(\fIdstsize\fR being the size of the string buffer \fIdst\fR). If the string +pointed to by \fIdst\fR contains a null-terminated string that fits into +\fIdstsize\fR bytes when \fBstrlcat()\fR is called, the string pointed to by +\fIdst\fR will be a null-terminated string that fits in \fIdstsize\fR bytes +(including the terminating null character) when it completes, and the initial +character of \fIsrc\fR will override the null character at the end of +\fIdst\fR. If the string pointed to by \fIdst\fR is longer than \fIdstsize\fR +bytes when \fBstrlcat()\fR is called, the string pointed to by \fIdst\fR will +not be changed. The function returns +\fBmin\fR{\fIdstsize\fR,\fBstrlen\fR(\fIdst\fR)}+\fBstrlen\fR(\fIsrc\fR). +Buffer overflow can be checked as follows: +.sp +.in +2 +.nf +if (strlcat(dst, src, dstsize) >= dstsize) + return \(mi1; +.fi +.in -2 + +.SS "\fBstrchr()\fR, \fBstrrchr()\fR" +.sp +.LP +The \fBstrchr()\fR function returns a pointer to the first occurrence of +\fIc\fR (converted to a \fBchar\fR) in string \fIs\fR, or a null pointer if +\fIc\fR does not occur in the string. The \fBstrrchr()\fR function returns a +pointer to the last occurrence of \fIc\fR. The null character terminating a +string is considered to be part of the string. +.SS "\fBstrcmp()\fR, \fBstrncmp()\fR" +.sp +.LP +The \fBstrcmp()\fR function compares two strings byte-by-byte, according to the +ordering of your machine's character set. The function returns an integer +greater than, equal to, or less than 0, if the string pointed to by \fIs1\fR +is greater than, equal to, or less than the string pointed to by \fIs2\fR +respectively. The sign of a non-zero return value is determined by the sign of +the difference between the values of the first pair of bytes that differ in the +strings being compared. The \fBstrncmp()\fR function makes the same comparison +but looks at a maximum of \fIn\fR bytes. Bytes following a null byte are not +compared. +.SS "\fBstrcpy()\fR, \fBstrncpy()\fR, \fBstrlcpy()\fR" +.sp +.LP +The \fBstrcpy()\fR function copies string \fIs2\fR to \fIs1\fR, including the +terminating null character, stopping after the null character has been copied. +The \fBstrncpy()\fR function copies exactly \fIn\fR bytes, truncating \fIs2\fR +or adding null characters to \fIs1\fR if necessary. The result will not be +null-terminated if the length of \fIs2\fR is \fIn\fR or more. Each function +returns \fIs1\fR. If copying takes place between objects that overlap, the +behavior of \fBstrcpy()\fR, \fBstrncpy()\fR, and \fBstrlcpy()\fR is undefined. +.sp +.LP +The \fBstrlcpy()\fR function copies at most \fIdstsize\fR\(mi1 characters +(\fIdstsize\fR being the size of the string buffer \fIdst\fR) from \fIsrc\fR +to \fIdst\fR, truncating \fIsrc\fR if necessary. The result is always +null-terminated. The function returns \fBstrlen\fR(\fIsrc\fR). Buffer overflow +can be checked as follows: +.sp +.in +2 +.nf +if (strlcpy(dst, src, dstsize) >= dstsize) + return \(mi1; +.fi +.in -2 + +.SS "\fBstrfree()\fR" +.sp +.LP +The \fBstrfree()\fR function frees the memory associated with the string +pointed to by \fIs\fR. This memory pointed to by \fIs\fR must be of size +\fBstrlen\fR(\fIs\fR)+1, and must have been allocated (either directly or +indirectly) by \fBkmem_alloc\fR(9F) or \fBkmem_zalloc\fR(9F). +.SS "\fBstrspn()\fR" +.sp +.LP +The \fBstrspn()\fR function returns the length of the initial segment of string +\fIs1\fR that consists entirely of characters from string \fIs2\fR. +.SS "\fBstrdup()\fR, \fBddi_strdup()\fR" +.sp +.LP +The \fBddi_strdup()\fR function returns a pointer to a new string that is a +duplicate of the string pointed to by \fIs1\fR. The returned pointer can be +passed to \fBstrfree()\fR or \fBkmem_free\fR(9F). The space for the new string +is obtained using \fBkmem_alloc()\fR. flag can be either \fBKM_SLEEP\fR or +\fBKM_NOSLEEP\fR, and determines whether the caller can sleep for memory. +\fBKM_SLEEP\fR allocations may sleep but are guaranteed to succeed. +\fBKM_NOSLEEP\fR allocations are guaranteed not to sleep but may fail (return +\fINULL\fR) if no memory is currently available. +.sp +.LP +The \fBstrdup()\fR function behaves the same as the \fBddi_strdup()\fR when +called with the \fBKM_SLEEP\fR flag. This means that \fBstrdup()\fR can sleep +until memory is available and will always succeed. +.SS "\fBstrlen()\fR, \fBstrnlen()\fR" +.sp +.LP +The \fBstrlen()\fR function returns the number of bytes in \fIs\fR, not +including the terminating null character. +.sp +.LP +The \fBstrnlen()\fR function returns the smaller of \fIn\fR or the number of +bytes in \fIs\fR, not including the terminating null character. The +\fBstrnlen()\fR function never examines more than \fIn\fR bytes of the string +pointed to by \fIs\fR. +.SH CONTEXT +.sp +.LP +The \fBstrdup()\fR and \fBddi_strdup()\fR functions can be called from user or +kernel context. +.sp +.LP +The \fBddi_strdup()\fR function can be called from interrupt context only if +the \fBKM_NOSLEEP\fR flag is set. +.sp +.LP +All the other string manipulation functions can be called from user, interrupt, +or kernel context. +.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 +\fBstring\fR(3C), \fBattributes\fR(5), \fBbcopy\fR(9F), \fBddi_copyin\fR(9F), +\fBkmem_alloc\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +If copying takes place between objects that overlap, the behavior of +\fBstrlcat()\fR, \fBstrncat()\fR, \fBstrcpy()\fR, \fBstrlcpy()\fR, and +\fBstrncpy()\fR is undefined. diff --git a/usr/src/man/man9f/strlog.9f b/usr/src/man/man9f/strlog.9f new file mode 100644 index 0000000000..f35f7c44fa --- /dev/null +++ b/usr/src/man/man9f/strlog.9f @@ -0,0 +1,215 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. +.\" All Rights Reserved. +.\" Copyright 2006 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 strlog 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +strlog \- submit messages to the log driver +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> +#include <sys/strlog.h> +#include <sys/log.h> + + + +\fBint\fR \fBstrlog\fR(\fBshort\fR \fImid\fR, \fBshort\fR \fIsid\fR, \fBchar\fR \fIlevel\fR, + \fBunsigned short\fR \fIflags\fR, \fBchar *\fR\fIfmt\fR, ...); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImid\fR\fR +.ad +.RS 9n +.rt +Identification number of the module or driver submitting the message (in the +case of a module, its \fBmi_idnum\fR value from \fBmodule_info\fR(9S)). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsid\fR\fR +.ad +.RS 9n +.rt +Identification number for a particular minor device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlevel\fR\fR +.ad +.RS 9n +.rt +Tracing level for selective screening of low priority messages. Larger values +imply less important information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 9n +.rt +Valid flag values are: +.sp +.ne 2 +.mk +.na +\fB\fBSL_ERROR\fR\fR +.ad +.RS 14n +.rt +Message is for error logger. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSL_TRACE\fR\fR +.ad +.RS 14n +.rt +Message is for trace. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSL_NOTIFY\fR\fR +.ad +.RS 14n +.rt +Mail copy of message to system administrator. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSL_CONSOLE\fR\fR +.ad +.RS 14n +.rt +Log message to console. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSL_FATAL\fR\fR +.ad +.RS 14n +.rt +Error is fatal. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSL_WARN\fR\fR +.ad +.RS 14n +.rt +Error is a warning. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBSL_NOTE\fR\fR +.ad +.RS 14n +.rt +Error is a notice. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfmt\fR\fR +.ad +.RS 9n +.rt +\fBprintf\fR(3C) style format string. \fB%e\fR, \fB%g\fR, and \fB%G\fR formats +are not allowed but \fB%s\fR is supported. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBstrlog()\fR function expands the \fBprintf\fR(3C) style format string +passed to it, that is, the conversion specifiers are replaced by the actual +argument values in the format string. The 32-bit representations of the +arguments (up to \fBNLORGARGS\fR) follow the string starting at the next 32-bit +boundary following the string. Note that the 64-bit argument will be truncated +to 32-bits here but will be fully represented in the string. +.sp +.LP +The messages can be retrieved with the \fBgetmsg\fR(2) system call. The +\fIflags\fR argument specifies the type of the message and where it is to be +sent. \fBstrace\fR(1M) receives messages from the \fBlog\fR driver and sends +them to the standard output. \fBstrerr\fR(1M) receives error messages from the +\fBlog\fR driver and appends them to a file called +\fB/var/adm/streams/error.\fR\fImm-dd\fR, where \fImm-dd\fR identifies the date +of the error message. +.SH RETURN VALUES +.sp +.LP +The \fBstrlog()\fR function returns \fB0\fR if it fails to submit the message +to the \fBlog\fR(7D) driver and \fB1\fR otherwise. +.SH CONTEXT +.sp +.LP +The \fBstrlog()\fR function can be called from user, interrupt, or kernel +context. +.SH FILES +.sp +.ne 2 +.mk +.na +\fB\fB/var/adm/streams/error.\fR\fImm-dd\fR\fR +.ad +.sp .6 +.RS 4n +Error messages dated \fImm-dd\fR appended by \fBstrerr\fR(1M) from the +\fBlog\fR driver +.RE + +.SH SEE ALSO +.sp +.LP +\fBstrace\fR(1M), \fBstrerr\fR(1M), \fBgetmsg\fR(2), \fBlog\fR(7D), +\fBmodule_info\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/strqget.9f b/usr/src/man/man9f/strqget.9f new file mode 100644 index 0000000000..cf40bae5cf --- /dev/null +++ b/usr/src/man/man9f/strqget.9f @@ -0,0 +1,185 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH strqget 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +strqget \- get information about a queue or band of the queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBstrqget\fR(\fBqueue_t *\fR\fIq\fR, \fBqfields_t\fR \fIwhat\fR, \fBunsigned char\fR \fIpri\fR, \fBvoid *\fR\fIvalp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 8n +.rt +Pointer to the queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwhat\fR\fR +.ad +.RS 8n +.rt +Field of the \fBqueue\fR structure for (or the specified priority band) to +return information about. Valid values are one of: +.sp +.ne 2 +.mk +.na +\fB\fBQHIWAT\fR\fR +.ad +.RS 11n +.rt +High water mark. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQLOWAT\fR\fR +.ad +.RS 11n +.rt +Low water mark. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQMAXPSZ\fR\fR +.ad +.RS 11n +.rt +Largest packet accepted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQMINPSZ\fR\fR +.ad +.RS 11n +.rt +Smallest packet accepted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQCOUNT\fR\fR +.ad +.RS 11n +.rt +Approximate size (in bytes) of data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQFIRST\fR\fR +.ad +.RS 11n +.rt +First message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQLAST\fR\fR +.ad +.RS 11n +.rt +Last message. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQFLAG\fR\fR +.ad +.RS 11n +.rt +Status. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpri\fR\fR +.ad +.RS 8n +.rt +Priority band of interest. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvalp\fR\fR +.ad +.RS 8n +.rt +The address of where to store the value of the requested field. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBstrqget()\fR function gives drivers and modules a way to get information +about a queue or a particular band of a queue without directly accessing +STREAMS data structures, thus insulating them from changes in the +implementation of these data structures from release to release. +.SH RETURN VALUES +.sp +.LP +On success, \fB0\fR is returned and the value of the requested field is stored +in the location pointed to by \fIvalp\fR. An error number is returned on +failure. +.SH CONTEXT +.sp +.LP +The \fBstrqget()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBstrqset\fR(9F), \fBqueue\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/strqset.9f b/usr/src/man/man9f/strqset.9f new file mode 100644 index 0000000000..1ebbfafe00 --- /dev/null +++ b/usr/src/man/man9f/strqset.9f @@ -0,0 +1,144 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH strqset 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +strqset \- change information about a queue or band of the queue +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBstrqset\fR(\fBqueue_t *\fR\fIq\fR, \fBqfields_t\fR \fIwhat\fR, \fBunsigned char\fR \fIpri\fR, \fBintptr_t\fR \fIval\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIq\fR\fR +.ad +.RS 8n +.rt +Pointer to the queue. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwhat\fR\fR +.ad +.RS 8n +.rt +Field of the \fBqueue\fR structure (or the specified priority band) to return +information about. Valid values are one of: +.sp +.ne 2 +.mk +.na +\fB\fBQHIWAT\fR\fR +.ad +.RS 11n +.rt +High water mark. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQLOWAT\fR\fR +.ad +.RS 11n +.rt +Low water mark. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQMAXPSZ\fR\fR +.ad +.RS 11n +.rt +Largest packet accepted. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBQMINPSZ\fR\fR +.ad +.RS 11n +.rt +Smallest packet accepted. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpri\fR\fR +.ad +.RS 8n +.rt +Priority band of interest. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIval\fR\fR +.ad +.RS 8n +.rt +The value for the field to be changed. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBstrqset()\fR function gives drivers and modules a way to change +information about a queue or a particular band of a queue without directly +accessing STREAMS data structures. +.SH RETURN VALUES +.sp +.LP +On success, \fB0\fR is returned. \fBEINVAL\fR is returned if an undefined +attribute is specified. +.SH CONTEXT +.sp +.LP +The \fBstrqset()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBstrqget\fR(9F), \fBqueue\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH NOTES +.sp +.LP +When lowering existing values, set \fBQMINPSZ\fR before setting \fBQMAXPSZ\fR; +when raising existing values, set \fBQMAXPSZ\fR before setting \fBQMINPSZ\fR. diff --git a/usr/src/man/man9f/swab.9f b/usr/src/man/man9f/swab.9f new file mode 100644 index 0000000000..4b895fc5f6 --- /dev/null +++ b/usr/src/man/man9f/swab.9f @@ -0,0 +1,78 @@ +'\" te +.\" Copyright (c) 2006, 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 swab 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +swab \- swap bytes in 16-bit halfwords +.SH SYNOPSIS +.LP +.nf +#include <sys/sunddi.h> + + + +\fBvoid\fR \fBswab\fR(\fBvoid *\fR\fIsrc\fR, \fBvoid *\fR\fIdst\fR, \fBsize_t\fR \fInbytes\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsrc\fR\fR +.ad +.RS 10n +.rt +A pointer to the buffer containing the bytes to be swapped. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdst\fR\fR +.ad +.RS 10n +.rt +A pointer to the destination buffer where the swapped bytes will be written. If +\fIdst\fR is the same as \fIsrc\fR the buffer will be swapped in place. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInbytes\fR\fR +.ad +.RS 10n +.rt +Number of bytes to be swapped, rounded down to the nearest half-word. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBswab()\fR function copies the bytes in the buffer pointed to by +\fIsrc\fR to the buffer pointer to by \fIdst\fR, swapping the order of adjacent +bytes in half-word pairs as the copy proceeds. A total of \fInbytes\fR bytes +are copied, rounded down to the nearest half-word. +.SH CONTEXT +.sp +.LP +The \fBswab()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fIWriting Device Drivers\fR +.SH NOTES +.sp +.LP +Since \fBswab()\fR operates byte-by-byte, it can be used on non-aligned +buffers. diff --git a/usr/src/man/man9f/taskq.9f b/usr/src/man/man9f/taskq.9f new file mode 100644 index 0000000000..2ad3c050ee --- /dev/null +++ b/usr/src/man/man9f/taskq.9f @@ -0,0 +1,295 @@ +'\" te +.\" Copyright (c) 2005, 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 taskq 9F "1 Mar 2005" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +taskq, ddi_taskq_create, ddi_taskq_destroy, ddi_taskq_dispatch, ddi_taskq_wait, +ddi_taskq_suspend, taskq_suspended, ddi_taskq_resume \- Kernel task queue +operations +.SH SYNOPSIS +.LP +.nf +#include <sys/sunddi.h> + +\fBddi_taskq_t *\fR\fBddi_taskq_create\fR(\fBdev_info_t *\fR\fIdip\fR, \fBconst char *\fR\fIname\fR, + \fBint\fR \fInthreads\fR, \fBpri_t\fR \fIpri\fR, \fBuint_t\fR \fIcflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_taskq_destroy\fR(\fBddi_taskq_t *\fR\fItq\fR); +.fi + +.LP +.nf +\fBint\fR \fBddi_taskq_dispatch\fR(\fBddi_taskq_t *\fR\fItq\fR, \fBvoid (*\fR \fIfunc)\fR(void *), + \fBvoid *\fR\fIarg\fR, \fBuint_t\fR \fIdflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_taskq_wait\fR(\fBddi_taskq_t *\fR\fItq\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_taskq_suspend\fR(\fBddi_taskq_t *\fR\fItq\fR); +.fi + +.LP +.nf +\fBboolean_t\fR \fBddi_taskq_suspended\fR(\fBddi_taskq_t *\fR\fItq\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBddi_taskq_resume\fR(\fBddi_taskq_t *\fR\fItq\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 12n +.rt +Pointer to the device's dev_info structure. May be NULL for kernel +modules that do not have an associated dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 12n +.rt +Descriptive string. Only alphanumeric characters can be used in name +and spaces are not allowed. The name should be unique. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInthreads\fR\fR +.ad +.RS 12n +.rt +Number of threads servicing the task queue. Note that the request ordering is +guaranteed (tasks are processed in the order scheduled) if the \fBtaskq\fR is +created with a single servicing thread. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpri\fR\fR +.ad +.RS 12n +.rt +Priority of threads servicing the task queue. Drivers and modules should +specify TASKQ_DEFAULTPRI. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcflags\fR\fR +.ad +.RS 12n +.rt +Should pass 0 as flags. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfunc\fR\fR +.ad +.RS 12n +.rt +Callback function to call. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 12n +.rt +Argument to the callback function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdflags\fR\fR +.ad +.RS 12n +.rt +Possible \fIdflags\fR are: +.sp +.ne 2 +.mk +.na +\fBDDI_SLEEP\fR +.ad +.RS 15n +.rt +Allow sleeping (blocking) until memory is available. +.RE + +.sp +.ne 2 +.mk +.na +\fBDDI_NOSLEEP\fR +.ad +.RS 15n +.rt +Return DDI_FAILURE immediately if memory is not available. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItq\fR\fR +.ad +.RS 12n +.rt +Pointer to a task queue (ddi_taskq_t *). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItp\fR\fR +.ad +.RS 12n +.rt +Pointer to a thread structure. +.RE + +.SH DESCRIPTION +.sp +.LP +A kernel task queue is a mechanism for general-purpose asynchronous task +scheduling that enables tasks to be performed at a later time by another +thread. There are several reasons why you may utilize asynchronous task +scheduling: +.RS +4 +.TP +1. +You have a task that isn't time-critical, but a current code path that is. +.RE +.RS +4 +.TP +2. +You have a task that may require grabbing locks that a thread already holds. +.RE +.RS +4 +.TP +3. +You have a task that needs to block (for example, to wait for memory), but a +have a thread that cannot block in its current context. +.RE +.RS +4 +.TP +4. +You have a code path that can't complete because of a specific condition, +but also can't sleep or fail. In this case, the task is immediately queued and +then is executed after the condition disappears. +.RE +.RS +4 +.TP +5. +A task queue is just a simple way to launch multiple tasks in parallel. +.RE +.sp +.LP +A task queue consists of a list of tasks, together with one or more threads to +service the list. If a task queue has a single service thread, all tasks are +guaranteed to execute in the order they were dispatched. Otherwise they can be +executed in any order. Note that since tasks are placed on a list, execution of +one task and should not depend on the execution of another task or a deadlock +may occur. A \fBtaskq\fR created with a single servicing thread guarantees that +all the tasks are serviced in the order in which they are scheduled. +.sp +.LP +The \fBddi_taskq_create()\fR function creates a task queue instance. +.sp +.LP +The \fBddi_taskq_dispatch()\fR function places \fBtaskq\fR on the list for +later execution. The \fIdflag\fR argument specifies whether it is allowed sleep +waiting for memory. DDI_SLEEP dispatches can sleep and are guaranteed to +succeed. DDI_NOSLEEP dispatches are guaranteed not to sleep but may fail +(return \fBDDI_FAILURE\fR) if resources are not available. +.sp +.LP +The \fBddi_taskq_destroy()\fR function waits for any scheduled tasks to +complete, then destroys the \fBtaskq\fR. The caller should guarantee that no +new tasks are scheduled for the closing \fBtaskq\fR. +.sp +.LP +The \fBddi_taskq_wait()\fR function waits for all previously scheduled tasks to +complete. Note that this function does not stop any new task dispatches. +.sp +.LP +The \fBddi_taskq_suspend()\fR function suspends all task execution until +\fBddi_taskq_resume()\fR is called. Although \fBddi_taskq_suspend()\fR attempts +to suspend pending tasks, there are no guarantees that they will be suspended. +The only guarantee is that all tasks dispatched after \fBddi_taskq_suspend()\fR +will not be executed. Because it will trigger a deadlock, the +\fBddi_taskq_suspend()\fR function should never be called by a task executing +on a \fBtaskq\fR. +.sp +.LP +The \fBddi_taskq_suspended()\fR function returns \fBB_TRUE\fR if \fBtaskq\fR is +suspended, and \fBB_FALSE\fR otherwise. It is intended to ASSERT that the task +queue is suspended. +.sp +.LP +The \fBddi_taskq_resume()\fR function resumes task queue execution. +.SH RETURN VALUES +.sp +.LP +The \fBddi_taskq_create()\fR function creates an opaque handle that is used for +all other \fBtaskq\fR operations. It returns a \fBtaskq\fR pointer on success +and NULL on failure. +.sp +.LP +The \fBddi_taskq_dispatch()\fR function returns \fBDDI_FAILURE\fR if it can't +dispatch a task and returns \fBDDI_SUCCESS\fR if dispatch succeeded. +.sp +.LP +The \fBddi_taskq_suspended()\fR function returns \fBB_TRUE\fR if \fBtaskq\fR is +suspended. Otherwise \fBB_FALSE\fR is returned. +.SH CONTEXT +.sp +.LP +All functions may be called from the user or kernel contexts. +.sp +.LP +Addtionally, the \fBddi_taskq_dispatch\fR function may be called from the +interrupt context only if the DDI_NOSLEEP flag is set. diff --git a/usr/src/man/man9f/testb.9f b/usr/src/man/man9f/testb.9f new file mode 100644 index 0000000000..684edd66b8 --- /dev/null +++ b/usr/src/man/man9f/testb.9f @@ -0,0 +1,142 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, 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 testb 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +testb \- check for an available buffer +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBint\fR \fBtestb\fR(\fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 8n +.rt +Size of the requested buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpri\fR\fR +.ad +.RS 8n +.rt +Priority of the allocb request. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtestb()\fR function checks to see if an \fBallocb\fR(9F) call is likely +to succeed if a buffer of \fBsize\fR bytes at priority \fIpri\fR is requested. +Even if \fBtestb()\fR returns successfully, the call to \fBallocb\fR(9F) can +fail. The \fIpri\fR argument is no longer used, but is retained for +compatibility. +.SH RETURN VALUES +.sp +.LP +Returns \fB1\fR if a buffer of the requested size is available, and \fB0\fR if +one is not. +.SH CONTEXT +.sp +.LP +The \fBtestb()\fR function can be called user, interrupt, or kernel context. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBtestb()\fR example +.sp +.LP +In a service routine, if \fBcopymsg\fR(9F) fails (line 6), the message is put +back on the queue (line 7) and a routine, \fBtryagain\fR, is scheduled to be +run in one tenth of a second. Then the service routine returns. + +.sp +.LP +When the \fBtimeout\fR(9F) function runs, if there is no message on the front +of the queue, it just returns. Otherwise, for each message block in the first +message, check to see if an allocation would succeed. If the number of message +blocks equals the number we can allocate, then enable the service procedure. +Otherwise, reschedule \fBtryagain\fR to run again in another tenth of a second. +Note that \fBtryagain\fR is merely an approximation. Its accounting may be +faulty. Consider the case of a message comprised of two 1024-byte message +blocks. If there is only one free 1024-byte message block and no free 2048-byte +message blocks, then \fBtestb()\fR will still succeed twice. If no message +blocks are freed of these sizes before the service procedure runs again, then +the \fBcopymsg\fR(9F) will still fail. The reason \fBtestb()\fR is used here is +because it is significantly faster than calling \fBcopymsg\fR. We must minimize +the amount of time spent in a \fBtimeout()\fR routine. + +.sp +.in +2 +.nf +\fB1 xxxsrv(q) + 2 queue_t *q; + 3 { + 4 mblk_t *mp; + 5 mblk_t *nmp; + . . . + 6 if ((nmp = copymsg(mp)) == NULL) { + 7 putbq(q, mp); + 8 timeout(tryagain, (intptr_t)q, drv_usectohz(100000)); + 9 return; +10 } + . . . +11 } +12 +13 tryagain(q) +14 queue_t *q; +15 { +16 register int can_alloc = 0; +17 register int num_blks = 0; +18 register mblk_t *mp; +19 +20 if (!q->q_first) +21 return; +22 for (mp = q->q_first; mp; mp = mp->b_cont) { +23 num_blks++; +24 can_alloc += testb((mp->b_datap->db_lim - +25 mp->b_datap->db_base), BPRI_MED); +26 } +27 if (num_blks == can_alloc) +28 qenable(q); +29 else +30 timeout(tryagain, (intptr_t)q, drv_usectohz(100000)); +31 }\fR +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBallocb\fR(9F), \fBbufcall\fR(9F), \fBcopymsg\fR(9F), \fBtimeout\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR +.SH NOTES +.sp +.LP +The \fIpri\fR argument is provided for compatibility only. Its value is +ignored. diff --git a/usr/src/man/man9f/timeout.9f b/usr/src/man/man9f/timeout.9f new file mode 100644 index 0000000000..2fa1157b95 --- /dev/null +++ b/usr/src/man/man9f/timeout.9f @@ -0,0 +1,158 @@ +'\" te +.\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH timeout 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +timeout \- execute a function after a specified length of time +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> + + + +\fBtimeout_id_t\fR \fBtimeout\fR(\fBvoid (\fR\fI* func\fR)(void \fI*\fR), \fBvoid\fR \fI*arg\fR, + \fBclock_t\fR \fIticks\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIfunc\fR\fR +.ad +.RS 9n +.rt +Kernel function to invoke when the time increment expires. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIarg\fR\fR +.ad +.RS 9n +.rt +Argument to the function. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIticks\fR\fR +.ad +.RS 9n +.rt +Number of clock ticks to wait before the function is called. Use +\fBdrv_usectohz\fR(9F) to convert microseconds to clock ticks. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBtimeout()\fR function schedules the specified function to be called +after a specified time interval. The exact time interval over which the timeout +takes effect cannot be guaranteed, but the value given is a close +approximation. +.sp +.LP +The function called by \fBtimeout()\fR must adhere to the same restrictions as +a driver soft interrupt handler. +.sp +.LP +The \fBdelay\fR(9F) function calls \fBtimeout()\fR. Because \fBtimeout()\fR is +subject to priority inversion, drivers waiting on behalf of processes with +real-time constraints should use \fBcv_timedwait\fR(9F) rather than +\fBdelay()\fR. +.SH RETURN VALUES +.sp +.LP +The \fBtimeout()\fR function returns an opaque non-zero \fBtimeout\fR +identifier that can be passed to \fBuntimeout\fR(9F) to cancel the request. +.SH CONTEXT +.sp +.LP +The \fBtimeout()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBtimeout()\fR +.sp +.LP +In the following example, the device driver has issued an IO request and is +waiting for the device to respond. If the device does not respond within 5 +seconds, the device driver will print out an error message to the console. + +.sp +.in +2 +.nf +static void +xxtimeout_handler(void *arg) +{ + struct xxstate *xsp = (struct xxstate *)arg; + mutex_enter(&xsp->lock); + cv_signal(&xsp->cv); + xsp->flags |= TIMED_OUT; + mutex_exit(&xsp->lock); + xsp->timeout_id = 0; +} +static uint_t +xxintr(caddr_t arg) +{ + struct xxstate *xsp = (struct xxstate *)arg; + . + . + . + mutex_enter(&xsp->lock); + /* Service interrupt */ + cv_signal(&xsp->cv); + mutex_exit(&xsp->lock); + if (xsp->timeout_id != 0) { + (void) untimeout(xsp->timeout_id); + xsp->timeout_id = 0; + } + return(DDI_INTR_CLAIMED); +} +static void +xxcheckcond(struct xxstate *xsp) +{ + . + . + . + xsp->timeout_id = timeout(xxtimeout_handler, + xsp, (5 * drv_usectohz(1000000))); + mutex_enter(&xsp->lock); + while (/* Waiting for interrupt or timeout*/) + cv_wait(&xsp->cv, &xsp->lock); + if (xsp->flags & TIMED_OUT) + cmn_err(CE_WARN, "Device not responding"); + . + . + . + mutex_exit(&xsp->lock); + . + . + . +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBbufcall\fR(9F), \fBcv_timedwait\fR(9F), \fBddi_in_panic\fR(9F), +\fBdelay\fR(9F), \fBdrv_usectohz\fR(9F), \fBuntimeout\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/u8_strcmp.9f b/usr/src/man/man9f/u8_strcmp.9f new file mode 100644 index 0000000000..257fa04abe --- /dev/null +++ b/usr/src/man/man9f/u8_strcmp.9f @@ -0,0 +1,384 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH u8_strcmp 9F "18 Sep 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +u8_strcmp \- UTF-8 string comparison function +.SH SYNOPSIS +.LP +.nf +#include <sys/sunddi.h> + +\fBint\fR \fBu8_strcmp\fR(\fBconst char *\fR\fIs1\fR, \fBconst char *\fR\fIs2\fR, \fBsize_t\fR \fIn\fR, + \fBint\fR \fIflag\fR, \fBsize_t\fR \fIunicode_version\fR, \fBint *\fR\fIerrno\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIs1\fR, \fIs2\fR\fR +.ad +.RS 20n +.rt +Pointers to null-terminated UTF-8 strings +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIn\fR\fR +.ad +.RS 20n +.rt +The maximum number of bytes to be compared. If 0, the comparison is performed +until either or both of the strings are examined to the string terminating null +byte. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 20n +.rt +The possible comparison options constructed by a bit-wise-inclusive-OR of the +following values: +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_CS\fR\fR +.ad +.sp .6 +.RS 4n +Perform case-sensitive string comparison. This is the default. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_CI_UPPER\fR\fR +.ad +.sp .6 +.RS 4n +Perform case-insensitive string comparison based on Unicode upper case +converted results of \fIs1\fR and \fIs2\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_CI_LOWER\fR\fR +.ad +.sp .6 +.RS 4n +Perform case-insensitive string comparison based on Unicode lower case +converted results of \fIs1\fR and \fIs2\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_NFD\fR\fR +.ad +.sp .6 +.RS 4n +Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by +using Unicode Normalization Form D. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_NFC\fR\fR +.ad +.sp .6 +.RS 4n +Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by +using Unicode Normalization Form C. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_NFKD\fR\fR +.ad +.sp .6 +.RS 4n +Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by +using Unicode Normalization Form KD. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_STRCMP_NFKC\fR\fR +.ad +.sp .6 +.RS 4n +Perform string comparison after \fIs1\fR and \fIs2\fR have been normalized by +using Unicode Normalization Form KC. +.RE + +Only one case-sensitive or case-insensitive option is allowed. Only one Unicode +Normalization option is allowed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIunicode_version\fR\fR +.ad +.RS 20n +.rt +The version of Unicode data that should be used during comparison. The +following values are supported: +.sp +.ne 2 +.mk +.na +\fB\fBU8_UNICODE_320\fR\fR +.ad +.sp .6 +.RS 4n +Use Unicode 3.2.0 data during comparison. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_UNICODE_500\fR\fR +.ad +.sp .6 +.RS 4n +Use Unicode 5.0.0 data during comparison. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_UNICODE_LATEST\fR\fR +.ad +.sp .6 +.RS 4n +Use the latest Unicode version data available, which is Unicode 5.0.0. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerrno\fR\fR +.ad +.RS 20n +.rt +A non-zero value indicates that an error has occurred during comparison. The +following values are supported: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +The specified option values are conflicting and cannot be supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +There was an illegal character at \fIs1\fR, \fIs2\fR, or both. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +There was an incomplete character at \fIs1\fR, \fIs2\fR, or both. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The specified Unicode version value is not supported. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +After proper pre-processing, the \fBu8_strcmp()\fR function compares two UTF-8 +strings byte-by-byte, according to the machine ordering defined by the +corresponding version of the Unicode Standard. +.sp +.LP +When multiple comparison options are specified, Unicode Normalization is +performed after case-sensitive or case-insensitive processing is performed. +.SH RETURN VALUES +.sp +.LP +The \fBu8_strcmp()\fR function returns an integer greater than, equal to, or +less than 0 if the string pointed to by \fIs1\fR is greater than, equal to, or +less than the string pointed to by \fIs2\fR, respectively. +.sp +.LP +When \fBu8_strcmp()\fR detects an illegal or incomplete character, such +character causes the function to set \fIerrno\fR to indicate the error. +Afterward, the comparison is still performed on the resultant strings and a +value based on byte-by-byte comparison is always returned. +.SH CONTEXT +.sp +.LP +The \fBu8_strcmp()\fR function can be called from user or interrupt context. +.SH EXAMPLES +.LP +\fBExample 1 \fRPerform simple default string comparison. +.sp +.in +2 +.nf +#include <sys/sunddi.h> + +int +docmp_default(const char *u1, const char *u2) { + int result; + int ; + + result = u8_strcmp(u1, u2, 0, 0, U8_UNICODE_LATEST, &errno); + if (errno == EILSEQ) + return (-1); + if (errno == EINVAL) + return (-2); + if (errno == EBADF) + return (-3); + if (errno == ERANGE) + return (-4); +.fi +.in -2 + +.LP +\fBExample 2 \fRPerform upper case based case-insensitive comparison with +Unicode 3.2.0 date. +.sp +.in +2 +.nf +#include <sys/sunddi.h> + +int +docmp_caseinsensitive_u320(const char *u1, const char *u2) { + int result; + int errno; + + result = u8_strcmp(u1, u2, 0, U8_STRCMP_CI_UPPER, + U8_UNICODE_320, &errno); + if (errno == EILSEQ) + return (-1); + if (errno == EINVAL) + return (-2); + if (errno == EBADF) + return (-3); + if (errno == ERANGE) + return (-4); + + return (result); +} +.fi +.in -2 + +.LP +\fBExample 3 \fRPerform Unicode Normalization Form D. +.sp +.LP +Perform Unicode Normalization Form D and uppercase-based case-insensitive +comparison with Unicode 3.2.0 date. + +.sp +.in +2 +.nf +#include <sys/sunddi.h> + +int +docmp_nfd_caseinsensitive_u320(const char *u1, const char *u2) { + int result; + int errno; + + result = u8_strcmp(u1, u2, 0, + (U8_STRCMP_NFD|U8_STRCMP_CI_UPPER), U8_UNICODE_320, + &errno); + if (errno == EILSEQ) + return (-1); + if (errno == EINVAL) + return (-2); + if (errno == EBADF) + return (-3); + if (errno == ERANGE) + return (-4); + + return (result); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBu8_validate\fR(3C), \fBu8_textprep_str\fR(3C), \fBu8_validate\fR(3C), +\fBattributes\fR(5), \fBu8_textprep_str\fR(9F), \fBu8_validate\fR(9F), +\fBuconv_u16tou32\fR(9F) +.sp +.LP +The Unicode Standard (http://www.unicode.org) diff --git a/usr/src/man/man9f/u8_textprep_str.9f b/usr/src/man/man9f/u8_textprep_str.9f new file mode 100644 index 0000000000..db69e2ab28 --- /dev/null +++ b/usr/src/man/man9f/u8_textprep_str.9f @@ -0,0 +1,426 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH u8_textprep_str 9F "18 Sep 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +u8_textprep_str \- string-based UTF-8 text preparation function +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> + +\fBsize_t\fR \fBu8_textprep_str\fR(\fBchar *\fR\fIinarray\fR, \fBsize_t *\fR\fIinlen\fR, + \fBchar *\fR\fIoutarray\fR, \fBsize_t *\fR\fIoutlen\fR, \fBint\fR \fIflag\fR, + \fBsize_t\fR \fIunicode_version\fR, \fBint *\fR\fIerrno\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIinarray\fR\fR +.ad +.RS 20n +.rt +A pointer to a byte array containing a sequence of UTF-8 character bytes to be +prepared. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinlen\fR\fR +.ad +.RS 20n +.rt +As input argument, the number of bytes to be prepared in \fIinarray\fR. As +output argument, the number of bytes in \fIinarray\fR still not consumed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoutarray\fR\fR +.ad +.RS 20n +.rt +A pointer to a byte array where prepared UTF-8 character bytes can be saved. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIoutlen\fR\fR +.ad +.RS 20n +.rt +As input argument, the number of available bytes at \fIoutarray\fR where +prepared character bytes can be saved. As output argument, after the +conversion, the number of bytes still available at \fIoutarray\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 20n +.rt +The possible preparation options constructed by a bitwise-inclusive-OR of the +following values: +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_IGNORE_NULL\fR\fR +.ad +.sp .6 +.RS 4n +Normally \fBu8_textprep_str()\fR stops the preparation if it encounters null +byte even if the current \fIinlen\fR is pointing to a value bigger than zero. +.sp +With this option, null byte does not stop the preparation and the preparation +continues until \fIinlen\fR specified amount of \fIinarray\fR bytes are all +consumed for preparation or an error happened. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_IGNORE_INVALID\fR\fR +.ad +.sp .6 +.RS 4n +Normally \fBu8_textprep_str()\fR stops the preparation if it encounters illegal +or incomplete characters with corresponding \fIerrno\fR values. +.sp +When this option is set, \fBu8_textprep_str()\fR does not stop the preparation +and instead treats such characters as no need to do any preparation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_TOUPPER\fR\fR +.ad +.sp .6 +.RS 4n +Map lowercase characters to uppercase characters if applicable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_TOLOWER\fR\fR +.ad +.sp .6 +.RS 4n +Map uppercase characters to lowercase characters if applicable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_NFD\fR\fR +.ad +.sp .6 +.RS 4n +Apply Unicode Normalization Form D. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_NFC\fR\fR +.ad +.sp .6 +.RS 4n +Apply Unicode Normalization Form C. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_NFKD\fR\fR +.ad +.sp .6 +.RS 4n +Apply Unicode Normalization Form KD. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_TEXTPREP_NFKC\fR\fR +.ad +.sp .6 +.RS 4n +Apply Unicode Normalization Form KC. +.RE + +Only one case folding option is allowed. Only one Unicode Normalization option +is allowed. +.sp +When a case folding option and a Unicode Normalization option are specified +together, UTF-8 text preparation is done by doing case folding first and then +Unicode Normalization. +.sp +If no option is specified, no processing occurs except the simple copying of +bytes from input to output. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIunicode_version\fR\fR +.ad +.RS 20n +.rt +The version of Unicode data that should be used during UTF-8 text preparation. +The following values are supported: +.sp +.ne 2 +.mk +.na +\fB\fBU8_UNICODE_320\fR\fR +.ad +.sp .6 +.RS 4n +Use Unicode 3.2.0 data during comparison. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_UNICODE_500\fR\fR +.ad +.sp .6 +.RS 4n +Use Unicode 5.0.0 data during comparison. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_UNICODE_LATEST\fR\fR +.ad +.sp .6 +.RS 4n +Use the latest Unicode version data available which is Unicode 5.0.0 currently. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerrno\fR\fR +.ad +.RS 20n +.rt +The error value when preparation is not completed or fails. The following +values are supported: +.sp +.ne 2 +.mk +.na +\fB\fBE2BIG\fR\fR +.ad +.RS 10n +.rt +Text preparation stopped due to lack of space in the output array. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +Specified option values are conflicting and cannot be supported. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +Text preparation stopped due to an input byte that does not belong to UTF-8. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Text preparation stopped due to an incomplete UTF-8 character at the end of the +input array. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +The specified Unicode version value is not a supported version. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBu8_textprep_str()\fR function prepares the sequence of UTF-8 characters +in the array specified by \fIinarray\fR into a sequence of corresponding UTF-8 +characters prepared in the array specified by \fIoutarray\fR. The \fIinarray\fR +argument points to a character byte array to the first character in the input +array and \fIinlen\fR indicates the number of bytes to the end of the array to +be converted. The \fIoutarray\fR argument points to a character byte array to +the first available byte in the output array and \fIoutlen\fR indicates the +number of the available bytes to the end of the array. Unless \fIflag\fR is +\fBU8_TEXTPREP_IGNORE_NULL\fR, \fBu8_textprep_str()\fR normally stops when it +encounters a null byte from the input array regardless of the current +\fIinlen\fR value. +.sp +.LP +If \fIflag\fR is \fBU8_TEXTPREP_IGNORE_INVALID\fR and a sequence of input bytes +does not form a valid UTF-8 character, preparation stops after the previous +successfully prepared character. If \fIflag\fR is +\fBU8_TEXTPREP_IGNORE_INVALID\fR and the input array ends with an incomplete +UTF-8 character, preparation stops after the previous successfully prepared +bytes. If the output array is not large enough to hold the entire prepared +text, preparation stops just prior to the input bytes that would cause the +output array to overflow. The value pointed to by \fIinlen\fR is decremented to +reflect the number of bytes still not prepared in the input array. The value +pointed to by \fIoutlen\fR is decremented to reflect the number of bytes still +available in the output array. +.SH RETURN VALUES +.sp +.LP +The \fBu8_textprep_str()\fR function updates the values pointed to by +\fIinlen\fR and \fIoutlen\fR arguments to reflect the extent of the +preparation. When \fBU8_TEXTPREP_IGNORE_INVALID\fR is specified, +\fBu8_textprep_str()\fR returns the number of illegal or incomplete characters +found during the text preparation. When \fBU8_TEXTPREP_IGNORE_INVALID\fR is not +specified and the text preparation is successful, the function returns 0. If +the entire string in the input array is prepared, the value pointed to by +\fIinlen\fR will be 0. If the text preparation is stopped due to any conditions +mentioned above, the value pointed to by \fIinlen\fR will be non-zero and +\fIerrno\fR is set to indicate the error. If such and any other error occurs, +\fBu8_textprep_str()\fR returns (\fBsize_t\fR)-1 and sets \fIerrno\fR to +indicate the error. +.SH CONTEXT +.sp +.LP +The \fBu8_textprep_str()\fR function can be called from user or interrupt +context. +.SH EXAMPLES +.LP +\fBExample 1 \fRSimple UTF-8 text preparation +.sp +.in +2 +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> +\&. +\&. +\&. +size_t ret; +char ib[MAXPATHLEN]; +char ob[MAXPATHLEN]; +size_t il, ol; +int err; +\&. +\&. +\&. +/* + * We got a UTF-8 pathname from somewhere. + * + * Calculate the length of input string including the terminating + * NULL byte and prepare other arguments. + */ +(void) strlcpy(ib, pathname, MAXPATHLEN); +il = strlen(ib) + 1; +ol = MAXPATHLEN; + +/* + * Do toupper case folding, apply Unicode Normalization Form D, + * ignore NULL byte, and ignore any illegal/incomplete characters. + */ +ret = u8_textprep_str(ib, &il, ob, &ol, + (U8_TEXTPREP_IGNORE_NULL|U8_TEXTPREP_IGNORE_INVALID| + U8_TEXTPREP_TOUPPER|U8_TEXTPREP_NFD), U8_UNICODE_LATEST, &err); +if (ret == (size_t)-1) { + if (err == E2BIG) + return (-1); + if (err == EBADF) + return (-2); + if (err == ERANGE) + return (-3); + return (-4); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBu8_strcmp\fR(3C), \fBu8_textprep_str\fR(3C), \fBu8_validate\fR(3C), +\fBattributes\fR(5), \fBu8_strcmp\fR(9F), \fBu8_validate\fR(9F), +\fBuconv_u16tou32\fR(9F) +.sp +.LP +The Unicode Standard (http://www.unicode.org) diff --git a/usr/src/man/man9f/u8_validate.9f b/usr/src/man/man9f/u8_validate.9f new file mode 100644 index 0000000000..2f0e311feb --- /dev/null +++ b/usr/src/man/man9f/u8_validate.9f @@ -0,0 +1,320 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH u8_validate 9F "18 Sep 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +u8_validate \- validate UTF-8 characters and calculate the byte length +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> + +\fBint\fR u8_validate(\fBchar *\fR\fIu8str\fR, \fBsize_t\fR \fIn\fR, \fBchar **\fR\fIlist\fR, \fBint\fR \fIflag\fR, + \fBint *\fR\fIerrno\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIu8str\fR\fR +.ad +.RS 9n +.rt +The UTF-8 string to be validated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIn\fR\fR +.ad +.RS 9n +.rt +The maximum number of bytes in \fIu8str\fR that can be examined and validated. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlist\fR\fR +.ad +.RS 9n +.rt +A list of null-terminated character strings in UTF-8 that must be additionally +checked against as invalid characters. The last string in \fIlist\fR must be +null to indicate there is no further string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 9n +.rt +Possible validation options constructed by a bitwise-inclusive-OR of the +following values: +.sp +.ne 2 +.mk +.na +\fB\fBU8_VALIDATE_ENTIRE\fR\fR +.ad +.sp .6 +.RS 4n +By default, \fBu8_validate()\fR looks at the first character or up to \fIn\fR +bytes, whichever is smaller in terms of the number of bytes to be consumed, and +returns with the result. +.sp +When this option is used, \fBu8_validate()\fR will check up to \fIn\fR bytes +from \fIu8str\fR and possibly more than a character before returning the +result. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_VALIDATE_CHECK_ADDITIONAL\fR\fR +.ad +.sp .6 +.RS 4n +By default, \fBu8_validate()\fR does not use list supplied. +.sp +When this option is supplied with a list of character strings, +\fBu8_validate()\fR additionally validates \fIu8str\fR against the character +strings supplied with \fIlist\fR and returns EBADF in \fIerrno\fR if +\fIu8str\fR has any one of the character strings in \fIlist\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBU8_VALIDATE_UCS2_RANGE\fR\fR +.ad +.sp .6 +.RS 4n +By default, \fBu8_validate()\fR uses the entire Unicode coding space of U+0000 +to U+10FFFF. +.sp +When this option is specified, the valid Unicode coding space is smaller to +U+0000 to U+FFFF. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIerrno\fR\fR +.ad +.RS 9n +.rt +An error occurred during validation. The following values are supported: +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +Validation failed because list-specified characters were found in the string +pointed to by \fIu8str\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +Validation failed because an illegal byte was found in the string pointed to by +\fIu8str\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +Validation failed because an incomplete byte was found in the string pointed to +by \fIu8str\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBERANGE\fR\fR +.ad +.RS 10n +.rt +Validation failed because character bytes were encountered that are outside the +range of the Unicode coding space. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBu8_validate()\fR function validates \fIu8str\fR in UTF-8 and determines +the number of bytes constituting the character(s) pointed to by \fIu8str\fR. +.SH RETURN VALUES +.sp +.LP +If \fIu8str\fR is a null pointer, \fBu8_validate()\fR returns 0. Otherwise, +\fBu8_validate()\fR returns either the number of bytes that constitute the +characters if the next \fIn\fR or fewer bytes form valid characters, or -1 if +there is an validation failure, in which case it may set \fIerrno\fR to +indicate the error. +.SH EXAMPLES +.LP +\fBExample 1 \fRDetermine the length of the first UTF-8 character. +.sp +.in +2 +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> + +char u8[MAXPATHLEN]; +int errno; +\&. +\&. +\&. +len = u8_validate(u8, 4, (char **)NULL, 0, &errno); +if (len == -1) { + switch (errno) { + case EILSEQ: + case EINVAL: + return (MYFS4_ERR_INVAL); + case EBADF: + return (MYFS4_ERR_BADNAME); + case ERANGE: + return (MYFS4_ERR_BADCHAR); + default: + return (-10); + } +} +.fi +.in -2 + +.LP +\fBExample 2 \fRCheck if there are any invalid characters in the entire string. +.sp +.in +2 +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> + +char u8[MAXPATHLEN]; +int n; +int errno; +\&. +\&. +\&. +n = strlen(u8); +len = u8_validate(u8, n, (char **)NULL, U8_VALIDATE_ENTIRE, &errno); +if (len == -1) { + switch (errno) { + case EILSEQ: + case EINVAL: + return (MYFS4_ERR_INVAL); + case EBADF: + return (MYFS4_ERR_BADNAME); + case ERANGE: + return (MYFS4_ERR_BADCHAR); + default: + return (-10); + } +} +.fi +.in -2 + +.LP +\fBExample 3 \fRCheck if there is any invalid character, including prohibited +characters, in the entire string. +.sp +.in +2 +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> + +char u8[MAXPATHLEN]; +int n; +int errno; +char *prohibited[4] = { + ".", "..", "\e\e", NULL +}; +\&. +\&. +\&. +n = strlen(u8); +len = u8_validate(u8, n, prohibited, + (U8_VALIDATE_ENTIRE|U8_VALIDATE_CHECK_ADDITIONAL), &errno); +if (len == -1) { + switch (errno) { + case EILSEQ: + case EINVAL: + return (MYFS4_ERR_INVAL); + case EBADF: + return (MYFS4_ERR_BADNAME); + case ERANGE: + return (MYFS4_ERR_BADCHAR); + default: + return (-10); + } +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBu8_strcmp\fR(3C), \fBu8_textprep_str\fR(3C), \fBu8_validate\fR(3C), +\fBattributes\fR(5), \fBu8_strcmp\fR(9F), \fBu8_textprep_str\fR(9F), +\fBuconv_u16tou32\fR(9F) +.sp +.LP +The Unicode Standard (http://www.unicode.org) diff --git a/usr/src/man/man9f/uconv_u16tou32.9f b/usr/src/man/man9f/uconv_u16tou32.9f new file mode 100644 index 0000000000..37e968102e --- /dev/null +++ b/usr/src/man/man9f/uconv_u16tou32.9f @@ -0,0 +1,540 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH uconv_u16tou32 9F "18 Sep 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +uconv_u16tou32, uconv_u16tou8, uconv_u32tou16, uconv_u32tou8, uconv_u8tou16, +uconv_u8tou32 \- Unicode encoding conversion functions +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> + +\fBint\fR \fBuconv_u16tou32\fR(const \fBuint16_t *\fR\fIutf16str\fR, \fBsize_t *\fR\fIutf16len\fR, + \fBuint32_t *\fR\fIutf32str\fR, \fBsize_t *\fR\fIutf32len\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBuconv_u16tou8\fR(const \fBuint16_t *\fR\fIutf16str\fR, \fBsize_t *\fR\fIutf16len\fR, + \fBuchar_t *\fR\fIutf8str\fR, \fBsize_t *\fR\fIutf8len\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBuconv_u32tou16\fR(const \fBuint32_t *\fR\fIutf32str\fR, \fBsize_t *\fR\fIutf32len\fR, + \fBuint16_t *\fR\fIutf16str\fR, \fBsize_t *\fR\fIutf16len\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBuconv_u32tou8\fR(const \fBuint32_t *\fR\fIutf32str\fR, \fBsize_t *\fR\fIutf32len\fR, + \fBuchar_t *\fR\fIutf8str\fR, \fBsize_t *\fR\fIutf8len\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBuconv_u8tou16\fR(const \fBuchar_t *\fR\fIutf8str\fR, \fBsize_t *\fR\fIutf8len\fR, + \fBuint16_t *\fR\fIutf16str\fR, \fBsize_t *\fR\fIutf16len\fR, \fBint\fR \fIflag\fR); +.fi + +.LP +.nf +\fBint\fR \fBuconv_u8tou32\fR(const \fBuchar_t *\fR\fIutf8str\fR, \fBsize_t *\fR\fIutf8len\fR, + \fBuint32_t *\fR\fIutf32str\fR, \fBsize_t *\fR\fIutf32len\fR, \fBint\fR \fIflag\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIutf16str\fR\fR +.ad +.RS 12n +.rt +A pointer to a \fBUTF-16\fR character string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIutf16len\fR\fR +.ad +.RS 12n +.rt +As an input parameter, the number of 16-bit unsigned integers in \fIutf16str\fR +as \fBUTF-16\fR characters to be converted or saved. +.sp +As an output parameter, the number of 16-bit unsigned integers in +\fIutf16str\fR consumed or saved during conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIutf32str\fR\fR +.ad +.RS 12n +.rt +A pointer to a \fBUTF-32\fR character string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIutf32len\fR\fR +.ad +.RS 12n +.rt +As an input parameter, the number of 32-bit unsigned integers in \fIutf32str\fR +as \fBUTF-32\fR characters to be converted or saved. +.sp +As an output parameter, the number of 32-bit unsigned integers in +\fIutf32str\fR consumed or saved during conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIutf8str\fR\fR +.ad +.RS 12n +.rt +A pointer to a \fBUTF-8\fR character string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIutf8len\fR\fR +.ad +.RS 12n +.rt +As an input parameter, the number of bytes in \fIutf8str\fR as \fBUTF-8\fR +characters to be converted or saved. +.sp +As an output parameter, the number of bytes in \fIutf8str\fR consumed or saved +during conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflag\fR\fR +.ad +.RS 12n +.rt +The possible conversion options that are constructed by a bitwise-inclusive-OR +of the following values: +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_IN_BIG_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +The input parameter is in big endian byte ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_OUT_BIG_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +The output parameter should be in big endian byte ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_IN_SYSTEM_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +The input parameter is in the default byte ordering of the current system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_OUT_SYSTEM_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +The output parameter should be in the default byte ordering of the current +system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_IN_LITTLE_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +The input parameter is in little endian byte ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_OUT_LITTLE_ENDIAN\fR\fR +.ad +.sp .6 +.RS 4n +The output parameter should be in little endian byte ordering. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_IGNORE_NULL\fR\fR +.ad +.sp .6 +.RS 4n +The null or \fBU+0000\fR character should not stop the conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_IN_ACCEPT_BOM\fR\fR +.ad +.sp .6 +.RS 4n +If the Byte Order Mark (\fBBOM\fR, \fBU+FEFF\fR) character exists as the first +character of the input parameter, interpret it as the \fBBOM\fR character. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUCONV_OUT_EMIT_BOM\fR\fR +.ad +.sp .6 +.RS 4n +Start the output parameter with Byte Order Mark (\fBBOM\fR, \fBU+FEFF\fR) +character to indicate the byte ordering if the output parameter is in +\fBUTF-16\fR or \fBUTF-32\fR. +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBuconv_u16tou32()\fR function reads the given \fIutf16str\fR in +\fBUTF-16\fR until \fBU+0000\fR (zero) in \fIutf16str\fR is encountered as a +character or until the number of 16-bit unsigned integers specified in +\fIutf16len\fR is read. The \fBUTF-16\fR characters that are read are converted +into \fBUTF-32\fR and the result is saved at \fIutf32str\fR. After the +successful conversion, \fIutf32len\fR contains the number of 32-bit unsigned +integers saved at \fIutf32str\fR as \fBUTF-32\fR characters. +.sp +.LP +The \fBuconv_u16tou8()\fR function reads the given \fIutf16str\fR in +\fBUTF-16\fR until \fBU+0000\fR (zero) in \fIutf16str\fR is encountered as a +character or until the number of 16-bit unsigned integers specified in +\fIutf16len\fR is read. The \fBUTF-16\fR characters that are read are converted +into \fBUTF-8\fR and the result is saved at \fIutf8str\fR. After the successful +conversion, \fIutf8len\fR contains the number of bytes saved at \fIutf8str\fR +as \fBUTF-8\fR characters. +.sp +.LP +The \fBuconv_u32tou16()\fR function reads the given \fIutf32str\fR in +\fBUTF-32\fR until \fBU+0000\fR (zero) in \fIutf32str\fR is encountered as a +character or until the number of 32-bit unsigned integers specified in +\fIutf32len\fR is read. The \fBUTF-32\fR characters that are read are converted +into \fBUTF-16\fR and the result is saved at \fIutf16str\fR. After the +successful conversion, \fIutf16len\fR contains the number of 16-bit unsigned +integers saved at \fIutf16str\fR as \fBUTF-16\fR characters. +.sp +.LP +The \fBuconv_u32tou8()\fR function reads the given \fIutf32str\fR in +\fBUTF-32\fR until \fBU+0000\fR (zero) in \fIutf32str\fR is encountered as a +character or until the number of 32-bit unsigned integers specified in +\fIutf32len\fR is read. The \fBUTF-32\fR characters that are read are converted +into \fBUTF-8\fR and the result is saved at \fIutf8str\fR. After the successful +conversion, \fIutf8len\fR contains the number of bytes saved at \fIutf8str\fR +as \fBUTF-8\fR characters. +.sp +.LP +The \fBuconv_u8tou16()\fR function reads the given \fIutf8str\fR in \fBUTF-8\fR +until the null ('\fB\e0\fR\&') byte in \fIutf8str\fR is encountered or until +the number of bytes specified in \fIutf8len\fR is read. The \fBUTF-8\fR +characters that are read are converted into \fBUTF-16\fR and the result is +saved at \fIutf16str\fR. After the successful conversion, \fIutf16len\fR +contains the number of 16-bit unsigned integers saved at \fIutf16str\fR as +\fBUTF-16\fR characters. +.sp +.LP +The \fBuconv_u8tou32()\fR function reads the given \fIutf8str\fR in \fBUTF-8\fR +until the null ('\fB\e0\fR\&') byte in \fIutf8str\fR is encountered or until +the number of bytes specified in \fIutf8len\fR is read. The \fBUTF-8\fR +characters that are read are converted into \fBUTF-32\fR and the result is +saved at \fIutf32str\fR. After the successful conversion, \fIutf32len\fR +contains the number of 32-bit unsigned integers saved at \fIutf32str\fR as +\fBUTF-32\fR characters. +.sp +.LP +During the conversion, the input and the output parameters are treated with +byte orderings specified in the \fIflag\fR parameter. When not specified, the +default byte ordering of the system is used. The byte ordering \fIflag\fR value +that is specified for \fBUTF-8\fR is ignored. +.sp +.LP +When \fBUCONV_IN_ACCEPT_BOM\fR is specified as the \fIflag\fR and the first +character of the string pointed to by the input parameter is the \fBBOM\fR +character, the value of the \fBBOM\fR character dictates the byte ordering of +the subsequent characters in the string pointed to by the input parameter, +regardless of the supplied input parameter byte ordering option \fIflag\fR +values. If the \fBUCONV_IN_ACCEPT_BOM\fR is not specified, the \fBBOM\fR as the +first character is treated as a regular Unicode character: Zero Width No Break +Space (\fBZWNBSP\fR) character. +.sp +.LP +When \fBUCONV_IGNORE_NULL\fR is specified, regardless of whether the input +parameter contains \fBU+0000\fR or null byte, the conversion continues until +the specified number of input parameter elements at \fIutf16len\fR, +\fIutf32len\fR, or \fIutf8len\fR are entirely consumed during the conversion. +.sp +.LP +As output parameters, \fIutf16len\fR, \fIutf32len\fR, and \fIutf8len\fR are not +changed if conversion fails for any reason. +.SH CONTEXT +.sp +.LP +The \fBuconv_u16tou32()\fR, \fBuconv_u16tou8()\fR, \fBuconv_u32tou16()\fR, +\fBuconv_u32tou8()\fR, \fBuconv_u8tou16()\fR, and \fBuconv_u8tou32()\fR +functions can be called from user or interrupt context. +.SH RETURN VALUES +.sp +.LP +Upon successful conversion, the functions return \fB0\fR. Upon failure, the +functions return one of the following \fBerrno\fR values: +.sp +.ne 2 +.mk +.na +\fB\fBEILSEQ\fR\fR +.ad +.RS 10n +.rt +The conversion detected an illegal or out of bound character value in the input +parameter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBE2BIG\fR\fR +.ad +.RS 10n +.rt +The conversion cannot finish because the size specified in the output parameter +is too small. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The conversion stops due to an incomplete character at the end of the input +string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEBADF\fR\fR +.ad +.RS 10n +.rt +Conflicting byte-ordering option \fIflag\fR values are detected. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRConvert a \fBUTF-16\fR string in little-endian byte ordering +into \fBUTF-8\fR string. +.sp +.in +2 +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> +\&. +\&. +\&. +uint16_t u16s[MAXNAMELEN + 1]; +uchar_t u8s[MAXNAMELEN + 1]; +size_t u16len, u8len; +int ret; +\&. +\&. +\&. +u16len = u8len = MAXNAMELEN; +ret = uconv_u16tou8(u16s, &u16len, u8s, &u8len, + UCONV_IN_LITTLE_ENDIAN); +if (ret != 0) { + /* Conversion error occurred. */ + return (ret); +} +\&. +\&. +\&. +.fi +.in -2 + +.LP +\fBExample 2 \fRConvert a \fBUTF-32\fR string in big endian byte ordering into +little endian \fBUTF-16\fR. +.sp +.in +2 +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> +\&. +\&. +\&. +/* + * An UTF-32 character can be mapped to an UTF-16 character with + * two 16-bit integer entities as a "surrogate pair." + */ +uint32_t u32s[101]; +uint16_t u16s[101]; +int ret; +size_t u32len, u16len; +\&. +\&. +\&. +u32len = u16len = 100; +ret = uconv_u32tou16(u32s, &u32len, u16s, &u16len, + UCONV_IN_BIG_ENDIAN | UCONV_OUT_LITTLE_ENDIAN); +if (ret == 0) { + return (0); +} else if (ret == E2BIG) { + /* Use bigger output parameter and try just one more time. */ + uint16_t u16s2[201]; + + u16len = 200; + ret = uconv_u32tou16(u32s, &u32len, u16s2, &u16len, + UCONV_IN_BIG_ENDIAN | UCONV_OUT_LITTLE_ENDIAN); + if (ret == 0) + return (0); +} + +/* Otherwise, return -1 to indicate an error condition. */ +return (-1); +.fi +.in -2 + +.LP +\fBExample 3 \fRConvert a \fBUTF-8\fR string into \fBUTF-16\fR in little-endian +byte ordering. +.sp +.LP +Convert a \fBUTF-8\fR string into \fBUTF-16\fR in little-endian byte ordering +with a Byte Order Mark (BOM) character at the beginning of the output +parameter. + +.sp +.in +2 +.nf +#include <sys/types.h> +#include <sys/errno.h> +#include <sys/sunddi.h> +\&. +\&. +\&. +uchar_t u8s[MAXNAMELEN + 1]; +uint16_t u16s[MAXNAMELEN + 1]; +size_t u8len, u16len; +int ret; +\&. +\&. +\&. +u8len = u16len = MAXNAMELEN; +ret = uconv_u8tou16(u8s, &u8len, u16s, &u16len, + UCONV_IN_LITTLE_ENDIAN | UCONV_EMIT_BOM); +if (ret != 0) { + /* Conversion error occurred. */ + return (ret); +} +\&. +\&. +\&. +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBuconv_u16tou32\fR(3C), \fBattributes\fR(5) +.sp +.LP +The Unicode Standard (http://www.unicode.org) +.SH NOTES +.sp +.LP +Each \fBUTF-16\fR or \fBUTF-32\fR character maps to an \fBUTF-8\fR character +that might need one to maximum of four bytes. +.sp +.LP +One \fBUTF-32\fR or \fBUTF-8\fR character can yield two 16-bit unsigned +integers as a \fBUTF-16\fR character, which is a surrogate pair if the Unicode +scalar value is bigger than \fBU+FFFF\fR. +.sp +.LP +Ill-formed \fBUTF-16\fR surrogate pairs are seen as illegal characters during +the conversion. diff --git a/usr/src/man/man9f/uiomove.9f b/usr/src/man/man9f/uiomove.9f new file mode 100644 index 0000000000..1bbbdd3dd0 --- /dev/null +++ b/usr/src/man/man9f/uiomove.9f @@ -0,0 +1,121 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH uiomove 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +uiomove \- copy kernel data using uio structure +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/uio.h> + + + +\fBint\fR \fBuiomove\fR(\fBcaddr_t\fR \fIaddress\fR, \fBsize_t\fR \fInbytes\fR, \fBenum uio_rw\fR \fIrwflag\fR, + \fBuio_t *\fR\fIuio_p\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIaddress\fR\fR +.ad +.RS 11n +.rt +Source/destination kernel address of the copy. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInbytes\fR\fR +.ad +.RS 11n +.rt +Number of bytes to copy. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrwflag\fR\fR +.ad +.RS 11n +.rt +Flag indicating read or write operation. Possible values are \fBUIO_READ\fR and +\fBUIO_WRITE\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuio_p\fR\fR +.ad +.RS 11n +.rt +Pointer to the \fBuio\fR structure for the copy. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBuiomove()\fR function copies \fInbytes\fR of data to or from the space +defined by the \fBuio\fR structure (described in \fBuio\fR(9S)) and the driver. +.sp +.LP +The \fBuio_segflg\fR member of the \fBuio\fR(9S) structure determines the type +of space to or from which the transfer is being made. If it is set to +\fBUIO_SYSSPACE\fR, the data transfer is between addresses in the kernel. If it +is set to \fBUIO_USERSPACE\fR, the transfer is between a user program and +kernel space. +.sp +.LP +\fIrwflag\fR indicates the direction of the transfer. If \fBUIO_READ\fR is set, +the data will be transferred from \fIaddress\fR to the buffer(s) described by +\fIuio_p\fR. If \fBUIO_WRITE\fR is set, the data will be transferred from the +buffer(s) described by \fIuio_p\fR to \fIaddress\fR. +.sp +.LP +In addition to moving the data, \fBuiomove()\fR adds the number of bytes moved +to the \fBiov_base\fR member of the \fBiovec\fR(9S) structure, decreases the +\fBiov_len\fR member, increases the \fBuio_offset\fR member of the +\fBuio\fR(9S) structure, and decreases the \fBuio_resid\fR member. +.sp +.LP +This function automatically handles page faults. \fInbytes\fR does not have to +be word-aligned. +.SH RETURN VALUES +.sp +.LP +The \fBuiomove()\fR function returns \fB0\fR upon success or \fBEFAULT\fR on +failure. +.SH CONTEXT +.sp +.LP +User context only, if \fBuio_segflg\fR is set to \fBUIO_USERSPACE\fR. User, +interrupt, or kernel context, if \fBuio_segflg\fR is set to \fBUIO_SYSSPACE\fR. +.SH SEE ALSO +.sp +.LP +\fBureadc\fR(9F), \fBuwritec\fR(9F), \fBiovec\fR(9S), \fBuio\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR +.SH WARNINGS +.sp +.LP +If \fBuio_segflg\fR is set to \fBUIO_SYSSPACE\fR and \fIaddress\fR is selected +from user space, the system may panic. diff --git a/usr/src/man/man9f/unbufcall.9f b/usr/src/man/man9f/unbufcall.9f new file mode 100644 index 0000000000..77a5cccc75 --- /dev/null +++ b/usr/src/man/man9f/unbufcall.9f @@ -0,0 +1,64 @@ +'\" te +.\" Copyright 2006 Sun Microsystems, Inc All rights reserved +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH unbufcall 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +unbufcall \- cancel a pending bufcall request +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBvoid\fR \fBunbufcall\fR(\fBbufcall_id_t\fR \fIid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIid\fR\fR +.ad +.RS 6n +.rt +Identifier returned from \fBbufcall\fR(9F) or \fBesbbcall\fR(9F). +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBunbufcall\fR function cancels a pending \fBbufcall()\fR or +\fBesbbcall()\fR request. The argument \fBid\fR is a non-zero identifier for +the request to be cancelled. \fBid\fR is returned from the \fBbufcall()\fR or +\fBesbbcall()\fR function used to issue the request. \fBunbufcall()\fR will not +return until the pending callback is cancelled or has run. Because of this, +locks acquired by the callback routine should not be held across the call to +\fBunbufcall()\fR or deadlock may result. +.SH RETURN VALUES +.sp +.LP +None. +.SH CONTEXT +.sp +.LP +The \fBunbufcall\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBbufcall\fR(9F), \fBesbbcall\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/unlinkb.9f b/usr/src/man/man9f/unlinkb.9f new file mode 100644 index 0000000000..376dc3cdaa --- /dev/null +++ b/usr/src/man/man9f/unlinkb.9f @@ -0,0 +1,87 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH unlinkb 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +unlinkb \- remove a message block from the head of a message +.SH SYNOPSIS +.LP +.nf +#include <sys/stream.h> + + + +\fBmblk_t *\fR\fBunlinkb\fR(\fBmblk_t *\fR\fImp\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fImp\fR\fR +.ad +.RS 6n +.rt +Pointer to the message. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBunlinkb()\fR function removes the first message block from the message +pointed to by \fImp\fR. A new message, minus the removed message block, is +returned. +.SH RETURN VALUES +.sp +.LP +If successful, the \fBunlinkb()\fR function returns a pointer to the message +with the first message block removed. If there is only one message block in the +message, \fINULL\fR is returned. +.SH CONTEXT +.sp +.LP +The \fBunlinkb()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.LP +\fBExample 1 \fR\fBunlinkb()\fR example +.sp +.LP +The routine expects to get passed an \fBM_PROTO T_DATA_IND\fR message. It will +remove and free the \fBM_PROTO\fR header and return the remaining +\fBM_DATA\fR portion of the message. + +.sp +.in +2 +.nf +1 mblk_t * +2 makedata(mp) +3 mblk_t *mp; +4 { +5 mblk_t *nmp; +6 +7 nmp = unlinkb(mp); +8 freeb(mp); +9 return(nmp); +10 } +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBlinkb\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR +.sp +.LP +\fISTREAMS Programming Guide\fR diff --git a/usr/src/man/man9f/untimeout.9f b/usr/src/man/man9f/untimeout.9f new file mode 100644 index 0000000000..5562086776 --- /dev/null +++ b/usr/src/man/man9f/untimeout.9f @@ -0,0 +1,130 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH untimeout 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +untimeout \- cancel previous timeout function call +.SH SYNOPSIS +.LP +.nf +#include <sys/types.h> +#include <sys/conf.h> + + + +\fBclock_t\fR \fBuntimeout\fR(\fBtimeout_id_t\fR \fIid\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIid\fR\fR +.ad +.RS 6n +.rt +Opaque timeout \fBID\fR from a previous \fBtimeout\fR(9F) call. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBuntimeout()\fR function cancels a pending \fBtimeout\fR(9F) request. +\fBuntimeout()\fR will not return until the pending callback is cancelled or +has run. Because of this, locks acquired by the callback routine should not be +held across the call to \fBuntimeout()\fR or a deadlock may result. +.sp +.LP +Since no mutex should be held across the call to \fBuntimeout()\fR, there is a +race condition between the occurrence of an expected event and the execution of +the timeout handler. In particular, it should be noted that no problems will +result from calling \fBuntimeout()\fR for a timeout which is either running on +another CPU, or has already completed. Drivers should be structured with the +understanding that the arrival of both an interrupt and a timeout for that +interrupt can occasionally occur, in either order. +.SH RETURN VALUES +.sp +.LP +The \fBuntimeout()\fR function returns \fB-1\fR if the \fIid\fR is not found. +Otherwise, it returns an integer value greater than or equal to \fB0\fR. +.SH CONTEXT +.sp +.LP +The \fBuntimeout()\fR function can be called from user, interrupt, or kernel +context. +.SH EXAMPLES +.sp +.LP +In the following example, the device driver has issued an IO request and is +waiting for the device to respond. If the device does not respond within 5 +seconds, the device driver will print out an error message to the console. +.sp +.in +2 +.nf +static void +xxtimeout_handler(void *arg) +{ + struct xxstate *xsp = (struct xxstate *)arg; + mutex_enter(&xsp->lock); + cv_signal(&xsp->cv); + xsp->flags |= TIMED_OUT; + mutex_exit(&xsp->lock); + xsp->timeout_id = 0; +} +static uint_t +xxintr(caddr_t arg) +{ + struct xxstate *xsp = (struct xxstate *)arg; + . + . + . + mutex_enter(&xsp->lock); + /* Service interrupt */ + cv_signal(&xsp->cv); + mutex_exit(&xsp->lock); + if (xsp->timeout_id != 0) { + (void) untimeout(xsp->timeout_id); + xsp->timeout_id = 0; + } + return(DDI_INTR_CLAIMED); +} +static void +xxcheckcond(struct xxstate *xsp) +{ + . + . + . + xsp->timeout_id = timeout(xxtimeout_handler, + xsp, (5 * drv_usectohz(1000000))); + mutex_enter(&xsp->lock); + while (/* Waiting for interrupt or timeout*/) + cv_wait(&xsp->cv, &xsp->lock); + if (xsp->flags & TIMED_OUT) + cmn_err(CE_WARN, "Device not responding"); + . + . + . + mutex_exit(&xsp->lock); + . + . + . +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBopen\fR(9E), \fBcv_signal\fR(9F), \fBcv_wait_sig\fR(9F), \fBdelay\fR(9F), +\fBtimeout\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/ureadc.9f b/usr/src/man/man9f/ureadc.9f new file mode 100644 index 0000000000..cd94efac38 --- /dev/null +++ b/usr/src/man/man9f/ureadc.9f @@ -0,0 +1,69 @@ +'\" te +.\" Copyright 1989 AT&T +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH ureadc 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +ureadc \- add character to a uio structure +.SH SYNOPSIS +.LP +.nf +#include <sys/uio.h> +#include <sys/types.h> + + + +\fBint\fR \fBureadc\fR(\fBint\fR \fIc\fR, \fBuio_t *\fR\fIuio_p\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIc\fR\fR +.ad +.RS 9n +.rt +The character added to the \fBuio\fR(9S) structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuio_p\fR\fR +.ad +.RS 9n +.rt +Pointer to the \fBuio\fR(9S) structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBureadc()\fR function transfers the character \fIc\fR into the address +space of the \fBuio\fR(9S) structure pointed to by \fIuio_p\fR, and updates the +\fBuio\fR structure as for \fBuiomove\fR(9F). +.SH RETURN VALUES +.sp +.LP +\fB0\fR is returned on success and \fBEFAULT\fR on failure. +.SH CONTEXT +.sp +.LP +The \fBureadc()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBuiomove\fR(9F), \fBuwritec\fR(9F), \fBiovec\fR(9S), \fBuio\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/usb_alloc_request.9f b/usr/src/man/man9f/usb_alloc_request.9f new file mode 100644 index 0000000000..26d0ca1d46 --- /dev/null +++ b/usr/src/man/man9f/usb_alloc_request.9f @@ -0,0 +1,274 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_alloc_request 9F "25 July 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_alloc_request, usb_alloc_ctrl_req, usb_free_ctrl_req, usb_alloc_bulk_req, +usb_free_bulk_req, usb_alloc_intr_req, usb_free_intr_req, usb_alloc_isoc_req, +usb_free_isoc_req \- Allocate and free USB transfer requests +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + +\fBusb_ctrl_req_t *\fR\fBusb_alloc_ctrl_req\fR(\fBdev_info_t *\fR\fIdip\fR, \fBsize_t\fR \fIlen\fR, + \fBusb_flags_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBusb_free_ctrl_req\fR(\fBusb_ctrl_req_t *\fR\fIrequest\fR); +.fi + +.LP +.nf +\fBusb_bulk_req_t *\fR\fBusb_alloc_bulk_req\fR(\fBdev_info_t\fR \fIdip\fR, \fBsize_t\fR \fIlen\fR, + \fBusb_flags_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBusb_free_bulk_req\fR(\fBusb_bulk_req_t *\fR\fIrequest\fR); +.fi + +.LP +.nf +\fBusb_intr_req_t *\fR\fBusb_alloc_intr_req\fR(\fBdev_info_t *\fR\fIdip\fR, \fBsize_t\fR \fIlen\fR, + \fBusb_flags_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBusb_free_intr_req\fR(\fBusb_intr_req_t *\fR\fIrequest\fR); +.fi + +.LP +.nf +\fBusb_isoc_req_t *\fR\fBusb_alloc_isoc_req\fR(\fBdev_info_t *\fR\fIdip\fR, + \fBuint_t\fR \fIisoc_pkts_count\fR, \fBsize_t\fR \fIlen\fR, \fBusb_flags_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBusb_free_isoc_req\fR(\fBusb_isoc_req_t *\fR\fIrequest\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.LP +For \fBusb_alloc_ctrl_req()\fR, \fBusb_alloc_bulk_req()\fR and +\fBusb_alloc_intr_req()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 9n +.rt +Pointer to the device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 9n +.rt +Length of \fIdata\fR for this request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 9n +.rt +Only USB_FLAGS_SLEEP is recognized. Wait for resources if not immediately +available. +.RE + +.sp +.LP +For \fBusb_alloc_isoc_req()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 19n +.rt +Pointer to the device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIisoc_pkts_count\fR\fR +.ad +.RS 19n +.rt +Number of isochronous packet descriptors to associate with this request. Must +be greater than zero. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlen\fR\fR +.ad +.RS 19n +.rt +Length of \fIdata\fR for this isochronous request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 19n +.rt +Only USB_FLAGS_SLEEP is recognized. Wait for resources if not immediately +available. +.RE + +.sp +.LP +For \fBusb_free_ctrl_req()\fR, \fBusb_free_bulk_req()\fR, +\fBusb_free_intr_req()\fR and \fBusb_free_isoc_req()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIrequest\fR\fR +.ad +.RS 11n +.rt +Pointer to the request structure to be freed. Can be \fBNULL\fR. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_alloc_ctrl_req()\fR, \fBusb_alloc_bulk_req()\fR, +\fBusb_alloc_intr_req()\fR, and \fBusb_alloc_isoc_req()\fR functions allocate +control, bulk, interrupt, or isochronous requests. Optionally, these +functions can also allocate an mblk of the specified length to pass data +associated with the request. (For guidelines on mblk data allocation, see the +manpage for the relevant transfer function). +.sp +.LP +The \fBusb_alloc_isoc_req()\fR function also allocates a number of isochronous +packet descriptors (usb_isoc_pkt_descr_t) specified by isoc_pkts_count to the +end of the request proper (usb_isoc_req_t). See \fBusb_isoc_request\fR(9S) for +more information on isochronous packet descriptors. +.sp +.LP +These functions always succeed when the USB_FLAGS_SLEEP flag is set, provided +that they are given valid args and are not called from interrupt context. +.sp +.LP +The \fBusb_free_ctrl_req()\fR, \fBusb_free_bulk_req()\fR, +\fBusb_free_intr_req()\fR, and \fBusb_free_isoc_req()\fR functions free their +corresponding request. If the request's data block pointer is non-zero, the +data block is also freed. For isoc requests, the array of packet descriptors is +freed. +.SH RETURN VALUES +.sp +.LP +For \fBusb_alloc_ctrl_req()\fR, \fBusb_alloc_bulk_req()\fR, +\fBusb_alloc_intr_req()\fR and \fBusb_alloc_isoc_req()\fR: +.sp +.LP +On success: returns a pointer to the appropriate usb_xxx_request_t. +.sp +.LP +On failure: returns \fBNULL\fR. Fails because the dip argument is invalid, +USB_FLAGS_SLEEP is not set and memory is not available or because +USB_FLAGS_SLEEP is set but the call was made in interrupt context. +.sp +.LP +For \fBusb_free_ctrl_req()\fR, \fBusb_free_bulk_req()\fR, +\fBusb_free_intr_req()\fR and \fBusb_free_isoc_req()\fR: None. +.SH CONTEXT +.sp +.LP +The allocation routines can always be called from kernel and user context. They +may be called from interrupt context only if USB_FLAGS_SLEEP is not specified. +.sp +.LP +The free routines may be called from kernel, user, and interrupt context. +.SH EXAMPLES +.sp +.in +2 +.nf + /* This allocates and initializes an asynchronous control + * request which will pass no data. Asynchronous requests + * are used when they cannot block the calling thread. + */ + + usb_ctrl_req_t *ctrl_req; + + if ((ctrl_req = usb_alloc_ctrl_req(dip, 0, 0)) == NULL) { + return (FAILURE); + } + + /* Now initialize. */ + ctrl_req->ctrl_bmRequestType = USB_DEV_REQ_DEV_TO_HOST | + USB_DEV_REQ_STANDARD | USB_DEV_REQ_RCPT_DEV; + + ctrl_req->ctrl_bRequest = (uint8_t)USB_REQ_GET_STATUS; + ... + ... + ctrl_req->ctrl_callback = normal_callback; + ctrl_req->ctrl_exc_callback = exception_callback; + ... + ... + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_current_frame_number\fR(9F), +\fBusb_get_max_pkts_per_isoc_request\fR(9F), +\fBusb_pipe_get_max_bulk_transfer_size\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F), +\fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_intr_xfer\fR(9F), +\fBusb_pipe_isoc_xfer\fR(9F), \fBusb_bulk_request\fR(9S), +\fBusb_ctrl_request\fR(9S), \fBusb_intr_request\fR(9S), +\fBusb_isoc_request\fR(9S) diff --git a/usr/src/man/man9f/usb_client_attach.9f b/usr/src/man/man9f/usb_client_attach.9f new file mode 100644 index 0000000000..39b68a54f2 --- /dev/null +++ b/usr/src/man/man9f/usb_client_attach.9f @@ -0,0 +1,270 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_client_attach 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_client_attach, usb_client_detach \- USBA framework registration of client +USB drivers +.SH SYNOPSIS +.LP +.nf +#define USBDRV_MAJOR_VER <major> +#define USBDRV_MINOR_VER <minor> +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_client_attach\fR(\fBdev_info_t *\fR\fIdip\fR, + \fBuint_t\fR \fIversion\fR, \fBusb_flags_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBusb_client_detach\fR(\fBdev_info_t *\fR\fIdip\fR, + \fBusb_client_dev_data_t *\fR\fIdev_data\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.LP +For \fBusb_client_attach()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 11n +.rt +Pointer to the device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIversion\fR\fR +.ad +.RS 11n +.rt +Must be set to USBDRV_VERSION. (See below.) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 11n +.rt +Not used. +.RE + +.sp +.LP +For \fBusb_client_detach()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 12n +.rt +Pointer to the device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_data\fR\fR +.ad +.RS 12n +.rt +Pointer to a usb_client_dev_data_t to free. Can be NULL. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_client_attach()\fR function registers a driver with the USBA +framework and must be called before any other USBA function. Usually, +\fBusb_client_attach()\fR is followed by a call to \fBusb_get_dev_data\fR(9F). +.sp +.LP +The \fBusb_client_detach()\fR function unregisters a driver with the USBA +framework. The \fBusb_client_detach()\fR function releases memory for all +strings, descriptors and trees set up by \fBusb_get_dev_data\fR(9F) when its +dev_data argument is non-NULL. The \fBusb_client_detach()\fR function is the +last USBA function a client calls before completing \fBdetach\fR(9E). It is not +necessary to call \fBusb_client_detach()\fR during a suspend operation. +.SS "VERSIONING" +.sp +.LP +USBDRV_VERSION is a macro which creates a version number based on the +USBDRV_MAJOR_VER and USBDRV_MINOR_VER definitions. It must be passed as the +version argument. +.sp +.LP +For drivers version 2.0 or greater, the value of USBDRV_MAJOR_VERSION must +match its corresponding USBA_MAJOR_VER value in <\fBsys/usb/usbai.h\fR>, and +the value of USBDRV_MINOR_VERSION must not be greater than its corresponding +USBA_MINOR_VER value also in <sys/usb/usbai.h>. +.sp +.LP +Version 0.8 drivers from previous releases are binary compatible and run on +Solaris 10, but are not compilable. Version 0.8 binary compatibility will not +be supported in subsequent Solaris OS releases. +.sp +.LP +Definitions of USBDRV_MAJOR_VERSION and USBDRV_MINOR_VERSION must appear in the +client driver above the reference to <\fBsys/usb/usba.h\fR>. Note that +different releases have different USBA_[MAJOR|MINOR]_VER numbers. +.SH RETURN VALUES +.sp +.LP +For \fBusb_client_attach()\fR: +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 23n +.rt +Registration is successful. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 23n +.rt +\fIdip\fR is \fBNULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 23n +.rt +Called from interrupt context. Not called from an attach routine context. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_VERSION\fR +.ad +.RS 23n +.rt +Version passed in version is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 23n +.rt +Other internal error. +.RE + +.sp +.LP +For \fBusb_client_detach()\fR: +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 23n +.rt +\fIdip\fR is \fBNULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 23n +.rt +Not called from an attach routine context. +.RE + +.SH CONTEXT +.sp +.LP +The \fBusb_client_attach()\fR function may only be called from +\fBattach\fR(9E). +.sp +.LP +The \fBusb_client_detach()\fR function may be called only from \fBattach\fR(9E) +or \fBdetach\fR(9E). +.SH EXAMPLES +.sp +.in +2 +.nf + if (usb_client_attach(dip, USBDRV_VERSION, 0) != USB_SUCCESS) { + cmn_err (CE_WARN, "%s%d: Couldn't register USB device", + ddi_driver_name(dip), ddi_get_instance(dip)); + + return (USB_FAILURE); + } + + if (usb_get_dev_data(dip, &dev_data, USB_PARSE_LVL_IF, 0) != + USB_SUCCESS) { + cmn_err (CE_WARN, "%s%d: Couldn't get device descriptor data.", + ddi_driver_name(dip), ddi_get_instance(dip)); + + return (USB_FAILURE); + } + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E), +\fBusb_get_dev_data\fR(9F) diff --git a/usr/src/man/man9f/usb_clr_feature.9f b/usr/src/man/man9f/usb_clr_feature.9f new file mode 100644 index 0000000000..1686ba4f93 --- /dev/null +++ b/usr/src/man/man9f/usb_clr_feature.9f @@ -0,0 +1,261 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_clr_feature 9F "Feb 9 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_clr_feature \- Clear feature of USB device, interface or endpoint +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_clr_feature\fR(\fBdev_info_t *\fR\fIdip\fR, + \fBuint_t\fR \fIrequest_type\fR, \fBuint_t\fR \fIfeature\fR, + \fBuint_t\fR \fIwhich\fR, \fBusb_flags_t\fR \fIflags\fR, + \fBvoid (\fR\fI*callback)\fR (usb_pipe_handle_t \fIpipe_handle\fR, + \fBusb_opaque_t\fR \fIcallback_arg\fR, \fBint\fR \fIrval\fR, \fBusb_cb_flags_t\fR \fIflags)\fR, + \fBusb_opaque_t\fR \fIcallback_arg\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 16n +.rt +Pointer to the device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 16n +.rt +Pipe handle to device, device interface or endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrequest_type\fR\fR +.ad +.RS 16n +.rt +bmRequestType to be used. One of the following: +.sp +USB_DEV_REQ_RCPT_DEV - Clear feature on device. +.sp +USB_DEV_REQ_RCPT_IF - Clear feature on interface. +.sp +USB_DEV_REQ_RCPT_EP - Clear feature on endpoint. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfeature\fR\fR +.ad +.RS 16n +.rt +Feature to be cleared. Can be any device-defined device-, interface-, or +endpoint-specific feature, including the following which are defined in the +\fIUSB 2.0\fR specification: +.sp +USB_EP_HALT - Clear a HALT on an endpoint. +.sp +USB_DEV_REMOTE_WAKEUP - Clear REMOTE_WAKEUP on a device. +.sp +USB_DEV_TEST_MODE - Clear TEST_MODE on a device. +.RE + +.sp +.ne 2 +.mk +.na +\fBwhich\fR +.ad +.RS 9n +.rt +Device, interface or endpoint on which to clear the feature. One of: +.br +.in +2 +Interface number, for interfaces. +.in -2 +.br +.in +2 +Endpoint number, for endpoints. +.in -2 +.br +.in +2 +0 for devices. +.in -2 +.RE + +.sp +.ne 2 +.mk +.na +\fBflags\fR +.ad +.RS 16n +.rt +USB_FLAGS_SLEEP is the only flag recognized. Wait for completion and do not +call callback. +.RE + +.sp +.ne 2 +.mk +.na +\fBcallback\fR +.ad +.RS 16n +.rt +Callback handler to notify of asynchronous completion. +.RE + +.sp +.ne 2 +.mk +.na +\fBcallback_arg\fR +.ad +.RS 16n +.rt +Second argument passed to callback handler. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_clr_feature()\fR function clears a specific feature of a device, +interface or endpoint. This function always blocks and waits for resources if +not available, regardless of the flags argument. +.sp +.LP +This call blocks for completion if USB_FLAGS_SLEEP is set in flags. It returns +immediately and calls the callback upon completion if USB_FLAGS_SLEEP is not +set. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 23n +.rt +Feature was successfully cleared. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 23n +.rt +\fIdip\fR argument is NULL. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PIPE\fR +.ad +.RS 23n +.rt +\fIpipe_handle\fR argument is NULL +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 23n +.rt +Called from interrupt context with USB_FLAGS_SLEEP flag set. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 23n +.rt +Clearing of feature was unsuccessful. +.RE + +.SH CONTEXT +.sp +.LP +May always be called from user or kernel context. May be called from interrupt +context only if USB_FLAGS_SLEEP is not set in flags. +.sp +.LP +If the USB_CB_ASYNC_REQ_FAILED bit is clear in usb_cb_flags_t, the callback, if +supplied, can block because it is executing in kernel context. Otherwise the +callback cannot block. Please see \fBusb_callback_flags\fR(9S) for more +information on callbacks. +.SH EXAMPLES +.sp +.in +2 +.nf +if (usb_clr_feature(dip, pipe_handle, USB_DEV_REQ_RCPT_EP, + USB_EP_HALT, data_endpoint_num, 0) == USB_FAILURE) { + cmn_err (CE_WARN, + "%s%d: Error clearing halt condition on data endpoint %d.", + ddi_driver_name(dip), ddi_get_instance(dip), + data_endpoint_num); + } + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_status\fR(9F), \fBusb_pipe_reset\fR(9F), +\fBusb_pipe_get_state\fR(9F), \fBusb_callback_flags\fR(9S) diff --git a/usr/src/man/man9f/usb_create_pm_components.9f b/usr/src/man/man9f/usb_create_pm_components.9f new file mode 100644 index 0000000000..5e902e7f19 --- /dev/null +++ b/usr/src/man/man9f/usb_create_pm_components.9f @@ -0,0 +1,172 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_create_pm_components 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_create_pm_components \- Create power management components for USB devices +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_create_pm_components\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t *\fR\fIpwrstates\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 13n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpwrstates\fR\fR +.ad +.RS 13n +.rt +Address into which a mask which lists power states capable by device is +returned. This is a bitmask containing zero or more of the following values: +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_DEV_PWRMASK_D0\fR +.ad +.RS 22n +.rt +Corresponds to USB_DEV_OS_PWR_3 or full power. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_DEV_PWRMASK_D1\fR +.ad +.RS 22n +.rt +Corresponds to USB_DEV_OS_PWR_2. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_DEV_PWRMASK_D2\fR +.ad +.RS 22n +.rt +Corresponds to USB_DEV_OS_PWR_1. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_DEV_PWRMASK_D3\fR +.ad +.RS 22n +.rt +Corresponds to USB_DEV_OS_PWR_0 or no power. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_create_pm_components()\fR function creates pm component properties +that assume the standard USB D0-D3 powerlevels (USB_DEV_PWR_D0 - +USB_DEV_PWR_D3). See the device's relevant USB descriptor to determine the +device's power management capabilities and account for bus-powered devices. The +\fBusb_create_pm_components()\fR function also updates the pm-components +property in the device's dev_info structure. +.sp +.LP +Note that these USB power levels are inverse of OS power levels. For example, +USB_DEV_OS_PWR_0 and USB_DEV_PWR_D3 are equivalent levels corresponding to +powered-down. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 15n +.rt +Power management facilities in device are recognized by system. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 15n +.rt +An error occurred. +.RE + +.SH CONTEXT +.sp +.LP +May be called from user or kernel context. +.SH EXAMPLES +.sp +.in +2 +.nf + uint_t *pwrstates; + + /* Hook into device's power management. Enable remote wakeup. */ + if (usb_create_pm_components(dip, pwrstates) == USB_SUCCESS) { + usb_handle_remote_wakeup(dip,USB_REMOTE_WAKEUP_ENABLE); + } + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_clr_feature\fR(9F), +\fBusb_register_hotplug_cbs\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_dev_data\fR(9F), \fBusb_handle_remote_wakeup\fR(9F), +\fBpm_idle_component\fR(9F), \fBpm_busy_component\fR(9F), +\fBpm_raise_power\fR(9F), \fBpm_lower_power\fR(9F), \fBusb_cfg_descr\fR(9S) diff --git a/usr/src/man/man9f/usb_get_addr.9f b/usr/src/man/man9f/usb_get_addr.9f new file mode 100644 index 0000000000..4c54eac38d --- /dev/null +++ b/usr/src/man/man9f/usb_get_addr.9f @@ -0,0 +1,83 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_get_addr 9F "Feb 9 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_get_addr \- Retrieve device USB address +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + +\fBint\fR \fB\fR\fBusb_get_addr\fR(\fBdev_info_t *\fR\fIdip\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 +Pointer to the device's dev_info structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_get_addr()\fR function returns the current USB bus address for +debugging purposes. The returned address is unique for a specific USB bus, and +may be replicated if multiple host controller instances are present on the +system. +.SH RETURN VALUES +.sp +.LP +On success: USB device address. +.sp +.LP +On failure: returns 0. Fails if dip is NULL. +.SH CONTEXT +.sp +.LP +May be called from user, kernel or interrupt context. +.SH EXAMPLES +.sp +.in +2 +.nf +int usb_addr; + +usb_addr = usb_get_addr(dip); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_pipe_open\fR(9F) diff --git a/usr/src/man/man9f/usb_get_alt_if.9f b/usr/src/man/man9f/usb_get_alt_if.9f new file mode 100644 index 0000000000..45818d4562 --- /dev/null +++ b/usr/src/man/man9f/usb_get_alt_if.9f @@ -0,0 +1,512 @@ +'\" te +.\" Copyright (c) 2006 Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_get_alt_if 9F "29 Dec 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_get_alt_if, usb_set_alt_if, usb_get_if_number, usb_owns_device \- Get and +set alternate interface values +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_get_alt_if\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinterface_number\fR, + \fBuint_t *\fR\fIalternate_number\fR, \fBusb_flags_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBint\fR \fBusb_set_alt_if\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIinterface_number\fR, + \fBuint_t\fR \fIalternate_number\fR, \fBusb_flags_t\fR \fIflags\fR, + \fBvoid (*\fR\fIcallback\fR)(usb_pipe_handle_t \fIpipe_handle\fR, + \fBusb_opaque_t\fR \fIcallback_arg\fR, \fBint\fR \fIrval\fR, \fBusb_cb_flags_t\fR \fIflags\fR), + \fBusb_opaque_t\fR \fIcallback_arg\fR); +.fi + +.LP +.nf +\fB\fR + +\fBint\fR \fBusb_get_if_number\fR(\fBdev_info_t *\fR\fIdip\fR); +.fi + +.LP +.nf +\fB\fR + +\fBboolean_t\fR \fBusb_owns_device\fR(\fBdev_info_t *\fR\fIdip\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.LP +For \fBusb_get_alt_if()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 20n +.rt +Pointer to device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinterface_number\fR\fR +.ad +.RS 20n +.rt +Interface of the desired alternate. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIalternate_number\fR\fR +.ad +.RS 20n +.rt +Address where current alternate setting is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 20n +.rt +No flags are recognized. Reserved for future expansion. +.RE + +.sp +.LP +For \fBusb_set_alt_if()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 20n +.rt +Pointer to device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinterface_number\fR\fR +.ad +.RS 20n +.rt +Interface of the desired alternate. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIalternate_number\fR\fR +.ad +.RS 20n +.rt +Alternate interface number to be set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 20n +.rt +Only USB_FLAGS_SLEEP is recognized. Wait for completion and do not call +callback. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 20n +.rt +Callback handler to notify of asynchronous completion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback_arg\fR\fR +.ad +.RS 20n +.rt +Second argument passed to callback handler. +.RE + +.sp +.LP +For \fBusb_get_if_number()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 7n +.rt +Pointer to device's \fBdev_info\fR structure. +.RE + +.sp +.LP +For \fBusb_owns_device()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 7n +.rt +Pointer to device's \fBdev_info\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +USB devices can have multiple configurations, each with many interfaces. Within +interfaces are alternate settings, and within alternate settings are endpoints. +.sp +.LP +Each interface within a configuration may be represented by the kernel as a +device node. Only one set of device nodes (interfaces as determined by the +configuration) can be active at one time. +.sp +.LP +Alternates to an interface represent different ways the kernel sees a device +node. Only one alternate setting within an interface can be active (or +selected) at one time. The functions presented in this man page get or set +interface or alternate setting information. +.sp +.LP +The \fBusb_get_alt_if()\fR function requests the device to return the current +alternate setting of the given interface. This function ignores the flags +argument and always blocks. +.sp +.LP +The \fBusb_set_alt_if()\fR function requests the device to set the interface +and its alternate setting as specified. Because this call changes the current +device's interface and sets the new interface's mode of operation as seen by +the system, the driver must insure that all pipes other than the default +control pipe are closed and quiescent. To avoid contending with another driver +for a different part of the device, the driver must be bound to: the entire +device, the interface-association which includes the alternative interface, or +to the interface whose number is \fIinterface_number\fR. +.sp +.LP +If \fBUSB_FLAGS_SLEEP\fR is set in flags, \fBusb_set_alt_if()\fR blocks until +completed. Otherwise, \fBusb_set_alt_if()\fR returns immediately and calls the +callback handler when completed. +.sp +.LP +\fIcallback\fR is the asynchronous callback handler and takes the following +arguments: +.sp +.ne 2 +.mk +.na +\fBusb_pipe_handle_t pipe_handle\fR +.ad +.sp .6 +.RS 4n +Handle of the default control pipe used to perform the request. +.RE + +.sp +.ne 2 +.mk +.na +\fBusb_opaque_t callback_arg\fR +.ad +.sp .6 +.RS 4n +Callback_arg specified to \fBusb_set_alt_if()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBint rval\fR +.ad +.sp .6 +.RS 4n +Request status. +.RE + +.sp +.ne 2 +.mk +.na +\fBusb_cb_flags_t callback_flags:\fR +.ad +.sp .6 +.RS 4n +Status of the queueing operation. Can be: +.sp +USB_CB_NO_INFO - Callback was uneventful. +.sp +USB_CB_ASYNC_REQ_FAILED - Error queueing request. +.sp +USB_CB_NO_RESOURCES - Error allocating resources. +.RE + +.sp +.LP +The \fBusb_get_if_number()\fR function returns the interface number, or +\fBUSB_COMBINED_NODE\fR or \fBUSB_DEVICE_NODE\fR node indicating that the +driver is bound to the entire device. +.sp +.LP +The \fBusb_owns_device()\fR function returns \fBB_TRUE\fR if the driver of the +dip argument owns the entire device, or \fBB_FALSE\fR if it owns just a +particular interface. +.SH RETURN VALUES +.sp +.LP +For \fBusb_get_alt_if()\fR: +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 23n +.rt +Interface's alternate setting was successfully obtained. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 23n +.rt +Pointer to alternate_number and/or dip are NULL. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 23n +.rt +Called from interrupt context. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 23n +.rt +The interface number is invalid. +.sp +An access error occurred. +.RE + +.sp +.LP +For \fBusb_set_alt_if()\fR: +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 23n +.rt +Alternate interface was successfully set. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 23n +.rt +dip is NULL. USB_FLAGS_SLEEP is clear and callback is NULL. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PERM\fR +.ad +.RS 23n +.rt +dip does not own the interface to be set. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 23n +.rt +Called from interrupt context with USB_FLAGS_SLEEP specified. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PIPE\fR +.ad +.RS 23n +.rt +Pipe handle is NULL, invalid, or refers to a pipe that is closing or closed. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 23n +.rt +The interface number and/or alternate setting are invalid. +.sp +Pipes were open. +.sp +An access error occurred. +.RE + +.sp +.LP +For \fBusb_get_if_number()\fR: +.sp +.LP +\fBUSB_COMBINED_NODE\fR if the driver is responsible for the entire active +device configuration. The \fBdip\fR doesn't correspond to an entire physical +device. +.sp +.LP +\fBUSB_DEVICE_NODE\fR if the driver is responsible for the entire device. The +\fIdip\fR corresponds to an entire physical device. +.sp +.LP +interface number: otherwise. +.sp +.LP +For \fBusb_owns_device()\fR: +.sp +.ne 2 +.mk +.na +\fBB_TRUE\fR +.ad +.RS 11n +.rt +Driver of the dip argument owns the entire device. +.RE + +.sp +.ne 2 +.mk +.na +\fBB_FALSE\fR +.ad +.RS 11n +.rt +Driver of the dip argument owns only the current interface. +.RE + +.SH CONTEXT +.sp +.LP +The \fBusb_get_if_number()\fR and \fBusb_owns_device()\fR functions may be +called from user or kernel context. +.sp +.LP +The \fBusb_set_alt_if()\fR function may always be called from user or kernel +context. It may be called from interrupt context only if \fBUSB_FLAGS_SLEEP\fR +is not set in flags. If the \fBUSB_CB_ASYNC_REQ_FAILED\fR bit is clear in +\fBusb_cb_flags_t\fR, the callback, if supplied, can block because it is +executing in kernel context. Otherwise the callback cannot block. See +\fBusb_callback_flags\fR(9S) for more information on callbacks. +.sp +.LP +The \fBusb_get_alt_if()\fR function may be called from user or kernel context. +.SH EXAMPLES +.sp +.in +2 +.nf +/* Change alternate setting of interface 0. Wait for completion. */ +if (usb_set_alt_if( + dip, 0, new_alternate_setting_num, USB_FLAGS_SLEEP, NULL, 0) != + USB_SUCCESS) { + cmn_err (CE_WARN, + "%s%d: Error setting alternate setting on pipe", + ddi_driver_name(dip), ddi_get_instance(dip)); + } +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_get_dev_data\fR(9F), +\fBusb_get_string_descr\fR(9F), \fBusb_get_cfg\fR(9F) diff --git a/usr/src/man/man9f/usb_get_cfg.9f b/usr/src/man/man9f/usb_get_cfg.9f new file mode 100644 index 0000000000..66b1a73b55 --- /dev/null +++ b/usr/src/man/man9f/usb_get_cfg.9f @@ -0,0 +1,350 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_get_cfg 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_get_cfg, usb_set_cfg \- Get and set current USB device configuration +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_get_cfg\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIcfgval\fR, \fBusb_flags_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBint\fR \fBusb_set_cfg\fR(\fBdev_info_t *\fR\fIdip\fR, \fBuint_t\fR \fIcfg_index\fR, \fBusb_flags_t\fR \fIflags\fR, + \fBvoid (*\fR\fIcallback\fR)(usb_pipe_handle_t \fIpipe_handle\fR, \fBusb_opaque_t\fR + \fIcallback_arg\fR, \fBint\fR \fIrval\fR, \fBusb_cb_flags_t\fR \fIflags)\fR, \fBusb_opaque_t\fR + \fIcallback_arg\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.LP +For \fBusb_get_cfg()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 10n +.rt +Pointer to device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcfgval\fR\fR +.ad +.RS 10n +.rt +Pointer to returned configuration value. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 10n +.rt +Not used. Always waits for completion. +.RE + +.sp +.LP +For \fBusb_set_cfg()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 16n +.rt +Pointer to device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcfg_index\fR\fR +.ad +.RS 16n +.rt +Desired device configuration index. Set to USB_DEV_DEFAULT_CONFIG_INDEX to +restore default configuration. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 16n +.rt +Only USB_FLAGS_SLEEP is recognized. Wait for completion and do not call +callback. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 16n +.rt +Callback handler to notify of asynchronous completion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback_arg\fR\fR +.ad +.RS 16n +.rt +Second argument passed to callback handler. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_get_cfg()\fR function retrieves the current configuration. It +ignores the flags argument and always blocks while contacting the device. +.sp +.LP +The \fBusb_set_cfg()\fR function sets a new configuration. Because this call +changes the device's mode of operation, the device must be quiescent and have +all pipes, with the exception of the default control pipe, closed. The driver +must have control over the entire device and cannot own just a single interface +on a composite device. Additionally, its device node must not be a parent to +other device nodes that can be operated by other drivers. The driver must own +the device exclusively, otherwise drivers managing other parts of the device +would be affected without their knowledge or control. +.sp +.LP +This call updates all internal USBA framework data structures, whereas issuing +a raw USB_REQ_SET_CFG device request does not. The \fBusb_set_cfg()\fR +function is the only supported programmatic way to change device configuration. +.sp +.LP +This call blocks if USB_FLAGS_SLEEP is set in flags. It returns immediately +and calls the callback on completion if USB_FLAGS_SLEEP is not set. +.SH RETURN VALUES +.sp +.LP +For \fBusb_get_cfg()\fR: +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 20n +.rt +New configuration is retrieved. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 20n +.rt +\fIcfgval\fR or \fIdip\fR is NULL. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 20n +.rt +Configuration cannot be retrieved. +.RE + +.sp +.LP +For \fBusb_set_cfg()\fR: +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 23n +.rt +New configuration is set. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 23n +.rt +dip is NULL. +.sp +USB_FLAGS_SLEEP is clear and callback is NULL. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 23n +.rt +Called from interrupt context with USB_FLAGS_SLEEP specified. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PERM\fR +.ad +.RS 23n +.rt +Caller does not own entire device or device is a parent to child devices. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_BUSY\fR +.ad +.RS 23n +.rt +One or more pipes other than the default control pipe are open on the device. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PIPE\fR +.ad +.RS 23n +.rt +Pipe handle is NULL or invalid, or pipe is closing or closed. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 23n +.rt +An illegal configuration is specified. +.sp +One or more pipes other than the default control pipe are open on the device. +.RE + +.SH CONTEXT +.sp +.LP +The \fBusb_get_cfg()\fR function may be called from user or kernel context. +.sp +.LP +The \fBusb_set_cfg()\fR function may be called from user or kernel context +always. It may be called from interrupt context only if USB_FLAGS_SLEEP is not +set in flags. +.sp +.LP +If the USB_CB_ASYNC_REQ_FAILED bit is clear in usb_cb_flags_t, the callback, if +supplied, can block because it is executing in kernel context. Otherwise the +callback cannot block. Please see \fBusb_callback_flags\fR(9S) for more +information on callbacks. +.SH EXAMPLES +.sp +.in +2 +.nf + Setting the configuration to the one at index 1 (in the + array of usb_cfg_data_t configuration nodes as returned + by usb_get_dev_data()), and verifying what the configuration + is at that index. (See usb_get_dev_data(9F)). + + uint_t cfg_index = 1; + + /* + * Assume all pipes other than the default control pipe + * are closed and make sure all requests to the default + * control pipe have completed. / + */ + + + if (usb_set_cfg(dip, cfg_index, USB_FLAGS_SLEEP, NULL, 0) + != USB_SUCCESS) { + cmn_err (CE_WARN, + "%s%d: Error setting USB device to configuration #%d", + ddi_driver_name(dip), ddi_get_instance(dip), cfg_index); + } + + if (usb_get_cfg(dip, &bConfigurationValue, 0) == USB_SUCCESS) { + cmn_err (CE_WARN, "%s%d: USB device active configuration is %d", + ddi_driver_name(dip), ddi_get_instance(dip), + bConfigurationValue); + } else { + ... + ... + } + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_alt_if\fR(9F), \fBusb_get_dev_data\fR(9F), +\fBusb_get_string_descr\fR(9F), \fBusb_pipe_open\fR(9F), +\fBusb_callback_flags\fR(9S), \fBusb_cfg_descr\fR(9S), \fBusb_ep_descr\fR(9S), +\fBusb_if_descr\fR(9S) diff --git a/usr/src/man/man9f/usb_get_current_frame_number.9f b/usr/src/man/man9f/usb_get_current_frame_number.9f new file mode 100644 index 0000000000..ab04d56ece --- /dev/null +++ b/usr/src/man/man9f/usb_get_current_frame_number.9f @@ -0,0 +1,107 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_get_current_frame_number 9F "25 July 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_get_current_frame_number \- Return current logical usb frame number +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBusb_frame_number_t\fR \fBusb_get_current_frame_number\fR(\fBdev_info_t *\fR\fIdip\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 +Pointer to the device's \fBdev_info\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_get_current_frame_number()\fR function retrieves the current logical +USB frame number. +.sp +.LP +Isochronous requests can be started on a particular numbered frame. An offset +number of frames (typically between 4 and 10) can be added to the current +logical frame number to specify the number of an upcoming frame to start an +isochronous request. +.sp +.LP +The USB specification requires that the frame frequency (the period between +start-of-frame packets) is one millisecond. The Solaris operating environment +USB implementation uses a running counter of the number of milliseconds since +boot as the current logical frame number. +.SH RETURN VALUES +.sp +.LP +On success, the \fBusb_get_current_frame_number()\fR function returns the +current USB frame number. On failure it returns \fB0\fR. The function fails if +\fIdip\fR is NULL. +.SH CONTEXT +.sp +.LP +May be called from user, kernel or interrupt context. +.SH EXAMPLES +.sp +.in +2 +.nf + usb_pipe_handle_t handle; + usb_frame_number_t offset = 10; + usb_isoc_req_t *isoc_req; + + isoc_req = usb_alloc_isoc_req(...); + ... + ... + isoc_req->isoc_frame_no = usb_get_current_frame_number(dip) + offset; + isoc_req->isoc_attributes = USB_ATTRS_ISOC_START_FRAME; + ... + ... + if (usb_pipe_isoc_xfer(handle, isoc_req, 0) != USB_SUCCESS) { + ... + } +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_alloc_isoc_req\fR(9F), +\fBusb_get_max_pkts_per_isoc_request\fR(9F), \fBusb_pipe_isoc_xfer\fR(9F), +\fBusb_pipe_get_max_bulk_transfer_size\fR(9F), \fBusb_isoc_request\fR(9S) diff --git a/usr/src/man/man9f/usb_get_dev_data.9f b/usr/src/man/man9f/usb_get_dev_data.9f new file mode 100644 index 0000000000..91d3108435 --- /dev/null +++ b/usr/src/man/man9f/usb_get_dev_data.9f @@ -0,0 +1,466 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_get_dev_data 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_get_dev_data, usb_free_dev_data, usb_free_descr_tree, usb_print_descr_tree +\- Retrieve device configuration information +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_get_dev_data\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_client_dev_data_t **\fR\fIdev_data\fR, + \fBusb_reg_parse_lvl_t\fR \fIparse_level\fR, \fBusb_flags_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBusb_free_dev_data\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_client_dev_data_t *\fR\fIdev_data\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBusb_free_descr_tree\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_client_dev_data_t *\fR\fIdev_data\fR); +.fi + +.LP +.nf +\fBint\fR \fBusb_print_descr_tree\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_client_dev_data_t *\fR\fIdev_data\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.LP +For \fBusb_get_dev_data()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 15n +.rt +Pointer to device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_data\fR\fR +.ad +.RS 15n +.rt +Address in which pointer to info is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIparse_level\fR\fR +.ad +.RS 15n +.rt +Portion of device represented in the tree of parsed descriptors. See below for +possible usb_reg_parse_lvl_t values and explanations. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 15n +.rt +Not used. +.RE + +.sp +.LP +For \fBusb_free_dev_data()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 12n +.rt +Pointer to device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_data\fR\fR +.ad +.RS 12n +.rt +Pointer to usb_client_dev_data_t to be freed. +.RE + +.sp +.LP +For \fBusb_free_descr_tree()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 12n +.rt +Pointer to device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_data\fR\fR +.ad +.RS 12n +.rt +Pointer to usb_client_dev_data_t containing the descriptor tree to free. +.RE + +.sp +.LP +For \fBusb_print_descr_tree()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 12n +.rt +Pointer to device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_data\fR\fR +.ad +.RS 12n +.rt +Pointer to usb_client_dev_data_t containing the descriptor tree to display +on-screen. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_get_dev_data()\fR function interrogates a device and returns its +configuration information in a usb_client_dev_data_t structure. Most USBA +functions require information which comes from a usb_client_dev_data_t, and all +other functions in this man page operate on this structure. Please see +\fBusb_client_dev_data(9S)\fR for a full content description. Pass the +usb_client_dev_data_t structure to \fBusb_client_detach\fR(9F) to completely +deallocate it. +.sp +.LP +A descriptor tree is included in the information returned. The +usb_reg_parse_lvl_t type represents the extent of the device to be +represented by the returned tree (2nd arg to usb_get_dev_data) or what is +actually represented in the returned tree (dev_parse_level field of the +returned usb_client_dev_data_t). It has the following possible values: +.sp +.ne 2 +.mk +.na +\fBUSB_PARSE_LVL_NONE\fR +.ad +.RS 22n +.rt +Build no tree. dev_n_cfg returns 0, dev_cfg and dev_curr_cfg are returned +NULL, and the dev_curr_xxx fields are invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_PARSE_LVL_IF\fR +.ad +.RS 22n +.rt +If configuration number and interface properties are set (as when different +interfaces are viewed by the OS as different device instances), parse +configured interface only. If an OS device instance is set up to represent an +entire physical device, USB_PARSE_LVL_IF works like USB_PARSE_LVL_ALL. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_PARSE_LVL_CFG\fR +.ad +.RS 22n +.rt +Parse entire configuration of configured interface only. Behaves similarly to +USB_PARSE_LVL_IF, except that entire configuration is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_PARSE_LVL_ALL\fR +.ad +.RS 22n +.rt +Parse entire device (all configurations), even when driver is bound to a single +interface of a single configuration. +.RE + +.sp +.LP +The \fBusb_free_dev_data()\fR function undoes what \fBusb_get_dev_data()\fR set +up. It releases memory for all strings, descriptors, and trees set up by +\fBusb_get_dev_data()\fR. +.sp +.LP +The \fBusb_free_descr_tree()\fR function frees the descriptor tree of its +usb_client_dev_data_t argument, while leaving the rest of the information +intact. The intent is for drivers to free memory after copying needed +descriptor information from the tree. Upon return, the following +usb_client_dev_data_t fields are modified as follows: dev_cfg is NULL, +dev_n_cfg is zero and dev_parse_level is USB_PARSE_LVL_NONE. Additionally, +dev_curr_cfg is NULL and dev_curr_if is invalid. +.sp +.LP +The \fBusb_print_descr_tree()\fR function is an easy-to-use diagnostic aid +which dumps the descriptor tree to the screen when the system is verbose booted +(\fBboot\fR \fB-v\fR). Output is spaced with blank lines for readability and +provides you with an on-screen look at what a device has to offer. +.SH RETURN VALUES +.sp +.LP +For \fBusb_get_dev_data()\fR: +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 23n +.rt +Registration is successful. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 23n +.rt +\fIdip\fR or \fIdev_data\fR is \fBNULL\fR. \fIparse_level\fR is invalid. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 23n +.rt +Called from interrupt context. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_VERSION\fR +.ad +.RS 23n +.rt +\fBusb_client_attach\fR(9F) was not called first. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 23n +.rt +Bad descriptor info or other internal error. +.RE + +.sp +.LP +For \fBusb_free_dev_data()\fR: None +.sp +.LP +For \fBusb_free_descr_tree()\fR: None, but no operation occurs if \fIdip\fR +and/or \fIdev_data\fR are NULL. +.sp +.LP +For \fBusb_print_descr_tree()\fR: +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 23n +.rt +Descriptor tree dump is successful. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 23n +.rt +\fIdev_data\fR or \fIdip\fR are NULL. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 23n +.rt +Called from interrupt context. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 23n +.rt +Other error. +.RE + +.SH CONTEXT +.sp +.LP +The \fBusb_get_dev_data()\fR and \fBusb_print_descr_tree()\fR functions may be +called from user or kernel context. +.sp +.LP +The \fBusb_free_dev_data()\fR and \fBusb_free_descr_tree()\fR functions may be +called from user, kernel or interrupt context. +.SH EXAMPLES +.sp +.in +2 +.nf +In this example, assume a device has the configuration shown +below, and the endpoint of config 2, iface 1, alt 1 +which supports intr IN transfers needs to be found. +Config 2, iface 1 is the "default" config/iface for the +current OS device node. + + config 1 + iface 0 + endpt 0 + config 2 + iface 0 + iface 1 + alt 0 + endpt 0 + cv 0 + alt 1 + endpt 0 + endpt 1 + cv 0 + endpt 2 + alt 2 + endpt 0 + cv 0 + + usb_client_dev_data_t *dev_data; + usb_ep_descr_t ep_descr; + usb_ep_data_t *ep_tree_node; + uint8_t interface = 1; + uint8_t alternate = 1; + uint8_t first_ep_number = 0; + + /* + * We want default config/iface, so specify USB__PARSE_LVL_IF. + * Default config will be returned as dev_cfg[0]. + / + if (usb_get_dev_data(dip, &dev_data, + USB_PARSE_LVL_IF, 0) != USB_SUCCESS) { + cmn_err (CE_WARN, + "%s%d: Couldn't get USB configuration descr tree", + ddi_driver_name(dip), ddi_get_instance(dip)); + + return (USB_FAILURE); + } + + ep_tree_node = usb_lookup_ep_data(dip, dev_data, interface, + alternate, first_ep_number, USB_EP_ATTR_INTR, USB_EP_DIR_IN); + if (ep_tree_node != NULL) { + ep_descr = ep_tree_node->ep_descr; + } else { + cmn_r (CE_WARN, + "%s%d: Device is missing intr-IN endpoint", + ddi_driver_name(dip), ddi_get_instance(dip)); + + usb_free_descr_tree(dip, &dev_data); + + return (USB_FAILURE); + } + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_client_attach\fR(9F), \fBusb_get_alt_if\fR(9F), +\fBusb_get_cfg\fR(9F), \fBusb_get_string_descr\fR(9F), +\fBusb_lookup_ep_data\fR(9F), \fBusb_parse_data\fR(9F), +\fBusb_pipe_open\fR(9F), \fBusb_cfg_descr\fR(9S), +\fBusb_client_dev_data(9S)\fR, \fBusb_ep_descr\fR(9S), \fBusb_if_descr\fR(9S), +\fBusb_string_descr\fR(9S) diff --git a/usr/src/man/man9f/usb_get_max_pkts_per_isoc_request.9f b/usr/src/man/man9f/usb_get_max_pkts_per_isoc_request.9f new file mode 100644 index 0000000000..c88217f6a2 --- /dev/null +++ b/usr/src/man/man9f/usb_get_max_pkts_per_isoc_request.9f @@ -0,0 +1,131 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_get_max_pkts_per_isoc_request 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_get_max_pkts_per_isoc_request \- Get maximum number of packets allowed per +isochronous request +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fB\fR\fBuint_t\fR usb_get_max_pkts_per_isoc_request(\fBdev_info_t *\fR\fIdip\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 +Pointer to the device's \fBdev_info\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_get_max_pkts_per_isoc_request()\fR function returns the maximum +number of isochronous packets per request that the host control driver can +support. This number can be used to determine the maximum amount of data which +can be handled by a single isochronous request. That length is found by: +.sp +.in +2 +.nf +max = usb_get_max_pkts_per_isoc_request(dip) * endpoint_max_packet_size; +.fi +.in -2 + +.sp +.LP +where endpoint_max_packet_size is the wMaxPacketSize field of the isochronous +endpoint over which the transfer will take place. +.SH RETURN VALUES +.sp +.LP +On success, the \fBusb_get_current_frame_number()\fR function returns the +maximum number of isochronous pkts per request. On failure it returns \fB0\fR. +The function fails if \fIdip\fR is NULL. +.SH CONTEXT +.sp +.LP +May be called from user, kernel or interrupt context. +.SH EXAMPLES +.sp +.in +2 +.nf +/* + * Set up to receive periodic isochronous data, requesting + * the maximum amount for each transfer. + */ + +int pkt; +/* Get max packet size from endpoint descriptor. */ +uint_t ep_max_pkt_size = ep_descr.wMaxPacketSize; +uint_t isoc_pkts_count = usb_get_max_pkts_per_isoc_request(dip); + +/* + * Allocate an isoc request, specifying the max number of packets + * and the greatest size transfer possible. + */ +usb_isoc_req_t *isoc_req = usb_alloc_isoc_req(dip, + isoc_pkts_count, + isoc_pkts_count * ep_max_pkt_size, + USB_FLAGS_SLEEP); + +/* Init each packet descriptor for maximum size. */ +for (pkt = 0; pkt < isoc_pkts_count; pkt++) { + isoc_req->isoc_pkt_descr[pkt].isoc_pkt_length = ep_max_pkt_size; + +} + + +/* Set the length of a packet in the request too. */ +isoc_req->isoc_pkts_length = ep_max_pkt_size; + +/* Other isoc request initialization. */ +\&... +\&... + +if (usb_pipe_isoc_xfer(pipe, isoc_req, USB_FLAGS_NOSLEEP) != USB_SUCCESS) { + ... +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_pipe_isoc_xfer\fR(9F), \fBusb_alloc_request\fR(9F), +\fBusb_get_current_frame_number\fR(9F). \fBusb_ep_descr\fR(9S), +\fBusb_isoc_request\fR(9S) diff --git a/usr/src/man/man9f/usb_get_status.9f b/usr/src/man/man9f/usb_get_status.9f new file mode 100644 index 0000000000..0d5d18231d --- /dev/null +++ b/usr/src/man/man9f/usb_get_status.9f @@ -0,0 +1,211 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_get_status 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_get_status \- Get status of a USB device/endpoint/interface +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_get_status\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_pipe_handle_t\fR \fIpipe_handle\fR, + \fBuint_t\fR \fIrequest_type\fR, \fBuint_t\fR \fIwhich\fR, \fBuint16_t *\fR\fIstatus\fR, + \fBusb_flags_t\fR \fIflags\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 16n +.rt +Pointer to device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 16n +.rt +Default control pipe handle on which request is made. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrequest_type\fR\fR +.ad +.RS 16n +.rt +bmRequestType. Either: +.sp +USB_DEV_REQ_RCPT_DEV \(em Get device status. +.sp +USB_DEV_REQ_RCPT_IF \(em Get interface status. +.sp +USB_DEV_REQ_RCPT_EP \(em Get endpoint status. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIwhich\fR\fR +.ad +.RS 16n +.rt +Device, interface or endpoint from which to get status. Either number of +interface or endpoint, or 0 if device status requested. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstatus\fR\fR +.ad +.RS 16n +.rt +Address into which the status is written. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 16n +.rt +None are recognized. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_get_status()\fR function returns the status of a device, interface +or endpoint. All status requests use the default control pipe. Length of data +returned is USB_GET_STATUS_LEN bytes. Always block and wait for resources if +not available, regardless of the flags argument. +.sp +.LP +When the \fIrequest_type\fR recipient is USB_DEV_REQ_RCPT_DEV, device status is +requested. Status returned includes bits for USB_DEV_SLF_PWRD_STATUS (device is +currently self-powered) and USB_DEV_RWAKEUP_STATUS (device has remote wakeup +enabled). A set bit indicates the corresponding status. +.sp +.LP +When the \fIrequest_type\fR is USB_DEV_REQ_RCPT_EP, endpoint status is +requested. Status returned includes bits for USB_EP_HALT_STATUS (endpoint is +halted). A set bit indicates the corresponding status. +.sp +.LP +When the \fIrequest_type\fR is USB_DEV_REQ_RCPT_IF, interface status is +requested and USB_IF_STATUS (zero) is returned. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 20n +.rt +Status returned successfully in the status argument. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 20n +.rt +Status pointer and/or dip argument is NULL. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PIPE\fR +.ad +.RS 20n +.rt +Pipe handle is NULL. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 20n +.rt +Status not returned successfully. +.RE + +.SH CONTEXT +.sp +.LP +May be called from user or kernel context. +.SH EXAMPLES +.sp +.in +2 +.nf + uint16_t status; + + if (usb_get_status( + dip, pipe_handle, USB_DEV_REQ_RCPT_DEV, 0 &status, 0) == + USB_SUCCESS) { + if (status & USB_DEV_SLF_PWRD_STATUS) { + cmn_err (CE_WARN, + "%s%d: USB device is running on its own power.", + ddi_driver_name(dip), ddi_get_instance(dip)); + } + } +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_clr_feature\fR(9F), \fBusb_get_alt_if\fR(9F), +\fBusb_pipe_get_state\fR(9F), \fBusb_get_cfg\fR(9F), diff --git a/usr/src/man/man9f/usb_get_string_descr.9f b/usr/src/man/man9f/usb_get_string_descr.9f new file mode 100644 index 0000000000..7ac059c1ef --- /dev/null +++ b/usr/src/man/man9f/usb_get_string_descr.9f @@ -0,0 +1,177 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_get_string_descr 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_get_string_descr \- Get string descriptor from device +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_get_string_descr\fR(\fBdev_info_t *\fR\fIdip\fR, + \fBuint16_t\fR \fIlangid\fR, \fBuint8_t\fR \fIindex\fR, + \fBchar *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\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 10n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlangid\fR\fR +.ad +.RS 10n +.rt +Language ID. Currently only USB_LANG_ID (English ascii) is valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIindex\fR\fR +.ad +.RS 10n +.rt +String index indicating descriptor to retrieve. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuf\fR\fR +.ad +.RS 10n +.rt +Address into which the string descriptor is placed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuflen\fR\fR +.ad +.RS 10n +.rt +Size of buf in bytes. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_get_string_descr()\fR function retrieves a parsed string descriptor +from a device. \fIdip\fR specifies the device, while \fIindex\fR indicates +which descriptor to return. +.sp +.LP +String descriptors provide information about other descriptors, or information +that is encoded in other descriptors, in readable form. Many descriptor types +have one or more index fields which identify string descriptors. (See +Sections \fI9.5\fR and \fI9.6\fR of the \fIUSB 2.0\fR specification.) For +example, a configuration descriptor's seventh byte contains the string +descriptor index describing a specific configuration. +.sp +.LP +Retrieved descriptors that do not fit into \fIbuflen\fR bytes are truncated. +All returned descriptors are null-terminated. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 20n +.rt +String descriptor is returned in \fIbuf\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 20n +.rt +\fIdip\fR or \fIbuf\fR are \fBNULL\fR, or \fIindex\fR or \fIbuflen\fR is +\fB0\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 20n +.rt +Descriptor cannot be retrieved. +.RE + +.SH CONTEXT +.sp +.LP +May be called from user or kernel context. +.SH EXAMPLES +.sp +.in +2 +.nf + /* Get the first string descriptor. */ + + char buf[SIZE]; + + if (usb_get_string_descr( + dip, USB_LANG_ID, 0, buf, SIZE) == USB_SUCCESS) { + cmn_err (CE_NOTE, "%s%d: %s", + ddi_driver_name(dip), ddi_get_instance(dip), buf); + } +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_dev_data\fR(9F), \fBusb_string_descr\fR(9S) diff --git a/usr/src/man/man9f/usb_handle_remote_wakeup.9f b/usr/src/man/man9f/usb_handle_remote_wakeup.9f new file mode 100644 index 0000000000..d9c50feda8 --- /dev/null +++ b/usr/src/man/man9f/usb_handle_remote_wakeup.9f @@ -0,0 +1,118 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_handle_remote_wakeup 9F "5 Feb 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_handle_remote_wakeup \- Enable or disable remote wakeup on USB devices +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_handle_remote_wakeup\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\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 +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcmd\fR\fR +.ad +.RS 7n +.rt +Command. Either USB_REMOTE_WAKEUP_ENABLE or USB_REMOTE_WAKEUP_DISABLE. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_handle_remote_wakeup()\fR function enables or disables remote wakeup +on a USB device. This call can block. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 15n +.rt +Remote wakeup is successfully enabled or disabled. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 15n +.rt +Remote wakeup is not supported by the device. An internal error occurred. +.RE + +.SH CONTEXT +.sp +.LP +May be called from user or kernel context. +.SH EXAMPLES +.sp +.in +2 +.nf + uint_t *pwrstates; + + /* Hook into device's power management. Enable remote wakeup. */ + if (usb_create_pm_components(dip, pwrstates) == USB_SUCCESS) { + usb_handle_remote_wakeup(dip, USB_REMOTE_WAKEUP_ENABLE); + } + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBpm_busy_component\fR(9F), \fBpm_idle_component\fR(9F), +\fBpm_lower_power\fR(9F), \fBpm_raise_power\fR(9F), \fBusb_clr_feature\fR(9F), +\fBusb_create_pm_components\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_dev_data\fR(9F), \fBusb_register_hotplug_cbs\fR(9F), +\fBusb_cfg_descr\fR(9S) diff --git a/usr/src/man/man9f/usb_lookup_ep_data.9f b/usr/src/man/man9f/usb_lookup_ep_data.9f new file mode 100644 index 0000000000..f2e390f0aa --- /dev/null +++ b/usr/src/man/man9f/usb_lookup_ep_data.9f @@ -0,0 +1,186 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_lookup_ep_data 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_lookup_ep_data \- Lookup endpoint information +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBusb_ep_data_t *\fR\fBusb_lookup_ep_data\fR(\fBdev_info_t *\fR\fIdip\fR, + \fBusb_client_dev_data_t *\fR\fIdev_datap\fR, \fBuint_t\fR \fIinterface\fR, + \fBuint_t\fR \fIalternate\fR, \fBuint_t\fR \fIskip\fR, \fBuint_t\fR \fItype\fR, \fBuint_t\fR \fIdirection\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 13n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdev_datap\fR\fR +.ad +.RS 13n +.rt +Pointer to a \fBusb_client_dev_data_t\fR structure containing tree. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinterface\fR\fR +.ad +.RS 13n +.rt +Number of interface in which endpoint resides. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIalternate\fR\fR +.ad +.RS 13n +.rt +Number of interface alternate setting in which endpoint resides. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIskip\fR\fR +.ad +.RS 13n +.rt +Number of endpoints which match the requested type and direction to skip before +finding one to retrieve. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 13n +.rt +Type of endpoint. This is one of: USB_EP_ATTR_CONTROL, USB_EP_ATTR_ISOCH, +USB_EP_ATTR_BULK, or USB_EP_ATTR_INTR. Please see \fBusb_pipe_open\fR(9F) for +more information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdirection\fR\fR +.ad +.RS 13n +.rt +Direction of endpoint, either USB_EP_DIR_OUT or USB_EP_DIR_IN. This argument is +ignored for bi-directional control endpoints. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_lookup_ep_data()\fR function returns endpoint information from the +tree embedded in client data returned from \fBusb_get_dev_data\fR. It operates +on the current configuration (pointed to by the dev_curr_cfg field of the +\fBusb_client_dev_data_t\fR argument). It skips the first <skip> number of +endpoints it finds which match the specifications of the other arguments, and +then retrieves information on the next matching endpoint it finds. Note that it +does not make a copy of the data, but points to the tree itself. +.SH RETURN VALUES +.sp +.LP +On success: the tree node corresponding to the desired endpoint. +.sp +.LP +On failure: returns NULL. Fails if \fIdip\fR or \fIdev_datap\fR are NULL, if +the desired endpoint does not exist in the tree, or no tree is present in +dev_datap. +.SH CONTEXT +.sp +.LP +May be called from user, kernel or interrupt context. +.SH EXAMPLES +.sp +.LP +Retrieve the polling interval for the second interrupt endpoint at interface 0, +alt 3: +.sp +.in +2 +.nf + uint8_t interval = 0; + usb_ep_data_t *ep_node = usb_lookup_ep_data( + dip, dev_datap, 0, 3, 1, USB_EP_ATTR_INTR, USB_EP_DIR_IN); + if (ep_node != NULL) { + interval = ep_node->ep_descr.bInterval; + } +.fi +.in -2 + +.sp +.LP +Retrieve the maximum packet size for the first control pipe at interface 0, alt +4: +.sp +.in +2 +.nf + uint16_t maxPacketSize = 0; + usb_ep_data_t *ep_node = usb_lookup_ep_data( + dip, dev_datap, 0, 4, 0, USB_EP_ATTR_CONTROL, 0); + if (ep_node != NULL) { + maxPacketSize = ep_node->ep_descr.wMaxPacketSize; + } +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_dev_data\fR(9F), \fBusb_pipe_open\fR(9F), +\fBusb_cfg_descr\fR(9S), \fBusb_if_descr\fR(9S), \fBusb_ep_descr\fR(9S) diff --git a/usr/src/man/man9f/usb_parse_data.9f b/usr/src/man/man9f/usb_parse_data.9f new file mode 100644 index 0000000000..68a0aa0ecd --- /dev/null +++ b/usr/src/man/man9f/usb_parse_data.9f @@ -0,0 +1,171 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_parse_data 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_parse_data \- Tokenize and align the bytes of raw variable-format data +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBsize_t\fR \fBusb_parse_data\fR(\fBchar *\fR\fIformat\fR, \fBuchar_t *\fR\fIdata\fR, + \fBsize_t\fR \fIdatalen\fR, \fBvoid *\fR\fIstructure\fR, \fBsize_t\fR \fIstructlen\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIformat\fR\fR +.ad +.RS 13n +.rt +Null terminated string describing the format of the data structure for +general-purpose byte swapping. The letters "c," "s," "l," and "L" represent 1, +2, 4 and 8 byte quantities, respectively. A descriptor that consists of a short +and two bytes would be described by "scc." A number preceding a letter serves +as a multiplier of that letter. A format equivalent to "scc" is "s2c." +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdata\fR\fR +.ad +.RS 13n +.rt +Raw descriptor data to parse. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdatalen\fR\fR +.ad +.RS 13n +.rt +Length, in bytes, of the raw descriptor data buffer. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstructure\fR\fR +.ad +.RS 13n +.rt +Destination data buffer where parsed data is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstructlen\fR\fR +.ad +.RS 13n +.rt +Length, in bytes, of the destination data buffer. Parsed result length will not +exceed this value. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_parse_data\fR function parses data such as a variable-format class- +or vendor-specific descriptor. The function also tokenizes and aligns the bytes +of raw descriptor data into fields of a variable-format descriptor. +.sp +.LP +While the USBA framework can parse the endpoint, interface, configuration, and +string descriptors defined by the \fIUSB 2.0\fR specification, the format of +class- or vendor-specific descriptors cannot be explicitly defined by the +specification and will be unique for each. The \fIformat\fR argument defines +how to parse such a descriptor. +.sp +.LP +While the USB specification defines bit ordering as little-endian, this routine +(like the entire API), converts the data to the endianness of the host. +.sp +.LP +The \fIstructlen\fR parameter defines the size of the destination data buffer. +Data is truncated to this size if the destination data buffer is too small. +.SH RETURN VALUES +.sp +.LP +On success: Returns the size (in bytes) of the parsed data result. +.sp +.LP +On failure: Returns 0. (Same as USB_PARSE_ERROR). +.SH CONTEXT +.sp +.LP +May be called from user, kernel or interrupt context. +.SH EXAMPLES +.sp +.in +2 +.nf + /* + * Parse raw descriptor data in buf, putting result into ret_descr. + * ret_buf_len holds the size of ret_descr buf; routine returns + * number of resulting bytes. + * + * Descriptor being parsed has 2 chars, followed by one short, + * 3 chars and one more short. + */ + size_t size_of_returned_descr; + xxx_descr_t ret_descr; + + size_of_returned_descr = usb_parse_data("ccscccs", + buf, sizeof(buf), (void *)ret_descr, (sizeof)xxx_descr_t)); + if (size_of_returned_descr < (sizeof (xxx_descr_t))) { + /* Data truncated. */ + } + + or: + + size_of_returned_descr = usb_parse_data("2cs3cs", + buf, sizeof(buf), (void *)ret_descr, (sizeof)xxx_descr_t)); + if (size_of_returned_descr < (sizeof (xxx_descr_t))) { + /* Data truncated. */ + } +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_dev_data\fR(9F), +\fBusb_get_string_descr\fR(9F), \fBusb_get_cfg\fR(9F) diff --git a/usr/src/man/man9f/usb_pipe_bulk_xfer.9f b/usr/src/man/man9f/usb_pipe_bulk_xfer.9f new file mode 100644 index 0000000000..c69513fdd0 --- /dev/null +++ b/usr/src/man/man9f/usb_pipe_bulk_xfer.9f @@ -0,0 +1,264 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_pipe_bulk_xfer 9F "3 Aug 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_pipe_bulk_xfer \- USB bulk transfer function +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_pipe_bulk_xfer\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, + \fBusb_bulk_req_t *\fR\fIrequest\fR, \fBusb_flags_t\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 15n +.rt +Bulk pipe handle on which request is made. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrequest\fR\fR +.ad +.RS 15n +.rt +Pointer to bulk transfer request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 15n +.rt +USB_FLAGS_SLEEP is the only flag recognized. Wait for request to complete. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_pipe_bulk_xfer()\fR function requests the USBA framework to perform +a transfer through a USB bulk pipe. The request is passed to the host +controller driver (HCD), which performs the necessary transactions to complete +the request. Requests are synchronous when USB_FLAGS_SLEEP has been specified +in flags. Calls for synchronous requests will not return until their +transaction has completed. Asynchronous requests (made without specifying the +USB_FLAGS_SLEEP flag) notify the caller of their completion via a callback +function. +.sp +.LP +Requests for bulk transfers must have mblks attached to store data. Allocate an +mblk for data when a request is allocated via \fBusb_alloc_bulk_req\fR(9F) by +passing a non-negative value for the \fIlen\fR argument. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 25n +.rt +Transfer was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 25n +.rt +Request is \fBNULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 25n +.rt +Called from interrupt context with the USB_FLAGS_SLEEP flag set. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_REQUEST\fR +.ad +.RS 25n +.rt +The request has been freed or otherwise invalidated. +.sp +A set of conflicting attributes were specified. See \fBusb_bulk_request\fR(9S). +.sp +The normal and/or exception callback was NULL and USB_FLAGS_SLEEP was not set. +.sp +Data space is not provided to a non-zero length bulk request: +.sp +.in +2 +.nf +(bulk_data == NULL and bulk_len != 0) +.fi +.in -2 + +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PIPE\fR +.ad +.RS 25n +.rt +Pipe handle is NULL or invalid. +.sp +Pipe is closing or closed. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_PIPE_ERROR\fR +.ad +.RS 25n +.rt +Pipe handle refers to a pipe which is in the USB_PIPE_STATE_ERROR state. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_NO_RESOURCES\fR +.ad +.RS 25n +.rt +Memory, descriptors or other resources are unavailable. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_HC_HARDWARE_ERROR\fR +.ad +.RS 25n +.rt +Host controller is in error state. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 25n +.rt +An asynchronous transfer failed or an internal error occurred. +.sp +A bulk request requested too much data: +.sp +.in +2 +.nf +(length > usb_get_max_bulk_xfer size()) +.fi +.in -2 + +The pipe is in a unsuitable state (error, busy, not ready). +.RE + +.sp +.LP +Additional status information may be available in the bulk_completion_reason +and bulk_cb_flags fields of the request. Please see +\fBusb_completion_reason\fR(9S) and \fBusb_callback_flags\fR(9S) for more +information. +.SH CONTEXT +.sp +.LP +May be called from kernel or user context without regard to arguments. May be +called from interrupt context only when the USB_FLAGS_SLEEP flag is clear. +.SH EXAMPLES +.sp +.in +2 +.nf + /* Allocate, initialize and issue a synchronous bulk request. */ + + usb_bulk_req_t bulk_req; + mblk_t *mblk; + + bulk_req = usb_alloc_bulk_req(dip, bp->b_bcount, USB_FLAGS_SLEEP); + + bulk_req->bulk_attributes = USB_ATTRS_AUTOCLEARING; + mblk = bulk_req->bulk_data; + bcopy(buffer, mblk->b_wptr, bp->b_bcount); + mblk->b_wptr += bp->b_bcount; + + if ((rval = usb_pipe_bulk_xfer(pipe, bulk_req, USB_FLAGS_SLEEP)) + != USB_SUCCESS) { + cmn_err (CE_WARN, "%s%d: Error writing bulk data.", + ddi_driver_name(dip), ddi_get_instance(dip)); + } + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_alloc_request\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_status\fR(9F), \fBusb_pipe_ctrl_xfer\fR(9F), +\fBusb_pipe_get_state\fR(9F), \fBusb_pipe_intr_xfer\fR(9F), +\fBusb_pipe_isoc_xfer\fR(9F), \fBusb_pipe_open\fR(9F), +\fBusb_pipe_reset\fR(9F), \fBusb_bulk_request\fR(9S), +\fBusb_callback_flags\fR(9S), \fBusb_completion_reason\fR(9S), +\fBusb_ctrl_request\fR(9S), \fBusb_intr_request\fR(9S), +\fBusb_isoc_request\fR(9S) diff --git a/usr/src/man/man9f/usb_pipe_close.9f b/usr/src/man/man9f/usb_pipe_close.9f new file mode 100644 index 0000000000..61ea8678c9 --- /dev/null +++ b/usr/src/man/man9f/usb_pipe_close.9f @@ -0,0 +1,303 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_pipe_close 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_pipe_close \- Close and cleanup a USB device pipe +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBvoid\fR \fBusb_pipe_close\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_pipe_handle_t\fR \fIpipe_handle\fR, + \fBusb_flags_t\fR \fIflags\fR, + \fBvoid\fR (\fI*callback\fR)(usb_pipe_handle_t \fIpipe_handle\fR, + \fBusb_opaque_t\fR \fIarg\fR, \fBint\fR \fIrval\fR, + \fBusb_cb_flags_t\fR \fIflags)\fR, \fBusb_opaque_t\fR \fIcallback_arg\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 16n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 16n +.rt +Handle of pipe to close. Cannot be a handle to the default control pipe. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 16n +.rt +USB_FLAGS_SLEEP is the only flag recognized. Set it to wait for resources, for +pipe to become free, and for all pending request callbacks to complete. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 16n +.rt +This function is called on completion if the USB_FLAGS_SLEEP flag is not +specified. Mandatory if the USB_FLAGS_SLEEP flag has not been specified. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback_arg\fR\fR +.ad +.RS 16n +.rt +Second argument to callback function. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_pipe_close()\fR function closes the pipe pointed to by +\fIpipe_handle\fR, releases all related resources and then frees the pipe +handle. This function stops polling if the pipe to be closed is an interrupt-IN +or isochronous-IN pipe. The default control pipe cannot be closed. +.sp +.LP +Pipe cleanup includes waiting for the all pending requests in the pipe to +finish, and then flushing residual requests remaining after waiting for several +seconds. Exception handlers of flushed requests are called with a completion +reason of USB_CR_FLUSHED. +.sp +.LP +If USB_FLAGS_SLEEP is specified in \fIflags\fR, wait for all cleanup operations +to complete before calling the callback handler and returning. +.sp +.LP +If USB_FLAGS_SLEEP is not specified in \fIflags\fR, an asynchronous close (to +be done in a separate thread) is requested. Return immediately. The callback +handler is called after all pending operations are completed. +.sp +.LP +The \fIcallback\fR parameter is the callback handler and takes the following +arguments: +.sp +.ne 2 +.mk +.na +\fBusb_pipe_handle_t pipe_handle\fR +.ad +.sp .6 +.RS 4n +Handle of the pipe to close. +.RE + +.sp +.ne 2 +.mk +.na +\fBusb_opaque_t callback_arg\fR +.ad +.sp .6 +.RS 4n +Callback_arg specified to \fBusb_pipe_close()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBint rval\fR +.ad +.sp .6 +.RS 4n +Return value of close operation +.RE + +.sp +.ne 2 +.mk +.na +\fBusb_cb_flags_t callback_flags\fR +.ad +.sp .6 +.RS 4n +Status of queueing operation. Can be: +.sp +.ne 2 +.mk +.na +\fBUSB_CB_NO_INFO\fR +.ad +.RS 27n +.rt +Callback was uneventful. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CB_ASYNC_REQ_FAILED\fR +.ad +.RS 27n +.rt +Error starting asynchronous request. +.RE + +.RE + +.SH RETURN VALUES +.sp +.LP +Status is returned to the caller via the callback handler's rval argument. +Possible callback hander rval argument values are: +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PIPE\fR +.ad +.RS 23n +.rt +Pipe handle specifies a pipe which is closed or closing. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 23n +.rt +\fIdip\fR or \fIpipe_handle\fR arguments are NULL. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 23n +.rt +Called from interrupt context. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PERM\fR +.ad +.RS 23n +.rt +Pipe handle specifies the default control pipe. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 23n +.rt +Asynchronous resources are unavailable. In this case, USB_CB_ASYNC_REQ_FAILED +is passed in as the \fIcallback_flags\fR arg to the callback hander. +.RE + +.sp +.LP +Exception handlers of any queued requests which were flushed are called with a +completion reason of USB_CR_FLUSHED. Exception handlers of periodic pipe +requests which were terminated are called with USB_CR_PIPE_CLOSING. +.sp +.LP +Note that messages mirroring the above errors are logged to the console logfile +on error. (This provides status for calls which otherwise could provide +status). +.SH CONTEXT +.sp +.LP +May be called from user or kernel context regardless of arguments. May not be +called from a callback executing in interrupt context. Please see +\fBusb_callback_flags\fR(9S) for more information on callbacks. +.sp +.LP +If the USB_CB_ASYNC_REQ_FAILED bit is clear in usb_cb_flags_t, the callback, if +supplied, can block because it is executing in kernel context. Otherwise the +callback cannot block. Please see \fBusb_callback_flags\fR(9S) for more +information on callbacks. +.SH EXAMPLES +.sp +.in +2 +.nf +/* Synchronous close of pipe. */ +usb_pipe_close(dip, pipe, USB_FLAGS_SLEEP, NULL, NULL); + + -------- + +/* Template callback. */ +void close_callback(usb_pipe_handle_t, usb_opaque_t, usb_cb_flags_t); + +/* Asynchronous close of pipe. */ +usb_pipe_close(dip, pipe, 0, close_callback, callback_arg); + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_status\fR(9F), \fBusb_pipe_drain_reqs\fR(9F), +\fBusb_pipe_get_state\fR(9F), \fBusb_pipe_open\fR(9F), +\fBusb_pipe_reset\fR(9F), \fBusb_callback_flags\fR(9S) diff --git a/usr/src/man/man9f/usb_pipe_ctrl_xfer.9f b/usr/src/man/man9f/usb_pipe_ctrl_xfer.9f new file mode 100644 index 0000000000..3ab7832ae0 --- /dev/null +++ b/usr/src/man/man9f/usb_pipe_ctrl_xfer.9f @@ -0,0 +1,507 @@ +'\" 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 usb_pipe_ctrl_xfer 9F "15 Sep 2009" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_pipe_ctrl_xfer, usb_pipe_ctrl_xfer_wait \- USB control pipe transfer +functions +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + +\fBint\fR \fBusb_pipe_ctrl_xfer\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, + \fBusb_ctrl_req_t *\fR\fIrequest\fR, \fBusb_flags_t\fR \fIflags\fR); + +.fi + +.LP +.nf +\fBint\fR \fBusb_pipe_ctrl_xfer_wait\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, + \fBusb_ctrl_setup_t *\fR\fIsetup\fR, \fBmblk_t **\fR\fIdata\fR, + \fBusb_cr_t *\fR \fIcompletion_reason\fR, \fBusb_cb_flags_t *cb_\fR\fIflags\fR, + \fBusb_flags_t\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.LP +For \fBusb_pipe_ctrl_xfer()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 15n +.rt +Control pipe handle on which request is made. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrequest\fR\fR +.ad +.RS 15n +.rt +Pointer to control transfer request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 15n +.rt +USB_FLAGS_SLEEP is the only flag recognized. Wait for all pending request +callbacks to complete. +.RE + +.sp +.LP +For \fBusb_pipe_ctrl_xfer_wait()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 21n +.rt +Control pipe handle on which request is made. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsetup\fR\fR +.ad +.RS 21n +.rt +Pointer to setup parameters. (See below.) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdata\fR\fR +.ad +.RS 21n +.rt +Pointer to mblk containing data bytes to transfer with command. Ignored if +NULL. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcompletion_reason\fR\fR +.ad +.RS 21n +.rt +Returns overall completion status. Ignored if NULL. Please see +\fBusb_callback_flags\fR(9S) for more information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback_flags\fR\fR +.ad +.RS 21n +.rt +Returns flags set either during autoclearing or some other callback, which +indicate recovery handling done in callback. Ignored if NULL. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 21n +.rt +No flags are recognized. Reserved for future expansion. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_pipe_ctrl_xfer()\fR function requests the USBA framework to perform +a transfer through a USB control pipe. The request is passed to the host +controller driver (HCD), which performs the necessary transactions to complete +the request. Requests are synchronous when USB_FLAGS_SLEEP is specified in +flags; calls for synchronous requests do not return until their transaction is +completed. Asynchronous requests (made without specifying the USB_FLAGS_SLEEP +flag) notifies the caller of their completion via a callback function. +.sp +.LP +The \fBusb_pipe_ctrl_xfer_wait()\fR function is a wrapper around +\fBusb_pipe_ctrl_xfer()\fR that performs allocation and deallocation of all +required data structures, and a synchronous control-pipe transfer. It takes a +usb_ctrl_setup_t containing most usb setup parameters as an argument: +.sp +.in +2 +.nf + uchar_t bmRequestType /* characteristics of request. */ + /* (See USB 2.0 spec, section 9.3). */ + /* Combine one direction of: */ + /* USB_DEV_REQ_HOST_TO_DEV */ + /* USB_DEV_REQ_DEV_TO_HOST */ + /* with one request type of: */ + /* USB_DEV_REQ_TYPE_STANDARD */ + /* USB_DEV_REQ_TYPE_CLASS */ + /* USB_DEV_REQ_TYPE_VENDOR */ + /* with one recipient type of: */ + /* USB_DEV_REQ_RCPT_DEV */ + /* USB_DEV_REQ_RCPT_IF */ + /* USB_DEV_REQ_RCPT_EP */ + /* USB_DEV_REQ_RCPT_OTHER. */ + + uchar_t bRequest /* request or command. */ + /* (See USB 2.0 spec, section */ + /* 9.3 for standard commands.) */ + + uint16_t wValue /* value which varies according to */ + /* the command (bRequest). */ + + uint16_t wIndex /* value which varies according to */ + /* the command, typically used to */ + /* pass an index or offset. */ + + uint16_t wLength /* number of data bytes to transfer */ + /* with command, if any. Same as */ + /* size of mblk "data" below. */ + + usb_req_attrs_t attrs; /* required request attributes */ +.fi +.in -2 + +.sp +.LP +Please see \fBusb_request_attributes\fR(9S), or refer to Section \fI5.5\fR of +the \fIUSB 2.0\fR specification for more information on these parameters. (The +USB 2.0 specification is available at \fIwww.usb.org\fR.) +.sp +.LP +Mblks for data are allocated optionally when a request is allocated via +\fBusb_alloc_ctrl_req\fR(9F) by passing a positive value for the \fIlen\fR +argument. Control requests passing or receiving no supplemental data need not +allocate an mblk. +.SH RETURN VALUES +.sp +.LP +For \fBusb_pipe_ctrl_xfer()\fR: +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 25n +.rt +Transfer was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 25n +.rt +Request is \fBNULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 25n +.rt +Called from interrupt context with the USB_FLAGS_SLEEP flag set. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_REQUEST\fR +.ad +.RS 25n +.rt +The request has been freed or otherwise invalidated. +.sp +A set of conflicting attributes were specified. See +\fBusb_request_attributes\fR(9S). +.sp +The normal and/or exception callback is NULL and USB_FLAGS_SLEEP is not set. +.sp +Data space not provided to a control request while ctrl_wLength is nonzero. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PIPE\fR +.ad +.RS 25n +.rt +Pipe handle is NULL or invalid. +.sp +Pipe is closing or closed. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_NO_RESOURCES\fR +.ad +.RS 25n +.rt +Memory, descriptors or other resources unavailable. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_HC_HARDWARE_ERROR\fR +.ad +.RS 25n +.rt +Host controller is in error state. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 25n +.rt +An asynchronous transfer failed or an internal error occurred. +.sp +The pipe is in an unsuitable state (error, busy, not ready). +.RE + +.sp +.LP +Additional status information may be available in the ctrl_completion_reason +and ctrl_cb_flags fields of the request. Please see +\fBusb_callback_flags\fR(9S) and \fBusb_completion_reason\fR(9S) for more +information. +.sp +.LP +For \fBusb_pipe_ctrl_xfer_wait()\fR: +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 23n +.rt +Request was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 23n +.rt +Called from interrupt context. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 23n +.rt +\fIdip\fR is NULL. +.RE + +.sp +.LP +Any error code returned by \fBusb_pipe_ctrl_xfer()\fR. +.sp +.LP +Additional status information may be available in the ctrl_completion_reason +and ctrl_cb_flags fields of the request. Please see +\fBusb_callback_flags\fR(9S) and \fBusb_completion_reason\fR(9S) for more +information. +.SH CONTEXT +.sp +.LP +The \fBusb_pipe_ctrl_xfer()\fR function may be called from kernel or user +context without regard to arguments and from the interrupt context only when +the USB_FLAGS_SLEEP flag is clear. +.sp +.LP +The \fBusb_pipe_ctrl_xfer_wait()\fR function may be called from kernel or user +context. +.SH EXAMPLES +.sp +.in +2 +.nf + /* Allocate, initialize and issue a synchronous control request. */ + + usb_ctrl_req_t ctrl_req; + void control_pipe_exception_callback( + usb_pipe_handle_t, usb_ctrl_req_t*); + + ctrl_req = usb_alloc_ctrl_req(dip, 0, USB_FLAGS_SLEEP); + + ctrl_req->ctrl_bmRequestType = USB_DEV_REQ_HOST_TO_DEV | + USB_DEV_REQ_TYPE_CLASS | USB_DEV_REQ_RCPT_OTHER; + + ctrl_req->ctrl_bRequest = (uint8_t)USB_PRINTER_SOFT_RESET; + ctrl_req->ctrl_exc_cb = control_pipe_exception_callback; + ... + ... + if ((rval = usb_pipe_ctrl_xfer(pipe, ctrl_req, USB_FLAGS_SLEEP)) + != USB_SUCCESS) { + cmn_err (CE_WARN, "%s%d: Error issuing USB cmd.", + ddi_driver_name(dip), ddi_get_instance(dip)); + } + + ------- + + /* + * Allocate, initialize and issue an asynchronous control request to + * read a configuration descriptor. + */ + + usb_ctrl_req_t *ctrl_req; + void control_pipe_normal_callback( + usb_pipe_handle_t, usb_ctrl_req_t*); + void control_pipe_exception_callback( + usb_pipe_handle_t, usb_ctrl_req_t*); + struct buf *bp = ...; + + ctrl_req = + usb_alloc_ctrl_req(dip, sizeof(usb_cfg_descr_t), USB_FLAGS_SLEEP); + + ctrl_req->ctrl_bmRequestType = USB_DEV_REQ_DEV_TO_HOST | + USB_DEV_REQ_TYPE_STANDARD | USB_DEV_REQ_RCPT_DEV; + + ctrl_req->ctrl_wLength = sizeof(usb_cfg_descr_t); + ctrl_req->ctrl_wValue = USB_DESCR_TYPE_SETUP_CFG | 0; + ctrl_req->ctrl_bRequest = (uint8_t)USB_REQ_GET_DESCR; + ctrl_req->ctrl_cb = control_pipe_normal_callback; + ctrl_req->ctrl_exc_cb = control_pipe_exception_callback; + + /* Make buf struct available to callback handler. */ + ctrl_req->ctrl_client_private = (usb_opaque_t)bp; + ... + ... + if ((rval = usb_pipe_ctrl_xfer(pipe, ctrl_req, USB_FLAGS_NOSLEEP)) + != USB_SUCCESS) { + cmn_err (CE_WARN, "%s%d: Error issuing USB cmd.", + ddi_driver_name(dip), ddi_get_instance(dip)); + } + + ------- + + /* Call usb_pipe_ctrl_xfer_wait() to get device status. */ + + mblk_t *data; + usb_cr_t completion_reason; + usb_cb_flags_t callback_flags; + usb_ctrl_setup_t setup_params = { + USB_DEV_REQ_DEV_TO_HOST | /* bmRequestType */ + USB_DEV_REQ_TYPE_STANDARD | USB_DEV_REQ_RCPT_DEV, + USB_REQ_GET_STATUS, /* bRequest */ + 0, /* wValue */ + 0, /* wIndex */ + USB_GET_STATUS_LEN, /* wLength */ + 0 /* attributes. */ + }; + + if (usb_pipe_ctrl_xfer_wait( + pipe, + &setup_params, + &data, + &compleetion_reason, + &callback_flags, + 0) != USB_SUCCESS) { + cmn_err (CE_WARN, + "%s%d: USB get status command failed: " + "reason=%d callback_flags=0x%x", + ddi_driver_name(dip), ddi_get_instance(dip), + completion_reason, callback_flags); + return (EIO); + } + + /* Check data length. Should be USB_GET_STATUS_LEN (2 bytes). */ + length_returned = data->b_wptr - data->b_rptr; + if (length_returned != USB_GET_STATUS_LEN) { + cmn_err (CE_WARN, + "%s%d: USB get status command returned %d bytes of data.", + ddi_driver_name(dip), ddi_get_instance(dip), length_returned); + return (EIO); + } + + /* Retrieve data in endian neutral way. */ + status = (*(data->b_rptr + 1) << 8) | *(data->b_rptr); + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_alloc_request\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_status\fR(9F). \fBusb_pipe_bulk_xfer\fR(9F), +\fBusb_pipe_intr_xfer\fR(9F), \fBusb_pipe_isoc_xfer\fR(9F), +\fBusb_pipe_open\fR(9F), \fBusb_pipe_reset\fR(9F), +\fBusb_pipe_get_state\fR(9F), \fBusb_bulk_request\fR(9S), +\fBusb_callback_flags\fR(9S), \fBusb_ctrl_request\fR(9S), +\fBusb_completion_reason\fR(9S), \fBusb_intr_request\fR(9S), +\fBusb_isoc_request\fR(9S) diff --git a/usr/src/man/man9f/usb_pipe_drain_reqs.9f b/usr/src/man/man9f/usb_pipe_drain_reqs.9f new file mode 100644 index 0000000000..8e68e94f9b --- /dev/null +++ b/usr/src/man/man9f/usb_pipe_drain_reqs.9f @@ -0,0 +1,310 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_pipe_drain_reqs 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_pipe_drain_reqs \- Allow completion of pending pipe requests +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_pipe_drain_reqs\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_pipe_handle_t\fR \fIpipe_handle\fR, + \fBuint_t\fR \fItimeout\fR, \fBusb_flags_t\fR \fIusb_flags\fR, + \fBvoid (*\fR\fIcallback\fR)(usb_pipe_handle_t \fIpipe_handle\fR, + \fBusb_opaque_t\fR \fIcallback_arg\fR, \fBint\fR \fIrval\fR, \fBusb_cb_flags_t\fR \fIflags)\fR, + \fBusb_opaque_t\fR \fIcallback_arg\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 16n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 16n +.rt +Handle of the pipe containing pending requests. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItimeout\fR\fR +.ad +.RS 16n +.rt +Maximum wait time for requests to drain. Must be a non-negative value in +seconds. Zero specifies no timeout. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 16n +.rt +USB_FLAGS_SLEEP is the only flag recognized. Wait for completion and do not +call callback. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 16n +.rt +Callback handler to notify of asynchronous completion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback_arg\fR\fR +.ad +.RS 16n +.rt +Second argument passed to callback function. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_pipe_drain_reqs()\fR function provides waits for pending requests to +complete and then provides synchronous or asynchronous notification that all +pending requests on a non-shared pipe indicated by pipe_handle have completed. +For a shared pipe (such as the default control pipe used by multiple drivers +each managing one interface of a device), this function provides notification +that all pending requests on that pipe that are associated with a given dip are +completed. +.sp +.LP +The \fBusb_pipe_drain_reqs()\fR function can be used to notify a close +procedure when the default control pipe is clear during device closure, thereby +allowing the close procedure to continue safely. Normally, a synchronous call +to \fBusb_pipe_close\fR(9F) allows all requests in a pipe to finish before +returning. However, a client driver cannot close the default control pipe. +.sp +.LP +If USB_FLAGS_SLEEP is set in flags, block until all pending requests are +completed. Otherwise, return immediately and call the callback handler when all +pending requests are completed. +.sp +.LP +The \fIcallback\fR parameter accepts the asynchronous callback handler, which +takes the following arguments: +.sp +.ne 2 +.mk +.na +\fBusb_pipe_handle_t default_pipe_handle\fR +.ad +.sp .6 +.RS 4n +Handle of the pipe to drain. +.RE + +.sp +.ne 2 +.mk +.na +\fBusb_opaque_t callback_arg\fR +.ad +.sp .6 +.RS 4n +callback_arg specified to \fBusb_pipe_drain_reqs()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBint rval\fR +.ad +.sp .6 +.RS 4n +Request status. +.RE + +.sp +.ne 2 +.mk +.na +\fBusb_cb_flags_t callback_flags\fR +.ad +.sp .6 +.RS 4n +Status of the queueing operation. Can be: +.sp +.ne 2 +.mk +.na +\fBUSB_CB_NO_INFO\fR +.ad +.RS 27n +.rt +Callback was uneventful. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_CB_ASYNC_REQ_FAILED\fR +.ad +.RS 27n +.rt +Error starting asynchronous request. +.RE + +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 23n +.rt +Request is successful. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 23n +.rt +\fIdip\fR argument is \fBNULL\fR. USB_FLAGS_SLEEP is clear and callback is +\fBNULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 23n +.rt +Called from callback context with the USB_FLAGS_SLEEP flag set. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PIPE\fR +.ad +.RS 23n +.rt +Pipe is not open, is closing or is closed. +.RE + +.SH CONTEXT +.sp +.LP +May be called from user or kernel context. +.sp +.LP +If the USB_CB_ASYNC_REQ_FAILED bit is clear in usb_cb_flags_t, the callback, if +supplied, can block because it is executing in kernel context. Otherwise the +callback cannot block. Please see \fBusb_callback_flags\fR(9S) for more +information on callbacks. +.SH EXAMPLES +.sp +.in +2 +.nf + mydev_detach(dev_info_t *dip, ddi_detach_cmd_t cmd) + { + + ... + ... + + mydev_state->pipe_state = CLOSED; + + /* Wait for pending requests of a pipe to finish. Don't timeout. */ + (void) usb_pipe_drain_reqs( + dip, pipe_handle, 0, USB_FLAGS_SLEEP, NULL, 0); + + /* + * Dismantle streams and tear down this instance, + * now that all requests have been sent. + */ + qprocsoff(q); + ... + ... + ddi_remove_minor_node(dip, NULL); + ... + ... + } + +.fi +.in -2 + +.SH NOTES +.sp +.LP +For pipes other than the default control pipe, it is recommended to close the +pipe using a synchronous \fBusb_pipe_close()\fR. \fBusb_pipe_close()\fR with +the USB_FLAGS_SLEEP flag allows any pending requests in that pipe to complete +before returning. +.sp +.LP +Do not call \fBusb_pipe_drain_reqs()\fR while additional requests are being +submitted by a different thread. This action can stall the calling thread of +\fBusb_pipe_drain_reqs()\fR unnecessarily. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_pipe_close\fR(9F), \fBusb_pipe_reset\fR(9F), +\fBusb_callback_flags\fR(9S) diff --git a/usr/src/man/man9f/usb_pipe_get_max_bulk_transfer_size.9f b/usr/src/man/man9f/usb_pipe_get_max_bulk_transfer_size.9f new file mode 100644 index 0000000000..cb0e5652ff --- /dev/null +++ b/usr/src/man/man9f/usb_pipe_get_max_bulk_transfer_size.9f @@ -0,0 +1,139 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_pipe_get_max_bulk_transfer_size 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_pipe_get_max_bulk_transfer_size \- Get maximum bulk transfer size +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_pipe_get_max_bulk_transfer_size\fR(\fBdev_info_t\fR \fIdip\fR, \fBsize_t *\fR\fIsize\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 8n +.rt +Pointer to the device's dev_info structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsize\fR\fR +.ad +.RS 8n +.rt +Returns the bulk transfer size. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_pipe_get_max_bulk_transfer_size()\fR function returns the maximum +data transfer size in bytes that the host controller driver can support per +bulk request. This information can be used to limit or break down larger +requests to manageable sizes. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 20n +.rt +Size is returned in size argument. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 20n +.rt +\fIdip\fR and/or \fIsize\fR argument is \fBNULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 20n +.rt +Size could not be returned. Zero is returned in \fIsize\fR arg. +.RE + +.SH CONTEXT +.sp +.LP +May be called from user, kernel or interrupt context. +.SH EXAMPLES +.sp +.in +2 +.nf + int xxx_attach(dev_info_t *dip, int command) + { + ... + usb_pipe_get_max_bulk_transfer_size(dip, &state>max_xfer_size); + ... + } + + void xxx_minphys(struct buf bp) + { + ... + if (bp->b_bcount > state->max_xfer_size) { + bp->b_bcount = state->max_xfer_size; + } + ... + } + + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_pipe_bulk_xfer\fR(9F), \fBusb_alloc_request\fR(9F), +\fBusb_bulk_request\fR(9S) diff --git a/usr/src/man/man9f/usb_pipe_get_state.9f b/usr/src/man/man9f/usb_pipe_get_state.9f new file mode 100644 index 0000000000..fd03ff6eec --- /dev/null +++ b/usr/src/man/man9f/usb_pipe_get_state.9f @@ -0,0 +1,206 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_pipe_get_state 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_pipe_get_state \- Return USB pipe state +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_pipe_get_state\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, + \fBusb_pipe_state_t *\fR\fIpipe_state\fR, \fBusb_flags_t\fR \fIusb_flags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 15n +.rt +Handle of the pipe to retrieve the state. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpipe_state\fR\fR +.ad +.RS 15n +.rt +Pointer to where pipe state is returned. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIusb_flags\fR\fR +.ad +.RS 15n +.rt +No flags are recognized. Reserved for future expansion. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_pipe_get_state()\fR function retrieves the state of the pipe +referred to by \fIpipe_handle\fR into the location pointed to by +\fIpipe_state\fR. +.sp +.LP +Possible pipe states are: +.sp +.ne 2 +.mk +.na +\fBUSB_PIPE_STATE_CLOSED\fR +.ad +.RS 26n +.rt +Pipe is closed. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_PIPE_STATE_ACTIVE\fR +.ad +.RS 26n +.rt +Pipe is active and can send/receive data. Polling is active for isochronous and +interrupt pipes. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_PIPE_STATE_IDLE\fR +.ad +.RS 26n +.rt +Polling is stopped for isochronous and interrupt-IN pipes. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_PIPE_STATE_ERROR\fR +.ad +.RS 26n +.rt +An error occurred. Client must call \fBusb_pipe_reset()\fR. Note that this +status is not seen by a client driver if USB_ATTRS_AUTOCLEARING is set in the +request attributes. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_PIPE_STATE_CLOSING\fR +.ad +.RS 26n +.rt +Pipe is being closed. Requests are being drained from the pipe and other +cleanup is in progress. +.RE + +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 20n +.rt +Pipe state returned in second argument. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 20n +.rt +Pipe_state argument is \fBNULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PIPE\fR +.ad +.RS 20n +.rt +Pipe_handle argument is \fBNULL\fR. +.RE + +.SH CONTEXT +.sp +.LP +May be called from user, kernel or interrupt context. +.SH EXAMPLES +.sp +.in +2 +.nf + usb_pipe_handle_t pipe; + usb_pipe_state_t state; + + /* Recover if the pipe is in an error state. */ + if ((usb_pipe_get_state(pipe, &state, 0) == USB_SUCCESS) && + (state == USB_PIPE_STATE_ERROR)) { + cmn_err (CE_WARN, "%s%d: USB Pipe error.", + ddi_driver_name(dip), ddi_get_instance(dip)); + do_recovery(); + } + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_clr_feature\fR(9F), \fBusb_get_cfg\fR(9F). +\fBusb_get_status\fR(9F), \fBusb_pipe_close\fR(9F), +\fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_open\fR(9F). \fBusb_pipe_reset\fR(9F) diff --git a/usr/src/man/man9f/usb_pipe_intr_xfer.9f b/usr/src/man/man9f/usb_pipe_intr_xfer.9f new file mode 100644 index 0000000000..83da265347 --- /dev/null +++ b/usr/src/man/man9f/usb_pipe_intr_xfer.9f @@ -0,0 +1,448 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_pipe_intr_xfer 9F "3 Aug 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_pipe_intr_xfer, usb_pipe_stop_intr_polling \- USB interrupt transfer and +polling functions +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_pipe_intr_xfer\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, \fBusb_intr_req_t *\fR\fIrequest\fR, + \fBusb_flags_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBusb_pipe_stop_intr_polling\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, \fBusb__flags_t\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.LP +For \fBusb_pipe_intr_xfer()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 15n +.rt +Interrupt pipe handle on which request is made. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrequest\fR\fR +.ad +.RS 15n +.rt +Pointer to interrupt transfer request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 15n +.rt +USB_FLAGS_SLEEP is the only flag recognized. Wait for needed resources if +unavailable. For requests specifying the USB_ATTRS_ONE_XFER attribute, wait for +the request to complete. +.RE + +.sp +.LP +For \fBusb_pipe_stop_intr_polling()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 15n +.rt +Interrupt pipe handle on which to stop polling for data. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 15n +.rt +USB_FLAGS_SLEEP is the only flag recognized. Wait for polling to stop. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_pipe_intr_xfer()\fR function requests the USBA framework to perform +a transfer through a USB interrupt pipe. The request is passed to the host +controller driver (HCD), which performs the necessary transactions to complete +the request. +.sp +.LP +There are three categories of interrupt transfers: periodic or polled +interrupt-IN, single-transfer interrupt-IN, and (single-transfer) +interrupt-OUT. +.SS "Periodic Interrupt-IN Transfers" +.sp +.LP +Periodic or polled interrupt-IN transfers execute on input requests which do +not have the USB_ATTRS_ONE_XFER attribute set. One request enables repetitive +transfers at a periodic rate set by the endpoint's bInterval. There can be only +one interrupt-IN request submitted at a time. +.sp +.LP +Periodic interrupt-IN transfers are always asynchronous. Client driver +notification of new data is always via a callback. The USB_FLAGS_SLEEP flag is +only to wait for resources to become available. Callbacks must always be in +place to receive transfer completion notification. Please see +\fBusb_callback_flags\fR(9S) for details on USB callbacks. +.sp +.LP +Calls made to \fBusb_pipe_intr_xfer()\fR for starting input polling need +allocate only one request. The USBA framework allocates a new request each time +polling has new data to return. (Note that each request returned must be freed +via \fBusb_free_intr_req\fR(9F). Specify a zero length when calling +\fBusb_alloc_intr_req()\fR to allocate the original request, since it will not +be used to return data. Set the intr_len in the request to specify how much +data can be returned per polling interval. +.sp +.LP +The original request passed to \fBusb_pipe_intr_xfer()\fR is used to return +status when polling is terminated, or on an error condition when the +USB_ATTRS_AUTOCLEARING attribute is set for the request. If autoclearing is not +set, the current (non-original) request is returned on error. Call +\fBusb_pipe_reset\fR(9F) to reset the pipe and get back the original request in +this case. The USB_CR_STOPPED_POLLING flag is always set for callbacks where +the original request is returned. +.SS "Single-transfer Interrupt-IN Transfers" +.sp +.LP +Interrupt-IN requests which have the USB_ATTRS_ONE_XFER attribute perform a +single transfer. Such requests are synchronous when the USB_FLAGS_SLEEP flag is +specified. Calls for synchronous requests do not return until their transaction +is complete, and their callbacks are optional. The request is returned to the +client through the normal or the exception completion callback to signal either +normal completion or an error condition. +.SS "Interrupt-OUT Transfers" +.sp +.LP +Interrupt-OUT requests always set up for a single transfer. However, multiple +requests can be queued and execute in periodic fashion until depleted. +.sp +.LP +Interrupt-OUT transfers are synchronous when the USB_FLAGS_SLEEP flag is set in +the request's flags. Calls for synchronous transfers will not return until +their transaction has completed. Calls for asynchronous transfers notify the +client driver of transaction completion via a normal callback, or error +completion via an exception callback. +.sp +.LP +The \fBusb_pipe_stop_intr_polling()\fR function terminates polling on +interrupt-IN pipes and does the following: +.br +.in +2 +1. Cease polling. +.in -2 +.br +.in +2 +2. Allow any requests-in-progress to complete and be returned to the client +driver through the normal callback mechanism. +.in -2 +.br +.in +2 +3. Idle the pipe. +.in -2 +.br +.in +2 +4. Return the original polling request to the client driver through an +exception callback with a completion reason of USB_CR_STOPPED_POLLING. +.in -2 +.sp +.LP +The client driver may restart polling from an exception callback only if the +callback corresponds to an original request. The callback handler checks for +the following completion reasons to ensure that a callback corresponds to an +original request: +.sp +.in +2 +.nf + USB_CR_STOPPED_POLLING, + USB_CR_PIPE_RESET, + USB_CR_PIPE_CLOSING, + USB_CR_NOT_SUPPORTED +.fi +.in -2 + +.sp +.LP +The callback handler also checks the request's intr_data field to mark original +polling requests, when the requests are created with a zero \fIlen\fR argument. +In this case, a NULL intr_data field distinguishes a returned original request +from a request allocated by the framework during polling. +.sp +.LP +Mblks for data for interrupt-OUT requests are allocated when a request is +allocated via \fBusb_alloc_intr_req\fR(9F) by passing a non-negative value for +the \fIlen\fR argument. +.SH RETURN VALUES +.sp +.LP +For \fBusb_pipe_intr_xfer()\fR +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 25n +.rt +Transfer was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 25n +.rt +Request is \fBNULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 25n +.rt +Called from interrupt context with the USB_FLAGS_SLEEP flag set. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_REQUEST\fR +.ad +.RS 25n +.rt +The request has been freed or otherwise invalidated. +.sp +A set of conflicting attributes was specified. See \fBusb_intr_request\fR(9S). +.sp +The normal and/or exception callback was NULL, USB_FLAGS_SLEEP was not set and +USB_ATTRS_ONE_XFER was not set. +.sp +An interrupt request was specified with a NULL data and a non-zero intr_len +value. +.sp +An IN interrupt request was specified with both polling (USB_ATTRS_ONE_XFER +clear in attributes) and non-zero timeout specified. +.sp +An IN interrupt request was specified with a non-NULL data argument. +.sp +An OUT interrupt request was specified with a NULL data argument. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PIPE\fR +.ad +.RS 25n +.rt +Pipe handle is NULL or invalid. +.sp +Pipe is closing or closed. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_PIPE_ERROR\fR +.ad +.RS 25n +.rt +Pipe handle refers to a pipe which is in the USB_PIPE_STATE_ERROR state. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_NO_RESOURCES\fR +.ad +.RS 25n +.rt +Memory, descriptors or other resources unavailable. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_HC_HARDWARE_ERROR\fR +.ad +.RS 25n +.rt +Host controller is in error state. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 25n +.rt +An asynchronous transfer failed or an internal error occurred. +.sp +An intr polling request is made while polling is already in progress. +.sp +The pipe is in an unsuitable state (error, busy, not ready). +.sp +Additional status information may be available in the intr_completion_reason +and intr_cb_flags fields of the request. Please see +\fBusb_completion_reason\fR(9S) and \fBusb_callback_flags\fR(9S) for more +information. +.RE + +.sp +.LP +For \fBusb_pipe_stop_intr_polling()\fR +.sp +.LP +None, but fails if called with USB_FLAGS_SLEEP specified from interrupt +context, pipe handle is invalid, NULL or pertains to a closing or closed pipe, +or the pipe is in an error state. Error messages are logged to the console +logfile. +.sp +.LP +Exception handlers' queued requests which are flushed by these commands before +execution are returned with completion reason of USB_CR_FLUSHED. +.SH CONTEXT +.sp +.LP +Both of these functions can be called from kernel or user context without +regard to arguments, and may be called from interrupt context only when the +USB_FLAGS_SLEEP flag is clear. +.SH EXAMPLES +.sp +.in +2 +.nf + /* Start polling on interrupt-IN pipe. */ + + usb_intr_req_t intr_req; + void intr_pipe_callback(usb_pipe_handle_t, usb_intr_req_t*); + void intr_pipe_exception_callback( + usb_pipe_handle_t, usb_intr_req_t*); + usb_ep_descr_t *ep_descr; + + ep_descr = ...; + intr_req = usb_alloc_intr_req(dip, 0, USB_FLAGS_SLEEP); + ... + ... + intr_req->intr_attributes = USB_ATTRS_SHORT_XFER_OK; + intr_req->intr_len = ep_descr->wMaxPacketSize; + ... + ... + intr_req->intr_cb = intr_pipe_callback; + intr_req->intr_exc_cb = intr_pipe_exception_callback; + + if ((rval = usb_pipe_intr_xfer(pipe, intr_req, USB_FLAGS_NOSLEEP)) + != USB_SUCCESS) { + cmn_err (CE_WARN, "%s%d: Error starting interrupt pipe polling.", + ddi_driver_name(dip), ddi_get_instance(dip)); + } + + ------- + + /* Stop polling before setting device idle. Wait for polling to stop. */ + + usb_pipe_stop_intr_polling(pipe, USB_FLAGS_SLEEP); + (void) pm_idle_component(dip, 0); + + ------- + + /* Allocate, initialize and issue a synchronous intr-OUT request. */ + + usb_intr_req_t intr_req; + mblk_t *mblk; + usb_ep_descr_t *ep_descr; + + ep_descr = ...; + + intr_req = + usb_alloc_intr_req(dip, ep_descr->wMaxPacketSize, USB_FLAGS_SLEEP); + + intr_req->intr_attributes = USB_ATTRS_AUTOCLEARING; + mblk = intr_req->intr_data; + bcopy(buffer, mblk->b_wptr, ep_descr->wMaxPacketSize); + mblk->b_wptr += ep_descr->wMaxPacketSize; + + if ((rval = usb_pipe_intr_xfer(pipe, intr_req, USB_FLAGS_SLEEP)) + != USB_SUCCESS) { + cmn_err (CE_WARN, "%s%d: Error writing intr data.", + ddi_driver_name(dip), ddi_get_instance(dip)); + } + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_alloc_request\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_status\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F), +\fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_get_state\fR(9F), +\fBusb_pipe_isoc_xfer\fR(9F), \fBusb_pipe_open\fR(9F), +\fBusb_pipe_reset\fR(9F), \fBusb_bulk_request\fR(9S), +\fBusb_callback_flags\fR(9S), \fBusb_completion_reason\fR(9S), +\fBusb_ctrl_request\fR(9S), \fBusb_ep_descr\fR(9S), \fBusb_intr_request\fR(9S), +\fBusb_isoc_request\fR(9S) diff --git a/usr/src/man/man9f/usb_pipe_isoc_xfer.9f b/usr/src/man/man9f/usb_pipe_isoc_xfer.9f new file mode 100644 index 0000000000..ada850bf94 --- /dev/null +++ b/usr/src/man/man9f/usb_pipe_isoc_xfer.9f @@ -0,0 +1,494 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_pipe_isoc_xfer 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_pipe_isoc_xfer, usb_pipe_stop_isoc_polling \- USB isochronous transfer and +polling functions +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint \fR\fBusb_pipe_isoc_xfer\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, \fBusb_isoc_req_t *\fR\fIrequest\fR, + \fBusb_flags_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fB\fR + +\fBvoid \fR\fBusb_pipe_stop_isoc_polling\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, \fBusb__flags_t\fR \fIflags\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.LP +For \fBusb_pipe_isoc_xfer()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 15n +.rt +Isochronous pipe handle on which request is made. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrequest\fR\fR +.ad +.RS 15n +.rt +Pointer to isochronous transfer request. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 15n +.rt +USB_FLAGS_SLEEP is the only flag recognized. Wait for needed resources if +unavailable. +.RE + +.sp +.LP +For \fBusb_pipe_stop_isoc_polling()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 15n +.rt +Isochronous pipe handle on which to stop polling for input. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 15n +.rt +USB_FLAGS_SLEEP is the only flag recognized. Wait for polling to stop. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_pipe_isoc_xfer()\fR function requests the USBA framework to perform +a transfer through a USB isochronous pipe. The request is passed to the +host controller driver (HCD), which performs the necessary transactions to +complete the request. +.sp +.LP +By their nature, isochronous transfers require several transactions for +completion. Each request may contain several packet descriptors. Descriptors +correspond to subtransfers to be made in different frames. A request is deemed +completed once all packets of that request have been processed. It is illegal +to specify the USB_ATTRS_ONE_XFER attribute in an isochronous request. The +isochronous polling interval is always one millisecond, the period of a +full-speed frame. +.sp +.LP +All isochronous requests are asynchronous, and will notify the caller of +their completion via a callback function. All isochronous requests must +specify normal and exception callback handlers. +.sp +.LP +Requests will wait for needed, unavailable resources when USB_FLAGS_SLEEP has +been specified in flags. Requests made without USB_FLAGS_SLEEP set will fail +if needed resources are not readily available. +.sp +.LP +No errors seen during request processing will result in aborted transfers or +exception callbacks. Such errors will instead be logged in the packet +descriptor's isoc_pkt_status field. These errors can be examined when the +completed request is returned through a normal callback. +.SS "Isochronous-OUT TRANSFERS" +.sp +.LP +Allocate room for data when allocating isochronous-OUT requests via +usb_alloc_isoc_req(9F), by passing a positive value for the \fIlen\fR +argument. The data will be divided among the request transactions, each +transaction represented by a packet descriptor. (See usb_isoc_request(9F). +When all of the data has been sent, regardless of any errors encountered, a +normal transfer callback will be made to notify the client driver of +completion. +.sp +.LP +If a request is submitted while other requests are active or queued, and the +new request has its USB_ATTRS_ISOC_XFER_ASAP attribute set, the host controller +driver will queue the request to start on a frame which immediately follows the +last frame of the last queued request. +.SS "Isochronous-IN TRANSFERS" +.sp +.LP +All isochronous-IN transfers start background polling, and require only a +single (original) request. The USBA framework will allocate a new request each +time polling has new data to return. Specify a zero length when calling +usb_alloc_isoc_req() to allocate the original request, since it will not be +used to return data. Set the isoc_pkts_length in the request to specify how +much data to poll per interval (the length of one packet in the request). +.sp +.LP +The original request passed to \fBusb_pipe_isoc_xfer()\fR will be used to +return status when polling termination is requested, or for error condition +notification. There can be only one isochronous-IN request submitted at a time. +.SS "CALLBACKS" +.sp +.LP +Isochronous transfer normal-completion callbacks cannot block for any reason +since they are called from interrupt context. They will have +USB_CB_INTR_CONTEXT set in their callback flags to note this. +.sp +.LP +Isochronous exception callbacks have the following restrictions for blocking: +.RS +4 +.TP +1. +They can block for resources (for example to allocate memory). +.RE +.RS +4 +.TP +2. +They cannot block for synchronous completion of a command (for example +usb_pipe_close(9F)) done on the same pipe. Asynchronous commands can be +started, when the pipe's policy pp_max_async_reqs field is initialized to +accommodate them. +.RE +.RS +4 +.TP +3. +They cannot block waiting for another callback to complete. +.RE +.RS +4 +.TP +4. + They cannot block waiting for a synchronous transfer request to complete. +They can, however, make an asynchronous request (such as restarting polling +with a new isochronous-IN transfer). +.RE +.sp +.LP +Please see the section on callbacks in \fBusb_callback_flags\fR(9S) for more +information. +.sp +.LP +All isochronous transfer exception callbacks signify that polling has stopped. +Polling requests are returned with the following completion reasons: +.sp +.in +2 +.nf + USB_CR_STOPPED_POLLING + USB_CR_PIPE_CLOSING +.fi +.in -2 + +.sp +.LP +Note: There are no exception callbacks for error conditions. +.sp +.LP +The \fBusb_pipe_stop_isoc_polling()\fR function terminates polling on an +isochronous-IN pipe. The \fBusb_pipe_stop_isoc_polling()\fR function does the +following: +.RS +4 +.TP +1. +Cease polling. +.RE +.RS +4 +.TP +2. +Allow any requests-in-progress to complete and be returned to the client +driver through the normal callback mechanism. +.RE +.RS +4 +.TP +3. +Idle the pipe. +.RE +.RS +4 +.TP +4. +Return the original polling request to the client driver through an +exception callback with a completion reason of +USB_CR_STOPPED_POLLING. +.RE +.SH RETURN VALUES +.sp +.LP +For \fBusb_pipe_isoc_xfer()\fR: +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 27n +.rt +Transfer was successful. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 27n +.rt +Request is \fBNULL\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 27n +.rt +Called from interrupt context with the USB_FLAGS_SLEEP flag set. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_REQUEST\fR +.ad +.RS 27n +.rt +The request has been freed or otherwise invalidated. +.sp +A set of conflicting attributes were specified. See +\fBusb_isoc_request\fR(9S). +.sp +The normal and/or exception callback was NULL, USB_FLAGS_SLEEP was not set +and USB_ATTRS_ONE_XFER was not set. +.sp +An isochronous request was specified with a zeroed isoc_pkt_descr, a NULL +isoc_pkt_descr, or a NULL data argument. +.sp +An isochronous request was specified with USB_ATTRS_ISOC_XFER_ASAP and a +nonzero isoc_frame_no. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_NO_FRAME_NUMBER\fR +.ad +.RS 27n +.rt +An isochronous request was not specified with one and only one of +USB_ATTRS_ISOC_START_FRAME or USB_ATTRS_ISOC_XFER_ASAP specified. +.sp +An isochronous request was specified with USB_ATTRS_ISOC_START_FRAME and a +zero isoc_frame_no. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_START_FRAME\fR +.ad +.RS 27n +.rt +An isochronous request was specified with an invalid starting frame number +(less than current frame number, or zero) and USB_ATTRS_ISOC_START_FRAME +specified. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PIPE\fR +.ad +.RS 27n +.rt +Pipe handle is NULL or invalid. +.sp + Pipe is closing or closed. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_PIPE_ERROR\fR +.ad +.RS 27n +.rt +Pipe handle refers to a pipe which is in the USB_PIPE_STATE_ERROR state. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_NO_RESOURCES\fR +.ad +.RS 27n +.rt +Memory, descriptors or other resources unavailable. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_HC_HARDWARE_ERROR\fR +.ad +.RS 27n +.rt +Host controller is in error state. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 27n +.rt +An asynchronous transfer failed or an internal error occurred. +.sp +.in +2 +.nf +An isoch request requested too much data: + (length > (usb_get_max_pkts_per_isoc_request() * + endpoint's wMaxPacketSize)) +.fi +.in -2 + +The pipe is in an unsuitable state (error, busy, not ready). +.RE + +.sp +.LP +Additional status information may be available in the isoc_completion_reason +and isoc_cb_flags fields of the request. Please see +\fBusb_completion_reason\fR(9S) and \fBusb_callback_flags\fR(9S) for more +information. +.sp +.LP +For \fBusb_pipe_stop_isoc_polling()\fR: +.sp +.LP +None, but will fail if called with USB_FLAGS_SLEEP specified from interrupt +context; the pipe handle is invalid, NULL or pertains to a closing or closed +pipe; or the pipe is in an error state. Messages regarding these errors will be +logged to the console logfile. +.SH CONTEXT +.sp +.LP +Both of these functions may be called from kernel or user context without +regard to arguments. May be called from interrupt context only when the +USB_FLAGS_SLEEP flag is clear. +.SH EXAMPLES +.sp +.in +2 +.nf +/* Start polling on an isochronous-IN pipe. */ + + usb_isoc_req_t isoc_req; + void isoc_pipe_callback(usb_pipe_handle_t, usb_isoc_req_t*); + void isoc_pipe_exception_callback( + usb_pipe_handle_t, usb_isoc_req_t*); + uint_t pkt_size; + usb_ep_data_t *isoc_ep_tree_node; + usb_ep_descr_t *isoc_ep_descr = ...; /* From usb_lookup_ep_data() */ + + isoc_ep_descr = &isoc_ep_tree_node->ep_descr; + pkt_size = isoc_ep_descr->wMaxPacketSize; + + isoc_req = usb_alloc_isoc_req( + dip, num_pkts, NUM_PKTS * pkt_size, USB_FLAGS_SLEEP); + ... + ... + isoc_req->isoc_attributes = USB_ATTRS_ISOC_XFER_ASAP; + ... + ... + isoc_req->isoc_cb = isoc_pipe_callback; + isoc_req->isoc_exc_cb = isoc_pipe_exception_callback; + ... + ... + isoc_req->isoc_pkts_length = pkt_size; + isoc_req->isoc_pkts_count = NUM_PKTS; + for (pkt = 0; pkt < NUM_PKTS; pkt++) { + isoc_req->isoc_pkt_descr[pkt].isoc_pkt_length = pkt_size; + } + + if ((rval = usb_pipe_isoc_xfer(pipe, isoc_req, USB_FLAGS_NOSLEEP)) + != USB_SUCCESS) { + cmn_err (CE_WARN,"%s%d: Error starting isochronous pipe polling.", + ddi_driver_name(dip), ddi_get_instance(dip)); + } + + ------- + + /* Stop polling before powering off device. Wait for polling to stop. */ + + usb_pipe_stop_isoc_polling(pipe, USB_FLAGS_SLEEP); + pm_idle_component(dip, 0); + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_alloc_request\fR(9F), +\fBusb_get_current_frame_number\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_max_pkts_per_isoc_request\fR(9F), \fBusb_get_status\fR(9F), +\fBusb_pipe_bulk_xfer\fR(9F), \fBusb_pipe_ctrl_xfer\fR(9F), +\fBusb_pipe_get_state\fR(9F), \fBusb_pipe_intr_xfer\fR(9F), +\fBusb_pipe_open\fR(9F), \fBusb_pipe_reset\fR(9F), \fBusb_bulk_request\fR(9S), +\fBusb_callback_flags\fR(9S), \fBusb_completion_reason\fR(9S), +\fBusb_ctrl_request\fR(9S), \fBusb_ep_descr\fR(9S), \fBusb_intr_request\fR(9S), +\fBusb_isoc_request\fR(9S) diff --git a/usr/src/man/man9f/usb_pipe_open.9f b/usr/src/man/man9f/usb_pipe_open.9f new file mode 100644 index 0000000000..13e067f60c --- /dev/null +++ b/usr/src/man/man9f/usb_pipe_open.9f @@ -0,0 +1,410 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_pipe_open 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_pipe_open \- Open a USB pipe to a device +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fBint\fR \fBusb_pipe_open\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_ep_descr_t *\fR\fIendpoint\fR, + \fBusb_pipe_policy_t *\fR\fIpipe_policy\fR, +\fBusb_flags_t\fR \fIflags\fR, \fBusb_pipe_handle_t *\fR\fIpipe_handle\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 15n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIendpoint\fR\fR +.ad +.RS 15n +.rt +Pointer to endpoint descriptor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpipe_policy\fR\fR +.ad +.RS 15n +.rt +Pointer to \fIpipe_policy\fR. \fIpipe_policy\fR provides hints on pipe usage. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 15n +.rt +USB_FLAGS_SLEEP is only flag that is recognized. Wait for memory resources if +not immediately available. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 15n +.rt +Address to where new pipe handle is returned. (The handle is opaque.) +.RE + +.SH DESCRIPTION +.sp +.LP +A pipe is a logical connection to an endpoint on a USB device. The +\fBusb_pipe_open()\fR function creates such a logical connection and returns an +initialized handle which refers to that connection. +.sp +.LP +The \fIUSB 2.0\fR specification defines four endpoint types, each with a +corresponding type of pipe. Each of the four types of pipes uses its physical +connection resource differently. They are: +.sp +.ne 2 +.mk +.na +\fBControl pipe\fR +.ad +.RS 20n +.rt +Used for bursty, non-periodic, reliable, host-initiated request/response +communication, such as for command/status operations. These are guaranteed to +get approximately 10% of frame time and will get more if needed and if +available, but there is no guarantee on transfer promptness. Bidirectional. +.RE + +.sp +.ne 2 +.mk +.na +\fBBulk pipe\fR +.ad +.RS 20n +.rt +Used for large, reliable, non-time-critical data transfers. These get the bus +on a bandwidth-available basis. Unidirectional. Sample uses include printer +data. +.RE + +.sp +.ne 2 +.mk +.na +\fBInterrupt pipe\fR +.ad +.RS 20n +.rt +Used for sending or receiving small amounts of reliable data infrequently but +with bounded service periods, as for interrupt handling. Unidirectional. +.RE + +.sp +.ne 2 +.mk +.na +\fBIsochronous pipe\fR +.ad +.RS 20n +.rt +Used for large, unreliable, time-critical data transfers. Boasts a guaranteed +constant data rate as long as there is data, but there are no retries of failed +transfers. Interrupt and isochronous data are together guaranteed 90% of frame +time as needed. Unidirectional. Sample uses include audio. +.RE + +.sp +.LP +The type of endpoint to which a pipe connects (and therefore the pipe type) is +defined by the \fBbmAttributes\fR field of that pipe's endpoint descriptor. +(See \fBusb_ep_descr\fR(9S)). Opens to interrupt and isochronous pipes can fail +if the required bandwidth cannot be guaranteed. +.sp +.LP +The polling interval for periodic (interrupt or isochronous) pipes, carried by +the endpoint argument's bInterval field, must be within range. Valid ranges +are: +.sp +.LP +Full speed: range of 1-255 maps to 1-255 ms. +.sp +.LP +Low speed: range of 10-255 maps to 10-255 ms. +.sp +.LP +High speed: range of 1-16 maps to (2**(bInterval-1)) * 125us. +.sp +.LP +Adequate bandwidth during transfers is guaranteed for all periodic pipes which +are opened successfully. Interrupt and isochronous pipes have guaranteed +latency times, so bandwidth for them is allocated when they are opened. (Please +refer to Sections \fI5.7\fR and \fI5.8\fR of the \fIUSB 2.0\fR specification +which address isochronous and interrupt transfers.) Opens of interrupt and +isochronous pipes fail if inadequate bandwidth is available to support their +guaranteed latency time. Because periodic pipe bandwidth is allocated on pipe +open, open periodic pipes only when needed. +.sp +.LP +The bandwidth required by a device varies based on polling interval, the +maximum packet size (\fBwMaxPacketSize\fR) and the device speed. Unallocated +bandwidth remaining for new devices depends on the bandwidth already allocated +for previously opened periodic pipes. +.sp +.LP +The \fIpipe_policy\fR parameter provides a hint as to pipe usage and must be +specified. It is a \fBusb_pipe_policy_t\fR which contains the following fields: +.sp +.in +2 +.nf +uchar_t pp_max_async_reqs: + A hint indicating how many + asynchronous operations requiring + their own kernel thread will be + concurrently in progress, the highest + number of threads ever needed at one + time. Allow at least one for + synchronous callback handling and as + many as are needed to accommodate the + anticipated parallelism of asynchronous* + calls to the following functions: + usb_pipe_close(9F) + usb_set_cfg(9F) + usb_set_alt_if(9F) + usb_clr_feature(9F) + usb_pipe_reset(9F) + usb_pipe_drain_reqs(9F) + usb_pipe_stop_intr_polling(9F) + usb_pipe_stop_isoc_polling(9F) + Setting to too small a value can + deadlock the pipe. + + * Asynchronous calls are calls made + without the USB_FLAGS_SLEEP flag being + passed. Note that a large number of + callbacks becomes an issue mainly when + blocking functions are called from + callback handlers. +.fi +.in -2 + +.sp +.LP +The control pipe to the default endpoints (endpoints for both directions with +addr 0, sometimes called the default control pipe or default pipe) comes +pre-opened by the hub. A client driver receives the default control pipe handle +through \fBusb_get_dev_data\fR(9F). A client driver cannot open the default +control pipe manually. Note that the same control pipe may be shared among +several drivers when a device has multiple interfaces and each interface is +operated by its own driver. +.sp +.LP +All explicit pipe opens are exclusive; attempts to open an opened pipe fail. +.sp +.LP +On success, the pipe_handle argument points to an opaque handle of the opened +pipe. On failure, it is set to NULL. +.SH RETURN VALUES +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 25n +.rt +Open succeeded. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_NO_RESOURCES\fR +.ad +.RS 25n +.rt +Insufficient resources were available. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_NO_BANDWIDTH\fR +.ad +.RS 25n +.rt +Insufficient bandwidth available. (isochronous and interrupt pipes). +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 25n +.rt +Called from interrupt handler with USB_FLAGS_SLEEP set. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 25n +.rt +dip and/or pipe_handle is NULL. Pipe_policy is NULL. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PERM\fR +.ad +.RS 25n +.rt +Endpoint is NULL, signifying the default control pipe. A client driver cannot +open the default control pipe. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_NOT_SUPPORTED\fR +.ad +.RS 25n +.rt +Isochronous or interrupt endpoint with maximum packet size of zero is not +supported. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_HC_HARDWARE_ERROR\fR +.ad +.RS 25n +.rt +Host controller is in an error state. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 25n +.rt +Pipe is already open. Host controller not in an operational state. Polling +interval (\fBep_descr bInterval\fR field) is out of range (intr or isoc pipes). +.RE + +.SH CONTEXT +.sp +.LP +May be called from user or kernel context regardless of arguments. May also be +called from interrupt context if the \fIUSB_FLAGS_SLEEP\fR option is not set. +.SH EXAMPLES +.sp +.in +2 +.nf + usb_ep_data_t *ep_data; + usb_pipe_policy_t policy; + usb_pipe_handle_t pipe; + usb_client_dev_data_t *reg_data; + uint8_t interface = 1; + uint8_t alternate = 1; + uint8_t first_ep_number = 0; + + /* Initialize pipe policy. */ + bzero(policy, sizeof(usb_pipe_policy_t)); + policy.pp_max_async_requests = 2; + + /* Get tree of descriptors for device. */ + if (usb_get_dev_data( + dip, USBDRV_VERSION, ®_data, USB_FLAGS_ALL_DESCR, 0) != + USB_SUCCESS) { + ... + } + + /* Get first interrupt-IN endpoint. */ + ep_data = usb_lookup_ep_data(dip, reg_data, interface, alternate, + first_ep_number, USB_EP_ATTR_INTR, USB_EP_DIR_IN); + if (ep_data == NULL) { + ... + } + + /* Open the pipe. Get handle to pipe back in 5th argument. */ + if (usb_pipe_open(dip, &ep_data.ep_descr + &policy, USB_FLAGS_SLEEP, &pipe) != USB_SUCCESS) { + ... + } +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_alt_if\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_get_status\fR(9F), \fBusb_get_dev_data\fR(9F), +\fBusb_pipe_bulk_xfer\fR(9F), \fBusb_pipe_ctrl_xfer\fR(9F), +\fBusb_pipe_close\fR(9F), \fBusb_pipe_get_state\fR(9F), +\fBusb_pipe_intr_xfer\fR(9F), \fBusb_pipe_isoc_xfer\fR(9F), +\fBusb_pipe_reset\fR(9F), \fBusb_pipe_set_private\fR(9F), +\fBusb_ep_descr\fR(9S), \fBusb_callback_flags\fR(9S) diff --git a/usr/src/man/man9f/usb_pipe_reset.9f b/usr/src/man/man9f/usb_pipe_reset.9f new file mode 100644 index 0000000000..0e747648b8 --- /dev/null +++ b/usr/src/man/man9f/usb_pipe_reset.9f @@ -0,0 +1,326 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_pipe_reset 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_pipe_reset \- Abort queued requests from a USB pipe and reset the pipe +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + +\fBvoid\fR \fB\fR\fBusb_pipe_reset\fR(\fBdev_info_t *\fR\fIdip\fR, + \fBusb_pipe_handle_t\fR \fIpipe_handle\fR, \fBusb_flags_t\fR \fIusb_flags\fR, + \fBvoid (*\fR\fIcallback\fR)(usb_pipe_handle_t \fIcb_pipe_handle\fR, + \fBusb_opaque_t\fR \fIarg\fR, \fBint\fR \fIrval\fR, \fBusb_cb_flags_t\fR \fIflags)\fR, + \fBusb_opaque_t\fR \fIcallback_arg\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 16n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 16n +.rt +Handle of the pipe to reset. Cannot be the handle to the default control pipe. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIusb_flags\fR\fR +.ad +.RS 16n +.rt +USB_FLAGS_SLEEP is the only flag recognized. Wait for completion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback\fR\fR +.ad +.RS 16n +.rt +Function called on completion if the USB_FLAGS_SLEEP flag is not specified. If +NULL, no notification of completion is provided. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcallback_arg\fR\fR +.ad +.RS 16n +.rt +Second argument to callback function. +.RE + +.SH DESCRIPTION +.sp +.LP +Call \fBusb_pipe_reset()\fR to reset a pipe which is in an error state, or to +abort a current request and clear the pipe. The \fBusb_pipe_reset()\fR function +can be called on any pipe other than the default control pipe. +.sp +.LP +A pipe can be reset automatically when requests sent to the pipe have the +USB_ATTRS_AUTOCLEARING attribute specified. Client drivers see an exception +callback with the USB_CB_STALL_CLEARED callback flag set in such cases. +.sp +.LP +Stalls on pipes executing requests without the USB_ATTRS_AUTOCLEARING attribute +set must be cleared by the client driver. The client driver is notified of the +stall via an exception callback. The client driver must then call +\fBusb_pipe_reset()\fR to clear the stall. +.sp +.LP +The \fBusb_pipe_reset()\fR function resets a pipe as follows: +.br +.in +2 +1. Any polling activity is stopped if the pipe being reset is an interrupt or +isochronous pipe. +.in -2 +.br +.in +2 +2. All pending requests are removed from the pipe. An exception callback, if +specified beforehand, is executed for each aborted request. +.in -2 +.br +.in +2 +3. The pipe is reset to the idle state. +.in -2 +.sp +.LP +Requests to reset the default control pipe are not allowed. No action is taken +on a pipe which is closing. +.sp +.LP +If USB_FLAGS_SLEEP is specified in \fIflags\fR, this function waits for the +action to complete before calling the callback handler and returning. If not +specified, this function queues the request and returns immediately, and the +specified callback is called upon completion. +.sp +.LP +\fIcallback\fR is the callback handler. It takes the following arguments: +.sp +.ne 2 +.mk +.na +\fBusb_pipe_handle_t cb_pipe_handle\fR +.ad +.sp .6 +.RS 4n +Handle of the pipe to reset. +.RE + +.sp +.ne 2 +.mk +.na +\fBusb_opaque_t callback_arg\fR +.ad +.sp .6 +.RS 4n +Callback_arg specified to \fBusb_pipe_reset()\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fBint rval\fR +.ad +.sp .6 +.RS 4n +Return value of the reset call. +.RE + +.sp +.ne 2 +.mk +.na +\fBusb_cb_flags_t callback_flags\fR +.ad +.sp .6 +.RS 4n +Status of the queueing operation. Can be: +.sp +USB_CB_NO_INFO \(em Callback was uneventful. +.sp +USB_CB_ASYNC_REQ_FAILED \(em Error starting asynchronous request. +.RE + +.SH RETURN VALUES +.sp +.LP +Status is returned to the caller via the callback handler's rval argument. +Possible callback hander rval argument values are: +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 23n +.rt +Pipe successfully reset. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PIPE\fR +.ad +.RS 23n +.rt +\fIpipe_handle\fR specifies a pipe which is closed or closing. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_ARGS\fR +.ad +.RS 23n +.rt +\fIdip\fR or \fIpipe_handle\fR arguments are \fBNULL\fR. USB_FLAGS_SLEEP is +clear and callback is NULL. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_CONTEXT\fR +.ad +.RS 23n +.rt +Called from interrupt context with the USB_FLAGS_SLEEP flag set. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PERM\fR +.ad +.RS 23n +.rt +\fIpipe_handle\fR specifies the default control pipe. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 23n +.rt +Asynchronous resources are unavailable. In this case, USB_CB_ASYNC_REQ_FAILED +is passed in as the \fIcallback_flags\fR arg to the callback hander. +.RE + +.sp +.LP +Exception callback handlers of interrupt-IN and isochronous-IN requests which +are terminated by these commands are called with a completion reason of +USB_CR_STOPPED_POLLING. +.sp +.LP +Exception handlers of incomplete bulk requests are called with a completion +reason of USB_CR_FLUSHED. +.sp +.LP +Exception handlers of unstarted requests are called with USB_CR_PIPE_RESET. +.sp +.LP +Note that messages mirroring the above errors are logged to the console logfile +on error. This provides status for calls which could not otherwise provide +status. +.SH CONTEXT +.sp +.LP +May be called from user or kernel context regardless of arguments. May be +called from any callback with the USB_FLAGS_SLEEP clear. May not be called from +a callback executing in interrupt context if the USB_FLAGS_SLEEP flag is set. +.sp +.LP +If the USB_CB_ASYNC_REQ_FAILED bit is clear in usb_cb_flags_t, the callback, if +supplied, can block because it is executing in kernel context. Otherwise the +callback cannot block. Please see \fBusb_callback_flags\fR(9S) for more +information on callbacks. +.SH EXAMPLES +.sp +.in +2 +.nf +void post_reset_handler( + usb_pipe_handle_t, usb_opaque_t, int, usb_cb_flags_t); + +/* + * Do an asynchronous reset on bulk_pipe. + * Execute post_reset_handler when done. + */ +usb_pipe_reset(dip, bulk_pipe, 0, post_reset_handler, arg); + +/* Do a synchronous reset on bulk_pipe. */ +usb_pipe_reset(dip, bulk_pipe, USB_FLAGS_SLEEP, NULL, NULL); + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_get_cfg\fR(9F), \fBusb_pipe_bulk_xfer\fR(9F), +\fBusb_pipe_close\fR(9F), \fBusb_get_status\fR(9F), +\fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_drain_reqs\fR(9F), +\fBusb_pipe_get_state\fR(9F), \fBusb_pipe_intr_xfer\fR(9F), +\fBusb_pipe_isoc_xfer\fR(9F), \fBusb_pipe_open\fR(9F), +\fBusb_pipe_stop_intr_polling\fR(9F), \fBusb_pipe_stop_isoc_polling\fR(9F), +\fBusb_callback_flags\fR(9S) diff --git a/usr/src/man/man9f/usb_pipe_set_private.9f b/usr/src/man/man9f/usb_pipe_set_private.9f new file mode 100644 index 0000000000..ff16d0bc78 --- /dev/null +++ b/usr/src/man/man9f/usb_pipe_set_private.9f @@ -0,0 +1,173 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_pipe_set_private 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_pipe_set_private, usb_pipe_get_private \- USB user-defined pipe data-field +facility +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + +\fBint \fR\fBusb_pipe_set_private\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, \fBusb_opaque_t\fR \fIdata\fR); +.fi + +.LP +.nf +\fB\fR\fBusb_opaque_t usb_pipe_get_private \fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.LP +For \fBusb_pipe_set_private()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 15n +.rt +Pipe handle into which user-defined data is placed. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdata\fR\fR +.ad +.RS 15n +.rt +Data to store in the pipe handle. +.RE + +.sp +.LP +For \fBusb_pipe_get_private()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIpipe_handle\fR\fR +.ad +.RS 15n +.rt +Pipe handle from which user-defined data is retrieved. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_set_driver_private()\fR function initializes the user-private data +field of the pipe referred to by \fIpipe_handle\fR, using \fIdata\fR. The +user-private data field is used to store any data the client desires and is +not used in any way by the USBA or OS framework. Client drivers often store +their soft-state here for convenient retrieval by their callback handlers. +.sp +.LP +The \fBusb_get_driver_private()\fR function retrieves the user-private data +stored via \fBusb_set_driver_private()\fR, from the pipe referred to by +\fIpipe_handle\fR. +.SH RETURN VALUES +.sp +.LP +For \fBusb_pipe_set_private()\fR: +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 20n +.rt +Private data has been successfully stored in pipe handle. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PIPE\fR +.ad +.RS 20n +.rt +\fIpipe_handle\fR argument is \fBNULL\fR or invalid. +.sp +Pipe is closing or closed. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_INVALID_PERM\fR +.ad +.RS 20n +.rt +The \fIpipe_handle\fR argument refers to the default control pipe. +.RE + +.sp +.LP +For \fBusb_pipe_get_private()\fR: +.sp +.LP +On success: usb_opaque_t pointer to data being retrieved. +.sp +.LP +On failure: \fBNULL\fR. Fails if pipe handle is \fBNULL\fR or invalid. Fails if +pipe handle is to a pipe which is closing or closed. +.SH CONTEXT +.sp +.LP +May be called from user, kernel or interrupt context. +.SH EXAMPLES +.sp +.in +2 +.nf + usb_pipe_handle_t pipe; + + /* Some driver defined datatype. */ + xxx_data_t *data = kmem_zalloc(...); + + usb_pipe_set_private(pipe, data); + + ---- + + xxx_data_t *xxx_data_ptr = (xxx_data_t *)usb_pipe_get_private(pipe); + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_pipe_open\fR(9F), \fBusb_alloc_request\fR(9F) diff --git a/usr/src/man/man9f/usb_register_hotplug_cbs.9f b/usr/src/man/man9f/usb_register_hotplug_cbs.9f new file mode 100644 index 0000000000..458200e62c --- /dev/null +++ b/usr/src/man/man9f/usb_register_hotplug_cbs.9f @@ -0,0 +1,198 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc., +.\" All Rights Reserved +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_register_hotplug_cbs 9F "17 Aug 2004" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_register_hotplug_cbs, usb_unregister_hotplug_cbs \- Register/unregister for +notification of device hotplug events +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h> + + + +\fB\fR\fBint\fR \fBusb_register_hotplug_cbs\fR(\fBdev_info_t *\fR\fIdip\fR, + \fBint\fR \fI(*disconnection_event_handler)\fR(dev_info_t *\fIdip\fR, + \fBint\fR \fI(*reconnection_event_handler)\fR(dev_info_t *\fIdip\fR); +.fi + +.LP +.nf + \fBvoid\fR \fB\fR\fBusb_unregister_hotplug_cbs\fR(\fBdev_info_t *\fR\fIdip\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.LP +For \fBusb_register_hotplug_cbs()\fR +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.sp .6 +.RS 4n +Pointer to the device's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdisconnection_event_handler\fR\fR +.ad +.sp .6 +.RS 4n +Called when device is disconnected. This handler takes a dev_info_t as an +argument (representing the device being disconnected) and always returns +USB_SUCCESS. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreconnection_event_handler\fR\fR +.ad +.sp .6 +.RS 4n +Called when device is reconnected. This handler takes a dev_info_t as an +argument (representing the device being reconnected) and always returns +USB_SUCCESS. +.RE + +.sp +.LP +For \fBusb_unregister_hotplug_cbs()\fR: +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.RS 7n +.rt +Pointer to the device's \fBdev_info\fR structure. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_register_hotplug_cbs()\fR function registers callbacks to be +executed when the USB device represented by \fIdip\fR is hotplugged or removed. +.sp +.LP +The \fBusb_unregister_hotplug_cbs()\fR function unregisters or disengages +callbacks from executing when the USB device represented by \fIdip\fR is +hotplugged or removed. +.SH RETURN VALUES +.sp +.LP +For \fBusb_register_hotplug_cbs()\fR: +.sp +.ne 2 +.mk +.na +\fBUSB_SUCCESS\fR +.ad +.RS 15n +.rt +Callbacks were successfully registered. +.RE + +.sp +.ne 2 +.mk +.na +\fBUSB_FAILURE\fR +.ad +.RS 15n +.rt +One or more arguments were NULL. +.sp +Callbacks could not be successfully registered. +.RE + +.sp +.LP +For \fBusb_unregister_hotplug_cbs()\fR: None +.SH CONTEXT +.sp +.LP +The \fBusb_register_hotplug_cbs()\fR function may be called only from +\fBattach\fR(9E). +.sp +.LP +The \fBusb_unregister_hotplug_cbs()\fR function may be called only from +\fBdetach\fR(9E). +.sp +.LP +Registered callback handlers requiring the use of any DDI (section 9F) function +(except ddi_taskq_* functions), should launch a separate thread using +ddi_taskq_* routines for processing their event, to avoid deadlocks. The new +thread can then safely call any DDI function it needs to handle the event. +.sp +.LP +The registered callback handlers execute in kernel context. +.SH EXAMPLES +.sp +.in +2 +.nf + + int remove_device(dev_info_t *) + { + ... + ... + return (USB_SUCCESS); + } + + int accommodate_device(dev_info_t *) + { + ... + ... + return (USB_SUCCESS); + } + + if (usb_register_hotplug_cbs( + dip, remove_device, accommodate_device) == USB_FAILURE) { + cmn_err (CE_WARN, + "%s%d: Could not register hotplug handlers.", + ddi_driver_name(dip), ddi_get_instance(dip)); + } + +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface stabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E), +\fBusb_get_status\fR(9F) diff --git a/usr/src/man/man9f/usb_reset_device.9f b/usr/src/man/man9f/usb_reset_device.9f new file mode 100644 index 0000000000..747cee6878 --- /dev/null +++ b/usr/src/man/man9f/usb_reset_device.9f @@ -0,0 +1,343 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH usb_reset_device 9F "21 August 2007" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +usb_reset_device \- reset a USB device according to the reset_level. +.SH SYNOPSIS +.LP +.nf +#include <sys/usb/usba.h + + + +\fBint\fR \fBusb_reset_device\fR (\fBdev_info_t *\fR\fIdip\fR, + \fBusb_dev_reset_lvl_t\fR \fIreset_level\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIdip\fR\fR +.ad +.sp .6 +.RS 4n +Pointer to the devices's \fBdev_info\fR structure. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIreset_level\fR\fR +.ad +.sp .6 +.RS 4n +The level to which the device is reset. See below for a list of valid +\fBusb_dev_reset_lvl_t\fR values and explanations. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBusb_reset_device()\fR function provides a client driver to request a +hardware reset for a \fBUSB\fR device, which may be required in some situations +such as: +.RS +4 +.TP +.ie t \(bu +.el o +Resetting the hardware may help drivers to recover devices from an error state +caused by physical or firmware defects. +.RE +.RS +4 +.TP +.ie t \(bu +.el o +Some \fBUSB\fR devices need the driver to upload firmware into the device's +\fBRAM\fR and initiate a hardware reset in order to activate the new firmware. +.RE +.sp +.LP +The valid values for the \fIreset_level\fR are: +.sp +.ne 2 +.mk +.na +\fB\fBUSB_RESET_LVL_DEFAULT\fR\fR +.ad +.sp .6 +.RS 4n +The default reset level. The device is reset and any error status is cleared. +The device state machines and registers are also cleared and need to be +reinitialized in the driver. The current driver remains attached. This reset +level applies to hardware error recovery, or firmware download without changing +the descriptors. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUSB_RESET_LVL_REATTACH\fR\fR +.ad +.sp .6 +.RS 4n +The device is reset. The original driver is detached and a new driver attaching +process is started according to the updated compatible name. This reset level +applies to the firmware download with the descriptors changing, or other +situations in which the device needs to be reattached. +.sp +The \fBusb_reset_device()\fR function creates a new helper thread for +reattachment. When called from \fBattach\fR(9E), the new thread sets a timer (1 +second), and waits until the driver's \fBattach\fR(9E) completes, after which +the thread attempts to reattach the driver. When not called from +\fBattach\fR(9E), the new thread attempts to reattach the driver immediately. +.sp +If the thread fails to reattach to the driver, an error message is printed in +system log with the detailed reason. The driver returns to a stable state, +depending on where the failure occurred. +.RE + +.SH RETURN VALUES +.sp +.LP +The return values for the \fBusb_reset_device()\fR function are: +.sp +.ne 2 +.mk +.na +\fB\fBUSB_SUCCESS\fR\fR +.ad +.RS 23n +.rt +If \fBUSB_RESET_LVL_DEFAULT\fR is specified, the device was reset successfully. +If \fBUSB_RESET_LVL_REATTACH\fR is specified, reattaching was started +successfully or a previous reset is still in progress. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUSB_FAILURE\fR\fR +.ad +.RS 23n +.rt +The state of the device's parent hub is invalid (disconnected or suspended). +This is called when the driver being detached. If \fBUSB_RESET_LVL_DEFAULT\fR +is specified, the device failed to be reset. If \fBUSB_RESET_LVL_REATTACH\fR is +specified, reattaching failed to start. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUSB_INVALID_ARGS\fR\fR +.ad +.RS 23n +.rt +Invalid arguments. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUSB_INVALID_PERM\fR\fR +.ad +.RS 23n +.rt +The driver of the dip does not own the entire device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUSB_BUSY\fR\fR +.ad +.RS 23n +.rt +If \fBUSB_RESET_LVL_DEFAULT\fR is specified, one or more pipes other than the +default control pipe are open on the device. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBUSB_INVALID_CONTEXT\fR\fR +.ad +.RS 23n +.rt +If \fBUSB_RESET_LVL_DEFAULT\fR is specified, called from interrupt context +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRResetting a Device +.sp +.LP +The following example shows how a device is reset to recover it from an error +state: + +.sp +.in +2 +.nf +xxx_configure() +{ + xxx_set_parameter1(); + + if (xxx_set_parameter2() == USB_FAILURE) { + + /* Close all the opened pipes except the default pipe */ + xxx_close_all_opened_pipes(); + + /* Reset the device */ + rval = usb_reset_device(dip, USB_RESET_LVL_DEFAULT); + if (rval == USB_SUCCESS) { + /* Re-configure the device */ + xxx_set_parameter1(); + xxx_set_parameter2(); + + /* Open the closed pipes if needed */ + ... + } else { + /* Failed to reset the device, check the return value for + further process */ + ... + } + } +} +.fi +.in -2 + +.LP +\fBExample 2 \fRResetting a Device After Downloading Firmware +.sp +.LP +The following example shows how a device is reset after downloading firmware. +the device's descriptors change after the reset: + +.sp +.in +2 +.nf +static int xxx_attach(dev_info_t *dip, ddi_attach_cmd_t cmd) +{ + ... + /* Download the firmware to the RAM of the device */ + if (firmware_download() == USB_SUCCESS) { + /* Reset the device and re-enumerate it */ + rval = usb_reset_device(dip, USB_RESET_LVL_REATTACH); + if (rval == USB_SUCCESS) { + /* The re-enumeration has been started up, just return */ + return (DDI_SUCCESS); + } else { + /* Failed to start the re-enumeration, check the return value + for further process*/ + ... + return (DDI_FAILURE); + } +} +.fi +.in -2 + +.SH CONTEXT +.sp +.LP +The \fBusb_reset_device()\fR function may be called from user or kernel +context. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +ArchitecturePCI-based systems +_ +Interface StabilityCommitted +.TE + +.SH SEE ALSO +.sp +.LP +\fBattributes\fR(5), \fBusb_clr_feature\fR(9F), \fBusb_get_cfg\fR(9F), +\fBusb_pipe_close\fR(9F), \fBusb_pipe_open\fR(9F), \fBusb_pipe_reset\fR(9F), +.SH DIAGNOSTICS +.sp +.LP +The messages described below may appear on the system console as well as being +logged. All messages are formatted in the following manner: +.sp +.in +2 +.nf +WARNING: \fIdev_path\fR hubd\fIinstance_num\fR \fIdriver_name\fR Error message ... +.fi +.in -2 +.sp + +.sp +.ne 2 +.mk +.na +\fB\fIdriver_name\fR \fIinstance_num\fR is under bus power management, cannot +be reset. Please disconnect and reconnect this device.\fR +.ad +.sp .6 +.RS 4n +Bus power management is in process when calling the reset function, the device +failed to be reset and stayed in the former state. Please disconnect and +reconnect it to system. +.RE + +.sp +.ne 2 +.mk +.na +\fBTime out when resetting the device \fIdriver_name\fR \fIinstance_num\fR. +Please disconnect and reconnect it to system.\fR +.ad +.sp .6 +.RS 4n +The parent hub/root hub of this device is busy now. The device failed to be +reset and stayed in the former state. Please disconnect the device, wait for a +while and reconnect it to system. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdriver_name\fR \fIinstance_num\fR cannot be reset due to other +applications are using it, please first close these applications, then +disconnect and reconnect the device.\fR +.ad +.sp .6 +.RS 4n +The device is using by other applications, the related driver failed to be +detached. Please make sure to close these applications before calling the reset +function. +.RE + +.SH NOTES +.sp +.LP +Always close all applications before resetting a device. diff --git a/usr/src/man/man9f/uwritec.9f b/usr/src/man/man9f/uwritec.9f new file mode 100644 index 0000000000..b266114da1 --- /dev/null +++ b/usr/src/man/man9f/uwritec.9f @@ -0,0 +1,58 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH uwritec 9F "16 Jan 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +uwritec \- remove a character from a uio structure +.SH SYNOPSIS +.LP +.nf +#include <sys/uio.h> + + + +\fBint\fR \fBuwritec\fR(\fBuio_t *\fR\fIuio_p\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Architecture independent level 1 (DDI/DKI) +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIuio_p\fR\fR +.ad +.RS 9n +.rt +Pointer to the \fBuio\fR(9S) structure +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBuwritec()\fR function returns a character from the \fBuio\fR structure +pointed to by \fIuio_p\fR and updates the \fBuio\fR structure. See +\fBuiomove\fR(9F). +.SH RETURN VALUES +.sp +.LP +The next character for processing is returned on success, and \fB-1\fR is +returned if \fBuio\fR is empty or if there is an error. +.SH CONTEXT +.sp +.LP +The \fBuwritec()\fR function can be called from user, interrupt, or kernel +context. +.SH SEE ALSO +.sp +.LP +\fBuiomove\fR(9F), \fBureadc\fR(9F), \fBiovec\fR(9S), \fBuio\fR(9S) +.sp +.LP +\fIWriting Device Drivers\fR diff --git a/usr/src/man/man9f/va_arg.9f b/usr/src/man/man9f/va_arg.9f new file mode 100644 index 0000000000..8acd91a2cd --- /dev/null +++ b/usr/src/man/man9f/va_arg.9f @@ -0,0 +1,218 @@ +'\" te +.\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved. +.\" Copyright 1989 AT&T +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH va_arg 9F "22 Mar 2006" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +va_arg, va_start, va_copy, va_end \- handle variable argument list +.SH SYNOPSIS +.LP +.nf +#include <sys/varargs.h> + + + +\fBvoid\fR \fBva_start\fR(\fBva_list\fR \fIpvar\fR, \fB\fR\fIname\fR); +.fi + +.LP +.nf +\fB(type *)\fR \fBva_arg\fR(\fBva_list\fR \fIpvar\fR, \fB\fR\fItype\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBva_copy\fR(\fBva_list\fR \fIdest\fR, \fBva_list\fR \fIsrc\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBva_end\fR(\fBva_list\fR \fIpvar\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.SS "\fBva_start()\fR" +.sp +.ne 2 +.mk +.na +\fB\fIpvar\fR\fR +.ad +.RS 8n +.rt +Pointer to variable argument list. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 8n +.rt +Identifier of rightmost parameter in the function definition. +.RE + +.SS "\fBva_arg()\fR" +.sp +.ne 2 +.mk +.na +\fB\fIpvar\fR\fR +.ad +.RS 8n +.rt +Pointer to variable argument list. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 8n +.rt +Type name of the next argument to be returned. +.RE + +.SS "\fBva_copy()\fR" +.sp +.ne 2 +.mk +.na +\fB\fIdest\fR\fR +.ad +.RS 8n +.rt +Destination variable argument list. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsrc\fR\fR +.ad +.RS 8n +.rt +Source variable argument list. +.RE + +.SS "\fBva_end()\fR" +.sp +.ne 2 +.mk +.na +\fB\fIpvar\fR\fR +.ad +.RS 8n +.rt +Pointer to variable argument list. +.RE + +.SH DESCRIPTION +.sp +.LP +This set of macros allows portable procedures that accept variable argument +lists to be written. Routines that have variable argument lists but do not use +the \fBvarargs\fR macros are inherently non-portable, as different machines use +different argument-passing conventions. Routines that accept a variable +argument list can use these macros to traverse the list. +.sp +.LP +\fBva_list\fR is the type defined for the variable used to traverse the list of +arguments. +.sp +.LP +\fBva_start()\fR is called to initialize \fIpvar\fR to the beginning of the +variable argument list. \fBva_start()\fR must be invoked before any access to +the unnamed arguments. The parameter \fIname\fR is the identifier of the +rightmost parameter in the variable parameter list in the function definition +(the one just before the "\fB, .\|.\|.\|\fR"). If this parameter is declared +with the \fBregister\fR storage class or with a function or array type, or with +a type that is not compatible with the type that results after application of +the default argument promotions, the behavior is undefined. +.sp +.LP +\fBva_arg()\fR expands to an expression that has the type and value of the next +argument in the call. The parameter \fIpvar\fR must be initialized by +\fBva_start()\fR. Each invocation of \fBva_arg()\fR modifies \fIpvar\fR so that +the values of successive arguments are returned in turn. The parameter +\fItype\fR is the type name of the next argument to be returned. The type name +must be specified in such a way that the type of pointer to an object that has +the specified type can be obtained by postfixing a \fB*\fR to \fItype\fR. If +there is no actual next argument, or if\fBtype\fR is not compatible with the +type of the actual next argument (as promoted according to the default argument +promotions), the behavior is undefined. +.sp +.LP +The \fBva_copy()\fR macro saves the state represented by the +\fBva_list\fR\fIsrc\fR in the \fBva_list\fR \fIdest\fR. The \fBva_list\fR +passed as \fIdest\fR should not be initialized by a previous call to +\fBva_start()\fR It then must be passed to \fBva_end()\fR before being reused +as a parameter to \fBva_start()\fR or as the \fIdest\fR parameter of a +subsequent call to \fBva_copy()\fR. The behavior is undefined if any of these +restrictions are not met. +.sp +.LP +The \fBva_end()\fR macro is used to clean up. It invalidates \fIpvar\fR for use +(unless \fBva_start()\fR is invoked again). +.sp +.LP +Multiple traversals, each bracketed by a call to \fBva_start()\fR and +\fBva_end()\fR, are possible. +.SH EXAMPLES +.LP +\fBExample 1 \fRCreating a Variable Length Command +.sp +.LP +The following example uses these routines to create a variable length command. +This might be useful for a device that provides for a variable-length command +set. \fBncmdbytes\fR is the number of bytes in the command. The new command is +written to \fBcmdp\fR. + +.sp +.in +2 +.nf +static void +xx_write_cmd(uchar_t *cmdp, int ncmdbytes, ...) +{ + va_list ap; + int i; + + /* + * Write variable-length command to destination + */ + va_start(ap, ncmdbytes); + for (i = 0; i < ncmdbytes; i++) { + *cmdp++ = va_arg(ap, uchar_t); + } + va_end(ap); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBvcmn_err\fR(9F), \fBvsprintf\fR(9F) +.SH NOTES +.sp +.LP +It is up to the calling routine to specify in some manner how many arguments +there are, since it is not always possible to determine the number of arguments +from the stack frame. +.sp +.LP +Specifying a second argument of \fBchar\fR or \fBshort\fR to \fBva_arg\fR makes +your code non-portable, because arguments seen by the called function are not +\fBchar\fR or \fBshort\fR. C converts \fBchar\fR and \fBshort\fR arguments to +\fBint\fR before passing them to a function. diff --git a/usr/src/man/man9f/vsprintf.9f b/usr/src/man/man9f/vsprintf.9f new file mode 100644 index 0000000000..fc13fe0873 --- /dev/null +++ b/usr/src/man/man9f/vsprintf.9f @@ -0,0 +1,248 @@ +'\" 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 vsprintf 9F "6 May 1996" "SunOS 5.11" "Kernel Functions for Drivers" +.SH NAME +vsprintf \- format characters in memory +.SH SYNOPSIS +.LP +.nf +#include <sys/varargs.h> + #include <sys/ddi.h> + #include <sys/sunddi.h> + + + +\fBchar *\fR\fBvsprintf\fR(\fBchar *\fR\fIbuf\fR, \fBconst char *\fR\fIfmt\fR, \fBva_list\fR \fIap\fR); +.fi + +.SH INTERFACE LEVEL +.sp +.LP +Solaris DDI specific (Solaris DDI). +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIbuf\fR \fR +.ad +.RS 8n +.rt +Pointer to a character string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfmt\fR \fR +.ad +.RS 8n +.rt +Pointer to a character string. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIap\fR \fR +.ad +.RS 8n +.rt +Pointer to a variable argument list. +.RE + +.SH DESCRIPTION +.sp +.LP +\fBvsprintf()\fR builds a string in \fIbuf\fR under the control of the format +\fIfmt\fR. The format is a character string with either plain characters, which +are simply copied into \fIbuf\fR, or conversion specifications, each of which +converts zero or more arguments, again copied into \fIbuf\fR. The results are +unpredictable if there are insufficient arguments for the format; excess +arguments are simply ignored. It is the user's responsibility to ensure that +enough storage is available for \fIbuf\fR. +.sp +.LP +\fIap\fR contains the list of arguments used by the conversion specifications +in \fIfmt\fR. \fIap\fR is a variable argument list and must be initialized by +calling \fBva_start\fR(9F). \fBva_end\fR(9F) is used to clean up and must be +called after each traversal of the list. Multiple traversals of the argument +list, each bracketed by \fBva_start\fR(9F) and \fBva_end\fR(9F), are +possible. +.sp +.LP +Each conversion specification is introduced by the \fB%\fR character, after +which the following appear in sequence: +.sp +.LP +An optional decimal digit specifying a minimum field width for numeric +conversion. The converted value will be right-justified and padded with leading +zeroes if it has fewer characters than the minimum. +.sp +.LP +An optional \fBl\fR (\fBll\fR) specifying that a following \fBd\fR, \fBD\fR, +\fBo\fR, \fBO\fR, \fBx\fR, \fBX\fR, or \fBu\fR conversion character applies to +a \fBlong\fR (\fBlong long\fR) integer argument. An \fBl\fR (\fBll\fR) before +any other conversion character is ignored. +.sp +.LP +A character indicating the type of conversion to be applied: +.sp +.ne 2 +.mk +.na +\fB\fBd\fR,\fBD\fR,\fBo\fR,\fBO\fR,\fBx\fR,\fBX\fR,\fBu\fR\fR +.ad +.RS 17n +.rt +The integer argument is converted to signed decimal (\fBd\fR, \fBD\fR), +unsigned octal (\fBo\fR, \fBO\fR), unsigned hexadecimal (\fBx\fR, \fBX\fR) or +unsigned decimal (\fBu\fR), respectively, and copied. The letters \fBabcdef\fR +are used for \fBx\fR conversion. The letters \fBABCDEF\fR are used for \fBX\fR +conversion. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBc\fR\fR +.ad +.RS 17n +.rt +The character value of the argument is copied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBb\fR\fR +.ad +.RS 17n +.rt +This conversion uses two additional arguments. The first is an integer, and is +converted according to the base specified in the second argument. The second +argument is a character string in the form +\fB<\fR\fIbase\fR\fB>[<\fR\fIarg\fR\fB>\|.\|.\|.\|].\fR The base supplies the +conversion base for the first argument as a binary value; \e10 gives octal, +\e20 gives hexadecimal. Each subsequent <arg> is a sequence of characters, the +first of which is the bit number to be tested, and subsequent characters, up to +the next bit number or terminating null, supply the name of the bit. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fR +.ad +.RS 17n +.rt +A bit number is a binary-valued character in the range \fB1-32\fR. For each bit +set in the first argument, and named in the second argument, the bit names are +copied, separated by commas, and bracketed by \fB<\fR and \fB>\fR. Thus, the +following function call would generate \fBreg=3<BitTwo,BitOne>\en\fR in +\fIbuf\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fR +.ad +.RS 17n +.rt +\fBvsprintf(buf, "reg=%b\en", 3, "\e10\e2BitTwo\e1BitOne")\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBs\fR\fR +.ad +.RS 17n +.rt +The argument is taken to be a string (character pointer), and characters from +the string are copied until a null character is encountered. If the character +pointer is \fINULL\fR on \fBSPARC\fR, the string \fB<nullstring>\fR is used in +its place; on x86, it is undefined. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fB%\fR\fR +.ad +.RS 17n +.rt +Copy a \fB%\fR; no argument is converted. +.RE + +.SH RETURN VALUES +.sp +.LP +\fBvsprintf()\fR returns its first parameter, \fIbuf\fR. +.SH CONTEXT +.sp +.LP +\fBvsprintf()\fR can be called from user, kernel, or interrupt context. +.SH EXAMPLES +.LP +\fBExample 1 \fRUsing \fBvsprintf()\fR +.sp +.LP +In this example, \fBxxerror()\fR accepts a pointer to a \fBdev_info_t\fR +structure \fBdip\fR, an error level \fBlevel\fR, a format \fBfmt\fR, and a +variable number of arguments. The routine uses \fBvsprintf()\fR to format the +error message in \fBbuf\fR. Note that \fBva_start\fR(9F) and \fBva_end\fR(9F) +bracket the call to \fBvsprintf()\fR. \fBinstance\fR, \fBlevel\fR, \fBname\fR, +and \fBbuf\fR are then passed to \fBcmn_err\fR(9F). + +.sp +.in +2 +.nf +#include <sys/varargs.h> +#include <sys/ddi.h> +#include <sys/sunddi.h> +#define MAX_MSG 256 + +void +xxerror(dev_info_t *dip, int level, const char *fmt, .\|.\|.\|) +{ + va_list ap; + int instance; + char buf[MAX_MSG], + *name; + + instance = ddi_get_instance(dip); + name = ddi_binding_name(dip); + + /* format buf using fmt and arguments contained in ap */ + va_start(ap, fmt); + vsprintf(buf, fmt, ap); + va_end(ap); + + /* pass formatted string to cmn_err(9F) */ + cmn_err(level, "%s%d: %s", name, instance, buf); +} +.fi +.in -2 + +.SH SEE ALSO +.sp +.LP +\fBcmn_err\fR(9F), \fBddi_binding_name\fR(9F), \fBddi_get_instance\fR(9F), +\fBva_arg\fR(9F) +.sp +.LP +\fIWriting Device Drivers\fR |