mcicap(4) Kernel Interfaces Manual mcicap(4)
NAME
mcicap - media changer capability database
SYNOPSIS
/etc/mcicap
DESCRIPTION
The mcicap file is a database consisting of media changer descriptions. Each entry within the mcicap file describes a specific media
changer, or a model of media changer.
The entries within the mcicap file are used by certain functions within the media changer driver software. For example, entries are neces-
sary for all media changers that you plan on accessing with the mcutil command.
An mcicap file entry has the following form:
name|alt_name|another_alt_name:capability:capability: ...
This form is described as follows: The vertical bars (|) are part of the entry. Fields are separated by colons (:). The first field lists
all names that are used for the particular media changer, separated by vertical bars (|). The first name (name) is the most common abbre-
viation for the media changer. The first and second names should contain no blanks. The third name (another_alt_name) is optional and may
contain blanks for readability; it should be a long name, fully identifying the media changer. Following the media changer's names are its
capabilities. Each capability is separated by a colon (:). Capabilities may be in any order, and are described in the following section.
An entry may continue onto multiple lines by inserting a backslash () as the last character of the line that you wish to continue.
Capabilities
The capabilities that you list in an mcicap file entry each consist of two-letter codes, possibly followed by further information. The
various capabilities fall under three categories: The capability code, if present in the entry, means that the media changer has a particu-
lar feature. For example, the HP100 media changer has auto-eject. Therefore, the entry for a HP100 media changer includes the ae code.
The capability code must be followed by a pound sign (#) and a number. For example, the following ns capability code setting indicates
that there are 144 slot elements:
ns#144 The capability code must be followed by an equal sign and a string. The string must be enclosed within double quotes if it
contains any whitespace; otherwise, double quotes are optional. For example, the following dt capability code setting indicates
that the data transfer unit is a disk type:
dt=disk
Capability Codes
A listing of all capability codes appears in this section. For clarity, the following conventions are used: Boolean capability codes are
shown exactly as they would appear in an entry (as a two-letter code) Numeric capability codes are followed by #n String capability codes
are followed by =string
The following is a list of all capability codes: Auto-eject. Indicates that the media changer does not need to send an explicit eject
sequence to a drive when the drive is the source of a move or exchange operation. Bar code reader. Indicates that the media changer has
the ability to return the bar code information printed on the medium. The information is returned in the volume tag field (the last field)
in the output of the element status function. The element status function is the -e option to the mcutil command. Device names. Contains
a list (separated by commas) of the device names for the accessible drives. If the first character of a device name is a slash (/), then
the name is a full path to the device. If the first character of a name is not a slash, then the /dev directory path is assumed as a pre-
fix. For example, the following are equivalent device name capability code settings:
dn="mc0,mc5"
dn="/dev/changer/mc0, /dev/changer/mc5" Data transfer unit type. Contains the disk or tape string. This information is needed for
the eject command if the device requires an explicit eject operation. It is useful to provide this information regardless of the
status of the auto-eject capability because the mcutil command can be used to provide configuration information. Including the dt
capability field could provide the mcutil command, and therefore the user, with more information. Exchange medium. Indicates that
the media changer supports the exchange medium capability as stated in the SCSI-II standards documentation. Interface arguments.
Contains interface-specific information. Media changers using the scsi2 interface type do not use this field. The uagent interface
requires the bus target and logical unit number (LUN) identifiers of the media changer. For example, the following interface argu-
ment setting is for a device on bus 0, target 1, and LUN 1:
ia="0 1 1" Initialize element status. Indicates that the media changer supports an initialize element status capability as stated
in the SCSI-II standards documentation. Interface type. Specifies the interface type to connect to the media changer. Currently,
the scsi2 and uagent interface types are supported. The scsi2 interface type uses the SCSI CAM Media Changer interface (see mc(7))
and therefore requires the SCSI CAM Media Changer Driver to be built into the running kernel. The uagent interface requires the CAM
systems uagent driver, which is contained in any kernel running the SCSI CAM system. The /dev/cam pseudo device is required and is
used by the uagent driver to communicate with the media changer. Log select/sense. Indicates that the media changer supports a
logging interface capability as stated in the SCSI-II standards documentation. Media changer device file. Names the device file
that is used for controlling the media changer. For the scsi2 interface type it is the device file that connects to the SCSI CAM
Media Changer Driver. For the uagent interface, the /dev/cam file is almost always used.
MD=range
MP=range
MS=range
Physical maps. Maps the physical addresses of the slot (MS), drive (MD), port (MP), and transport (MT) elements to their logical
addresses. Most SCSI-II compliant media changers provide element address information so these entries are not required. The use of physi-
cal map codes within an mcicap file entry is indicated when your jukebox is not SCSI-II compliant, or when you wish to override the jukebox
addressing. By overriding the jukebox addressing you could, for example, prevent a particular drive from being used. If you wish to pro-
vide physical mapping information, see your jukebox hardware manual for the physical addresses of the elements.
The range value can be one of the following: A range from a lower number to a higher number, indicated by using a minus sign (-).
For example, the following MS code setting indicates that the physical address for the slot elements are 116, 117, 118, and 119:
MS=116-119 A list of numbers or ranges separated by commas. For example, the following MD code setting indicates that the physical
addresses for the drive elements are 111, 112, 113, 114, 115, 311, 210, 211, and 212:
MD=111-115,311,210-212
The media changer driver software maps logical addresses to physical addresses. For each element type (slot, drive, port, or transport)
the logical addresses are mapped to the physical addresses consecutively starting at logical address zero.
The following are examples of address mappings: Maps the physical slot addresses 116, 117, 118, and 119 to the logical slot addresses 0, 1,
2, and 3. Maps the physical drive addresses 111, 112, 113, 114, 115, 311, 210, 211, and 212 to the logical drive addresses 0, 1, 2, 3, 4,
5, 6, 7, and 8.
Note that for the above examples to map exactly as depicted, you should indicate in your mcicap file entry the precise number of elements.
In other words, the two previous examples should include the following capability code settings in the mcicap file entries:
ns#4
nd#9
Defaults for Mapping
If the quantity of a type of element or its physical addresses are not provided within an mcicap file entry, then the jukebox is queried by
the driver software. If the quantity of a type of element becomes known to the driver software but not all (or none) of the physical
addresses become known, then the "missing" physical addresses are assumed to be the same as the corresponding logical addresses. Mode
select/sense. Indicates that the media changer supports a mode select/sense capability as stated in the SCSI-II standards documentation.
Number of slots. Specifies the number of slot type elements. The media changer, when queried by the media changer driver, may provide the
number of slot type elements that it supports. The ns capability code setting overrides the number provided by the media changer. Number
of drives. Specifies the number of drive type elements. The media changer, when queried by the media changer driver, may provide the num-
ber of drive type elements that it supports. The nd capability code setting overrides the number provided by the media changer. Number of
import/export ports. Specifies the number of port type elements. The media changer, when queried by the media changer driver, may provide
the number of port type elements that it supports. The np capability code setting overrides the number provided by the media changer.
Number of transports. Specifies the number of transport type elements. The media changer, when queried by the media changer driver, may
provide the number of transport type elements that it supports. The nt capability code setting overrides the number provided by the media
changer. Prevent/allow functionality. Indicates that the media changer supports a prevent/allow capability as stated in the SCSI-II stan-
dards documentation. Position-to-element. Indicates that the media changer supports a position-to-element capability as stated in the
SCSI-II standards documentation. Read diagnostics. Indicates that the media changer supports a read diagnostics capability as stated in
the SCSI-II standards documentation. Read element status. Indicates that the media changer supports a read element status capability as
stated in the SCSI-II standards documentation. Release/reserve element. Indicates that the media changer supports a release/reserve ele-
ment capability as stated in the SCSI-II standards documentation. Type compatible entry field. Equates the string value to the first name
of a previous entry in the mcicap file. The entry in which the tc field exists is compatible (has the same capabilities) as a previously
defined entry - the entry indicated by the string value. This allows capabilities which are associated with the media changer model to be
defined once, while the more specific media changer information - such as that regarding connectivity and device naming - is defined with
each individual media changer's logical name. For a sample of how to use the tc field see the EXAMPLE section near the end of these refer-
ence pages. Two-sided medium. Indicates that the jukebox media is double sided; also indicates that the media changer transport mechanism
can perform an invert operation. Volume tag. Indicates that the jukebox returns volume tag information (when valid) as part of the output
for the element status function. The element status function is the -e option to the mcutil command.
Preparing Descriptions
The amount of information that must be provided in the mcicap file entry is dependent on the particular jukebox. It is possible to have a
very short entry because the media changer can provide certain information. For example, the HP100 is typical of most SCSI-II compliant
media changers because the number and address of each element can be provided by the media changer. Therefore, that information is not
required in the mcicap file entry. Some jukeboxes require an explicit command to eject the media from the drive before a move from a drive
can be accomplished. Therefore, for some jukeboxes, you must provide certain information within the mcicap file entry - information such
as device names - that allows for particular media changer operations. Such an operation would be opening a drive and giving the eject
command.
If an mcicap file entry provides information that the media changer also provides, the mcicap file entry takes precedence. For example, if
the media changer states it has X number of slots, the mcicap file entry for that media changer changes that number by providing a ns capa-
bility code setting. In this way you can, for example, make the HP100 media changer look and act like it has fewer slots available.
The most effective way to prepare a media changer description is by imitating the description of a similar media changer in the mcicap
file; then build up a description gradually. To check the validity of a particular media changer description, use the mcutil command. To
test a new media changer description, set the MCICAP environment variable to the path name of the file containing the description. The
mcutil command reads that file rather than the /etc/mcicap file. The MCICAP environment variable can also be set to the mcicap file entry
(to avoid having the mcutil utility read a file). See the mcutil reference page for more information.
RESTRICTIONS
A very unusual media changer may expose deficiencies in the ability of the mcicap file to describe it. Also, an unusual media changer may
expose deficiencies in the mcutil command.
EXAMPLES
The following entry, which describes the TL800, is typical of an entry in the mcicap file:
TL800|backup_tape_changer|remote_backup_TC:
:ae:re:is:ls:pe:pa:rs:
:dt=tape:
:mc=/dev/mc9:it=scsi2:dn="/dev/changer/mc9":
FILES
File containing media changer descriptions.
RELATED INFORMATION
Commands: mcutil(1)
Files: mc(7) delim off
mcicap(4)