ShuriZma
/
BizHawk
mirror of https://github.com/TASEmulators/BizHawk.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
BizHawk/ExternalProjects/libchd-rs-capi/README.md

3.0 KiB
Raw Permalink Blame History

chd-capi

⚠️The C API has not been heavily tested. Use at your own risk. ⚠️

chd-rs provides a C API compatible with chd.h. ABI compatibility is detailed below but is untested when compiling as a dynamic library. The intended consumption for this crate is not via cargo, but by vendoring the sources of the C API in tree, along with a compatible libchdcorefile implementation for your platform.

Features

verify_block_crc

Enables the verify_block_crc of the chd crate to verify decompressed CHD hunks with their internal hash.

chd_core_file

Enables core_file* and thechd_open_file, and chd_core_file APIs. This feature requires a libchdcorefile implementation, or the default POSIX compatible implementation (where core_file* is FILE*) will be used.

Note that by default, core_file* is not an opaque pointer and is a C FILE* stream. This allows the underlying file pointer to be changed unsafely beneath the memory safety guarantees of chd-rs. We strongly encourage using chd_open instead of chd_open_file.

If you need core_file* support, chd-capi should have the chd_core_file feature enabled, which will wrap FILE* to be usable in Rust with a lightweight wrapper in libchdcorefile. If the default implementation is not suitable, you may need to implement libchdcorefile yourself. The chd_core_file feature requires CMake and Clang to be installed.

chd_virtio

Enables the virtual I/O functions chd_open_core_file. Because this C API requires core_file to be an opaque pointer, there is no difference between chd_open_file and chd_open_core_file unlike libchdr, and chd_open_core_file is simply an alias for chd_open_file. All functions that take core_file* require a libchdcorefile implementation.

chd_precache

Enables precaching of the underlying file into memory with the chd_precache_progress and chd_precache functions.

ABI compatibility

chd-rs makes the following ABI-compatibility guarantees compared to libchdr when compiled statically.

  • chd_error is ABI and API-compatible with chd.h
  • chd_header is ABI and API-compatible chd.h
  • chd_file * is an opaque pointer. It is not layout compatible with chd.c
  • The layout of core_file * is user-defined when the chd_core_file feature is enabled.
  • Freeing any pointer returned by chd-rs with free is undefined behaviour. The exception are chd_file * pointers which can be safely freed with chd_close.