| 1 |
Introduction |
| 2 |
------------ |
| 3 |
ddpt is a utility for copying files like its namesake, the Unix dd command. |
| 4 |
ddpt is specialized for files that are actually block devices. And if |
| 5 |
those block devices understand SCSI commands then the copy can be done by |
| 6 |
using either SCSI READ or WRITE commands (or both). This latter facility |
| 7 |
is done using a pass-through interface that bypasses the normal operating |
| 8 |
system block handling. This can give very fine-grained control over the |
| 9 |
copy process. |
| 10 |
|
| 11 |
ddpt also supports two forms of offloaded copies, one based on the EXTENDED |
| 12 |
COPY command introduced in T10's SPC-2 standard. EXTENDED COPY is often |
| 13 |
abbreviated to XCOPY or xcopy. As new forms of offloaded copy have been |
| 14 |
added (especially in SPC-4) the original XCOPY is now called XCOPY(LID1) |
| 15 |
with lot of new feature added to XCOPY(LID4). A subset of XCOPY(LID4) which |
| 16 |
only supports disk to disk, token based copies, has the market name of ODX. |
| 17 |
So ddpt supports the original XCOPY(LID1) and uses the term "xcopy" to |
| 18 |
refer to it. ddpt now also supports ODX and uses the term "odx" to refer |
| 19 |
to it. |
| 20 |
|
| 21 |
ddptctl is a helper/auxiliary for the ddpt utility. ddptctl mainly supplies |
| 22 |
extra functionality for ODX. |
| 23 |
|
| 24 |
This utility was originally written for Linux. It has been ported to FreeBSD, |
| 25 |
Solaris and Windows. |
| 26 |
|
| 27 |
Relationship to sg3_utils |
| 28 |
------------------------- |
| 29 |
The sg3_utils (version 1.33) package contains several utilities that mimic |
| 30 |
the standard Unix dd command. Currently those utilities are sg_dd, sgm_dd, |
| 31 |
sgp_dd and sg_xcopy. Even though most of the other utilities in the |
| 32 |
sg3_utils package are ported to other operating systems, sg_dd and friends |
| 33 |
are not ported since they are too tightly bound to Linux and some of the |
| 34 |
idiosyncrasies of its SCSI generic (sg) and bsg drivers and the associated |
| 35 |
SG_IO ioctl. So the ddpt utility drops some Linux specific features while |
| 36 |
adding some more general features (e.g. write sparing). An attempt has also |
| 37 |
been made to simplify the command line syntax which is still based on the |
| 38 |
distinctive dd command line syntax. Note that the dd command line syntax is |
| 39 |
unlike any other Unix command (probably imported from some IBM OS many |
| 40 |
years ago). |
| 41 |
|
| 42 |
This package shares code with sg3_utils (version 1.38). With the subversion |
| 43 |
revision control system this is done by having ddpt's "include/" and "lib/" |
| 44 |
sub-directories pointing to the correspondingly named directories in the |
| 45 |
sg3_utils package using the "svn:externals" property. These two "external" |
| 46 |
directories include more files than ddpt uses. The excess files include |
| 47 |
"lib/Makefile.am" and "lib/Makefile.in". The "Makefile.am" in ddpt's "src/" |
| 48 |
directory does the main part of the build. When the tarball is generated |
| 49 |
for this utility, various files are "exported" out of the subversion |
| 50 |
repository and "svn:externals" redirection is no longer visible (but the |
| 51 |
unused files are visible). |
| 52 |
|
| 53 |
The ddpt executable may or may not be built depending on the libsgutils |
| 54 |
(shared) library. Currently the ./configure rules are looking for a library |
| 55 |
called libsgutils2.a or libsgutils2.so . In Debian those libraries are found |
| 56 |
only in the libsgutils2-dev package, not the libsgutils2 package. If one of |
| 57 |
those libraries is detected then ddpt will be built depending on libsgutils |
| 58 |
(check 'ldd ddpt'). If neither of those libraries is detected at build time, |
| 59 |
then the ddpt executable built will compile and link the relevant code from |
| 60 |
its "include/" and "lib/" subdirectories. |
| 61 |
|
| 62 |
Documentation |
| 63 |
------------- |
| 64 |
The utility outputs a usage message when the "--help" (or '-?') option is |
| 65 |
given. Many syntax errors also result in the usage message being printed. |
| 66 |
There is also a man page which is in section 8 (administration and privileged |
| 67 |
commands). It can be accessed with "man ddpt" once this package is installed. |
| 68 |
Prior to installation the man page can be viewed from this package's main |
| 69 |
directory with "man doc/ddpt.8". |
| 70 |
|
| 71 |
There is a web page at https://sg.danny.cz/sg/ddpt.html and a copy of that |
| 72 |
html file is placed in the "doc" directory. |
| 73 |
|
| 74 |
Build infrastructure |
| 75 |
-------------------- |
| 76 |
This package uses the automake and autoconf tools. The generating files |
| 77 |
(scripts) are configure.ac, Makefile.am, doc/Makefile.am, src/Makefile.am and |
| 78 |
autogen.sh . The autogen.sh script only needs to be executed if one of the |
| 79 |
other generating files in the above list is changed. |
| 80 |
|
| 81 |
There is a rpm "spec" file in the main directory: ddpt.spec . There are Debian |
| 82 |
build files in the "debian" directory and a script called build_debian.sh in |
| 83 |
the main directory. Amongst other things debian builds are sensitive to the |
| 84 |
value in the debian/compat file. If it contains "7" then it works on lenny and |
| 85 |
gives warning on squeeze (but fails on the earlier etch). |
| 86 |
|
| 87 |
The ./configure script supports these extra options: |
| 88 |
- '--disable-libsgutils' stops the build using the libsgutils library |
| 89 |
if it is found. Instead the copy of those files found under the |
| 90 |
include and lib directories is used. |
| 91 |
- '--disable-linuxbsg' does nothing and is only present for backward |
| 92 |
compatibility |
| 93 |
for testing and should no longer be necessary. |
| 94 |
- '--disable-scsistrings' excludes the asc/ascq and command name strings |
| 95 |
(defined by SCSI/T10) in an attempt to reduce the size of executables. |
| 96 |
- '--disable-nvme-supp' instructs the build to ignore the added NVMe |
| 97 |
detection code added in version 0.96 |
| 98 |
- '--disable-fast-lebe' . A header called sg_unaligned.h has several |
| 99 |
implementations of inline functions for alignment moves and byte |
| 100 |
swapping. The default is to use little and big endian specific code that |
| 101 |
depends on the non-standard bswap_<16|32|64> functions. This option |
| 102 |
forces the use of more generic implementations that depend on C shift |
| 103 |
operators. |
| 104 |
|
| 105 |
At the request of some Linux distributions, this package will attempt to |
| 106 |
use the libsgutils library (name varies between distributions) at build time. |
| 107 |
If that library is old then the link at the end of build can fail. One way |
| 108 |
to sidestep that problem is by using './configure --disable-libsgutils'. |
| 109 |
Another way is to remove the "dev" version of the libsgutils library package |
| 110 |
(e.g. 'libsgutils2-dev' on a Debian based distribution). |
| 111 |
|
| 112 |
License |
| 113 |
------- |
| 114 |
This utility is covered by a FreeBSD license also known as the BSD 3-clause |
| 115 |
license (see Wikipedia). The intention of the author is that both open |
| 116 |
source and commercial entities can re-use this code. Naturally attribution |
| 117 |
and improvement/bug feedback are encouraged. |
| 118 |
|
| 119 |
Notes |
| 120 |
----- |
| 121 |
Generic information about building this package (i.e. './configure ; make; |
| 122 |
make install') can be found in the INSTALL file. The contents of COPYING is a |
| 123 |
FreeBSD license (rather than the GPL v2 found in the usual template). |
| 124 |
|
| 125 |
Linux port |
| 126 |
---------- |
| 127 |
The utility can be used on any storage device. |
| 128 |
|
| 129 |
To use the "pt" interface the device needs to support the SG_IO ioctl. In |
| 130 |
the Linux 2.4 series that is only the scsi generic (i.e. /dev/sg* ) |
| 131 |
device nodes. In the Linux 2.6 and 3 series the supported device nodes have |
| 132 |
expanded to all other SCSI device nodes (e.g. /dev/sd* and /dev/sr*) |
| 133 |
plus block devices such as /dev/hdc when the associated device is a |
| 134 |
DVD drive. The man page and sg.danny.cz/sg/ddpt.html web page examples use |
| 135 |
Linux device node names. |
| 136 |
|
| 137 |
FreeBSD port |
| 138 |
------------ |
| 139 |
See README.freebsd |
| 140 |
|
| 141 |
Solaris port |
| 142 |
------------ |
| 143 |
See README.solaris |
| 144 |
|
| 145 |
Win32 port |
| 146 |
---------- |
| 147 |
See README.win32 |
| 148 |
|
| 149 |
|
| 150 |
Douglas Gilbert |
| 151 |
3rd March 2020 |