path: root/usr/src/man/man1m/cfgadm_sdcard.1m

'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH CFGADM_SDCARD 1M "Feb 28, 2008"
.SH NAME
cfgadm_sdcard \- SD/MMC hardware-specific commands for cfgadm
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/cfgadm\fR  [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-o\fR \fIhardware_options\fR]
     \fB-c\fR \fIfunction\fR \fIap_id\fR[...]
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR  [\fB-f\fR] [\fB-y\fR | \fB-n\fR] [\fB-o\fR \fIhardware_options\fR]
     \fB-c\fR \fIhardware_function\fR \fIap_id\fR[...]
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR  [\fB-v\fR] [\fB-a\fR] [\fB-s\fR \fIlisting_options\fR]
     [\fB-o\fR \fIhardware_options\fR] [\fB-l\fR [\fIap_id\fR | \fIap_type\fR[...]]]
.fi

.LP
.nf
\fB/usr/sbin/cfgadm\fR  [\fB-v\fR] [\fB-o\fR \fIhardware_options\fR] \fB-h\fR [\fIap_id\fR[...]]
.fi

.SH DESCRIPTION
.sp
.LP
The Secure Digital (SD) and MultiMediaCard (MMC) hardware specific library,
\fB/usr/lib/cfgadm/sdcard.so.1\fR, provides the functionality for SD/MMC
hot-plugging through the \fBcfgadm\fR(1M) command. The \fBcfgadm\fR command
operates on attachment  points, which are locations in the system where
hardware resources can be dynamically reconfigured.  See  \fBcfgadm\fR(1M) for
information on attachment points.
.sp
.LP
Each SD/MMC slot is represented by an attachment point in the device tree. Card
devices that are connected and configured in the system are shown as attachment
point name extensions. The terms "attachment point" and "SD/MMC slot" are used
interchangeably throughout this manpage.
.sp
.LP
Attachment points are named through  ap_ids. All SD/MMC attachment points
consist of a string in the following form:
.sp
.in +2
.nf
sdcardX/[S][::dsk/cXtYd0]
.fi
.in -2

.sp
.LP
Where:
.sp
.LP
\fIX\fR is the SD/MMC controller number.
.sp
.LP
\fIS\fR is the slot number on the controller (0 to 8).
.sp
.LP
\fBdev/cXtYd0\fR identifies the inserted memory card.
.sp
.LP
\fIY\fR is a target number.
.sp
.LP
In general,  the device identifier is derived from the corresponding logical
link for the device in \fB/dev\fR. Because only one LUN (LUN 0) is supported by
the SD/MMC device, the "d" component of the device string will always have
number 0 (zero). For example, the logical \fIap_id\fR of slot 4 of SD/MMC
controller 2 would be \fBsdcard2/4\fR. If the SD/MMC media card is inserted in
this attachment point and the device is configured, the \fBap_id\fR might be
\fBsdcard2/4::dsk/c2t0d0\fR.
.sp
.LP
The  c\fIX\fRt\fIY\fRd\fI0\fR string identifying a device has one-to-one
correspondence to the device attachment point.
.sp
.LP
A simple listing of attachment points in the system includes all SD/MMC device
slots and attached devices. For example:
.sp
.in +2
.nf
#cfgadm -l
Ap_Id                    Type       Receptacle   Occupant    Condition
 sdcard0/0::dev/c2t0d0   sdcard      connected    configured     ok
 sata0/1::dev/c0t1d0     disk        connected    configured     ok
 sata0/2::dev/c0t2d0     cd-dvd      connected    configured     ok
 sata0/3                 sata-port   empty        unconfigured   ok
 usb0/1                  unknown     empty        unconfigured   ok
 usb0/2                  unknown     empty        unconfigured   ok
.fi
.in -2

.sp
.LP
See \fBcfgadm\fR(1M) for more information regarding listing of attachment
points.
.sp
.LP
The receptacle state for an attachment point at the  SD/MMC slot has the
following  meanings:
.sp
.ne 2
.na
\fBempty\fR
.ad
.sp .6
.RS 4n
The SD/MMC slot is powered-on and enabled.  No device presence was detected for
this slot.
.RE

.sp
.ne 2
.na
\fBdisconnected\fR
.ad
.sp .6
.RS 4n
The SD/MMC slot is not  enabled, or the SD/MMC device presence was detected but
no communication with the device was established,  or the slot has failed.
.RE

.sp
.ne 2
.na
\fBconnected\fR
.ad
.sp .6
.RS 4n
The SD/MMC device is detected in the slot and device communication is
established.
.RE

.sp
.LP
The occupant (device inserted in the SD/MMC slot) state has the following
meanings:
.sp
.ne 2
.na
\fBconfigured\fR
.ad
.sp .6
.RS 4n
The attached SD/MMC device is  configured and ready to use by the operating
system.
.RE

.sp
.ne 2
.na
\fBunconfigured\fR
.ad
.sp .6
.RS 4n
No device is attached, or the  SD/MMC device inserted in the SD/MMC slot is not
yet configured.                      To configure, run  the command \fBcfgadm
-c configure ap_id\fR.
.RE

.sp
.LP
The attachment point (SD/MMC slot) condition has the following meanings:
.sp
.ne 2
.na
\fBok\fR
.ad
.sp .6
.RS 4n
The SD/MMC slot is powered-on, enabled and  ready for use.
.RE

.sp
.ne 2
.na
\fBfailed\fR
.ad
.sp .6
.RS 4n
The SD/MMC slot failed. It may be disabled and/or powered-off by the system. It
is unusable and its                 condition is unknown. The failure  may be
due to the device inserted in the slot.
.RE

.sp
.ne 2
.na
\fBunknown\fR
.ad
.sp .6
.RS 4n
The SD/MMC slot is disabled and  its condition  is unknown.
.RE

.SH OPTIONS
.sp
.LP
The \fBcfgadm\fR command defines several types of operations besides  listing
(\fB-l\fR). These operations include invoking configuration state changes
(\fB-c\fR), invoking  hardware specific functions (\fB-x\fR),  and obtaining
configuration administration help messages (\fB-h\fR).
.sp
.LP
\fB-c\fR: For SD/MMC slot attachment points, the following configuration state
change operations are supported:
.sp
.ne 2
.na
\fBconnect\fR
.ad
.sp .6
.RS 4n
Enable (activate) the SD/MMC slot and establish  the communication with an
attached device. This operation implies powering-on the slot if necessary.
.RE

.sp
.ne 2
.na
\fBdisconnect\fR
.ad
.sp .6
.RS 4n
Unconfigure the inserted  device if it is not already  unconfigured and disable
(deactivate) the SD/MMC slot. A subsequent "connect" command enables SD/MMC
slot operation but does not bring a device to the "configured" state.
.RE

.sp
.LP
The following state change operations are supported for an SD/MMC card inserted
in to the SD/MMC slot:
.sp
.ne 2
.na
\fBconfigure\fR
.ad
.sp .6
.RS 4n
Configure new device for use by the operating system  if  it  is not already
configured.  This command  also  implies connect operation, if necessary.
.RE

.sp
.ne 2
.na
\fBunconfigure\fR
.ad
.sp .6
.RS 4n
Unconfigure the device inserted in the SD/MMC slot if it is not already
unconfigured.
.RE

.sp
.LP
\fB-f \fR: Not supported.
.sp
.LP
\fB-h\fR \fBap_id\fR: SD/MMC specific help can be obtained  by using the  help
option with any SD/MMC attachment point.
.sp
.LP
\fB-l\fR [-v]: The -l option works as  described  in  \fBcfgadm\fR(1M).  When
paired  with the -v option, the "Information" field contains the following
SD/MMC-specific information:
.br
.in +2
Mod: product model string
.in -2
.br
.in +2
Rev: product revision number (major.minor)
.in -2
.br
.in +2
Date: month and year of manufacture
.in -2
.br
.in +2
SN: product serial number (hexadecimal)
.in -2
.sp
.LP
\fB-o\fR hardware_options \(em No hardware specific options are currently
defined.
.sp
.LP
\fB-s\fR listing_options: Attachment points of class SD/MMC can be listed  by
using the select suboption. See \fBcfgadm\fR(1M).
.sp
.LP
\fB-t\fR \fBap_id\fR: Self-test functionality. Not supported by SD/MMC slots.
.sp
.LP
\fB-x\fR \fBhardware_function\fR: Perform hardware specific function.
sdcard_reset_slot \fBap_id\fRindicates reset of the SD/MMC slot specified by
\fBap_id\fR.  If an SD/MMC device is inserted in the slot, it is also reset.
.sp
.LP
\fB-v\fR: Execute in verbose mode.
.SH EXAMPLES
.sp
.LP
Example 1 - Configuring an SD/MMC card:
.sp
.LP
The following command configures a card attached to SD/MMC controller 0, slot
0. It should be issued only when there is a device inserted in the SD/MMC slot.
.sp
.in +2
.nf
       # cfgadm -c configure sdcard0/0
.fi
.in -2

.sp
.LP
Example 2 - Unconfiguring an SD/MMC card:
.sp
.LP
The following command unconfigures a card inserted in SD/MMC controller 0, slot
3:
.sp
.in +2
.nf
       # cfgadm -c unconfigure sdcard0/3
.fi
.in -2

.sp
.LP
Example 3 \(em Encountering a mounted file system while unconfiguring a disk:
.sp
.LP
The following command illustrates encountering a mounted file system while
unconfiguring a disk:
.sp
.in +2
.nf
       # cfgadm -c unconfigure sdcard1/5::dsk/c01t35d0


.fi
.in -2

.sp
.LP
The system responds with the following:
.sp
.in +2
.nf
 cfgadm: Component system is busy, try again: failed to offline:
       /devices/pci@0,0/pci8086,244e@1e/pci1095,3124@1/sd@5,0
           Resource              Information
       ------------------  --------------------------
       /dev/dsk/c1t5d0s0   mounted filesystem "/mnt"
.fi
.in -2

.SH FILES
.sp
.ne 2
.na
\fB/usr/lib/cfgadm/sdcard.so.1\fR
.ad
.sp .6
.RS 4n
Hardware specific  library  for generic SD/MMC hot plugging.
.RE

.SH SEE ALSO
.sp
.LP
\fBcfgadm\fR(1M), \fBconfig_admin\fR(3CFGADM), \fBlibcfgadm\fR(3LIB),
\fBattributes\fR(5), \fBsda\fR(7D), \fBsdcard\fR(7D), \fBsdhost\fR(7D)
.SH NOTES
.sp
.LP
Under normal operation, SD/MMC media cards are automatically configured when a
card is inserted. Most administrators do not find it necessary to use this
command under normal use.
.sp
.LP
Removing an SD/MMC card without first unconfiguring it may result in data loss
if the device is being written to when it's being removed. Devices that are
mounted read-only can be safely removed at any time.
.sp
.LP
Devices that have filesystems other than \fBpcfs\fR(7FS) on them should always
be explicitly unconfigured before removal.