man smp_conf_zone_perm_tbl (8): 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.

CONFORMING TO

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