scsi_ctl(7)scsi_ctl(7)NAMEscsi_ctl - SCSI pass-through driver (esctl/sctl)
DESCRIPTION
SCSI devices are controlled by a device-specific driver, when one
exists. Device-specific drivers, such as those for SCSI direct access
(disk) and sequential access (tape) devices, coordinate device and
driver states to accomplish correct logical device behavior. The SCSI
pass-through driver enables use of SCSI devices and commands not nor‐
mally supported by these device-specific drivers.
is the SCSI pass-through driver and works with persistent device files
(see intro(7)). is the SCSI pass-through driver already used on HP-UX
releases prior to HP-UX 11i v3. It is maintained here for backward
compatibility, and works with legacy device files. In this document
refers to both and
Once the device is opened through driver, ioctl calls can be used to
change SCSI communication parameters or to attempt SCSI commands and
other SCSI operations. Since the pass-through driver does not attempt
to logically understand the target device, and calls are not supported.
Except where noted, the ioctls described here are available through all
SCSI device drivers (including device-specific drivers). All fields in
the data structures associated with these ioctls must be zero-filled.
The following ioctls which are specific to parallel SCSI, are depre‐
cated for issuance on LUN device special files (DSF). They are not
supported on persistent device special files. They continue to be sup‐
ported on legacy device special files for backward compatibility. How‐
ever, HP now recommends to issue these ioctls (or equivalent ioctls
introduced with HP-UX 11i v3) directly on the parallel SCSI HBA device
special file (DSF).
The
fol‐
low‐
ing
par‐
al‐
lel
SCSI
spe‐
cific
ioctls
intro‐
duced
with
HP-
UX
11i
v3
should
be
issued
directly
on
the
par‐
al‐
lel
SCSI
HBA
DSF.
These
ioctls
replace
some
exist‐
ing
ioctls,
which
can
no
longer
be
issued
on
LUN
per‐
sis‐
tent
device
files
start‐
ing
with
HP-
UX
11i
v3:
replaces
replaccs
replaces
replaces
Legacy
device
files
are
dep‐
re‐
cated
with
HP-
UX
release
11i
v3.
They
are
main‐
tained
for
back‐
ward
com‐
pat‐
i‐
bil‐
ity,
and
may
be
obso‐
lete
in
a
future
release
(see
intro(7)
for
details
about
legacy
device
files
and
per‐
sis‐
tent
device
files).
It
is
rec‐
om‐
mended
to
use
per‐
sis‐
tent
device
files
for
new
appli‐
ca‐
tions.
Most
of
the
ioctls
described
here
can
be
issued
either
on
per‐
sis‐
tent
device
files
or
legacy
device
files.
The
behav‐
ior
of
some
ioctls
may
dif‐
fer
depend‐
ing
on
whether
they
are
issued
on
per‐
sis‐
tent
or
legacy
device
files,
and
whether
multi-
pathing
is
enabled
on
legacy
device
files.
Typ‐
i‐
cally
ioctls
issu‐
ing
SCSI
com‐
mands
to
a
device
may
use
any
avail‐
able
LUN
path
to
the
device
to
send
the
com‐
mands.
How‐
ever,
when
multi-
pathing
is
dis‐
abled
on
legacy
device
files
(see
the
attribute
in
scsimgr(1M)),
the
ioctl
only
attempts
to
use
the
LUN
path
cor‐
re‐
spond‐
ing
to
the
legacy
device
file.
If
this
LUN
path
is
not
avail‐
able,
the
ioctl
will
fail
even
if
there
are
other
LUN
paths
avail‐
able.
This
behav‐
ior
cor‐
re‐
sponds
to
the
legacy
behav‐
ior.
Device
Spe‐
cial
File
Minor
Num‐
ber
The
pass-
through
driver
is
the
pre‐
ferred
method
to
per‐
form
the
ioctls
and
ioctls,
rather
than
going
through
a
device-
spe‐
cific
driver
(such
as
To
do
this,
you
must
cre‐
ate
the
device
spe‐
cial
file
for
the
pass-
through
driver.
mksf(1M)
is
the
rec‐
om‐
mended
method
to
cre‐
ate
a
pass-
through
device
file
for
To
cre‐
ate
a
device
file
for
the
legacy
pass-
through
driver
use
mknod(1M),
sub‐
sti‐
tut‐
ing
the
val‐
ues
in
the
minor
num‐
ber
as
noted:
where
com‐
po‐
nent
parts
of
the
minor
num‐
ber
are
con‐
structed
as
fol‐
lows:
ii Two
hexa‐
dec‐
i‐
mal
dig‐
its,
iden‐
ti‐
fy‐
ing
the
con‐
trol‐
ling
inter‐
face
card
by
its
"Instance"
num‐
ber.
The
Instance
value
is
dis‐
played
in
ioscan(1M)
out‐
put,
under
col‐
umn
for
the
"Inter‐
face"
hard‐
ware
type.
t One
hexa‐
dec‐
i‐
mal
digit
iden‐
ti‐
fy‐
ing
the
drive
(tar‐
get)
address.
l One
hexa‐
dec‐
i‐
mal
digit
iden‐
ti‐
fy‐
ing
the
log‐
i‐
cal
unit
num‐
ber
(LUN)
within
the
device.
0 Hexa‐
dec‐
i‐
mal
digit
zero,
for
the
reserved
por‐
tion
of
the
minor
of
the
minor
num‐
ber.
o Optional
val‐
ues
as
fol‐
lows:
0 To
per‐
form
Inquiry
on
open
to
to
ensure
the
device
exists
(rec‐
om‐
mended);
or
2 To
inhibit
Inquiry
on
open.
Start‐
ing
with
HP-
UX
11i
v3,
option
2
is
dep‐
re‐
cated.
It
is
main‐
tained
for
binary
com‐
pat‐
i‐
bil‐
ity
with
exist‐
ing
appli‐
ca‐
tions
that
already
set
it.
An
Inquiry
com‐
mand
will
actu‐
ally
be
sent
dur‐
ing
an
open,
regard‐
less
of
whether
or
not
this
option
is
set.
SCSI
Com‐
mu‐
ni‐
ca‐
tion
Param‐
e‐
ters
HP-
UX
sup‐
ports
the
SCSI
device
pro‐
to‐
col
on
par‐
al‐
lel
SCSI
inter‐
faces,
Fibre
Chan‐
nel
inter‐
faces,
and
Serial
Attached
SCSI
inter‐
faces.
The
SCSI
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
described
here
might
only
apply
to
cer‐
tain
SCSI
inter‐
faces
and
are
noted
as
such
in
the
descrip‐
tions.
SCSI
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
con‐
trol
fea‐
tures
related
to
com‐
mu‐
ni‐
ca‐
tion
for
three
dif‐
fer‐
ent
scope
lev‐
els:
bus
(link),
tar‐
get,
and
log‐
i‐
cal
unit
num‐
ber
(LUN).
Bus
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
apply
to
all
tar‐
gets
con‐
nected
to
a
spe‐
cific
bus.
Tar‐
get
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
apply
to
all
LUNs
asso‐
ci‐
ated
with
a
spe‐
cific
tar‐
get.
LUN
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
apply
to
a
spe‐
cific
LUN.
SCSI
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
apply
to
all
device
driv‐
ers
(both
device-
spe‐
cific
and
At
power-
up
and
after
being
reset,
all
par‐
al‐
lel
SCSI
devices
and
hosts
com‐
mu‐
ni‐
cate
using
asyn‐
chro‐
nous
data
trans‐
fers.
Asyn‐
chro‐
nous
data
trans‐
fers
use
request
(REQ)
and
acknowl‐
edge
(ACK)
sig‐
nal‐
ing.
The
strict
order‐
ing
of
REQ
and
ACK
sig‐
nal‐
ing
sim‐
pli‐
fies
the
com‐
mu‐
ni‐
ca‐
tion
pro‐
to‐
col
but
lim‐
its
I/O
per‐
for‐
mance.
A
SCSI
tar‐
get
and
host
pair
may
agree
to
use
syn‐
chro‐
nous
data
trans‐
fers
to
increase
I/O
per‐
for‐
mance.
Syn‐
chro‐
nous
data
trans‐
fers
improve
I/O
per‐
for‐
mance
by
less‐
en‐
ing
the
order‐
ing
require‐
ments
on
REQs
and
ACKs.
By
allow‐
ing
mul‐
ti‐
ple
out‐
stand‐
ing
REQs,
sig‐
nal
prop‐
a‐
ga‐
tion
delays
and
tem‐
po‐
rary
rate
imbal‐
ances
are
bet‐
ter
tol‐
er‐
ated.
To
make
use
of
syn‐
chro‐
nous
data
trans‐
fers,
a
SCSI
tar‐
get
and
host
must
nego‐
ti‐
ate
to
deter‐
mine
mutu‐
ally
accept‐
able
max‐
i‐
mum
REQ-
ACK-
off‐
set
and
data-
trans‐
fer
rate
param‐
e‐
ters.
The
max‐
i‐
mum
REQ-
ACK-
off‐
set
param‐
e‐
ter
indi‐
cates
the
max‐
i‐
mum
allow‐
able
num‐
ber
of
out‐
stand‐
ing
REQs.
The
value
zero
is
used
to
indi‐
cate
asyn‐
chro‐
nous
data
trans‐
fer.
Other
val‐
ues
indi‐
cate
syn‐
chro‐
nous
data
trans‐
fer.
The
appro‐
pri‐
ate
value
is
gen‐
er‐
ally
depen‐
dent
on
the
size
of
the
receive
data
FIFO.
High
val‐
ues
tend
to
improve
data
trans‐
fer
rates.
The
max‐
i‐
mum
data-
trans‐
fer
rate
param‐
e‐
ter
indi‐
cates
the
"burst"
data
trans‐
fer
rate
(min‐
i‐
mum
allow‐
able
time
between
suc‐
ces‐
sive
syn‐
chro‐
nous
data
trans‐
fers).
A
SCSI
syn‐
chro‐
nous
data
trans‐
fer
request
(SDTR)
mes‐
sage,
used
to
ini‐
ti‐
ate
the
nego‐
ti‐
a‐
tion
process,
is
asso‐
ci‐
ated
with
the
pro‐
cess‐
ing
of
a
SCSI
com‐
mand.
At
power-
up
and
after
being
reset,
all
par‐
al‐
lel
SCSI
devices
and
hosts
com‐
mu‐
ni‐
cate
using
eight-
bit
data
trans‐
fers.
A
SCSI
tar‐
get
and
host
pair
may
agree
to
use
six‐
teen-
bit
(wide)
data
trans‐
fers
to
increase
I/O
per‐
for‐
mance.
To
make
use
of
wide
data
trans‐
fers,
a
SCSI
tar‐
get
and
host
must
nego‐
ti‐
ate
to
deter‐
mine
a
mutu‐
ally
accept‐
able
data
trans‐
fer
width
param‐
e‐
ter.
A
SCSI
wide
data
trans‐
fer
request
(WDTR)
mes‐
sage,
used
to
ini‐
ti‐
ate
the
nego‐
ti‐
a‐
tion
process,
is
asso‐
ci‐
ated
with
the
pro‐
cess‐
ing
of
a
SCSI
com‐
mand.
Some
SCSI
devices
are
able
to
simul‐
ta‐
ne‐
ously
man‐
age
mul‐
ti‐
ple
active
com‐
mands.
Such
a
device
has
a
com‐
mand
queue
that
holds
com‐
mands
for
pro‐
cess‐
ing.
Com‐
mand
queu‐
ing
can
improve
I/O
per‐
for‐
mance
by
reduc‐
ing
the
time
spent
by
the
device
wait‐
ing
for
new
com‐
mands
from
the
host.
Note
that
com‐
mand
queu‐
ing
might
not
improve
I/O
per‐
for‐
mance
sub‐
stan‐
tially
for
devices
that
sup‐
port
"read-
ahead"
and
"imme‐
di‐
ate-
report‐
ing"
(see
scsi_disk(7)
and
scsi_tape(7)).
The
SCSI
device
and
host
use
com‐
mand
tags
to
cor‐
rectly
man‐
age
these
mul‐
ti‐
ple
simul‐
ta‐
ne‐
ously
active
com‐
mands.
At
all
times
when
com‐
mand
queu‐
ing
is
in
effect,
each
active
com‐
mand
being
han‐
dled
by
a
spe‐
cific
LUN
has
a
unique
com‐
mand
tag.
SCSI
devices
indi‐
cate
their
abil‐
ity
to
sup‐
port
the
spe‐
cial
com‐
mu‐
ni‐
ca‐
tion
fea‐
tures
described
above
in
their
SCSI
com‐
mand
data.
Nor‐
mally
the
SCSI
com‐
mand
data
and
nego‐
ti‐
a‐
tion
pro‐
to‐
cols
allow
hosts
and
devices
to
deter‐
mine
the
opti‐
mal
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
so
that
I/O
per‐
for‐
mance
is
max‐
i‐
mized.
The
cur‐
rent
oper‐
at‐
ing
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
may
be
deter‐
mined
by
use
of
the:
(rec‐
om‐
mended)
or
(for
back‐
ward
com‐
pat‐
i‐
bil‐
ity),
and
ioctls.
Occa‐
sion‐
ally,
it
is
desir‐
able
to
limit
SCSI
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
to
work
around
a
com‐
mu‐
ni‐
ca‐
tion
prob‐
lem
or
to
pro‐
vide
exter‐
nal
insight
in
deter‐
min‐
ing
opti‐
mal
param‐
e‐
ters.
SCSI
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
limit
sug‐
ges‐
tions
can
be
spec‐
i‐
fied
by
use
of
the:
and
ioctls.
Note
that
there
might
be
sub‐
stan‐
tial
dif‐
fer‐
ences
between
spec‐
i‐
fied
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
limit
sug‐
ges‐
tions
and
the
cor‐
re‐
spond‐
ing
actual
cur‐
rent
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
being
used
for
com‐
mu‐
ni‐
ca‐
tion.
These
dif‐
fer‐
ences
are
a
result
of
device-
spe‐
cific
driver
capa‐
bil‐
i‐
ties,
inter‐
face
driver
capa‐
bil‐
i‐
ties,
inter‐
face
hard‐
ware
capa‐
bil‐
i‐
ties,
device
capa‐
bil‐
i‐
ties,
delays
due
to
the
nego‐
ti‐
a‐
tion
process,
delays
due
to
cur‐
rently
active
com‐
mands,
and
delays
due
to
com‐
mands
wait‐
ing
to
be
sent
to
devices.
Note
that
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
limit
sug‐
ges‐
tions
might
not
sur‐
vive
between
and
calls,
when
no
SCSI
device
driv‐
ers
(device-
spe‐
cific
or
have
asso‐
ci‐
ated
LUN(s)
open.
The
cur‐
rent
SCSI
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
limit
sug‐
ges‐
tions
may
be
deter‐
mined
by
use
of
the
and
ioctls.
Log‐
i‐
cal
unit
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
may
be
man‐
aged
by
use
of
the
and
ioctls.
The
ioctl
indi‐
cates
the
cur‐
rent
LUN
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
val‐
ues.
The
max_q_depth
field
indi‐
cates
whether
or
not
tagged
queu‐
ing
is
enabled,
and
if
enabled,
the
max‐
i‐
mum
num‐
ber
of
simul‐
ta‐
ne‐
ously
active
com‐
mands
allowed.
When
max_q_depth
is
zero,
tagged
queu‐
ing
is
dis‐
abled.
When
it
is
one,
tags
are
being
used
but
com‐
mands
are
still
being
seri‐
ally
pro‐
cessed.
When
it
is
greater
than
one,
tags
are
being
used
and
max_q_depth
spec‐
i‐
fies
the
max‐
i‐
mum
num‐
ber
of
simul‐
ta‐
ne‐
ously
active
com‐
mands
allowed.
The
ioctl
may
be
used
to
pro‐
vide
LUN
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
limit
sug‐
ges‐
tions.
The
max_q_depth
field
indi‐
cates
whether
or
not
tagged
queu‐
ing
should
be
enabled,
and
if
enabled,
the
max‐
i‐
mum
num‐
ber
of
simul‐
ta‐
ne‐
ously
active
com‐
mands
that
should
be
allowed.
The
ioctl
indi‐
cates
the
cur‐
rent
LUN
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
limit
sug‐
ges‐
tions.
Tar‐
get
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
may
be
man‐
aged
by
use
of
the
ioctl
on
any
asso‐
ci‐
ated
HBA
DSF,
or
and
ioctls
to
any
asso‐
ci‐
ated
LUN.
The
and
ioctls
indi‐
cate
the
cur‐
rent
tar‐
get
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
val‐
ues.
The
width,
reqack_off‐
set,
and
xfer_rate
fields
indi‐
cate
the
cur‐
rently
nego‐
ti‐
ated
data
trans‐
fer
param‐
e‐
ters.
When
width
is
eight,
nar‐
row
trans‐
fers
are
in
effect.
When
it
is
six‐
teen,
wide
trans‐
fers
are
in
effect.
When
reqack_off‐
set
is
zero,
asyn‐
chro‐
nous
trans‐
fers
are
in
effect
and
xfer_rate
is
mean‐
ing‐
less.
When
reqack_off‐
set
is
non-
zero,
syn‐
chro‐
nous
trans‐
fers
are
in
effect
and
the
max‐
i‐
mum
"burst"
data
trans‐
fer
rate
is
xfer_rate
words
per
sec‐
ond,
where
the
size
of
a
word
is
as
indi‐
cated
in
width.
The
ioctl
spec‐
i‐
fies
the
tar‐
get
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
limit
sug‐
ges‐
tions.
The
max_width
field
spec‐
i‐
fies
the
max‐
i‐
mum
bus
width
that
should
be
used
for
data
trans‐
fers.
The
max_reqack_off‐
set
field
spec‐
i‐
fies
the
max‐
i‐
mum
num‐
ber
of
out‐
stand‐
ing
REQs
that
should
be
attempted
dur‐
ing
data
trans‐
fers.
The
max_xfer_rate
field
spec‐
i‐
fies
the
max‐
i‐
mum
"burst"
data
rate
that
should
be
allowed
dur‐
ing
syn‐
chro‐
nous
data
trans‐
fers.
The
ioctl
indi‐
cates
the
cur‐
rent
tar‐
get
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
limit
sug‐
ges‐
tions.
The
width,
reqack_off‐
set,
xfer_rate,
max_width,
max_reqack_off‐
set,
max_xfer_rate
fields
only
apply
to
par‐
al‐
lel
SCSI.
Bus
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
may
be
man‐
aged
by
use
of
the
and
ioctls
to
any
asso‐
ci‐
ated
LUN.
The
ioctl
indi‐
cates
the
cur‐
rent
bus
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
val‐
ues.
The
max_width
field
indi‐
cates
the
max‐
i‐
mum
data
trans‐
fer
width
that
will
be
attempted
for
data
trans‐
fers
to
any
tar‐
get
device
con‐
nected
to
the
asso‐
ci‐
ated
bus.
The
max_reqack_off‐
set
field
indi‐
cates
the
max‐
i‐
mum
num‐
ber
of
out‐
stand‐
ing
REQs
that
will
be
attempted
dur‐
ing
data
trans‐
fers
to
any
tar‐
get
device
con‐
nected
to
the
asso‐
ci‐
ated
bus.
The
max_xfer_rate
field
indi‐
cates
the
max‐
i‐
mum
"burst"
data
trans‐
fer
rate
that
will
be
attempted
for
data
trans‐
fers
to
any
tar‐
get
device
con‐
nected
to
the
asso‐
ci‐
ated
bus.
The
ioctl
spec‐
i‐
fies
the
bus
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
limit
sug‐
ges‐
tions
for
tar‐
gets
con‐
nected
to
the
asso‐
ci‐
ated
bus.
The
max_width
field
spec‐
i‐
fies
the
sug‐
gested
max‐
i‐
mum
data
trans‐
fer
width
that
should
be
attempted
for
data
trans‐
fers
to
any
tar‐
get
device
con‐
nected
to
the
asso‐
ci‐
ated
bus.
The
max_reqack_off‐
set
field
spec‐
i‐
fies
the
max‐
i‐
mum
num‐
ber
of
out‐
stand‐
ing
REQs
that
should
be
attempted
dur‐
ing
data
trans‐
fers
to
any
tar‐
get
device
con‐
nected
to
the
asso‐
ci‐
ated
bus.
The
max_xfer_rate
field
spec‐
i‐
fies
the
max‐
i‐
mum
syn‐
chro‐
nous
"burst"
data
trans‐
fer
rate
that
should
be
attempted
for
data
trans‐
fers
to
any
tar‐
get
device
con‐
nected
to
the
asso‐
ci‐
ated
bus.
The
ioctl
indi‐
cates
the
cur‐
rent
bus
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
limit
sug‐
ges‐
tions.
The
max_width,
max_reqack_off‐
set,
and
max_xfer_rate
fields
only
apply
to
par‐
al‐
lel
SCSI.
The
fol‐
low‐
ing
is
included
from
/* SCSI communication parameter ioctls */
#define SIOC_GET_LUN_PARMS _IOR('S', 58, struct sioc_lun_parms)
#define SIOC_GET_TGT_PARMS _IOR('S', 59, struct sioc_tgt_parms)
#define SIOC_GET_BUS_PARMS _IOR('S', 60, struct sioc_bus_parms)
#define SIOC_GET_LUN_LIMITS _IOR('S', 61, struct sioc_lun_limits)
#define SIOC_GET_TGT_LIMITS _IOR('S', 62, struct sioc_tgt_limits)
#define SIOC_GET_BUS_LIMITS _IOR('S', 63, struct sioc_bus_limits)
#define SIOC_SET_LUN_LIMITS _IOW('S', 64, struct sioc_lun_limits)
#define SIOC_SET_TGT_LIMITS _IOW('S', 65, struct sioc_tgt_limits)
#define SIOC_SET_BUS_LIMITS _IOW('S', 66, struct sioc_bus_limits)
struct sioc_lun_parms {
unsigned int flags;
unsigned int max_q_depth; /* maximum active I/O's */
unsigned int reserved[4]; /* reserved for future
* use
*/
} sioc_lun_parms_t;
struct sioc_lun_limits {
unsigned int flags;
unsigned int max_q_depth;
unsigned int reserved[4]; /* reserved for
* future use
*/
} sioc_lun_limits_t;
typedef struct sioc_tgt_parms {
unsigned int flags;
unsigned int width; /* bits per word */
unsigned int xfer_rate; /* words per second */
unsigned int reqack_offset; /* REQ/ACK offset */
unsigned int tgt_id; /* target Id */
unsigned int reserved[3]; /* reserved
* for future use
*/
} sioc_tgt_parms_t;
typedef struct sioc_tgt_limits {
unsigned int flags;
unsigned int max_width; /* Bits per word */
unsigned int max_xfer_rate; /* Words per second */
unsigned int max_reqack_offset; /* REQ/ACK offset */
unsigned int tgt_id; /* target Id */
unsigned int reserved[3]; /* Reserved for future
* use
*/
} sioc_tgt_limits_t;
struct sioc_bus_parms {
unsigned int flags; /* reserved for future
* use
*/
unsigned int max_width;
unsigned int max_reqack_offset;
unsigned int max_xfer_rate; /* bytes/sec */
unsigned int reserved[4]; /* reserved for future
* use
*/
} sioc_bus_parms_t;
struct sioc_bus_limits {
unsigned int flags; /* reserved for future
* use
*/
unsigned int max_width;
unsigned int max_reqack_offset;
unsigned int max_xfer_rate; /* bytes/sec */
unsigned int reserved[4]; /* reserved for future
* use
*/
} sioc_bus_limits_t;
The
fol‐
low‐
ing
is
included
from
#define PSIOC_GET_TGT_PARMS _IOWR('S', 114, struct sioc_tgt_parms)
#define PSIOC_GET_TGT_LIMITS _IOWR('S', 115, struct sioc_tgt_limits)
#define PSIOC_RESET_DEV _IOW('S', 116, int)
#define PDIOC_RSTCLR _IOW('S', 117, int)
SCSI
Com‐
mands
and
Oper‐
a‐
tions
and
ioctls
allow
an
arbi‐
trary
SCSI
com‐
mand
to
be
sent
to
a
device.
All
details
of
the
SCSI
com‐
mand
pro‐
to‐
col
are
han‐
dled
auto‐
mat‐
i‐
cally.
should
only
be
issued
on
per‐
sis‐
tent
device
files.
it
allows
to
send
the
scsi
com‐
mand
through
any
avail‐
able
LUN
path
or
through
a
selected
LUN
path.
is
dep‐
re‐
cated.
It
can
be
issued
on
both
per‐
sis‐
tent
and
legacy
device
files.
When
issued
on
a
per‐
sis‐
tent
device
file,
the
SCSI
com‐
mand
is
sent
through
any
avail‐
able
LUN
path.
The
fol‐
low‐
ing
flags
can
be
used
to
spec‐
ify
the
flags
field
value
of
both
and
unless
indi‐
cated
oth‐
er‐
wise:
Data
read
oper‐
a‐
tion
is
expected
if
data_length
field
is
non-
zero.
The
absence
of
this
flag
implies
that
data
write
oper‐
a‐
tion
is
expected
if
the
data_length
field
is
non-
zero.
Syn‐
chro‐
nous
data
trans‐
fer
request
nego‐
ti‐
a‐
tions
should
be
attempted
with
this
com‐
mand.
This
flag
only
applies
to
par‐
al‐
lel
SCSI
and
is
main‐
tained
for
back‐
ward
com‐
pat‐
i‐
bil‐
ity.
Wide
data
trans‐
fer
request
nego‐
ti‐
a‐
tions
should
be
attempted
with
this
com‐
mand.
This
flag
only
applies
to
par‐
al‐
lel
SCSI
and
is
main‐
tained
for
back‐
ward
com‐
pat‐
i‐
bil‐
ity.
dis‐
cpriv
bit
in
Iden‐
tify
mes‐
sage
is
not
set. This
flag
only
applies
to
par‐
al‐
lel
SCSI
and
is
main‐
tained
for
back‐
ward
com‐
pat‐
i‐
bil‐
ity.
The
SCSI
com‐
mand
is
to
be
issued
on
a
given
LUN
path. This
flag
can
only
be
spec‐
i‐
fied
with
ioctl.
When
spec‐
i‐
fied
the
hard‐
ware
path
of
the
LUN
path
to
use
is
spec‐
i‐
fied
in
field
lpt_hwp
The
cdb
field
spec‐
i‐
fies
the
SCSI
com‐
mand
bytes.
The
num‐
ber
of
com‐
mand
bytes
is
spec‐
i‐
fied
by
the
cdb_length
field.
These
com‐
mand
bytes
are
sent
to
the
tar‐
get
device
dur‐
ing
the
SCSI
com‐
mand
phase.
The
address
of
the
data
area
for
the
data
phase
of
the
SCSI
com‐
mand
is
spec‐
i‐
fied
by
the
data
field.
The
data_length
field
spec‐
i‐
fies
the
max‐
i‐
mum
num‐
ber
of
data
bytes
to
be
trans‐
ferred.
A
zero-
val‐
ued
data_length
indi‐
cates
that
no
data
phase
should
occur.
Most
SCSI
com‐
mands
with
a
data
phase
expect
the
data
length
infor‐
ma‐
tion
to
be
included
some‐
where
in
the
com‐
mand
bytes.
The
call‐
er
is
respon‐
si‐
ble
for
cor‐
rectly
spec‐
i‐
fy‐
ing
both
the
data_length
field
and
any
cdb
data
length
val‐
ues.
The
length
may
not
be
larger
than
and
some
imple‐
men‐
ta‐
tions
fur‐
ther
restrict
this
length.
The
max_msecs
field
spec‐
i‐
fies
the
max‐
i‐
mum
time,
in
mil‐
lisec‐
onds,
that
the
device
should
need
to
com‐
plete
the
com‐
mand.
If
this
period
of
time
expires
with‐
out
com‐
mand
com‐
ple‐
tion,
the
sys‐
tem
might
attempt
recov‐
ery
pro‐
ce‐
dures
to
regain
the
device's
atten‐
tion.
These
recov‐
ery
pro‐
ce‐
dures
might
include
abort
tag,
abort,
and
device
and
bus
reset
oper‐
a‐
tions.
A
zero
value
in
the
max_msecs
field
indi‐
cates
that
the
time‐
out
period
is
infi‐
nite
and
the
sys‐
tem
should
wait
indef‐
i‐
nitely
for
com‐
mand
com‐
ple‐
tion.
When
the
or
ioctl
call
returns,
all
com‐
mand
pro‐
cess‐
ing
has
been
com‐
pleted.
Most
ioctl
calls
will
return
zero
(suc‐
cess).
The
result‐
ing
detailed
ioctl
data
should
be
used
to
eval‐
u‐
ate
"suc‐
cess"
or
"fail‐
ure"
from
the
call‐
er's
per‐
spec‐
tive.
The
cdb_sta‐
tus
field
indi‐
cates
the
results
of
the
com‐
mand.
If
the
cdb_sta‐
tus
field
indi‐
cates
a
sta‐
tus,
the
sense_sta‐
tus
field
indi‐
cates
the
results
of
the
SCSI
com‐
mand
used
to
col‐
lect
the
asso‐
ci‐
ated
sense
data.
These
sta‐
tus
fields
will
con‐
tain
one
of
the
fol‐
low‐
ing
val‐
ues:
The
SCSI
com‐
mand
request
is
invalid
and
thus
not
attempted.
The
tar‐
get
device
does
not
answer
to
selec‐
tion
by
the
host SCSI
inter‐
face
(the
device
does
not
exist
or
does
not
respond).
The
device
answered
selec‐
tion
but
the
com‐
mand
is
not
com‐
pleted
(the
device
took
too
long
or
a
com‐
mu‐
ni‐
ca‐
tion
fail‐
ure
occurred).
Device
suc‐
cess‐
fully
com‐
pleted
the
com‐
mand.
Device
indi‐
cated
sense
data
is
avail‐
able.
Device
suc‐
cess‐
fully
com‐
pleted
the
com‐
mand and
the
requested
(search
or
pre-
fetch)
oper‐
a‐
tion
is
sat‐
is‐
fied.
Device
indi‐
cated
it
is
unable
to
accept
the
com‐
mand because
it
is
busy
doing
other
oper‐
a‐
tions.
Device
suc‐
cess‐
fully
com‐
pleted
this
com‐
mand, which
is
one
in
a
series
of
linked
com‐
mands
(not
sup‐
ported,
see
Device
indi‐
cated
both and
(not
sup‐
ported,
see
Device
indi‐
cated
the
com‐
mand
con‐
flicted
with
an
exist‐
ing
reser‐
va‐
tion.
Device
indi‐
cated
the
com‐
mand
is
ter‐
mi‐
nated
early
by
the
host
sys‐
tem.
Device
indi‐
cated
it
is
unable
to
accept
the
com‐
mand because
its
com‐
mand
queue
is
cur‐
rently
full.
The
data_xfer
field
indi‐
cates
the
num‐
ber
of
data
bytes
actu‐
ally
trans‐
ferred
dur‐
ing
the
data
phase
of
the
com‐
mand.
This
field
is
valid
only
when
the
cdb_sta‐
tus
field
con‐
tains
one
of
the
fol‐
low‐
ing
val‐
ues:
or
The
sense_xfer
field
indi‐
cates
the
num‐
ber
of
valid
sense
data
bytes.
This
field
is
valid
only
when
the
cdb_sta‐
tus
field
con‐
tains
the
value
and
the
sense_sta‐
tus
field
con‐
tains
the
value
The
ioctl
causes
a
SCSI
mes‐
sage
to
be
sent
to
the
LUN.
This
clears
all
active
com‐
mands
to
the
LUN
from
this
ini‐
tia‐
tor.
The
ioctl
causes
a
SCSI
task
man‐
age‐
ment
func‐
tion
to
be
per‐
formed
if
sup‐
ported
by
the
SCSI
trans‐
port.
The
fol‐
low‐
ing
task
man‐
age‐
ment
func‐
tion
val‐
ues
can
be
spec‐
i‐
fied.
They
are
defined
in
Lun
Reset
Warm
Tar‐
get
Reset
Cold
Tar‐
get
Reset
The
ioctl
causes
a
SCSI
device
to
be
reset
(includ‐
ing
clear‐
ing
all
active
com‐
mands).
On
par‐
al‐
lel
SCSI
a
and
ioctls
cause
a
SCSI
mes‐
sage
to
be
sent
to
the
asso‐
ci‐
ated
tar‐
get.
On
Fibre
Chan‐
nel
a
ioctl
causes
a
"TAR‐
GET
RESET"
task
man‐
age‐
ment
func‐
tion
to
be
sent
to
the
asso‐
ci‐
ated
tar‐
get
fol‐
lowed
by
a
Global
Process
Logout
(GPRLO).
The
ioctl
causes
the
sys‐
tem
to
gen‐
er‐
ate
a
SCSI
bus
reset
con‐
di‐
tion
on
the
asso‐
ci‐
ated
bus.
A
SCSI
bus
reset
con‐
di‐
tion
causes
all
devices
on
the
bus
to
be
reset
(includ‐
ing
clear‐
ing
all
active
com‐
mands
on
all
devices).
The
ioctl
does
not
apply
to
Fibre
Chan‐
nel.
Often
it
is
nec‐
es‐
sary
or
use‐
ful
to
pro‐
hibit
other
SCSI
com‐
mands
while
per‐
form‐
ing
device-
con‐
trol
oper‐
a‐
tions.
This
should
be
done
by
gain‐
ing
exclu‐
sive
access
via
the
ioctl.
The
asso‐
ci‐
ated
argu‐
ment
points
to
an
inte‐
ger
with
one
of
these
val‐
ues
defined
in
Note
that
if
the
ioctl
is
issued
on
a
per‐
sis‐
tent
device
file,
tar‐
get
and
bus
exclu‐
sive
access
requests
result
to
a
LUN
exclu‐
sive
access
being
per‐
formed.
release
exclu‐
sive
access
to
log‐
i‐
cal
unit
obtain
exclu‐
sive
access
to
log‐
i‐
cal
unit
release
exclu‐
sive
access
to
tar‐
get
obtain
exclu‐
sive
access
to
tar‐
get
release
exclu‐
sive
access
to
bus
obtain
exclu‐
sive
access
to
bus
The
ioctl
is
dep‐
re‐
cated
with
HP-
UX
release
11i
V3.
If
called,
it
will
just
fake
suc‐
cess.
This
ioctl
was
used
to
work‐
around
sit‐
u‐
a‐
tions
where
it
is
not
pos‐
si‐
ble
to
set
exclu‐
sive
access
to
the
device.
It
put
the
device
in
"Pri‐
or‐
ity
mode".
This
caused
all
device-
spe‐
cific
driver
I/O
oper‐
a‐
tions
(for
exam‐
ple,
file
sys‐
tem
I/O
and
vir‐
tual
mem‐
ory
page
swap‐
ping)
and
all
SCSI
device
driver
open
calls
(includ‐
ing
pass-
through
driver
open
calls)
to
the
asso‐
ci‐
ated
LUN
to
block.
These
I/O
oper‐
a‐
tions
and
open
calls
were
blocked
for
the
entire
dura‐
tion
that
pri‐
or‐
ity
mode
was
in
effect.
While
pri‐
or‐
ity
mode
was
in
effect
only
oper‐
a‐
tions
could
be
attempted.
(these
oper‐
a‐
tions
will
not
be
blocked).
It
was
very
easy
to
cause
sys‐
tem
dead‐
lock
through
incor‐
rect
use
of
the
ioctl.
It
nor‐
mally
required
to
lock
the
call‐
ing
process
into
mem‐
ory
(see
plock(2))
prior
to
enabling
pri‐
or‐
ity
mode.
The
header
file
has
use‐
ful
infor‐
ma‐
tion
for
SCSI
device
con‐
trol.
The
fol‐
low‐
ing
is
included
from
/* SCSI device control ioctls */
#define SIOC_IO _IOWR('S', 22, struct sctl_io)
#define SIOC_RESET_DEV _IO('S', 16)
#define SIOC_RESET_BUS _IO('S', 9)
#define SIOC_PRIORITY_MODE _IOW('S', 67, int)
#define SIOC_IO_EXT _IOWR('S', 102, esctl_io_t)
#define SIOC_TASK_MGMT _IOWR('S', 104, sioc_task_mgmt_t)
/* Structure for SIOC_IO_EXT ioctl */
typedef struct {
int version;
escsi_sctl_io_flags_t flags;
int max_msecs;
uint32_t cdb_length;
uint32_t data_length;
ptr64_t data;
union sense_data sense;
escsi_hw_path_t lpt_hwp;
uint32_t data_xfer;
uint32_t sense_xfer;
uint32_t cdb_status;
uint32_t sense_status;
uint8_t cdb[ESCSI_MAX_CDB_LEN];
uint32_t rsvd[32]; /* Reserved for
* future use
*/
} esctl_io_t;
/* Structure for SIOC_IO ioctl */
struct sctl_io
{
unsigned flags;
unsigned char cdb_length;
unsigned char cdb[16];
void *data;
unsigned data_length;
unsigned max_msecs;
unsigned data_xfer;
unsigned cdb_status;
unsigned char sense[256];
unsigned sense_status;
unsigned char sense_xfer;
unsigned char reserved[64];
} sctl_io_t;
Secu‐
rity
Restric‐
tions
Supe‐
ruser
or
priv‐
i‐
lege,
or
device
write
per‐
mis‐
sions
are
required
to
use
these
ioctls.
See
priv‐
i‐
leges(5)
for
more
infor‐
ma‐
tion
about
priv‐
i‐
leged
access
on
sys‐
tems
that
sup‐
port
fine-
grained
priv‐
i‐
leges.
EXAMPLES
Assume
that
fildes
is
a
valid
file
descrip‐
tor
for
a
per‐
sis‐
tent
device
file
of
a
SCSI
device,
and
leg_fildes
is
a
valid
file
descrip‐
tor
for
a
legacy
device
file
of
a
SCSI
device,
and
lpt_hwp
con‐
tains
a
valid
hard‐
ware
path
of
a
LUN
path
to
the
device.
The
first
exam‐
ple
attempts
a
SCSI
com‐
mand:
#include <sys/scsi.h>
esctl_io_t esctl_io;
#define MAX_LEN 255
unsigned char inquiry_data[MAX_LEN];
memset(&esctl_io, 0, sizeof(esctl_io)); /* clear reserved fields */
esctl_io.flags = ESCTL_READ; /* input data expected */
esctl_io.cdb[0] = CMDinquiry;
esctl_io.cdb[1] = 0x00;
esctl_io.cdb[2] = 0x00;
esctl_io.cdb[3] = 0x00;
esctl_io.cdb[4] = MAX_LEN; /* allocation length */
esctl_io.cdb[5] = 0x00;
esctl_io.cdb_length = 6; /* 6 byte command */
esctl_io.data = &inquiry_data[0]; /* data buffer location */
esctl_io.data_length = MAX_LEN; /* maximum transfer length */
esctl_io.max_msecs = 10000; /* allow 10 seconds for cmd */
if (ioctl(fildes, SIOC_IO_EXT, &esctl_io) < 0) {
/* request is invalid */
} else {
if ( esctl_io.cdb_status == S_GOOD) {
/* success. display inquiry data */
else {
/* failure. process depending on cdb_status */
}
}
The
sec‐
ond
exam‐
ple
attempts
a
SCSI
com‐
mand
via
a
spe‐
cific
LUN
path.
#include <sys/scsi.h>
esctl_io_t esctl_io;
#define MAX_LEN 255
unsigned char inquiry_data[MAX_LEN];
memset(&esctl_io, 0, sizeof(esctl_io)); /* clear reserved fields */
esctl_io.flags = ESCTL_READ | ESCTL_IO_LPT; /* input data
* expected and command
* to be sent on given
* LUN path
*/
memcpy(&esctl_io.lpt_hwp, lpt_hwp, sizeof(lpt_hwp); /* specify
* the hardware path of
* LUN path through which
* command must be sent
*/
esctl_io.cdb[0] = CMDinquiry;
esctl_io.cdb[1] = 0x00;
esctl_io.cdb[2] = 0x00;
esctl_io.cdb[3] = 0x00;
esctl_io.cdb[4] = MAX_LEN; /* allocation length */
esctl_io.cdb[5] = 0x00;
esctl_io.cdb_length = 6; /* 6 byte command */
esctl_io.data = &inquiry_data[0]; /* data buffer location */
esctl_io.data_length = MAX_LEN; /* maximum transfer length */
esctl_io.max_msecs = 10000; /* allow 10 seconds for cmd */
if (ioctl(fildes, SIOC_IO_EXT, &esctl_io) < 0) {
/* request is invalid */
} else {
if ( esctl_io.cdb_status == S_GOOD) {
/* success. display inquiry data */
else {
/* failure. process depending on cdb_status */
}
}
The
fol‐
low‐
ing
exam‐
ple
attempts
a
SCSI
com‐
mand
and
checks
to
see
if
the
device
is
ready,
not
ready,
or
in
some
other
state.
#include <sys/scsi.h>
struct sctl_io sctl_io;
memset(&sctl_io, 0, sizeof(sctl_io)); /* clear reserved fields */
sctl_io.flags = 0; /* no data transfer expected */
sctl_io.cdb[0] = 0x00; /* can use CMDtest_unit_ready */
sctl_io.cdb[1] = 0x00;
sctl_io.cdb[2] = 0x00;
sctl_io.cdb[3] = 0x00;
sctl_io.cdb[4] = 0x00;
sctl_io.cdb[5] = 0x00;
sctl_io.cdb_length = 6; /* 6 byte command */
sctl_io.data = NULL; /* no data buffer is provided */
sctl_io.data_length = 0; /* do not transfer data */
sctl_io.max_msecs = 10000; /* allow 10 seconds for cmd */
if (ioctl(leg_fildes, SIOC_IO, &sctl_io) < 0) {
/* request is invalid */
} else if (sctl_io.cdb_status == S_GOOD) {
/* device is ready */
} else if (sctl_io.cdb_status == S_BUSY ||
(sctl_io.cdb_status == S_CHECK_CONDITION &&
sctl_io.sense_status == S_GOOD &&
sctl_io.sense_xfer > 2 &&
(sctl_io.sense[2] & 0x0F) == 2)) {
/* can use sense_data */
/* device is not ready */
} else {
/* unknown state */
}
WARNINGS
Incor‐
rect
use
of
oper‐
a‐
tions
(even
those
attempt‐
ing
access
to
non-
exis‐
tent
devices)
can
cause
data
loss,
sys‐
tem
pan‐
ics,
and
device
dam‐
age.
The
ioctl
should
be
used
to
gain
exclu‐
sive
access
to
a
device
prior
to
attempt‐
ing
com‐
mands.
If
exclu‐
sive
access
is
not
obtained,
com‐
mands
will
be
inter‐
mixed
with
device-
spe‐
cific
driver
com‐
mands,
which
can
lead
to
unde‐
sir‐
able
results.
Device-
spe‐
cific
driv‐
ers
can
reject
inap‐
pro‐
pri‐
ate
or
trou‐
ble‐
some
com‐
mands.
How‐
ever,
since
not
all
such
oper‐
a‐
tions
are
known
and
detected,
care
should
be
exer‐
cised
to
avoid
dis‐
rupt‐
ing
device-
spe‐
cific
driv‐
ers
when
using
com‐
mands
that
mod‐
ify
inter‐
nal
device
states.
Most
SCSI
com‐
mands
have
a
log‐
i‐
cal
unit
num‐
ber
(LUN)
field.
Par‐
al‐
lel
SCSI
imple‐
men‐
ta‐
tions
on
the
HP-
UX
oper‐
at‐
ing
sys‐
tem
select
log‐
i‐
cal
units
via
the
SCSI
mes‐
sage.
The
LUN
por‐
tion
of
the
cdb
should
nor‐
mally
be
set
to
zero,
even
when
the
LUN
being
accessed
is
not
zero.
Use
of
linked
com‐
mands
is
not
sup‐
ported.
Most
SCSI
com‐
mands
with
a
data
phase
expect
the
data
length
infor‐
ma‐
tion
to
be
included
some‐
where
in
the
com‐
mand
bytes.
Both
the
data_length
field
and
any
cdb
data
length
val‐
ues
must
be
cor‐
rectly
spec‐
i‐
fied
to
get
cor‐
rect
com‐
mand
results.
Very
large
(or
infi‐
nite)
time‐
out
val‐
ues
can
cause
a
par‐
al‐
lel
SCSI
bus
(poten‐
tially
the
entire
sys‐
tem)
to
hang.
Device
and/or
bus
reset
oper‐
a‐
tions
can
be
used
to
regain
a
device's
atten‐
tion
when
a
time‐
out
expires.
Reset‐
ting
a
device
can
cause
I/O
errors
and/or
loss
of
cached
data.
This
can
result
in
loss
of
data
and/or
sys‐
tem
pan‐
ics.
Obtain‐
ing
SCSI
data
by
use
of
the
ioctl
instead
of
by
use
of
the
ioctl
is
gen‐
er‐
ally
prefer‐
able
since
SCSI
imple‐
men‐
ta‐
tions
on
the
HP-
UX
oper‐
at‐
ing
sys‐
tem
syn‐
chro‐
nize
access
of
inquiry
data
dur‐
ing
driver
open
calls.
Since
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ters
can
be
affected
by
device-
spe‐
cific
driver
capa‐
bil‐
i‐
ties,
device-
spe‐
cific
driver
use
might
result
in
com‐
mu‐
ni‐
ca‐
tion
param‐
e‐
ter
changes.
The
ioctl
is
not
sup‐
ported
by
because
the
mean‐
ing
of
capac‐
ity
is
device-
spe‐
cific.
FILESSEE ALSOmknod(1M),
mksf(1M),
ioctl(2),
plock(2).
priv‐
i‐
leges(5),
intro(7),
scsi(7).
scsi_ctl(7)