| Introduction |
| ============ |
| The FreeBSD port of sg3_utils contains those utilities that are _not_ |
| specific to Linux. In some cases the FreeBSD camcontrol command supplies |
| similar functionality; for example 'sg_map' is similar to |
| 'camcontrol devlist'. |
| |
| The dd variants from the sg3_utils package (e.g. sg_dd) rely on too many |
| Linux idiosyncrasies to be easily ported. A new package called 'ddpt' |
| contains a utility with similar functionality to sg_dd and ddpt is available |
| for FreeBSD. |
| |
| Supported Utilities |
| =================== |
| Here is a list of utilities that have been ported: |
| sg_bg_ctl |
| sg_compare_and_write |
| sg_decode_sense |
| sg_format |
| sg_get_config |
| sg_get_elem_status |
| sg_get_lba_status |
| sg_ident |
| sg_inq [dropped ATA IDENTIFY DEVICE capability] |
| sg_logs |
| sg_luns |
| sg_modes |
| sg_opcodes |
| sg_persist |
| sg_prevent |
| sg_raw |
| sg_rdac |
| sg_read_block_limits |
| sg_read_buffer |
| sg_read_long |
| sg_readcap |
| sg_reassign |
| sg_referrals |
| sg_rep_pip |
| sg_rep_zones |
| sg_requests |
| sg_rmsn |
| sg_rtpg |
| sg_safte |
| sg_sanitize |
| sg_sat_identify |
| sg_sat_phy_event |
| sg_sat_set_features |
| sg_seek |
| sg_senddiag |
| sg_ses |
| sg_start |
| sg_stpg |
| sg_stream_ctl |
| sg_sync |
| sg_turs |
| sg_verify |
| sg_unmap |
| sg_vpd |
| sg_wr_mode |
| sg_write_buffer |
| sg_write_long |
| sg_write_same |
| sg_write_verify |
| sg_write_x |
| sg_zone |
| |
| Most utility names are indicative of the main SCSI command |
| that they execute. Some utilities are slightly higher level, for |
| example sg_ses fetches SCSI Enclosure Services (SES) status pages and |
| can send control pages. Each utility has a man page (placed in |
| section 8). An overview of sg3_utils can be found at: |
| https://sg.danny.cz/sg/sg3_utils.html . |
| A copy of the "sg3_utils.html" file is in the "doc" subdirectory. |
| |
| This package on FreeBSD can be built with either GNU Autotools or |
| cmake. |
| |
| Autotool build |
| ============== |
| The executables and library can be built from the source code in |
| the tarball and installed with the familiar sequence: |
| |
| # cd <top-level-directory-of-source-package> |
| # ./autogen.sh |
| # ./configure |
| # make |
| # make install |
| |
| The last step requires root permission. After the make (fourth step in |
| the above sequence), the executables will be in the src sub-directory |
| and the library (shared object) in the lib sub-directory. |
| The object files, executables, and library can be removed with: |
| |
| # cd <top-level-directory-of-source-package> |
| # make clean |
| |
| All those plus the artifacts of the build system can be removed with |
| 'make distclean'. Package options can be viewed with the third step |
| of the above sequence changed to './configure --help' . |
| |
| There are generic instructions on configure and friends in the INSTALL file. |
| There is a brief overview of this package in the README file. There is a |
| more detailed description in the README.details file. |
| |
| Some man pages have examples which use Linux device names which |
| hopefully will not confuse the FreeBSD users. |
| |
| The above build sequence does an "in-tree" build which is so-called because |
| it scatters artifacts of the build in the same directories as the |
| original source files (and build instructions). An "out-of-tree" |
| build can be done as follows: |
| |
| # cd <top-level-directory-of-source-package> |
| # ./autogen.sh |
| # mkdir build |
| # cd build |
| # ../configure |
| # make |
| # make install |
| |
| Notice the "double dot" prefixing 'configure' to execute the configure script |
| in the _parent_ of the build directory. Now all executables, compressed |
| manpages, library and other (obscure) build artifacts are under the build |
| sub-directory and can all be removed with: |
| |
| # cd <top-level-directory-of-source-package> |
| # rm -rf build |
| |
| cmake build |
| =========== |
| cmake is a relatively newer build system than autotools (circa 2000 compared |
| 1991 for the first autoconf release). At this time autotools are still the |
| backbone of Unix based application builds, especially for C and C++ with |
| few new features being added, but the tools remain stable and well |
| maintained. cmake seems to be moving much faster (and maybe breaking |
| things). cmake now has the ability to package projects for FreeBSD (as well |
| as Linux deb and rpm formats). The steps of a cmake build sequence are |
| similar to those of Autotools shown in the above section. Here is a simple |
| "in-tree" build: |
| |
| # cd <top-level-directory-of-source-package> |
| # cmake . |
| # cmake --build . |
| # make install |
| |
| The last step requires root permission. After the 'cmake --build . ' |
| (third step in the above sequence), the executables will be in the src |
| sub-directory and the library (shared object) in the lib sub-directory. |
| The object files, executables, and library can be removed with: |
| |
| # cd <top-level-directory-of-source-package> |
| # make clean |
| |
| Cmake does not have the equivalent of 'make distclean' so the author |
| wrote a small script to do the same thing, visiting all sub-directories |
| containing build artifacts: |
| |
| # cd <top-level-directory-of-source-package> |
| # ./cmake_del_artifacts.sh |
| |
| An "out-of-tree" cmake build and package can be done as follows: |
| |
| # cd <top-level-directory-of-source-package> |
| # cmake -S . -B build |
| # cd build |
| # cmake --build . |
| # cpack . |
| |
| That should generate a FreeBSD ".pkg" file in the build sub-directory. |
| All the artifacts (including the ".pkg" file) can be removed in the |
| same way as an autotools "out-of-tree" build: |
| |
| # cd <top-level-directory-of-source-package> |
| # rm -rf build |
| |
| The "artifact" sub-directory doesn't need to be called "build", that |
| is just a useful convention. For example: |
| |
| # cd <top-level-directory-of-source-package> |
| # cmake -S . -B build-static DBUILD_SHARED_LIBS=OFF |
| # cd build-static |
| # cmake --build . |
| # .... |
| |
| That will build (larger) executables that don't depend on any runtime |
| libraries being available. |
| To list the available package options: |
| |
| # cd <top-level-directory-of-source-package> |
| # cmake -LH . |
| |
| |
| Device naming |
| ============= |
| In FreeBSD disks have block names like '/dev/da0' with a corresponding |
| pass-through device name like '/dev/pass0'. Use this command: |
| "camcontrol devlist" to see that SCSI devices available. To list NVMe |
| devices: "nvmecontrol devlist" can be used. Any many, but not all |
| contexts, the device name can be used without the '/dev/' prefix. |
| FreeBSD is relatively unique in this respect and support for this |
| abbreviated form has been broken in this package and fixed in |
| sg3_utils release 1.46 . |
| |
| Device naming for NVMe is a bit more complex. Controllers have names |
| like /dev/nvme0 and namespaces /dev/nvme0ns1 . Partitions are not |
| supported on /dev/nvme0ns1 type nodes. Instead there are /dev/nvd0 |
| and /dev/nvd0p<m> where <m> is th partition number starting at 1. |
| The nvd driver (written by Intel) is not CAM compatible and has its |
| own utility nvmecontrol which has similar capabilities as camcontrol |
| has for CAM devices. In FreeBSD release 12 the nda driver was |
| introduced with names like /dev/nda0 and /dev/nda0n<m>. The difference |
| is that nda is CAM compatible. From the point of view of this package, |
| the nda driver is preferred as CAM supports NVMe command timeouts and |
| the error processing is more mature. |
| |
| FreeBSD installation |
| ==================== |
| The traditional './configure ; make ; make install' sequence from the |
| top level of the unpacked tarball will work on FreeBSD. But the man pages |
| will be placed under the /usr/local/share/man directory which unfortunately |
| is not on the standard manpath. One solution is to add this path by |
| creating a file with a name like local_share.conf in the |
| /usr/local/etc/man.d/ directory and placing this line in it: |
| MANPATH /usr/local/share/man |
| |
| FreeBSD 9.0 has a "ports" entry for sg3_utils under the |
| /usr/ports/sysutils directory. It points to version 1.28 of sg3_utils |
| which is now a bit dated. It could be used as a template to point |
| to more recent versions. |
| |
| kFreeBSD |
| ======== |
| sg3_utils can be built into a Debian package for kFreeBSD using the |
| ./debian_build.sh script in the top level directory. This has been tested |
| with Debian 6.0 release. |
| |
| Details |
| ======= |
| Most of the ported utilities listed above use SCSI command functions |
| declared in sg_cmds_*.h headers . Those SCSI command functions are |
| implemented in the corresponding ".c" files. The ".c" files pass SCSI |
| commands to the host operating system via an interface declared in sg_pt.h . |
| There are currently five implementations of that interface depending on |
| the host operating system: |
| - sg_pt_linux.c |
| - sg_pt_freebsd.c |
| - sg_pt_osf1.c [Tru64] |
| - sg_pt_win32.c |
| - sg_pt_solaris.c |
| |
| The sg_pt_freebsd.c file uses the FreeBSD CAM SCSI pass through mechanism. |
| Hence only FreeBSD device nodes that support CAM can be used. These can be |
| viewed with the "camcontrol devlist" command. To access ATAPI devices (e.g. |
| ATAPI DVD drives) the kernel may need to be configured with the "atapicam" |
| device. |
| |
| Attempts to send SCSI commands with data-in or data-out buffers around 64 KB |
| and larger failed on a FreeBSD 7.0 with an "argument list too long" error |
| message. There is an associated kernel message (viewable with dmesg) that an |
| attempt has been made to map <n> bytes which is greater than |
| DFLTPHYS(65536). Still a problem in FreeBSD 8.1 . Due to CAM overhead the |
| largest power of 2 that can fit through with one command is 32768 bytes (32 |
| KB). |
| |
| FreeBSD 15.0 is the most recent version of FreeBSD tested with these |
| utilities. |
| |
| |
| Douglas Gilbert |
| 24th May 2026 |
