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.

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).

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.