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

   1 '\" te
   2 .\" Copyright (c) 2004, 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_CREATE_MINOR_NODE 9F "Dec 14, 2004"
   7 .SH NAME
   8 ddi_create_minor_node \- Create a minor node for this device
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/stat.h>
  13 #include <sys/sunddi.h>
  14
  15
  16
  17 \fBint\fR \fBddi_create_minor_node\fR(\fBdev_info_t *\fR\fIdip\fR, \fBchar *\fR\fIname\fR, \fBint\fR \fIspec_type\fR,
  18      \fBminor_t\fR \fIminor_num\fR, \fBchar *\fR\fInode_type\fR, \fBint\fR \fIflag\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Solaris DDI specific (Solaris DDI).
  25 .SH PARAMETERS
  26 .sp
  27 .ne 2
  28 .na
  29 \fB\fIdip\fR \fR
  30 .ad
  31 .RS 14n
  32 A pointer to the device's \fBdev_info\fR structure.
  33 .RE
  34
  35 .sp
  36 .ne 2
  37 .na
  38 \fB\fIname\fR \fR
  39 .ad
  40 .RS 14n
  41 The name of this particular minor device.
  42 .RE
  43
  44 .sp
  45 .ne 2
  46 .na
  47 \fB\fIspec_type\fR \fR
  48 .ad
  49 .RS 14n
  50 \fBS_IFCHR\fR or \fBS_IFBLK\fR for character or block minor devices
  51 respectively.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIminor_num\fR \fR
  58 .ad
  59 .RS 14n
  60 The minor number for this particular minor device.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fInode_type\fR \fR
  67 .ad
  68 .RS 14n
  69 Any string literal that uniquely identifies the type of  node. The following
  70 predefined node types are provided with this release:
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fBDDI_NT_SERIAL\fR \fR
  75 .ad
  76 .RS 24n
  77 For serial ports
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBDDI_NT_SERIAL_MB\fR \fR
  84 .ad
  85 .RS 24n
  86 For on board serial ports
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fBDDI_NT_SERIAL_DO\fR \fR
  93 .ad
  94 .RS 24n
  95 For dial out ports
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBDDI_NT_SERIAL_MB_DO\fR \fR
 102 .ad
 103 .RS 24n
 104 For on board dial out ports
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBDDI_NT_BLOCK\fR \fR
 111 .ad
 112 .RS 24n
 113 For hard disks
 114 .RE
 115
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBDDI_NT_BLOCK_CHAN\fR \fR
 120 .ad
 121 .RS 24n
 122 For hard disks with channel or target numbers
 123 .RE
 124
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fBDDI_NT_CD\fR \fR
 129 .ad
 130 .RS 24n
 131 For CDROM drives
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBDDI_NT_CD_CHAN\fR \fR
 138 .ad
 139 .RS 24n
 140 For CDROM drives with channel or target numbers
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fBDDI_NT_FD\fR \fR
 147 .ad
 148 .RS 24n
 149 For floppy disks
 150 .RE
 151
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fBDDI_NT_TAPE\fR \fR
 156 .ad
 157 .RS 24n
 158 For tape drives
 159 .RE
 160
 161 .sp
 162 .ne 2
 163 .na
 164 \fB\fBDDI_NT_NET\fR \fR
 165 .ad
 166 .RS 24n
 167 For DLPI style 1 or style 2 network devices
 168 .RE
 169
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fBDDI_NT_DISPLAY\fR \fR
 174 .ad
 175 .RS 24n
 176 For display devices
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBDDI_PSEUDO\fR \fR
 183 .ad
 184 .RS 24n
 185 For pseudo devices
 186 .RE
 187
 188 .RE
 189
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fIflag\fR \fR
 194 .ad
 195 .RS 14n
 196 If the device is a clone device then this flag is set to \fBCLONE_DEV\fR else
 197 it is set to \fB0\fR.
 198 .RE
 199
 200 .SH DESCRIPTION
 201 .sp
 202 .LP
 203 \fBddi_create_minor_node()\fR provides the necessary information to enable the
 204 system to create the \fB/dev\fR and \fB/devices\fR hierarchies. The \fIname\fR
 205 is used to create the minor name of the block or character special file under
 206 the \fB/devices\fR hierarchy. At-sign (\fB@\fR), slash (\fB/\fR), and space are
 207 not allowed. The \fIspec_type\fR specifies whether this is a block or character
 208 device. The \fIminor_num\fR is the minor number for the device. The
 209 \fInode_type\fR is used to create the names in the \fB/dev\fR hierarchy that
 210 refers to the names in the \fB/devices\fR hierarchy. See \fBdisks\fR(1M),
 211 \fBports\fR(1M), \fBtapes\fR(1M), \fBdevlinks\fR(1M). Finally \fIflag\fR
 212 determines if this is a clone device or not, and what device class the node
 213 belongs to.
 214 .SH RETURN VALUES
 215 .sp
 216 .LP
 217 \fBddi_create_minor_node()\fR returns:
 218 .sp
 219 .ne 2
 220 .na
 221 \fB\fBDDI_SUCCESS\fR \fR
 222 .ad
 223 .RS 16n
 224 Was able to allocate memory, create the minor data structure, and place it into
 225 the linked list of minor devices for this driver.
 226 .RE
 227
 228 .sp
 229 .ne 2
 230 .na
 231 \fB\fBDDI_FAILURE\fR \fR
 232 .ad
 233 .RS 16n
 234 Minor node creation failed.
 235 .RE
 236
 237 .SH CONTEXT
 238 .sp
 239 .LP
 240 The \fBddi_create_minor_node()\fR function can be called from user context. It
 241 is typically called from \fBattach\fR(9E) or \fBioctl\fR(9E).
 242 .SH EXAMPLES
 243 .LP
 244 \fBExample 1 \fRCreate Data Structure Describing Minor Device with Minor Number
 245 of 0
 246 .sp
 247 .LP
 248 The following example creates a data structure describing a minor device called
 249 \fIfoo\fR which has a minor number of 0. It is of type \fBDDI_NT_BLOCK\fR (a
 250 block device) and it is not a clone device.
 251
 252 .sp
 253 .in +2
 254 .nf
 255 ddi_create_minor_node(dip, "foo", S_IFBLK, 0, DDI_NT_BLOCK, 0);
 256 .fi
 257 .in -2
 258
 259 .SH SEE ALSO
 260 .sp
 261 .LP
 262 \fBadd_drv\fR(1M), \fBdevlinks\fR(1M), \fBdisks\fR(1M), \fBdrvconfig\fR(1M),
 263 \fBports\fR(1M), \fBtapes\fR(1M), \fBattach\fR(9E),
 264 \fBddi_remove_minor_node\fR(9F)
 265 .sp
 266 .LP
 267 \fIWriting Device Drivers\fR
 268 .SH NOTES
 269 .sp
 270 .LP
 271 If the driver is for a network device (\fInode_type\fR \fBDDI_NT_NET\fR), note
 272 that the driver name will undergo the driver name constraints identified in the
 273 NOTES section of \fBdlpi\fR(7P). Additionally, the minor name must match the
 274 driver name for a DLPI style 2 provider. If the driver is a DLPI style 1
 275 provider, the minor name must also match the driver name with the exception
 276 that the ppa is appended to the minor name.
 277 .sp
 278 .LP
 279 Non-\fBgld\fR(7D)-based DLPI network streams drivers are encouraged to switch
 280 to \fBgld\fR(7D). Failing this, a driver that creates DLPI style-2   minor
 281 nodes must specify CLONE_DEV for its style-2 \fBddi_create_minor_node()\fR
 282 nodes and use \fBqassociate\fR(9F). A driver that supports both style-1 and
 283 style-2 minor nodes should return DDI_FAILURE for DDI_INFO_DEVT2INSTANCE and
 284 DDI_INFO_DEVT2DEVINFO \fBgetinfo\fR(9E) calls to style-2 minor nodes. (The
 285 correct association is already established by \fBqassociate\fR(9F)). A driver
 286 that only supports style-2 minor nodes can use \fBddi_no_info\fR(9F) for its
 287 \fBgetinfo\fR(9E) implementation. For drivers that do not follow these rules,
 288 the results of a \fBmodunload\fR(1M) of the driver or a \fBcfgadm\fR(1M) remove
 289 of hardware controlled by the driver are undefined.
 290 .SH WARNING
 291 .sp
 292 .LP
 293 Drivers must remove references to GLOBAL_DEV, NODEBOUND_DEV, NODESPECIFIC_DEV,
 294 and ENUMERATED_DEV to compile under Solaris 10 and later versions.