usr/src/man/man9f/ddi_intr_set_nreq.9f

   1 '\" te
   2 .\" Copyright (c) 2009, Sun Microsystems, Inc.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH DDI_INTR_SET_NREQ 9F "Jan 5, 2009"
   7 .SH NAME
   8 ddi_intr_set_nreq \- set the number of interrupts requested for a device driver
   9 instance
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ddi_intr.h>
  14
  15
  16
  17 \fBint\fR \fBddi_intr_set_nreq\fR(\fBdev_info_t *\fR\fIdip\fR, \fBint\fR \fInreq\fR);
  18 .fi
  19
  20 .SH INTERFACE LEVEL
  21 .sp
  22 .LP
  23 Solaris DDI specific (Solaris DDI).
  24 .SH PARAMETERS
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fIdip\fR\fR
  29 .ad
  30 .RS 8n
  31 Pointer to the \fBdev_info\fR structure.
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fInreq\fR\fR
  38 .ad
  39 .RS 8n
  40 Number of interrupts requested.
  41 .RE
  42
  43 .SH DESCRIPTION
  44 .sp
  45 .LP
  46 The \fBddi_intr_set_nreq()\fR function changes the number of interrupts
  47 requested by a device driver instance.
  48 .sp
  49 .LP
  50 The \fInreq\fR parameter is the total number of interrupt resources that this
  51 instance of the device driver would like to have available. The \fInreq\fR
  52 parameter includes any interrupt resources already allocated by the driver. For
  53 example, if the driver instance already has two MSI-X vectors and it wants two
  54 more, it should call this function with an \fInreq\fR parameter set to four.
  55 .sp
  56 .LP
  57 The \fInreq\fR parameter can be any value between one and the maximum number of
  58 interrupts supported by the device hardware, as reported by a call to the
  59 \fBddi_intr_get_nintrs\fR(9F) function. The driver receives a callback
  60 notifying it in cases when it must release any previously allocated interrupts,
  61 or when it is allowed to allocate more interrupts as a result of its new
  62 \fInreq\fR parameter.
  63 .sp
  64 .LP
  65 The \fBddi_intr_set_nreq()\fRfunction is not supported unless a driver is
  66 already consuming interrupts, and if it has a registered callback handler that
  67 can process actions related to changes in interrupt availability. See
  68 \fBddi_cb_register\fR(9F) for an explanation on how to enable this
  69 functionality.
  70 .SH RETURN VALUES
  71 .sp
  72 .LP
  73 The \fBddi_intr_set_nreq()\fR function returns:
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fBDDI_SUCCESS\fR\fR
  78 .ad
  79 .RS 15n
  80 on success
  81 .RE
  82
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fBDDI_EINVAL\fR\fR
  87 .ad
  88 .RS 15n
  89 The operation is invalid because the \fInreq\fR parameter is not a legal value
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBDDI_ENOTSUP\fR\fR
  96 .ad
  97 .RS 15n
  98 The operation is not supported. The driver must have a registered callback, and
  99 the system must have interrupt pools implemented.
 100 .RE
 101
 102 .sp
 103 .ne 2
 104 .na
 105 \fB\fBDDI_FAILURE\fR\fR
 106 .ad
 107 .RS 15n
 108 Implementation specific failure
 109 .RE
 110
 111 .SH CONTEXT
 112 .sp
 113 .LP
 114 These functions can be called from kernel, non-interrupt context.
 115 .SH ATTRIBUTES
 116 .sp
 117 .LP
 118 See \fBattributes\fR(5) for descriptions of the following attributes:
 119 .sp
 120
 121 .sp
 122 .TS
 123 box;
 124 c | c
 125 l | l .
 126 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 127 _
 128 Interface Stability     Private
 129 _
 130 MT-Level        MT-Safe
 131 .TE
 132
 133 .SH SEE ALSO
 134 .sp
 135 .LP
 136 \fBattributes\fR(5), \fBattach\fR(9E), \fBddi_cb_register\fR(9F),
 137 \fBddi_intr_alloc\fR(9F), \fBddi_intr_get_nintrs\fR(9F)
 138 .SH NOTES
 139 .sp
 140 .LP
 141 The Interrupt Resource Management feature is limited to device driver instances
 142 that are using MSI-X interrupts (interrupt type \fBDDI_INTR_TYPE_MSIX\fR).
 143 Attempts to use this function for any other type of interrupts fails with
 144 \fBDDI_ENOTSUP\fR.
 145 .sp
 146 .LP
 147 The total number of interrupts requested by the driver is initially defined by
 148 the \fIcount\fR parameter provided by the driver's first call to the
 149 \fBddi_intr_alloc\fR(9F) function, specifically during the driver instance's
 150 \fBattach\fR(9E) routine. The \fBddi_intr_set_nreq()\fR function is only used
 151 if the driver instance experiences changes in its I/O load. In response to
 152 increased I/O load, the driver may want to request additional interrupt
 153 resources. In response to diminished I/O load. the driver may volunteer to
 154 return extra interrupt resources back to the system.