'\" 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 "Jan 5, 2009"
.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
.na
\fB\fIdip\fR\fR
.ad
.RS 8n
Pointer to the \fBdev_info\fR structure.
.RE

.sp
.ne 2
.na
\fB\fInreq\fR\fR
.ad
.RS 8n
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
.na
\fB\fBDDI_SUCCESS\fR\fR
.ad
.RS 15n
on success
.RE

.sp
.ne 2
.na
\fB\fBDDI_EINVAL\fR\fR
.ad
.RS 15n
The operation is invalid because the \fInreq\fR parameter is not a legal value
.RE

.sp
.ne 2
.na
\fB\fBDDI_ENOTSUP\fR\fR
.ad
.RS 15n
The operation is not supported. The driver must have a registered callback, and
the system must have interrupt pools implemented.
.RE

.sp
.ne 2
.na
\fB\fBDDI_FAILURE\fR\fR
.ad
.RS 15n
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
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Private
_
MT-Level	MT-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.