1Introduction 2============ 3The FreeBSD port of sg3_utils contains those utilities that are _not_ 4specific to Linux. In some cases the FreeBSD camcontrol command supplies 5similar functionality; for example 'sg_map' is similar to 6'camcontrol devlist'. 7 8The dd variants from the sg3_utils package (e.g. sg_dd) rely on too many 9Linux idiosyncrasies to be easily ported. A new package called 'ddpt' 10contains a utility with similar functionality to sg_dd and ddpt is available 11for FreeBSD. 12 13Supported Utilities 14=================== 15Here is a list of utilities that have been ported: 16 sg_bg_ctl 17 sg_compare_and_write 18 sg_decode_sense 19 sg_format 20 sg_get_config 21 sg_get_elem_status 22 sg_get_lba_status 23 sg_ident 24 sg_inq [dropped ATA IDENTIFY DEVICE capability] 25 sg_logs 26 sg_luns 27 sg_modes 28 sg_opcodes 29 sg_persist 30 sg_prevent 31 sg_raw 32 sg_rdac 33 sg_read_block_limits 34 sg_read_buffer 35 sg_read_long 36 sg_readcap 37 sg_reassign 38 sg_referrals 39 sg_rep_pip 40 sg_rep_zones 41 sg_requests 42 sg_rmsn 43 sg_rtpg 44 sg_safte 45 sg_sanitize 46 sg_sat_identify 47 sg_sat_phy_event 48 sg_sat_set_features 49 sg_seek 50 sg_senddiag 51 sg_ses 52 sg_start 53 sg_stpg 54 sg_stream_ctl 55 sg_sync 56 sg_turs 57 sg_verify 58 sg_unmap 59 sg_vpd 60 sg_wr_mode 61 sg_write_buffer 62 sg_write_long 63 sg_write_same 64 sg_write_verify 65 sg_write_x 66 sg_zone 67 68Most utility names are indicative of the main SCSI command 69that they execute. Some utilities are slightly higher level, for 70example sg_ses fetches SCSI Enclosure Services (SES) status pages and 71can send control pages. Each utility has a man page (placed in 72section 8). An overview of sg3_utils can be found at: 73https://sg.danny.cz/sg/sg3_utils.html . 74A copy of the "sg3_utils.html" file is in the "doc" subdirectory. 75 76 77The executables and library can be built from the source code in 78the tarball and installed with the familiar 79"./configure ; make ; make install" sequence. If this fails try 80running the "./autogen.sh" script prior to that sequence. There 81are generic instruction on configure and friend in the INSTALL file. 82 83Some man pages have examples which use Linux device names which 84hopefully will not confuse the FreeBSD users. 85 86Device naming 87============= 88In FreeBSD disks have block names like '/dev/da0' with a corresponding 89pass-through device name like '/dev/pass0'. Use this command: 90"camcontrol devlist" to see that SCSI devices available. To list NVMe 91devices: "nvmecontrol devlist" can be used. Any many, but not all 92contexts, the device name can be used without the '/dev/' prefix. 93FreeBSD is relatively unique in this respect and support for this 94abbreviated form has been broken in this package and fixed in 95sg3_utils release 1.46 . 96 97Device naming for NVMe is a bit more complex. Controllers have names 98like /dev/nvme0 and namespaces /dev/nvme0ns1 . Partitions are not 99supported on /dev/nvme0ns1 type nodes. Instead there are /dev/nvd0 100and /dev/nvd0p<m> where <m> is th partition number starting at 1. 101The nvd driver (written by Intel) is not CAM compatible and has its 102own utility nvmecontrol which has similar capabilities as camcontrol 103has for CAM devices. In FreeBSD release 12 the nda driver was 104introduced with names like /dev/nda0 and /dev/nda0n<m>. The difference 105is that nda is CAM compatible. From the point of view of this package, 106the nda driver is preferred as CAM supports NVMe command timeouts and 107the error processing is more mature. 108 109FreeBSD installation 110==================== 111The traditional './configure ; make ; make install' sequence from the 112top level of the unpacked tarball will work on FreeBSD. But the man pages 113will be placed under the /usr/local/share/man directory which unfortunately 114is not on the standard manpath. One solution is to add this path by 115creating a file with a name like local_share.conf in the 116/usr/local/etc/man.d/ directory and placing this line in it: 117 MANPATH /usr/local/share/man 118 119FreeBSD 9.0 has a "ports" entry for sg3_utils under the 120/usr/ports/sysutils directory. It points to version 1.28 of sg3_utils 121which is now a bit dated. It could be used as a template to point 122to more recent versions. 123 124kFreeBSD 125======== 126sg3_utils can be built into a Debian package for kFreeBSD using the 127./build_debian.sh script in the top level directory. This has been tested 128with Debian 6.0 release. 129 130Details 131======= 132Most of the ported utilities listed above use SCSI command functions 133declared in sg_cmds_*.h headers . Those SCSI command functions are 134implemented in the corresponding ".c" files. The ".c" files pass SCSI 135commands to the host operating system via an interface declared in sg_pt.h . 136There are currently five implementations of that interface depending on 137the host operating system: 138 - sg_pt_linux.c 139 - sg_pt_freebsd.c 140 - sg_pt_osf1.c [Tru64] 141 - sg_pt_win32.c 142 - sg_pt_solaris.c 143 144The sg_pt_freebsd.c file uses the FreeBSD CAM SCSI pass through mechanism. 145Hence only FreeBSD device nodes that support CAM can be used. These can be 146viewed with the "camcontrol devlist" command. To access ATAPI devices (e.g. 147ATAPI DVD drives) the kernel may need to be configured with the "atapicam" 148device. 149 150Attempts to send SCSI commands with data-in or data-out buffers around 64 KB 151and larger failed on a FreeBSD 7.0 with an "argument list too long" error 152message. There is an associated kernel message (viewable with dmesg) that an 153attempt has been made to map <n> bytes which is greater than 154DFLTPHYS(65536). Still a problem in FreeBSD 8.1 . Due to CAM overhead the 155largest power of 2 that can fit through with one command is 32768 bytes (32 156KB). 157 158FreeBSD 9.0 is the most recent version of FreeBSD tested with these 159utilities. 160 161 162 163Douglas Gilbert 1641st May 2021 165