forked from westerndigitalcorporation/libzbc
-
Notifications
You must be signed in to change notification settings - Fork 0
ZBC device manipulation library
License
mmilburn/libzbc
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
Copyright (C) 2009-2014, HGST, Inc. I. Introduction =============== I.1. Overview ------------- libzbc is a simple library providing functions for manipulating Zoned Block Command (ZBC) and Zoned-device ATA command set (ZAC) disks. Its implemented is compliant with the current version of the ZBC and ZAC standard drafts defined by INCITS technical committee T10 and T13. At the time of this writing, the current version of the ZBC standard draft is Rev 01c (released on 2014/10/17) and Rev 00 of the ZAC standard draft (released on 2014/06/23). In addition to supporting ZBC and ZAC disks, libzbc also implements an emulation mode allowing emulating the behavior of a zoned disks using a regular file or a raw standard block device. Several example applications using libzbc are available under the tools directory. I.2. License ------------ libzbc is distributed under the terms of the of the BSD 2-clause license ("Simplified BSD License" or "FreeBSD License"). A copy of this license with the library copyright can be found in the COPYING.BSD file. With the exception of the linear key value store (lkvs) tool, all example applications under the tools directory are distributed under the terms of the GNU Lesser General Public License version 3, or any later version. A copy of version 3 this license can be found in the COPYING.LESSER file. The lkvs tool is distributed under the terms of the of the GNU General Public License version 3, or any later version. A copy of version 3 of this license can be found in the COPYING.GPL file. libzbc and all its example applications are distributed "as is," without technical support, and WITHOUT ANY WARRANTY, without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Along with libzbc, you should have received a copy of the BSD 2-clause license, GNU General Public License and og the GNU Lesser General Public License. If not, please see <http://opensource.org/licenses/BSD-2-Clause> and <http://www.gnu.org/licenses/>. I.3. Contact and Bug Reports ---------------------------- Please contact Damine Le Moal (damien.lemoal@hgst.com) and Adam Manzanares (adam.manzanares@hgst.com) to report problems. II. Compilation and installation ================================ II.1. Compilation ----------------- To compile the library and all example applications, execute the following commands. > sh ./autogen.sh > ./configure > make II.2. Installation ------------------ To install the library and all example applications, as root, execute the following command. > make install The library files are installed in /usr/lib. The library header files are installed in /usr/include/libzbc The executable files for the example applications are installed in /usr/bin. III. Usage ========== III.1 Kernel Version -------------------- libzbc functions operate using device handles which are obtain by executing the zbc_open function. This function argument can be a regular file or a legacy raw block device file for operating in emulation mode, or the SG node device file (/dev/sg<x>) of the target ZBC or ZAC disk.s such some level of kernel support is required for these SG nodes to exist. Linux kernel introduced support for ZBC device type with version 3.17. Any kernel with version 3.17 and above will thus recognize SAS ZBC devices and create an SG node for these disks (but not a regular block device). As of kernel version 3.17.4, ZAC device types are not yet recognized and no SG device node is created for those devices. To allow using ZAC disks, the following patches must be used. https://git.kernel.org/cgit/linux/kernel/git/hare/scsi-devel.git/commit/?h=zac.v2&id=ec07b9a8b168499c6009bf5bfe925a0a10b49729 https://git.kernel.org/cgit/linux/kernel/git/hare/scsi-devel.git/commit/?h=zac.v2&id=02582e1667f05b0c64f2998877216e395e7fda52 https://git.kernel.org/cgit/linux/kernel/git/hare/scsi-devel.git/commit/?h=zac.v2&id=70eb02d6eca2c0706b388a3971f9e156bac092d7 These patches are included in kernel 3.19 development tree. https://git.kernel.org/cgit/linux/kernel/git/tj/libata.git/log/?h=for-3.19 III.2 Library Functions ----------------------- libzbc exports the following functions. +------------------------------+------------------------------------+ | Function | Description | +==============================+====================================+ | zbc_open | Open a ZBC device | +------------------------------+------------------------------------+ | zbc_close | Close a ZBC device | +------------------------------+------------------------------------+ | zbc_get_device_info | Get sector and size information | +------------------------------+------------------------------------+ | zbc_report_zones | Get device zone information | +------------------------------+------------------------------------+ | zbc_report_nr_zones | Get the number of zones | +------------------------------+------------------------------------+ | zbc_list_zones | Get device zone information | +------------------------------+------------------------------------+ | zbc_reset_write_pointer | Reset a zone write pointer | +------------------------------+------------------------------------+ | zbc_reset_all_write_pointers | Reset all zones write pointer | +------------------------------+------------------------------------+ | zbc_pread | Read data from a zone | +------------------------------+------------------------------------+ | zbc_pwrite | Write data to a zone | +------------------------------+------------------------------------+ | zbc_set_log_level | Set the library log level | +------------------------------+------------------------------------+ | zbc_flush | Flush data to disk | +------------------------------+------------------------------------+ More detailed information on these functions is available through the comments in the file include/libzbc/zbc.h The current implementation of these functions is NOT thread safe. In particular, iconcurrent write operations by multiple threads to the same zone may result in write errors without write ordering control by the application. III.3 Native Mode ----------------- As of version 3.16.x, the standard Linux kernel does not support ZBC host-managed device type 14h. As a result, such device will not be avalaible as a regular block device (with a device file name /dev/sdx). However, ZBC host-managed disks will be accessible through the SG driver using the device SG node (/dev/sgx device file). Opening a native ZBC disk with libzbc thus needs to be done by specifying the device SG node. Further accesses (report zones, reset zone write pointer, etc) can then proceed using the device handle provided by the zbc_open function. III.4 Emulation Mode -------------------- libzbc can emulate host-managed ZBC disks operation using a regular file or a raw standard block device (regular disk or loopback device). The use of the library in such case is identical to the native mode case, assuming that the emulated device is first configured by executing teh zbc_set_zones tool (see next section). IV. Example Applications ======================== Under the tools directory, several simple applications are available as examples. These appliations are as follows. IV.1. gzbc (tools/gui) ---------------------- A simple graphical interface showing zone information of a zoned device. It alos displays the write status (write pointer position) of zones graphically using color coding (red for written space and green for unwritten space). IV.2. zbc_report_zones (tools/report_zones/) -------------------------------------------- This application illustrates the use of the zone reporting functions (zbc_report_zones, zbc_report_nr_zones, zbc_list_zones). It obtains the zone information of a device and displays it in readable form on the standard output. IV.3. zbc_reset_write_ptr (tools/reset_write_ptr/) -------------------------------------------------- This application illustrates the use of the zbc_reset_write_pointer function allowing resetting the write pointer of a zone to the start LBA of the zone. IV.4. zbc_read_zone (tools/read_zone/) -------------------------------------- This application reads data from a zone, up to the zone write pointer location and either send the read data to the standard output or copy the data to a regular file. It implementation uses the function zbc_pread. IV.5. zbc_write_zone (tools/write_zone/) ---------------------------------------- This application illustrates the use of the zbc_pwrite function which write data to a zone at the zone write pointer location. IV.6. zbc_set_zones (tools/set_zones/) -------------------------------------- This application can be used to initialize the ZBC emulation mode for a regular file or a raw standard block device. IV.7. zbc_set_write_ptr (tools/set_write_ptr/) ---------------------------------------------- This application can be used to set the write pointer of a zone of an emulated ZBC device to any LBA value (within the range of the specified zone). It is intended for testing purposes only and is not valid for native ZBC devices. IV.8. lkvs (tools/lkvs/) ------------------------ ### Purpose ZBC drives have three types of zones: conventional, sequential preferred, and sequential only. This project aims to create a key/value store on top of a drive that contains seqential only zones exclusively. I.e. all writes to the drive must be linear within the LBA space of one zone. This work is intended to be a demonstration of how to build systems software on top of a ZBC drive. This is not a full featured key/value store and we do not intend it to be so. The main limitations of the current design is that we require all of the metadata for the KV store to fit into main memory and there is no garbage collection built into LKVS. Therfor, updates to an existing key are not supported. If you want to build the python or java bindings please pass the option of --with-pybind or --with-javabind to the configure script, to build the corresponding bindings. ### How To Run LKVS tests Must be done after make install of libzbc. ``` cd tools/lkvs sudo make check-local LKVSDEVFILE=/path/to/zbcdevice ``` Also make sure that src/test/zbc_reset.sh is executable. ### How to Build Python or Java bindings ``` cd tools/lkvs make pybind make javabind ``` Cleaning the bindings ``` make pybind-clean make javabind-clean ``` ### Using LKVS #### C++ See src/examples #### Python See src/pybind/example.py #### Java See src/javabind/Tester.java ### LKVS Contact Information Contact: adam.manzanares@hgst.com
About
ZBC device manipulation library
Resources
License
Stars
Watchers
Forks
Releases
No releases published
Packages 0
No packages published
Languages
- C 100.0%