{"id":13420553,"url":"https://github.com/westerndigitalcorporation/libzbc","last_synced_at":"2026-01-18T01:50:23.945Z","repository":{"id":20380547,"uuid":"23656130","full_name":"westerndigitalcorporation/libzbc","owner":"westerndigitalcorporation","description":"ZBC device manipulation library. When submitting a bug report, PLEASE DO NOT SUBMIT CONFIDENTIAL INFORMATION OR INFORMATION SPECIFIC TO DRIVES THAT ARE VENDOR SAMPLES OR NOT PUBLICLY AVAILABLE.","archived":false,"fork":false,"pushed_at":"2022-11-07T01:10:23.000Z","size":2431,"stargazers_count":150,"open_issues_count":0,"forks_count":54,"subscribers_count":38,"default_branch":"master","last_synced_at":"2024-04-10T05:28:08.481Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/westerndigitalcorporation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING.BSD","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-09-04T09:19:58.000Z","updated_at":"2024-01-01T16:55:47.000Z","dependencies_parsed_at":"2023-01-13T20:56:31.701Z","dependency_job_id":null,"html_url":"https://github.com/westerndigitalcorporation/libzbc","commit_stats":null,"previous_names":["hgst/libzbc"],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/westerndigitalcorporation%2Flibzbc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/westerndigitalcorporation%2Flibzbc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/westerndigitalcorporation%2Flibzbc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/westerndigitalcorporation%2Flibzbc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/westerndigitalcorporation","download_url":"https://codeload.github.com/westerndigitalcorporation/libzbc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243700930,"owners_count":20333614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T22:01:36.125Z","updated_at":"2026-01-18T01:50:23.920Z","avatar_url":"https://github.com/westerndigitalcorporation.png","language":"C","funding_links":[],"categories":["TODO scan for Android support in followings"],"sub_categories":[],"readme":"Copyright (C) 2016, Western Digital.\u003cbr\u003e\nCopyright (C) 2020 Western Digital Corporation or its affiliates.\n\n# libzbc\n\n*libzbc* is a simple library providing functions for manipulating SCSI and ATA\ndevices supporting the Zoned Block Command (ZBC) and Zoned-device ATA command\nset (ZAC) specifications.\n\n*libzbc* implementation is compliant with the latest drafts of the ZBC and ZAC\nstandards defined by INCITS technical committee T10 and T13 (respectively).\n\nSeveral example applications using *libzbc* are available under the tools\ndirectory.\n\n## Online Documentation\n\nInformation about *libzbc*, including examples, can be found on the\n[zonedstorage.io](https://zonedstorage.io/docs/tools/libzbc) site.\n\nDetailed information on the execution of device compliance tests can be found\n[here](https://zonedstorage.io/docs/tests/zbc-tests).\n\n## Library version\n\n*libzbc* current major version is 6. Due to interface changes, this version is\nnot compatible with previous *libzbc* versions (version 5.x). Applications\nwritten for previous *libzbc* versions may require updating to use this new\nversion.\n\nIn version 6, *libzbc* emulation mode allowing to imitate the behavior of a host\nmanaged zoned disk has been removed. Users of that feature are encouraged to\nmigrate to a more advanced zone device emulation provided by QEMU.\n\nIn *libzbc* 6.x, the block zone backend driver has been removed. The\nfunctionality provided by this backend is now available by means of a different\nlibrary, [libzbd](https://github.com/westerndigitalcorporation/libzbd).\n\n## ZBC and ZAC Standards Versions Supported\n\n*libzbc* latest version implements INCITS 550 ZBC-2 and ZAC-2 rev. 15\nstandards. Support for the older draft standards are available with\n [previous releases and pre-releases](https://github.com/hgst/libzbc/releases).\n\n## License\n\n*libzbc* source code is distributed under the terms of the BSD 2-clause\nlicense (\"Simplified BSD License\" or \"FreeBSD License\", SPDX: *BSD-2-Clause*)\nand under the terms of the GNU Lesser General Public License version 3, or any\nlater version (SPDX: *LGPL-3.0-or-later*).\nA copy of these licenses with *libzbc* copyright can be found in the files\n[LICENSES/BSD-2-Clause.txt] and [COPYING.BSD] for the BSD 2-clause license and\n[LICENSES/LGPL-3.0-or-later.txt] and [COPYING.LESSER] for the LGPL-v3 license.\nIf not, please see\nhttp://opensource.org/licenses/BSD-2-Clause and http://www.gnu.org/licenses/.\n\nAll example applications under the tools directory are distributed under the\nterms of the GNU Lesser General Public License version 3, or any later version\n(SPDX: *LGPL-3.0-or-later*).\n\n*libzbc* and all its example applications are distributed \"as is,\" without\ntechnical support, and WITHOUT ANY WARRANTY, without even the implied warranty\nof MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\nAll source files in *libzbc* contain the BSD 2-clause and LGPL v3 license SPDX\nshort identifiers in place of the full license text.\n\n```\nSPDX-License-Identifier: BSD-2-Clause\nSPDX-License-Identifier: LGPL-3.0-or-later\n```\n\nSome files such as the `.gitignore` file are public domain specified by the\nCC0 1.0 Universal (CC0 1.0) Public Domain Dedication. These files are\nidentified with the following SPDX header.\n\n```\nSPDX-License-Identifier: CC0-1.0\n```\n\nSee [LICENSES/CC0-1.0.txt] for the full text of this license.\n\n## Contributions and Bug Reports\n\nContributions are accepted as github pull requests. Any problem may also be\nreported through github issue page or by contacting:\n\n* Damien Le Moal (damien.lemoal@wdc.com)\n* Dmitry Fomichev (dmitry.fomichev@wdc.com)\n\nPLEASE DO NOT SUBMIT CONFIDENTIAL INFORMATION OR INFORMATION SPECIFIC TO DRIVES\nTHAT ARE VENDOR SAMPLES OR NOT PUBLICLY AVAILABLE.\n\n## Compilation and installation\n\n### Requirements\n\n*libzbc* requires the following packages for compilation:\n\n* m4\n* autoconf\n* automake\n* libtool\n\nThe GTK3 and GTK3 development packages must be installed to automatically enable\ncompiling the *gzbc* and *gzviewer* applications.\n\n### Compilation\n\nTo compile the library and all example applications under the tools directory,\nexecute the following commands.\n\n```\n$ sh ./autogen.sh\n$ ./configure\n$ make\n```\n\n#### Compilation with GUI tools\n\nThe *gzbc* and *gzviewer* tools implement a graphical user interface (GUI) using\nthe GTK3 toolkit. The configure script will automatically detect the presence of\nGTK3 and its development header files and compile these tools if the header\nfiles are found. This behavior can be manually changed and the compilation of\n*gzbc* and *gzviewer* disabled using the `--disable-gui` configuration option.\n\n```\n$ ./configure --disable-gui\n```\n\n#### Compilation for device tests\n\nThe test directory contains several test programs and scripts allowing testing\nthe compatibility of *libzbc* with a particular device. That is, testing if a\ndevice follows the same standard as currently supported by *libzbc*. The\ncompilation of these test programs is disabled by default.\n\nTo compile the test programs, *libzbc* must be configured as follows.\n\n```\n$ ./configure --with-test\n```\n\nThe test programs and scripts are not affected by the execution of \"make\ninstall\". All defined tests must be executed directly from the test directory\nusing the *zbc_test.sh* script. To test the device `/dev/\u003cSG node\u003e`, the\nfollowing can be executed.\n\n```\n$ cd test\n$ sudo ./zbc_test.sh /dev/\u003cSG node\u003e\n```\n\nBy default, the script will run through all the test cases. Detailed control\nof the test execution is possible using the `-e` (execute) and `-s`(skip)\noptions. Run `zbc_test.sh --help` for details.\n\n*libzbc* tests check the detailed error output from the device for invalid\ncommands.\n\nEach test outputs a log file in the `test/log` directory. These files can be\nconsulted in case of a failed test to identify the reason for the test failure.\n\n### Installation\n\nTo install the library and all example applications compiled under the tools\ndirectory, execute the following command.\n\n```\n$ sudo make install\n```\n\nThe library file is by default installed under `/usr/lib` (or `/usr/lib64`).\nThe library header file is installed in `/usr/include/libzbc`. The executable\nfiles for the example applications are installed under `/usr/bin`.\n\nThese default installation locations can be changed using the configure script.\nExecuting the following command displays the options used to control the\ninstallation paths.\n\n```\n$ ./configure --help\n```\n\n### Building RPM packages\n\nThe *rpm* and *rpmbuild* utilities are necessary to build *libzbc* RPM\npackages. Once these utilities are installed, the RPM packages can be built\nusing the following command.\n\n```\n$ sh ./autogen.sh\n$ ./configure\n$ make rpm\n```\n\nFive RPM packages are built:\n* A binary package providing *libzbc* library, tools, documentation and\n  license files.\n* A source RPM package\n* A *debuginfo* RPM package and a *debugsource* RPM package\n* A development package providing the library header files\n\nThe source RPM package can be used to build the binary and debug RPM packages\noutside of *libzbc* source tree using the following command.\n\n```\n$ rpmbuild --rebuild libzbc-\u003cversion\u003e.src.rpm\n```\n\n## Library Overview\n\n*libzbc* functions operate using a device handle obtained by executing the\n*zbc_open()* function. The path specified to identify a device can point to a\nregular file, a block device file (*/dev/sdX*)or an SG node device file\n(*/dev/sgY*).\n\nAs host-aware devices are backward-compatible with regular block device files\n(device type/signature 0x00), a host-aware device will always be accessible\neither through a block device file as well as its SG node device file.\n\nFor host-managed devices, the different device type and device signature require\nkernel support for block device files to be enabled. Kernel support for\nhost-managed devices has been added with Linux kernel 4.10. For older kernels,\nhost-managed devices will be accessible only through their SG node device files.\nKernel support for the ZAC host-managed device signature (0xabcd) was introduced\nin kernel 3.18. Any kernel older than this version will not create an SG node\ndevice file for ZAC host-managed devices connected to an AHCI SATA port on the\ntarget host.\n\nRegular files and block device files for regular devices can be used to operate\n*libzbc* in emulation mode. This will enable exposing the target file or block\ndevice as a host-managed zoned device.\n\n### Library Functions\n\n*libzbc* provides functions for discovering the zone configuration of a zoned\ndevice and for accessing the device. Accesses to the device may result in\nchanges to the device zones condition, attributes and state (such as a\nsequential zone write pointer location). These changes are not internally\ntracked by *libzbc*. The functions provided to obtain the device zone\ninformation only provide a snapshot of the zone condition and state when\nexecuted. It is the responsibility of an application to implement tracking of\nthe device zone changes (such as increment to a sequential zone write pointer as\nwrites to the zone are executed) if necessary.\n\nAll *libzbc* functions since version 5.0.0 use 512B sector unit for reporting\nzone information and as the addressing unit for device accesses, regardless of\nthe actual device logical block size. This unification in the unit used by all\nAPI functions can simplify application development by hiding potential\ndifferences in logical block sizes between devices. However, application\nprogrammers must be careful to always implement write accesses to sequential\nwrite required zones of the device in multiple of the physical block size.\n\nThe main functions provided by *libzbc* are as follows.\n\nFunction                 | Description\n-------------------------|---------------------------------------------\n*zbc_open()*             | Open a zoned device\n*zbc_close()*            | Close a zoned device\n*zbc_get_device_info()*  | Get device information\n*zbc_report_nr_zones()*  | Get the number of zones of the device\n*zbc_report_zones()* \u003cbr\u003e *zbc_list_zones()* | Get zone information\n*zbc_zone_operation()*   | Execute a zone operation\n*zbc_open_zone()*        | Explicitly open a zone\n*zbc_close_zone()*       | Close an open zone\n*zbc_finish_zone()*      | Finish a zone\n*zbc_reset_zone()*       | Reset a zone write pointer\n*zbc_pread()*            | Read data from a zone\n*zbc_preadv()*           | Read data from a zone using vectored buffer\n*zbc_pwrite()*           | Write data to a zone\n*zbc_pwritev()*          | Write data to a zone using vectored buffer\n*zbc_flush()*            | Flush data to disk\n\nAdditionally, the following functions are also provided to facilitate\napplication development and tests.\n\nFunction                   | Description\n---------------------------|---------------------------------------------------\n*zbc_map_iov()*            | Map a vectored buffer using a single buffer\n*zbc_set_log_level()*      | Set the logging level of the library functions\n*zbc_device_is_zoned()*    | Test if a device is a zoned block device\n*zbc_print_device_info()*  | Print device information to a file (stream)\n*zbc_device_type_str()*    | Get a string description of a device type\n*zbc_device_model_str()*   | Get a string description of a device model\n*zbc_zone_type_str()*      | Get a string description of a zone type\n*zbc_zone_condition_str()* | Get a string description of a zone condition\n*zbc_errno()*              | Get the sense key and code of the last function call\n*zbc_sk_str()*             | Get a string description of a sense key\n*zbc_asc_ascq_str()*       | Get a string description of a sense code\n\n*libzbc* does not implement any synchronization mechanism for multiple threads\nor processes to safely operate simultaneously on the same zone. In particular,\nconcurrent write operations by multiple threads to the same zone may result in\nwrite errors without write ordering control by the application. The\n*zbc_errno()* function is the only exception to this rule. This function is\nthread safe and does not require serialized execution by the application.\n\n### Native Operation Mode\n\nLinux kernels older than version 4.10 do not create a block device file for\nhost-managed ZBC and ZAC devices. As a result, these devices can only be\naccessed through their associated SG node (/dev/sgx device file). For these\nolder kernels, opening a ZBC or ZAC host managed disk with *libzbc* must thus\nbe done using the device SG node. For kernel versions 4.10 and beyond compiled\nwith zoned block device support, the device will be exposed also through a block\ndevice file which can be used with *libzbc* to identify the device.\n\nFor host-aware devices, a block device file and an SG node file will exist and\ncan both be used to open the device.\n\nOnce the device is open, accesses to the device are done transparently using the\ndevice handle returned by the *zbc_open()* function. Operations such as report\nzones, reset zone write pointer, etc. only need the device handle.\n\n### Functions Documentation\n\nMore detailed information on *libzbc* functions and data types is available\nthrough the comments in the file `include/libzbc/zbc.h`. This file has comments\nformatted with the doxygen convention. HTML files documenting *libzbc* API can\nbe generated using the doxygen project file documentation/libzbc.doxygen.\n\n```\n$ cd documentation\n$ doxygen libzbc.doxygen\n```\n\n## Tools\n\nUnder the tools directory, several simple applications are available as\nexamples. These applications are as follows.\n\n* **zbc_info** This application tests if a device file points to a physical\n  zoned device supporting ZBC or ZAC features. This excludes the emulation mode\n  implemented by *libzbc*. If the device is identified as a zoned device, some\n  information about the device are displayed (e.g. the device type, capacity,\n  sector size, etc).\n\n* **zbc_report_zones** This application illustrates the use of the zone\n  reporting functions *zbc_report_zones()*, *zbc_report_nr_zones()* and\n  *zbc_list_zones()*. *zbc_report_zones* obtains the zone information of a\n  device and displays it in readable form on the standard output.\n\n* **zbc_open_zone** This application illustrates the use of the\n  *zbc_open_zone()* function allowing opening a zone.\n\n* **zbc_close_zone** This application illustrates the use of the\n  *zbc_close_zone()* function allowing closing a zone.\n\n* **zbc_finish_zone** This application illustrates the use of the\n  *zbc_finish_zone()* function allowing finishing a zone.\n\n* **zbc_reset_zone** This application illustrates the use of the\n  *zbc_reset_zone()* function allowing resetting the write pointer of a zone to\n  the first sector of the zone.\n\n* **zbc_read_zone** This application reads data from a zone, up to the zone\n  write pointer location and either sends the read data to the standard output\n  or copies the data to a regular file. Its implementation illustrates the use\n  of the functions *zbc_pread()* and *zbc_preadv()*.\n\n* **zbc_write_zone** This application illustrates the use of the functions\n  *zbc_pwrite()* and *zbc_pwritev()* to write data to a zone at the zone write\n  pointer location.\n\n* **gzbc** provides a graphical user interface showing zone information of a\n  zoned device. It also displays the write status (write pointer position) of\n  zones graphically using color coding (red for written space and green for\n  unwritten space). Some operations on zones can also be executed directly from\n  the interface (reset zone write pointer, open zone, close zone, etc).\n\n* **gzviewer** provides a simple graphical user interface showing the write\n  pointer position and zone state of zones of a zoned device. Similar color\n  coding as *gzbc* is used.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwesterndigitalcorporation%2Flibzbc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwesterndigitalcorporation%2Flibzbc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwesterndigitalcorporation%2Flibzbc/lists"}