share/man/man9f/pci_report_pmcap.9f

   1 '\" te
   2 .\"  Copyright (c) 2000, Sun Microsystems, Inc.  All Rights Reserved
   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 PCI_REPORT_PMCAP 9F "Aug 13, 1999"
   7 .SH NAME
   8 pci_report_pmcap \- Report Power Management capability of a PCI device
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBint\fR \fBpci_report_pmcap\fR(\fBdev_info_t *\fR\fIdip\fR,  int \fIcap,\fR void *\fIarg\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 7n
  31 Pointer to the device's \fBdev_info\fR structure
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIcap\fR\fR
  38 .ad
  39 .RS 7n
  40 Power management capability
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIarg\fR\fR
  47 .ad
  48 .RS 7n
  49 Argument for the capability
  50 .RE
  51
  52 .SH DESCRIPTION
  53 .sp
  54 .LP
  55 Some PCI devices provide power management capabilities in addition to those
  56 provided by the PCI Power Management Specification. The
  57 \fBpci_report_pmcap()\fR function reports those Power Management capabilities
  58 of the PCI device to the framework. Framework supports dynamic changing of the
  59 capability by allowing \fBpci_report_pmcap()\fR to be called multiple times.
  60 Following are the supported capabilities as indicated by the \fBcap\fR:
  61 .sp
  62 .LP
  63 \fBPCI_PM_IDLESPEED\fR \(em The \fBPCI_PM_IDLESPEED\fR value indicates the
  64 lowest PCI clock speed that a device can tolerate when idle, and is  applicable
  65 only to 33 MHz PCI bus. \fBarg\fR represents the lowest possible idle speed in
  66 KHz (1 KHz is 1000 Hz). The integer value representing the speed should be cast
  67 to \fB(void *)\fRbefore passing as \fBarg\fR to \fBpci_report_pmcap()\fR.
  68 .sp
  69 .LP
  70 The special values of \fBarg\fR are:
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fBPCI_PM_IDLESPEED_ANY\fR\fR
  75 .ad
  76 .RS 25n
  77 The device can tolerate any idle clock speed.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBPCI_PM_IDLESPEED_NONE\fR\fR
  84 .ad
  85 .RS 25n
  86 The device cannot tolerate slowing down of PCI clock even when idle.
  87 .RE
  88
  89 .sp
  90 .LP
  91 If the driver doesn't make this call, \fBPCI_PM_IDLESPEED_NONE\fR is assumed.
  92 In this case, one offending device can keep the entire bus from being power
  93 managed.
  94 .SH RETURN VALUES
  95 .sp
  96 .LP
  97 The \fBpci_report_pmcap()\fR function returns:
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBDDI_SUCCESS\fR\fR
 102 .ad
 103 .RS 15n
 104 Successful reporting of the capability
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBDDI_FAILURE\fR\fR
 111 .ad
 112 .RS 15n
 113 Failure to report capability because of invalid argument(s)
 114 .RE
 115
 116 .SH CONTEXT
 117 .sp
 118 .LP
 119 The \fBpci_report_pmcap()\fR function can be called from user, kernel and
 120 interrupt context.
 121 .SH EXAMPLES
 122 .sp
 123 .LP
 124 1. A device driver knows that the device it controls works with any clock
 125 between DC and 33 MHz as specified in \fISection 4.2.3.1: Clock Specification
 126 \fR of the \fIPCI Bus Specification Revision 2.1\fR. The device driver makes
 127 the following call from its \fBattach\fR(9E):
 128 .sp
 129 .in +2
 130 .nf
 131 if (pci_report_pmcap(dip, PCI_PM_IDLESPEED, PCI_PM_IDLESPEED_ANY) !=
 132             DDI_SUCCESS)
 133                 cmn_err(CE_WARN, "%s%d: pci_report_pmcap failed\fB\en\fR",
 134                     ddi_driver_name(dip), ddi_get_instance(dip));
 135 .fi
 136 .in -2
 137
 138 .sp
 139 .LP
 140 2. A device driver controls a 10/100 Mb Ethernet device which runs the device
 141 state machine on the chip from the PCI clock. For the device state machine to
 142 receive packets at 100 Mb, the PCI clock cannot drop below 4 MHz. The driver
 143 makes the following call whenever it negotiates a 100 Mb Ethernet connection:
 144 .sp
 145 .in +2
 146 .nf
 147 if (pci_report_pmcap(dip,  PCI_PM_IDLESPEED, (void *)4000) !=
 148                DDI_SUCCESS)
 149                 cmn_err(CE_WARN, "%s%d: pci_report_pmcap failed\fB\en\fR",
 150                     ddi_driver_name(dip), ddi_get_instance(dip));
 151 .fi
 152 .in -2
 153
 154 .SH ATTRIBUTES
 155 .sp
 156 .LP
 157 See \fBattributes\fR(5) for descriptions of the following attributes:
 158 .sp
 159
 160 .sp
 161 .TS
 162 box;
 163 c | c
 164 l | l .
 165 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 166 _
 167 Interface Stability     Committed
 168 .TE
 169
 170 .SH SEE ALSO
 171 .sp
 172 .LP
 173 \fIWriting Device Drivers\fR
 174 .sp
 175 .LP
 176 \fIPCI Bus Power Management Interface Specification Version 1.1\fR
 177 .sp
 178 .LP
 179 \fIPCI Bus Specification Revision 2.1\fR