usr/src/man/man9e/getinfo.9e

   1 '\" te
   2 .\" Copyright (c) 2004, 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 GETINFO 9E "Jan 16, 2008"
   7 .SH NAME
   8 getinfo \- get device driver information
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/ddi.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBint prefix\fR\fBgetinfo\fR(\fBdev_info_t *\fR\fIdip\fR, \fBddi_info_cmd_t\fR \fIcmd\fR,
  18      \fBvoid *\fR\fIarg\fR, \fBvoid **\fR\fIresultp\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Solaris DDI specific (Solaris DDI). This entry point is \fBrequired\fR for
  25 drivers which export \fBcb_ops\fR(9S) entry points.
  26 .SH ARGUMENTS
  27 .sp
  28 .ne 2
  29 .na
  30 \fB\fIdip\fR\fR
  31 .ad
  32 .RS 11n
  33 Do not use.
  34 .RE
  35
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fIcmd\fR\fR
  40 .ad
  41 .RS 11n
  42 Command argument - valid command values are \fBDDI_INFO_DEVT2DEVINFO\fR and
  43 \fBDDI_INFO_DEVT2INSTANCE\fR.
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIarg\fR\fR
  50 .ad
  51 .RS 11n
  52 Command specific argument.
  53 .RE
  54
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fIresultp\fR\fR
  59 .ad
  60 .RS 11n
  61 Pointer to where the requested information is stored.
  62 .RE
  63
  64 .SH DESCRIPTION
  65 .sp
  66 .LP
  67 When \fIcmd\fR is set to \fBDDI_INFO_DEVT2DEVINFO\fR, \fBgetinfo()\fR should
  68 return the \fBdev_info_t\fR pointer associated with the \fBdev_t\fR \fIarg\fR.
  69 The \fBdev_info_t\fR pointer should be returned in the field pointed to by
  70 \fIresultp\fR.
  71 .sp
  72 .LP
  73 When \fIcmd\fR is set to \fBDDI_INFO_DEVT2INSTANCE\fR, \fBgetinfo()\fR should
  74 return the instance number associated with the \fBdev_t\fR \fIarg\fR. The
  75 instance number should be returned in the field pointed to by \fIresultp\fR.
  76 .sp
  77 .LP
  78 Drivers which do not export \fBcb_ops\fR(9S) entry points are not required to
  79 provide a \fBgetinfo()\fR entry point, and may use \fBnodev\fR(9F) in the
  80 \fBdevo_getinfo\fR field of the \fBdev_ops\fR(9S) structure. A \fBSCSI HBA
  81 \fRdriver is an example of a driver which is not required to provide
  82 \fBcb_ops\fR(9S) entry points.
  83 .SH RETURN VALUES
  84 .sp
  85 .LP
  86 \fBgetinfo()\fR should return:
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBDDI_SUCCESS\fR\fR
  91 .ad
  92 .RS 15n
  93 on success.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBDDI_FAILURE\fR\fR
 100 .ad
 101 .RS 15n
 102 on failure.
 103 .RE
 104
 105 .SH EXAMPLES
 106 .LP
 107 \fBExample 1 \fR\fBgetinfo()\fR implementation
 108 .sp
 109 .in +2
 110 .nf
 111 /*ARGSUSED*/
 112 static int
 113 rd_getinfo(dev_info_t *dip, ddi_info_cmd_t infocmd, void *arg, \e
 114 void **resultp)
 115 {
 116        /* Note that in this simple example
 117         * the minor number is the instance
 118         * number.        */
 119
 120      devstate_t *sp;
 121      int error = DDI_FAILURE;
 122      switch (infocmd) {
 123      case DDI_INFO_DEVT2DEVINFO:
 124           if ((sp = ddi_get_soft_state(statep,
 125               getminor((dev_t) arg))) != NULL) {
 126                  *resultp = sp->devi;
 127                  error = DDI_SUCCESS;
 128           } else
 129                  *result = NULL;
 130           break;
 131
 132      case DDI_INFO_DEVT2INSTANCE:
 133           *resultp = (void *) (uintptr_t) getminor((dev_t) arg);
 134           error = DDI_SUCCESS;
 135           break;
 136      }
 137
 138      return (error);
 139 }
 140 .fi
 141 .in -2
 142
 143 .SH SEE ALSO
 144 .sp
 145 .LP
 146 \fBddi_no_info\fR(9F), \fBnodev\fR(9F), \fBcb_ops\fR(9S), \fBdev_ops\fR(9S)
 147 .sp
 148 .LP
 149 \fIWriting Device Drivers\fR
 150 .SH NOTES
 151 .sp
 152 .LP
 153 Non-\fBgld\fR(7D)-based DLPI network streams drivers are encouraged to switch
 154 to \fBgld\fR(7D). Failing this, a driver that creates DLPI style-2   minor
 155 nodes must specify CLONE_DEV for its style-2 \fBddi_create_minor_node\fR(9F)
 156 nodes and use \fBqassociate\fR(9F). A driver that supports both style-1 and
 157 style-2 minor nodes should return DDI_FAILURE for DDI_INFO_DEVT2INSTANCE and
 158 DDI_INFO_DEVT2DEVINFO \fBgetinfo()\fR calls to style-2 minor nodes. (The
 159 correct association is already established by \fBqassociate\fR(9F)). A driver
 160 that only supports style-2 minor nodes can use \fBddi_no_info\fR(9F) for its
 161 \fBgetinfo()\fR implementation. For drivers that do not follow these rules, the
 162 results of a \fBmodunload\fR(1M) of the driver or a \fBcfgadm\fR(1M) remove of
 163 hardware controlled by the driver are undefined.