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.

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

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)