pci_report_pmcap(9F)

NAME

     pci_report_pmcap - Report Power Management capability  of  a
     PCI device

SYNOPSIS

     #include <sys/ddi.h>
     #include <sys/sunddi.h>

     int pci_report_pmcap(dev_info_t *dip,  int cap, void *arg);

INTERFACE LEVEL

     Solaris DDI specific (Solaris DDI)

PARAMETERS

     dip   Pointer to the device's dev_info structure

     cap   Power management capability

     arg   Argument for the capability

DESCRIPTION

     Some PCI devices provide power  management  capabilities  in
     addition  to  those  provided  by  the  PCI Power Management
     Specification.  The  pci_report_pmcap(9F)  function  reports
     those Power Management capabilities of the PCI device to the
     framework. Framework supports dynamic changing of the  capa-
     bility  by allowing pci_report_pmcap(9F) to be called multi-
     ple times. Following are the supported capabilities as indi-
     cated by the cap:

     PCI_PM_IDLESPEED - The PCI_PM_IDLESPEED value indicates  the
     lowest PCI clock speed that a device can tolerate when idle,
     and is  applicable only to 33 MHz PCI  bus.  arg  represents
     the  lowest  possible  idle speed in KHz (1 KHz is 1000 Hz).
     The integer value representing the speed should be  cast  to
     (void *) before passing as arg to pci_report_pmcap(9F).

       The special values of arg are:

          PCI_PM_IDLESPEED_ANY
                The device can tolerate any idle clock speed.

          PCI_PM_IDLESPEED_NONE
                The device cannot tolerate slowing  down  of  PCI
                clock even when idle.

     If the driver doesn't make this call,  PCI_PM_IDLESPEED_NONE
     is  assumed. In this case, one offending device can keep the
     entire bus from being power managed.

RETURN VALUES

     The pci_report_pmcap(9F) function returns:

     DDI_SUCCESS
           Successful reporting of the capability

     DDI_FAILURE
           Failure  to  report  capability  because  of   invalid
           argument(s)

CONTEXT

     The pci_report_pmcap(9F) function can be called  from  user,
     kernel and interrupt context.

EXAMPLES

     1. A device driver knows that the device it  controls  works
     with any clock between DC and 33 MHz as specified in Section
     4.2.3.1: Clock Specification  of the PCI  Bus  Specification
     Revision  2.1.  The  device  driver makes the following call
     from its  attach(9E):

     if (pci_report_pmcap(dip, PCI_PM_IDLESPEED, PCI_PM_IDLESPEED_ANY) !=
                 DDI_SUCCESS)
                     cmn_err(CE_WARN, "%s%d: pci_report_pmcap failed\n",
                         ddi_driver_name(dip), ddi_get_instance(dip));

     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:

     if (pci_report_pmcap(dip,  PCI_PM_IDLESPEED, (void *)4000) !=
                    DDI_SUCCESS)
                     cmn_err(CE_WARN, "%s%d: pci_report_pmcap failed\n",
                         ddi_driver_name(dip), ddi_get_instance(dip));

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |      ATTRIBUTE TYPE      |         ATTRIBUTE VALUE        |
    |__________________________|________________________________|
    | Interface Stability      |  Evolving                      |
    |__________________________|________________________________|

SEE ALSO

     Writing Device Drivers

     PCI Bus Power Management Interface Specification Version 1.1

     PCI Bus Specification Revision 2.1