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

   1 '\" te
   2 .\"  Copyright (c) 2006, 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 DDI_PEEK 9F "Jan 16, 2006"
   7 .SH NAME
   8 ddi_peek, ddi_peek8, ddi_peek16, ddi_peek32, ddi_peek64, ddi_peekc, ddi_peeks,
   9 ddi_peekl, ddi_peekd \- read a value from a location
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ddi.h>
  14 #include <sys/sunddi.h>
  15
  16
  17
  18 \fBint\fR \fBddi_peek8\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint8_t\fR \fI*addr\fR, \fBint8_t\fR \fI*valuep\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBddi_peek16\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint16_t\fR \fI*addr\fR, \fBint16_t\fR \fI*valuep\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBint\fR \fBddi_peek32\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint32_t\fR \fI*addr\fR, \fBint32_t\fR \fI*valuep\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBddi_peek64\fR(\fBdev_info_t\fR \fI*dip\fR, \fBint64_t\fR \fI*addr\fR, \fBint64_t\fR \fI*valuep\fR);
  34 .fi
  35
  36 .SH INTERFACE LEVEL
  37 .sp
  38 .LP
  39 Solaris DDI specific (Solaris DDI). The \fBddi_peekc()\fR, \fBddi_peeks()\fR,
  40 \fBddi_peekl()\fR, and \fBddi_peekd()\fR functions are obsolete. Use,
  41 respectively, \fBddi_peek8()\fR, \fBddi_peek16()\fR, \fBddi_peek32()\fR, and
  42 \fBddi_peek64()\fR, instead.
  43 .SH PARAMETERS
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIdip\fR\fR
  48 .ad
  49 .RS 10n
  50 A pointer to the device's \fBdev_info\fR structure.
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fIaddr\fR\fR
  57 .ad
  58 .RS 10n
  59 Virtual address of the location to be examined.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fIvaluep\fR\fR
  66 .ad
  67 .RS 10n
  68 Pointer to a location to hold the result. If a null pointer is specified, then
  69 the value read from the location will simply be discarded.
  70 .RE
  71
  72 .SH DESCRIPTION
  73 .sp
  74 .LP
  75 These routines cautiously attempt to read a value from a specified virtual
  76 address, and return the value to the caller, using the parent nexus driver to
  77 assist in the process where necessary.
  78 .sp
  79 .LP
  80 If the address is not valid, or the value cannot be read without an error
  81 occurring, an error code is returned.
  82 .sp
  83 .LP
  84 The routines are most useful when first trying to establish the presence of a
  85 device on the system in a driver's \fBprobe\fR(9E) or \fBattach\fR(9E)
  86 routines.
  87 .SH RETURN VALUES
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fBDDI_SUCCESS\fR\fR
  92 .ad
  93 .RS 15n
  94 The value at the given virtual address was successfully read, and if
  95 \fIvaluep\fR is non-null, \fI*valuep\fR will have been updated.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBDDI_FAILURE\fR\fR
 102 .ad
 103 .RS 15n
 104 An error occurred while trying to read the location. \fI*valuep\fR is
 105 unchanged.
 106 .RE
 107
 108 .SH CONTEXT
 109 .sp
 110 .LP
 111 These functions can be called from user, interrupt, or kernel context.
 112 .SH EXAMPLES
 113 .LP
 114 \fBExample 1 \fRChecking to see that the status register of a device is mapped
 115 into the kernel address space:
 116 .sp
 117 .in +2
 118 .nf
 119 if (ddi_peek8(dip, csr, (int8_t *)0) != DDI_SUCCESS) {
 120         cmn_err(CE_WARN, "Status register not mapped");
 121         return (DDI_FAILURE);
 122 }
 123 .fi
 124 .in -2
 125
 126 .LP
 127 \fBExample 2 \fRReading and logging the device type of a particular device:
 128 .sp
 129 .in +2
 130 .nf
 131 int
 132 xx_attach(dev_info_t *dip, ddi_attach_cmd_t cmd)
 133 {
 134        \&.\|.\|.
 135       /* map device registers */
 136        \&.\|.\|.
 137
 138       if (ddi_peek32(dip, id_addr, &id_value) != DDI_SUCCESS) {
 139               cmn_err(CE_WARN, "%s%d: cannot read device identifier",
 140                 ddi_get_name(dip), ddi_get_instance(dip));
 141               goto failure;
 142       } else
 143               cmn_err(CE_CONT, "!%s%d: device type 0x%x\en",
 144                 ddi_get_name(dip), ddi_get_instance(dip), id_value);
 145               \&.\|.\|.
 146               \&.\|.\|.
 147
 148       ddi_report_dev(dip);
 149       return (DDI_SUCCESS);
 150
 151 failure:
 152       /* free any resources allocated */
 153       \&.\|.\|.
 154       return (DDI_FAILURE);
 155 }
 156 .fi
 157 .in -2
 158
 159 .SH SEE ALSO
 160 .sp
 161 .LP
 162 \fBattach\fR(9E), \fBprobe\fR(9E), \fBddi_poke\fR(9F)
 163 .sp
 164 .LP
 165 \fIWriting Device Drivers\fR
 166 .SH NOTES
 167 .sp
 168 .LP
 169 The functions described in this manual page previously used symbolic names
 170 which specified their data access size; the function names have been changed so
 171 they now specify a fixed-width data size. See the following table for the new
 172 name equivalents:
 173 .sp
 174
 175 .sp
 176 .TS
 177 box;
 178 l l
 179 l l .
 180 \fBPrevious Name\fR     \fBNew Name\fR
 181 \fBddi_peekc\fR \fBddi_peek8\fR
 182 \fBddi_peeks\fR \fBddi_peek16\fR
 183 \fBddi_peekl\fR \fBddi_peek32\fR
 184 \fBddi_peekd\fR \fBddi_peek64\fR
 185 .TE
 186