[Bug 294353] mfiutil(4)/mrsasutil(4): Information on enclosures is ambiguous and poorly documented

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=294353

            Bug ID: 294353
           Summary: mfiutil(4)/mrsasutil(4): Information on enclosures is
                    ambiguous and poorly documented
           Product: Base System
           Version: 14.4-STABLE
          Hardware: Any
                OS: Any
            Status: New
          Severity: Affects Some People
          Priority: ---
         Component: bin
          Assignee: bugs@FreeBSD.org
          Reporter: michaelo@FreeBSD.org

On: reeBSD deblndw014x.innomotics.net 14.4-STABLE FreeBSD 14.4-STABLE c5e1dde24
GENERIC amd64

Consider this output:
> # mrsasutil show drives
> /dev/mrsas0 Physical Drives:
>  4 (  279G) JBOD <SEAGATE ST9300653SS 5301 serial=6XN1LGJJ\000\000??@> SAS E1:S13
>  5 (  838G) JBOD <SEAGATE ST9900805SS 5101 serial=6XS2W2A9> SAS E1:S0
>  6 (  838G) JBOD <SEAGATE ST9900805SS 5101 serial=6XS2W2CT> SAS E1:S1
>  7 (  279G) JBOD <SEAGATE ST9300605SS 5101 serial=6XP3F4YH\000\000??@> SAS E1:S14
>  8 (  838G) JBOD <SEAGATE ST9900805SS 5101 serial=6XS2W25E> SAS E1:S2
>  9 (  279G) JBOD <SEAGATE ST9300653SS 5301 serial=6XN1LGL7\000\000??@> SAS E1:S12
> 10 (  838G) JBOD <SEAGATE ST9900805SS 5101 serial=6XS2SR8E> SAS E1:S3
> 11 (  838G) JBOD <SEAGATE ST9900805SS 5101 serial=6XS2W3D2> SAS E1:S7
> 12 (  838G) JBOD <SEAGATE ST9900805SS 5101 serial=6XS2W2PJ> SAS E1:S4
> 13 (  838G) JBOD <SEAGATE ST9900805SS 5101 serial=6XS2W3W3> SAS E1:S5
> 14 (  838G) JBOD <SEAGATE ST9900805SS 5101 serial=6XS2W2HG> SAS E1:S6
> 15 (  279G) JBOD <SEAGATE ST9300605SS 5101 serial=6XP3F6GJ\000\000??@> SAS E1:S15

Let's query the same from storcli by Broadcom:
> # ./storcli64 /c0 show all
> Generating detailed summary of the adapter, it may take a while to complete.
> 
> CLI Version = 007.3603.0000.0000 Oct 30, 2025
> Operating system = FreeBSD 14.4-STABLE
> Controller = 0
> Status = Success
> Description = None
> ...
> PD LIST :
> =======
> 
> ------------------------------------------------------------------------------
> EID:Slt DID State DG       Size Intf Med SED PI SeSz Model            Sp Type
> ------------------------------------------------------------------------------
> 16:0      5 JBOD  -  838.363 GB SAS  HDD N   N  512B ST9900805SS      U  -
> 16:1      6 JBOD  -  838.363 GB SAS  HDD N   N  512B ST9900805SS      U  -
> 16:2      8 JBOD  -  838.363 GB SAS  HDD N   N  512B ST9900805SS      U  -
> 16:3     10 JBOD  -  838.363 GB SAS  HDD N   N  512B ST9900805SS      U  -
> 16:4     12 JBOD  -  838.363 GB SAS  HDD N   N  512B ST9900805SS      U  -
> 16:5     13 JBOD  -  838.363 GB SAS  HDD N   N  512B ST9900805SS      U  -
> 16:6     14 JBOD  -  838.363 GB SAS  HDD N   N  512B ST9900805SS      U  -
> 16:7     11 JBOD  -  838.363 GB SAS  HDD N   N  512B ST9900805SS      U  -
> 16:12     9 JBOD  -  279.396 GB SAS  HDD N   N  512B ST9300653SS      U  -
> 16:13     4 JBOD  -  279.396 GB SAS  HDD N   N  512B ST9300653SS      U  -
> 16:14     7 JBOD  -  279.396 GB SAS  HDD N   N  512B ST9300605SS      U  -
> 16:15    15 JBOD  -  279.396 GB SAS  HDD N   N  512B ST9300605SS      U  -
> ------------------------------------------------------------------------------
> 
> EID=Enclosure Device ID|Slt=Slot No|DID=Device ID|DG=DriveGroup
> DHS=Dedicated Hot Spare|UGood=Unconfigured Good|GHS=Global Hotspare
> UBad=Unconfigured Bad|Sntze=Sanitize|Onln=Online|Offln=Offline|Intf=Interface
> Med=Media Type|SED=Self Encryptive Drive|PI=PI Eligible
> SeSz=Sector Size|Sp=Spun|U=Up|D=Down|T=Transition|F=Foreign
> UGUnsp=UGood Unsupported|UGShld=UGood shielded|HSPShld=Hotspare shielded
> CFShld=Configured shielded|Cpybck=CopyBack|CBShld=Copyback Shielded
> UBUnsp=UBad Unsupported|Rbld=Rebuild

The E value does not match. How so?
> # ./storcli64 /c0/e16 show all
> CLI Version = 007.3603.0000.0000 Oct 30, 2025
> Operating system = FreeBSD 14.4-STABLE
> Controller = 0
> Status = Success
> Description = None
> 
> 
> Enclosure /c0/e16  :
> ==================
> 
> Information :
> ===========
> Device ID = 16
> Position = 1
> Connector Name = Port 0 - 3 & Port 4 - 7 x8
> Enclosure Type = SES
> Status = OK
> FRU Part Number = N/A
> Enclosure Serial Number =
> Enclosure Zoning Mode = N/A
> Partner Device ID = Unavailable
> Device Type = Enclosure
> EnclLogicalID = 0x0000000000000000
> 
> 
> Inquiry Data :
> ============
> Vendor Identification = FTS CORP
> Product Identification = SAS20BP_12_25HD
> Product Revision Level = 0700
> 
> 
> EnclSasAddress :
> ==============
> 
> -------------------------
> Index SAS address
> -------------------------
>     0 0x500605B0000272BD
> -------------------------
> 
> 
> Properties :
> ==========
> 
> --------------------------------------------------------------------------------------------------
> EID State Slots PD PS Fans TSs Alms SIM Port#                      ProdID          VendorSpecific
> --------------------------------------------------------------------------------------------------
>  16 OK       16 12  0    0   3    0   0 Port 0 - 3 & Port 4 - 7 x8 SAS20BP_12_25HD x36-254.7.0.0
> --------------------------------------------------------------------------------------------------
> 
> 
> EID=Enclosure Device ID | PD=Physical drive count | PS=Power Supply count
> TSs=Temperature sensor count | Alms=Alarm count | SIM=SIM Count | ProdID=Product ID

As it turns out all Broadcom/AVAGO/LSI utils use always the enclosure id. The
value matching seems to be the "enclosure position", but wait there is an index
as well: 0. To make it even worse mfi(4) or mrsas(4) expose the position as
"unit8_t encl_index" in C.

This causes confusion because although it refers to the same item, but with
different numbering schemes. There are two ways to solve it:
* Align with Broadcom utils and use the enclosure id only since the manpage
just talks about "enclosure" w/o any specs (thus an implementation detail).
* Explicitly document as enclosure *position*, even better change from
encl_index to encl_pos in source code to make it unambiguous and add CAVEATS to
the manpage.

I'd prefer the first option for consistency.

-- 
You are receiving this mail because:
You are the assignee for the bug.