Skip to content

Commit f0320e1

Browse files
vkarpenkpablodelara
authored andcommitted
shim: add zlib shim library
This is experimental library is a drop-in replacement for zlib that utilizes ISA-L for improved compression/decompression performance. Signed-off-by: Karpenko, Veronika <[email protected]> Signed-off-by: Pablo de Lara <[email protected]>
1 parent 5e90721 commit f0320e1

File tree

9 files changed

+925
-1
lines changed

9 files changed

+925
-1
lines changed

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ erasure_code/*_test
3232
erasure_code/gf_vect_dot_prod_1tbl
3333
igzip/*_perf
3434
igzip/*_test
35+
igzip/shim/build
3536
mem/*_perf
3637
mem/*_test
3738
programs/igzip

CMakeLists.txt

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,9 @@ if(BUILD_TESTS)
4545
include(CTest)
4646
endif()
4747

48+
# Enable building ISAL shim library
49+
option(BUILD_ISAL_SHIM "Build the ISAL shim library" OFF)
50+
4851
# Set default build type
4952
if(NOT CMAKE_BUILD_TYPE)
5053
set(CMAKE_BUILD_TYPE Release)
@@ -107,6 +110,11 @@ include(cmake/crc.cmake)
107110
include(cmake/igzip.cmake)
108111
include(cmake/mem.cmake)
109112

113+
# Conditionally build ISAL shim library
114+
if(BUILD_ISAL_SHIM)
115+
add_subdirectory(igzip/shim)
116+
endif()
117+
110118
# Add test.h to extern headers (used by all modules)
111119
list(APPEND EXTERN_HEADERS include/test.h)
112120

@@ -219,4 +227,4 @@ configure_file(
219227

220228
install(FILES "${CMAKE_BINARY_DIR}/libisal.pc"
221229
DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig
222-
)
230+
)

Release_notes.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,9 @@ v2.32
147147
* Igzip compression improvements:
148148
- Added new RVV adler32 implementations.
149149

150+
* Igzip:
151+
- Added experimental ISA-L shim library to provide drop-in compatibility with zlib.
152+
150153
* RAID improvements:
151154
- Added new x86 AVX2+GFNI and AVX512+GFNI pq_gen implementations.
152155
- Added new RVV xor_gen, pq_gen implementations.

igzip/shim/CMakeLists.txt

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
#/**********************************************************************
2+
# Copyright(c) 2025 Intel Corporation All rights reserved.
3+
#
4+
# Redistribution and use in source and binary forms, with or without
5+
# modification, are permitted provided that the following conditions
6+
# are met:
7+
# * Redistributions of source code must retain the above copyright
8+
# notice, this list of conditions and the following disclaimer.
9+
# * Redistributions in binary form must reproduce the above copyright
10+
# notice, this list of conditions and the following disclaimer in
11+
# the documentation and/or other materials provided with the
12+
# distribution.
13+
# * Neither the name of Intel Corporation nor the names of its
14+
# contributors may be used to endorse or promote products derived
15+
# from this software without specific prior written permission.
16+
#
17+
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18+
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19+
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
20+
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
21+
# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
22+
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
23+
# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24+
# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25+
# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26+
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
27+
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28+
#**********************************************************************/
29+
30+
# Only set project and cmake_minimum_required if this is the root project
31+
if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
32+
cmake_minimum_required(VERSION 3.16)
33+
# Project name
34+
project(isal_shim LANGUAGES C)
35+
endif()
36+
37+
# Set the library name
38+
set(LIBRARY_NAME isal-shim)
39+
40+
# Collect all source files in the current directory
41+
file(GLOB SOURCES "${CMAKE_CURRENT_SOURCE_DIR}/*.c")
42+
43+
# Add the include directory for the header file
44+
include_directories("${CMAKE_CURRENT_SOURCE_DIR}/../../include")
45+
46+
# Set default build type to Release if not specified
47+
if(NOT CMAKE_BUILD_TYPE)
48+
set(CMAKE_BUILD_TYPE "Release" CACHE STRING "Choose the type of build" FORCE)
49+
endif()
50+
51+
# Set debug flags for Debug build type
52+
set(CMAKE_C_FLAGS_DEBUG "-g -O0 -DDEBUG")
53+
54+
# Create the shared library
55+
add_library(${LIBRARY_NAME} SHARED ${SOURCES})
56+
57+
# Handle linking differently based on whether this is built as part of the main project or standalone
58+
if(TARGET isal)
59+
# Building as part of the main ISA-L project - link with the isal target
60+
target_link_libraries(${LIBRARY_NAME} PRIVATE isal)
61+
target_include_directories(${LIBRARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}/include")
62+
else()
63+
# Building standalone - find and link with installed isal library
64+
if (NOT DEFINED ISAL_INSTALL_DIR)
65+
# Link the library with isal
66+
find_library(ISAL_LIBRARY isal REQUIRED)
67+
target_link_libraries(${LIBRARY_NAME} PRIVATE ${ISAL_LIBRARY})
68+
else()
69+
# Link the library with isal built and installed in ISAL_INSTALL_DIR
70+
find_library(ISAL_LIBRARY isal PATHS "${ISAL_INSTALL_DIR}/lib" NO_DEFAULT_PATH REQUIRED)
71+
target_include_directories(${LIBRARY_NAME} PRIVATE "${ISAL_INSTALL_DIR}/include")
72+
target_link_libraries(${LIBRARY_NAME} PRIVATE ${ISAL_LIBRARY})
73+
endif()
74+
endif()
75+
76+
# Set the output name for the shared library
77+
set_target_properties(${LIBRARY_NAME} PROPERTIES OUTPUT_NAME "isal-shim")
78+
79+
# Remove the "lib" prefix from the shared library name
80+
set_target_properties(${LIBRARY_NAME} PROPERTIES PREFIX "")
81+
82+
# Install the shim library when built as part of the main project
83+
if(TARGET isal)
84+
include(GNUInstallDirs)
85+
install(TARGETS ${LIBRARY_NAME}
86+
LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
87+
ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
88+
RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
89+
)
90+
endif()

igzip/shim/README.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Shim Library for zlib API with ISA-L (Experimental)
2+
3+
This library provides an experimental shim layer that implements the zlib API while utilizing the Intel® Storage Acceleration Library (ISA-L) for enhanced performance. It enables seamless integration of ISA-L's optimized compression and decompression routines into applications designed for the zlib interface.
4+
5+
**Note:** This is an experimental feature and may not be suitable for all production environments without thorough testing.
6+
7+
## Features
8+
9+
- **zlib API Compatibility**: Drop-in replacement for zlib with minimal code changes.
10+
- **ISA-L**: Leverages ISA-L for high-performance data compression and decompression.
11+
12+
## Requirements
13+
14+
- **ISA-L**: Ensure ISA-L is installed and available on your system.
15+
16+
## Installation
17+
18+
1. Clone the repository:
19+
```bash
20+
git clone https://github.com/intel-innersource/libraries.performance.storage.isa-l
21+
cd shim
22+
```
23+
24+
2. Build isal-shim.so:
25+
```bash
26+
mkdir build
27+
cd build
28+
29+
cmake ..
30+
31+
# Enable debug mode.
32+
cmake -DCMAKE_BUILD_TYPE=Debug ..
33+
34+
# Specify the custom installation directory for ISA-L.
35+
cmake -DISAL_INSTALL_DIR=/path/to/isal/install/ ..
36+
37+
make
38+
```
39+
40+
3. Preload the shim library in your project:
41+
```bash
42+
LD_PRELOAD=libraries.performance.storage.isa-l/shim/build/isal-shim.so ./app
43+
LD_PRELOAD=libraries.performance.storage.isa-l/shim/build/isal-shim.so python test.py
44+
```
45+
46+
## Usage
47+
48+
Replace your existing zlib library with this shim library. The API remains the same, so no additional changes are required in the application code.
49+
50+
## Scope/Constraints
51+
52+
This library is a drop-in replacement for zlib that utilizes Intel's Storage Acceleration Library (ISA-L) for improved compression/decompression performance. However, it has the following limitations:
53+
54+
- **Platform Support**: Currently only tested and supported on Linux systems
55+
- **Function Interception**: Only intercepts specific zlib functions (see Intercepted Zlib Functions section below)
56+
- **API Compatibility**: While designed as a drop-in replacement, some zlib functions are not supported yet
57+
58+
For production use, thorough testing in your specific environment is recommended before deployment.
59+
60+
## Intercepted Zlib Functions
61+
62+
deflate/inflate and related functions
63+
- deflateInit, deflateInit2, deflateSetDictionary, deflate, deflateEnd, deflateSetHeader
64+
- inflateInit, inflateInit2, inflateSetDictionary, inflate, inflateEnd
65+
66+
utility functions
67+
- compress, uncompress
68+
- compress, uncompress2

0 commit comments

Comments
 (0)