NAME¶
smp_conf_zone_perm_tbl - invoke CONFIGURE ZONE PERMISSION TABLE function
SYNOPSIS¶
smp_conf_zone_perm_tbl [
--deduce] [
--expected=EX]
[
--help] [
--hex] [
--interface=PARAMS]
[
--numzg=NG]
--permf=FN [
--raw] [
--sa=SAS_ADDR] [
--save=SAV] [
--start=SS] [
--verbose] [
--version]
SMP_DEVICE[,N]
DESCRIPTION¶
Sends one or more SAS Serial Management Protocol (SMP) CONFIGURE ZONE PERMISSION
TABLE function requests to an SMP target. The SMP target is identified by the
SMP_DEVICE and the
--sa=SAS_ADDR. Depending on the interface,
the
SAS_ADDR may be deduced from the
SMP_DEVICE. The mpt
interface uses
SMP_DEVICE to identify an HBA (an SMP initiator) and
needs the additional
,N to differentiate between HBAs if there are
multiple present.
The zone permission table has a row for each source zone group and a column for
each destination zone group. Each element in the table (ZP[s,d]) is a single
bit indicating whether the source zone group can access the destination zone
group (the bit is set: 1) or not (the bit is clear: 0). There are two
different table sizes: 128 and 256 zone groups. Descriptors provided to this
function request are either 16 bytes (128 bits) or 32 bytes (256 bits) long.
Each descriptor is basically a row in the zone permission table.
Apart from being row in the zone permission table each descriptor is transposed
and applied to the corresponding destination column. This "maintains
symmetry about the ZP[s,s] table axis" in the words of the draft. Also
descriptors are applied in the order that they appear in the request (i.e.
ascending source zone group numbers).
The maximum number of descriptors that one CONFIGURE ZONE PERMISSION TABLE
function request can hold is limited to 63 if there are 128 zone groups; and
is limited to 31 if there are 256 zone groups. A full zone table will contain
128 (or 256) descriptors so to configure a full table requires multiple
CONFIGURE ZONE PERMISSION TABLE requests.
The number of zone permission configuration descriptors is determined by reading
the
FN file associated with the
--permf=FN option. If there are
more descriptors than can fit in one CONFIGURE ZONE PERMISSION TABLE function
request then multiple requests are sent. All descriptors found in the
FN file will be sent unless an earlier function response indicates
there has been an error.
OPTIONS¶
Mandatory arguments to long options are mandatory for short options as well.
- -d, --deduce
- deduce number of zone groups from number of bytes on active FN
lines. With 128 zone groups each active line will contain 16 (or less)
bytes. With this option if any active line in FN contains more than
16 bytes then 256 zone groups are assumed, otherwise 128 zone groups are
assumed. This option cannot be given with the --numzg=NG option (as
they may contradict one another).
- -E, --expected=EX
- set the 'expected expander change count' field in the SMP request. The
value EX is from 0 to 65535 inclusive with 0 being the default
value. When EX is greater than zero then if the value doesn't match
the expander change count of the SMP target (i.e. the expander) when the
request arrives then the target ignores the request and sets a function
result of "invalid expander change count" in the response.
- -f, --start=SS
- starting (first) source zone group (default: zone group 0). If multiple
function requests are sent, this field in subsequent function requests
will be adjusted to reflect those descriptors already sent. Note that the
SS value may be picked up from FN and if this option and
that value are not the same, an error is generated.
- -h, --help
- output the usage message then exit.
- -H, --hex
- output the response (less the CRC field) in hexadecimal.
- -I, --interface=PARAMS
- interface specific parameters. In this case "interface" refers
to the path through the operating system to the SMP initiator. See the
smp_utils man page for more information.
- -n, --numzg=ZG
- number of zone groups. ZG can be 0 (default) or 1. 0 implies 128
zone groups while 1 implies 256 zone groups. This option cannot be used
with the --deduce option.
- -P, --permf=FN
- FN is a file containing zone permission configuration descriptors in ASCII
hexadecimal; either as bytes separated by space, tab, comma or newline, or
as longer strings of hexadecimal bytes in which every 2 digits represents
a byte. Empty lines and those starting with "#" are ignored. A
line with "--start=<num>" will be taken as the starting
source zone group number (i.e. <num> becomes SS) unless it
contradicts the command line --start=SS option. Otherwise lines
starting with "-" are ignored.
- -r, --raw
- send the response (less the CRC field) to stdout in binary. All error
messages are sent to stderr.
- -s, --sa=SAS_ADDR
- specifies the SAS address of the SMP target device. The mpt interface
needs this option and it will typically be an expander's SAS address. The
SAS_ADDR is in decimal but most SAS addresses are shown in
hexadecimal. To give a number in hexadecimal either prefix it with '0x' or
put a trailing 'h' on it.
- -S, --save=SAV
- set the 'save' field in the SMP request. SAV may take these values:
0 for updating the shadow values (default), 1 for updating the saved
values, 2 for updating shadow values and if available the saved values, 3
for updating both saved and shadow values.
- -f, --start=SS
- See entry above, listed in order by its short option letter (i.e.
-f).
- -v, --verbose
- increase the verbosity of the output. Can be used multiple times.
- -V, --version
- print the version string and then exit.
NOTES¶
For simplicity, each active line in the
FN file should contain 16 or 32
bytes. 16 bytes if there are 128 zone groups or 32 bytes if there are 256 zone
groups.
SCSI is big endian. So for 128 zone groups, the first byte placed in the zone
permission configuration descriptor is ZP[0,127-120]. If the
--start=SS
option is given then the first byte is ZP[
SS,127-120]. For 256 zone
groups, the first bytes are ZP[0,255-248] and ZP[
SS,255-248]
respectively.
There is an annex called "Zone permission configuration descriptor
examples" in recent SAS-2 and later drafts (Annex H in spl2r03.pdf).
There are some examples of the
--permf=FN format in the examples
directory. Not all SAS-2 expanders properly implement descriptor transpose and
only place the descriptor in the row corresponding to the source zone group.
The SMP CONFIGURE ZONE PERMISSION TABLE function was introduced in SAS-2 .
AUTHORS¶
Written by Douglas Gilbert.
REPORTING BUGS¶
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT¶
Copyright © 2011 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO warranty; not
even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
SEE ALSO¶
smp_utils, smp_conf_zone_phy_info, smp_zone_activate(smp_utils)