Copyright (C) 2009-2014, HGST, Inc.

I. Introduction
===============

I.1. Overview
-------------

libzbc is a simple library providing functions for manipulating Zoned
Block Command (ZBC) disks. It is implemented to be compliant with the
current version of the ZBC standard draft defined by INCITS technical
committee T10.  At the time of this writing, the current version of the
standard draft is Rev 01b, released on 2014/09/09.

In addition to supporting ZBC disks, libzbc also implements an emulation
mode allowing emulating the behavior of a ZBC device using a regular
file or a raw standard block device.

Several example applications using libzbc are available under the tools
directory.

I.2. License
------------

With the exception of the linear key value store (lkvs) tool, libzbc
and all example applications are distributed under the term of the of
the GNU Lesser General Public License version 3, or any later version.

The lkvs tool is distributed under the term of the of the GNU General
Public License version 3, or any later version.

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.
You should have received a copy of the GNU Lesser General Public License
along with libzbc.  If not, see <http://www.gnu.org/licenses/>.

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 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.2 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.2 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 the zone configuration of a device.
This application may not be able to handle devices with a large number
of zones (> 100).

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