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)