1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright (c) 2017, Joyent, Inc. 13.\" 14.Dd Apr 20, 2017 15.Dt SCSI_ADDRESS_DEVICE 9F 16.Os 17.Sh NAME 18.Nm scsi_address_device , 19.Nm scsi_device_unit_address , 20.Nm scsi_device_hba_private_get , 21.Nm scsi_device_hba_private_set 22.Nd SCSI Complex addressing utility functions 23.Sh SYNOPSIS 24.In sys/scsi/scsi.h 25.Ft "struct scsi_device *" 26.Fo scsi_address_device 27.Fa "struct scsi_address *sa" 28.Fc 29.Ft "void *" 30.Fo scsi_device_hba_private_get 31.Fa "struct scsi_device *sd" 32.Fc 33.Ft void 34.Fo scsi_device_hba_private_set 35.Fa "struct scsi_device *sd" 36.Fa "void *data" 37.Fc 38.Ft "char *" 39.Fo scsi_device_unit_address 40.Fa "struct scsi_device *sd" 41.Fc 42.Sh INTERFACE LEVEL 43.Sy Evolving - 44This interface is still evolving in illumos. 45API and ABI stability is 46not guaranteed. 47.Sh PARAMETERS 48.Bl -tag -width Fa 49.It Fa sa 50Pointer to a 51.Xr scsi_address 9S 52structure. 53.It Fa sd 54Pointer to a 55.Xr scsi_device 9S 56structure. 57.It Fa data 58A private value that the driver can get and set. 59.El 60.Sh DESCRIPTION 61These functions provide useful services for SCSI HBA drivers that use 62complex addressing. 63In complex addressing mode, the 64.Xr scsi_address 9S 65structure is treated as an opaque structure and is not a simple target 66and LUN. 67To use these functions, the driver must have enabled complex addressing 68by passing the 69.Dv SCSI_HBA_ADDR_COMPLEX 70flag into the 71.Fa hba_flags 72argument of the 73.Xr scsi_hba_attach_setup 9F 74function. 75If the 76.Dv SCSI_HBA_ADDR_COMPLEX 77flag was not passed, then the driver must not call the 78.Fn scsi_device_hba_private_get , 79.Fn scsi_device_hba_private_set , 80or 81.Fn scsi_device_unit_address 82functions. 83.Pp 84The 85.Fn scsi_address_device 86function maps the 87.Xr scsi_address 9S 88function back to its corresponding 89.Xr scsi_device 9S 90structure. 91If the 92.Dv SCSI_HBA_ADDR_COMPLEX 93flag has not been set, then the function will return 94.Dv NULL . 95This can be used as a way to check if the flag has been set on the 96device. 97.Pp 98The 99.Fn scsi_device_hba_private_set 100function, allows a driver to set a private data value on the 101.Xr scsi_device 9S 102structure, which it can later retrieve through the 103.Fn scsi_device_hba_private_get 104function. 105Most drivers will set a value during the 106.Xr tran_start 9E 107entry point and then reference the data structure later on. 108This is designed to simplify the management of mapping between driver 109data structures and the corresponding system objects. 110.Pp 111The 112.Fn scsi_device_unit_address 113function returns the unit address of the 114.Xr scsi_device 9S 115structure. 116The returned string should not be modified by the device driver. 117The unit address string comes from values that are passed when 118the device is enumerated, generally through an instance of an 119.Xr iport 9 . 120.Sh CONTEXT 121These functions may be used in 122.Sy user , 123.Sy kernel , 124and 125.Sy interrupt 126context. 127.Sh RETURN VALUES 128Upon successful completion, the 129.Fn scsi_address_device 130function returns a pointer to the 131.Xr scsi_device 9S 132structure. 133Otherwise, if an error occurred 134.Dv NULL 135is returned. 136.Pp 137The 138.Fn scsi_device_hba_private_get 139function returns a data value registered via the 140.Fn scsi_device_hba_private_set 141function. 142If the 143.Fn scsi_device_hba_private_set 144was never called, 145.Dv NULL 146is returned. 147.Pp 148Upon successful completion, the 149.Fn scsi_device_unit_address 150returns a pointer to a character string with the device's unit address. 151Otherwise, 152.Dv NULL 153is returned. 154.Pp 155If the 156.Dv SCSI_HBA_ADDR_COMPLEX 157flag has not been set for the HBA structure or iport, then the 158.Fn scsi_address_device , 159.Fn scsi_device_hba_private_get , 160and 161.Fn scsi_device_unit_address 162functions return 163.Dv NULL . 164.Sh SEE ALSO 165.Xr iport 9 , 166.Xr tran_start 9E , 167.Xr scsi_hba_attach_setup 9F , 168.Xr scsi_address 9S , 169.Xr scsi_device 9S 170