Version 2.0.0

This version splits the core code of the ptio utility into a library
(libptio). No change to the ptio tool itself.

Signed-off-by: Damien Le Moal <[email protected]>

Author: damien-lemoal

.gitignore

@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: CC0-1.0
 #
-# Copyright (c) 2021 Western Digital Corporation or its affiliates.
+# SPDX-FileCopyrightText: 2024 Western Digital Corporation or its affiliates.
 
 # Object files
 *.o
@@ -28,7 +28,7 @@
 *.i*86
 *.x86_64
 *.hex
-src/ptio
+tools/ptio
 
 # Kernel compile files
 *.symvers

CONTRIBUTING

@@ -1,6 +1,6 @@
 SPDX-License-Identifier: CC0-1.0
 
-Copyright (C) 2021 Western Digital Corporation or its affiliates.
+SPDX-FileCopyrightText: 2024 Western Digital Corporation or its affiliates.
 
 This project embraces the Developer Certificate of Origin (DCO) for
 contributions. This means you must agree to the following prior to submitting

COPYING.GPL

@@ -1,4 +1,4 @@
-Copyright (C) 2021, Western Digital Corporation or its affiliates.
+SPDX-FileCopyrightText: 2024 Western Digital Corporation or its affiliates.
 
                     GNU GENERAL PUBLIC LICENSE
                        Version 2, June 1991

LICENSES/GPL-2.0-or-later.txt

@@ -1,4 +1,4 @@
-Copyright (C) 2019, Western Digital Corporation or its affiliates.
+SPDX-FileCopyrightText: 2024 Western Digital Corporation or its affiliates.
 
                     GNU GENERAL PUBLIC LICENSE
                        Version 2, June 1991

Makefile.am

@@ -1,35 +1,39 @@
 # SPDX-License-Identifier: CC0-1.0
 #
-# Copyright (C) 2024 Western Digital Corporation or its affiliates.
+# SPDX-FileCopyrightText: 2024 Western Digital Corporation or its affiliates.
 
 ACLOCAL_AMFLAGS = -I m4
 
-SUBDIRS = src man
+SUBDIRS = lib tools
 
-EXTRA_DIST = autogen.sh README.md COPYING.GPL CONTRIBUTING
+EXTRA_DIST = autogen.sh \
+             README.md \
+             LICENSES/GPL-2.0-or-later.txt
 
 if BUILD_RPM
 
 rpmdir = $(abs_top_builddir)/rpmbuild
 
-EXTRA_DIST += ptio.spec
+EXTRA_DIST += pt-tools.spec
 RPMARCH=`$(RPM) --eval %_target_cpu`
 
 rpm: dist
 	@echo "Building RPM package..."
 	@mkdir -p $(rpmdir)
 	$(RPMBUILD) -ta --clean \
 		-D "_topdir $(rpmdir)" \
-		-D "pkg_name ptio" \
+		-D "pkg_name pt-tools" \
 		-D "pkg_version $(PACKAGE_VERSION)" \
-		ptio-$(PACKAGE_VERSION).tar.gz
+		pt-tools-$(PACKAGE_VERSION).tar.gz
 	@mv -f $(rpmdir)/RPMS/$(RPMARCH)/*.rpm $(abs_top_builddir)
-	@mv -f $(rpmdir)/RPMS/noarch/*.rpm $(abs_top_builddir)
 	@mv -f $(rpmdir)/SRPMS/*.rpm $(abs_top_builddir)
 	@rm -rf $(rpmdir)
-	@rm -f ptio-$(PACKAGE_VERSION).tar.gz
+	@rm -f pt-tools-$(PACKAGE_VERSION).tar.gz
 else
 rpm:
 	@echo "Building RPM packages requires rpmbuild and rpm utilities"
 	exit 1
 endif
+
+CLEANFILES = *.rpm *.tar.gz
+DISTCLEANFILES = *.rpm *.tar.gz configure

README.md

@@ -1,9 +1,9 @@
-Copyright (C) 2024, Western Digital Corporation or its affiliates.
+SPDX-FileCopyrightText: 2024 Western Digital Corporation or its affiliates.
 
 # <p align="center">Passthrough IO tools</p>
 
-This project provides the *ptio* command line utility to execute SCSI or ATA
-passthrough commands.
+This project provides the *ptio* library and command line utility to execute
+SCSI or ATA passthrough commands.
 
 ## License
 
@@ -44,24 +44,25 @@ The following packages must be installed prior to compiling *pt-tools*.
 
 ## Compilation and Installation
 
-The following commands will compile the *ptio* utility.
+The following commands will compile the *ptio* library and command line utility.
 
 ```
 $ sh ./autogen.sh
 $ ./configure
 $ make
 ```
 
-To install the compiled executable file and the man page for the *ptio*
-utility, the following command can be used.
+To install the compiled library and the utilities and their man pages, the
+use the following command.
 
 ```
 $ sudo make install
 ```
 
-The default installation directory is /usr/bin. This default location can be
-changed using the configure script. Executing the following command displays
-the options used to control the installation path.
+The default installation directory is /usr/lib64 for the *libptio.so* library.
+The utilities executable files are installed by default under /usr/bin.
+This default location can be changed using the configure script. Executing the
+following command displays the options used to control the installation path.
 
 ```
 $ ./configure --help
@@ -79,13 +80,13 @@ $ ./configure
 $ make rpm
 ```
 
-Five RPM packages are built: a binary package providing *ptio* executable
-and its documentation, a source RPM package, a *debuginfo*
-RPM package and a *debugsource* RPM package, and an RPM package containing the
-test suite.
+Seven RPM packages are built: a binary package providing the *libptio* library,
+a package providing *libptio* header file for development, a binary package
+providing the *ptio* command line utility and its documentation, a source RPM
+package, two *debuginfo* RPM packages and a *debugsource* RPM package.
 
 The source RPM package can be used to build the binary and debug RPM packages
-outside of *pt-tools* source tree using the following command.
+outside of the *pt-tools* source tree using the following command.
 
 ```
 $ rpmbuild --rebuild pt-tools-<version>.src.rpm
@@ -96,9 +97,8 @@ $ rpmbuild --rebuild pt-tools-<version>.src.rpm
 Read the [CONTRIBUTING](CONTRIBUTING) file and send patches to:
 
 	Damien Le Moal <[email protected]>
-	Niklas Cassel <[email protected]>
 
-# *ptio* Command Line Tool
+# *ptio* Command Line Utility
 
 The *ptio* command line tool allows executing SCSI or ATA passthrough commands.
 

autogen.sh

@@ -2,6 +2,6 @@
 #
 # SPDX-License-Identifier: CC0-1.0
 #
-# Copyright (C) 2024 Western Digital Corporation or its affiliates.
+# SPDX-FileCopyrightText: 2024 Western Digital Corporation or its affiliates.
 
 exec autoreconf -f -i

configure.ac

@@ -1,28 +1,45 @@
 # SPDX-License-Identifier: CC0-1.0
 #
-# Copyright (C) 2024 Western Digital Corporation or its affiliates.
+# SPDX-FileCopyrightText: 2024 Western Digital Corporation or its affiliates.
 
-AC_INIT([pt-tools], [1.0.0],
+AC_INIT([pt-tools], [2.0.0],
 	[[email protected]],
 	[pt-tools], [https://bitbucket.wdc.com/users/damien.lemoal_wdc.com/repos/pt-tools/browse])
 
-AC_PREFIX_DEFAULT(/usr)
-AC_CONFIG_HEADERS([src/config.h])
-AC_CONFIG_MACRO_DIR([m4])
 AC_CONFIG_AUX_DIR([build-aux])
+AC_CANONICAL_TARGET
+AC_CONFIG_MACRO_DIR([m4])
+AC_CONFIG_HEADERS([include/config.h])
+AC_PREFIX_DEFAULT(/usr)
 AM_INIT_AUTOMAKE([-Wall foreign subdir-objects])
 AM_SILENT_RULES([yes])
 
+# Change default CFLAGS from "-g -O2" to "-O2" for regular builds.
+AC_ARG_ENABLE(debug,
+    [  --enable-debug          Compile with "-g" option],
+    [DBGCFLAGS="-g"],
+    [DBGCFLAGS="-O2"])
+CFLAGS="$CFLAGS $DBGCFLAGS"
+
+AC_PROG_CC
+AM_PROG_CC_C_O
+AC_PROG_INSTALL
+
 AC_USE_SYSTEM_EXTENSIONS
 AC_SYS_LARGEFILE
 
 m4_ifdef([AM_PROG_AR], [AM_PROG_AR])
 m4_pattern_allow([AM_PROG_AR])
 LT_INIT
 
-# Checks for programs.
-AC_PROG_CC
-AM_PROG_CC_C_O
+# Package version details: <major>.<minor>.<release>
+PACKAGE_VERSION_MAJOR=$(echo $PACKAGE_VERSION | awk -F. '{print $1}')
+PACKAGE_VERSION_MINOR=$(echo $PACKAGE_VERSION | awk -F. '{print $2}')
+PACKAGE_VERSION_RELEASE=$(echo $PACKAGE_VERSION | awk -F. '{print $3}')
+
+# libtool friendly library version format
+LIBPTIO_VERSION_LT=$PACKAGE_VERSION_MAJOR:$PACKAGE_VERSION_MINOR:$PACKAGE_VERSION_RELEASE
+AC_SUBST([LIBPTIO_VERSION_LT])
 
 # Checks for header files.
 AC_CHECK_HEADER(scsi/scsi.h, [],
@@ -39,9 +56,10 @@ AM_CONDITIONAL([BUILD_RPM],
 		[test "x$RPMBUILD" != xnotfound && test "x$RPM" != xnotfound])
 
 AC_CONFIG_FILES([
+	lib/libptio.pc
+	lib/Makefile
+	tools/Makefile
 	Makefile
-	man/Makefile
-	src/Makefile
 ])
 
 AC_OUTPUT

include/libptio/ptio.h

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+/*
+ * SPDX-FileCopyrightText: 2024 Western Digital Corporation or its affiliates.
+ *
+ * Authors: Damien Le Moal ([email protected])
+ */
+#ifndef LIBPTIO_H
+#define LIBPTIO_H
+
+#include <stdint.h>
+#include <inttypes.h>
+#include <stdbool.h>
+#include <sys/types.h>
+#include <scsi/sg.h>
+
+/*
+ * CDB types.
+ */
+enum ptio_cdb_type {
+	PTIO_CDB_NONE = 0,
+	PTIO_CDB_SCSI,
+	PTIO_CDB_ATA,
+};
+
+/*
+ * Command data transfer direction.
+ */
+enum ptio_dxfer {
+	PTIO_DXFER_NONE = 0,
+	PTIO_DXFER_FROM_DEV,
+	PTIO_DXFER_TO_DEV,
+};
+
+/*
+ * Device flags.
+ */
+#define PTIO_VERBOSE			(1 << 0)
+#define PTIO_ATA			(1 << 1)
+#define PTIO_INFO			(1 << 2)
+#define PTIO_REVALIDATE			(1 << 3)
+
+#define PTIO_VENDOR_LEN	9
+#define PTIO_ID_LEN	17
+#define PTIO_REV_LEN	5
+
+#define PTIO_SAT_VENDOR_LEN	9
+#define PTIO_SAT_PRODUCT_LEN	17
+#define PTIO_SAT_REV_LEN	5
+
+#define PTIO_SENSE_MAX_LENGTH	64
+#define PTIO_CDB_MAX_SIZE	32
+
+struct ptio_dev {
+	/* Device file path and basename */
+	char			*path;
+	char			*name;
+
+	/* Device file descriptor */
+	int			fd;
+
+	/* Device info */
+	unsigned int		flags;
+
+	unsigned int		acs_ver;
+
+	char			vendor[PTIO_VENDOR_LEN];
+	char			id[PTIO_ID_LEN];
+	char			rev[PTIO_REV_LEN];
+	char			sat_vendor[PTIO_SAT_VENDOR_LEN];
+	char			sat_product[PTIO_SAT_PRODUCT_LEN];
+	char			sat_rev[PTIO_SAT_REV_LEN];
+
+	size_t			logical_block_size;
+	size_t			physical_block_size;
+	unsigned long long	capacity;
+};
+
+struct ptio_cmd {
+	uint8_t			cdb[PTIO_CDB_MAX_SIZE];
+	size_t			cdbsz;
+	enum ptio_cdb_type	cdbtype;
+
+	uint8_t			*buf;
+	size_t			bufsz;
+	enum ptio_dxfer		dxfer;
+
+	sg_io_hdr_t		io_hdr;
+
+	uint8_t			sense_buf[PTIO_SENSE_MAX_LENGTH];
+	uint8_t			sense_key;
+	uint16_t		asc_ascq;
+};
+
+extern int ptio_open_dev(struct ptio_dev *dev, enum ptio_dxfer dxfer);
+extern void ptio_close_dev(struct ptio_dev *dev);
+
+extern int ptio_revalidate_dev(struct ptio_dev *dev);
+extern int ptio_get_dev_information(struct ptio_dev *dev);
+extern const char *ptio_ata_acs_ver(struct ptio_dev *dev);
+
+extern int ptio_parse_cdb(char *cdb_str, uint8_t *cdb);
+
+extern uint8_t *ptio_alloc_buf(size_t bufsz);
+extern uint8_t *ptio_read_buf(char *path, size_t *bufsz);
+extern int ptio_write_buf(char *path, uint8_t *buf, size_t bufsz);
+extern void ptio_print_buf(uint8_t *buf, size_t bufsz);
+
+extern int ptio_exec_cmd(struct ptio_dev *dev, struct ptio_cmd *cmd,
+		uint8_t *cdb, size_t cdbsz, enum ptio_cdb_type cdb_type,
+		uint8_t *buf, size_t bufsz, enum ptio_dxfer dxfer);
+
+static inline bool ptio_dev_is_ata(struct ptio_dev *dev)
+{
+	return dev->flags & PTIO_ATA;
+}
+
+#endif /* LIBPTIO_H */

include/stamp-h1

@@ -0,0 +1 @@
+timestamp for include/config.h