gh0s7/csapp2025
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

cachelab started

Browse Source
This commit is contained in:
CGH0S7
2025-04-21 23:52:27 +08:00
parent cc99d9b5d9
commit ace7a46fb9
58 changed files with 10071 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

443
cachelab/cbsl/references.md Normal file
View File

@@ -0,0 +1,443 @@
# CBSL library references
# Build and link libraries
## C
```bash
export CBSL_INCLUDE_PATH=${CBSL_INSTALLED_PATH}/include
export CBSL_LIBRARY_PATH=${CBSL_INSTALLED_PATH}/lib
cc -c xcbsl_use_code.c -I${CBSL_INCLUDE_PATH}
cc -o xcbsl_use_program ${OBJS} -lcbsl -lzstd -L${CBSL_LIBRARY_PATH}
```
## Fortran
```bash
export CBSL_INCLUDE_PATH=${CBSL_INSTALLED_PATH}/include
export CBSL_LIBRARY_PATH=${CBSL_INSTALLED_PATH}/lib
f95 -c xcbslf_use_code.f95 -I${CBSL_INCLUDE_PATH}
f95 -o xcbslf_use_program ${OBJS} -lcbslf -lcbsl -lzstd -L${CBSL_LIBRARY_PATH}
```
# API
We provide `cbslf` module for using the library in Fortran application.
## Versioning
|Version|Value |
|-------|-----------------------|
|major |release year (ex. 2019)|
|minor |release month (ex. 5) |
|patch |patch version (0-9) |
### C
```c
#define CBSL_VERSION // full version (integer)
#define CBSL_VERSION_STRING // full version (string)
#define CBSL_MAJOR_VERSION // major
#define CBSL_MINOR_VERSION // minor
#define CBSL_PATCH_VERSION // patch
```
### Fortran
```fortran
integer(8), parameter :: CBSL_VERSION
character(*), parameter :: CBSL_VERSION_STRING
integer(4), parameter :: CBSL_MAJOR_VERSION
integer(4), parameter :: CBSL_MINOR_VERSION
integer(4), parameter :: CBSL_PATCH_VERSION
```
## Types
### C
```c
// library context
typedef struct cbsl_ctx_ cbsl_ctx;
```
### Fortran
```fortran
type(cbslf_context)
```
## Constant values
### C
```c
// Context mode
typedef enum
{
cbsl_load_mode, // deserialize mode
cbsl_store_mode, // serialize mode
cbsl_unknown_mode // unknown
}
cbsl_mode;
// Errors
typedef enum
{
cbsl_success, // no error
cbsl_error // function happens any error
}
cbsl_errors;
```
### Fortran
```fortran
integer(4), parameter :: cbslf_load_mode
integer(4), parameter :: cbslf_store_mode
integer(4), parameter :: cbslf_unknown_mode
integer(4), parameter :: cbslf_success
integer(4), parameter :: cbslf_errors
```
## API
### C
```c
/*
[brief]
open serialized data file stream.
[arguments]
open_mode: specifies load/store mode
path : data file path
[return]
success : return context pointer
fail : NULL pointer
*/
cbsl_ctx* cbsl_open(cbsl_mode open_mode, char* path);
/*
[brief]
close serialized data file stream.
this function calls cbsl_flush() before closing stream.
[arguments]
ctx : context pointer
[return]
success : cbsl_success
fail : cbsl_error
*/
cbsl_errors cbsl_close(cbsl_ctx* ctx);
/*
[brief]
flush file stream.
this function executes data compression and write to file stream.
[arguments]
ctx : context pointer
[return]
success : cbsl_success
fail : cbsl_error
*/
cbsl_errors cbsl_flush(cbsl_ctx* ctx);
/*
[brief]
the data stores with compression.
this function stores internal buffer to stored data.
When the stored data fills enough size to compress, this function calls cbsl_flush().
[arguments]
ctx : context pointer
data : write data pointer (must be allocated)
size : byte size of data
[return]
success : cbsl_success
fail : cbsl_error
*/
cbsl_errors cbsl_write(cbsl_ctx* ctx, const void* data, uint64_t size);
/*
[brief]
the data loads with decompression.
this function decompresses data from a file stream, and loads from internal decompressed buffer.
[arguments]
ctx : context pointer
data : read data pointer (must be allocated)
size : byte size of data
[return]
success : cbsl_success
fail : cbsl_error
*/
cbsl_errors cbsl_read(cbsl_ctx* ctx, void* data, uint64_t size);
/*
[brief]
the data loads/stores with compression/decompression.
this function calls cbsl_read()/cbsl_write() by context mode to help the implementation of checkpoint/restart in the application.
[argumetns]
ctx : context pointer
data : read/write data pointer (must be allocated)
size : byte size of data
[return]
success : cbsl_success
fail : cbsl_error
*/
cbsl_errors cbsl_record(cbsl_ctx* ctx, void* data, uint64_t size);
/*
[brief]
this is a specialized function of cbsl_record() for heap allocated array.
the function loads/stores array data size [bytes] and array values from/to a file stream.
an array will be allocated on heap memory by malloc() routine if `data` is null pointer.
[arguments]
ctx : context pointer
data : read/write data pointer (it accepts NULL pointer)
size : byte size of data
[return]
success : cbsl_success
fail : cbsl_error
*/
cbsl_errors cbsl_record_heap(cbsl_ctx* ctx, void** data, uint64_t* size);
/*
[brief]
gets context mode.
[arguments]
ctx : context pointer
[return]
success : context mode
*/
cbsl_mode cbsl_get_mode(cbsl_ctx* ctx);
/*
[brief]
sets zstd compression level of serialized data.
[arguments]
ctx : context pointer
clevel : compression level 1-22 (zstd 1.4.0)
[return]
success : cbsl_success
fail : cbsl_error
*/
cbsl_errors cbsl_set_compression_level(cbsl_ctx* ctx, int clevel);
/*
[brief]
gets zstd compression level of serialized data.
[arguments]
ctx : context pointer
[return]
success : compression level 1-22 (zstd 1.4.0)
fail : -1
*/
int cbsl_get_compression_level(cbsl_ctx* ctx);
```
### Fortran
```fortran
!
! [brief]
! open serialized data file stream.
! [arguments]
! open_mode: specifies load/store mode
! path : data file path
! errcode : error code
! [return]
! success : return context pointer
! fail : NULL pointer
!
function cbslf_open(open_mode, path, errcode) result(ctx)
integer(4), intent(in) :: open_mode
character(*), intent(in) :: path
integer(4), intent(out), optional :: errcode
type(cbslf_context) :: ctx
end function
!
! [brief]
! close serialized data file stream.
! this subroutine calls cbslf_flush() before closing stream.
! [arguments]
! ctx : context pointer
! errcode : error code
!
subroutine cbslf_close(ctx, errcode)
type(cbslf_context), intent(in) :: ctx
integer(4), intent(out), optional :: errcode
end subroutine
!
! [brief]
! flush file stream.
! this subroutine executes data compression and write to file stream.
! [arguments]
! ctx : context pointer
! errcode : error code
!
subroutine cbslf_flush(ctx, errcode)
type(cbslf_context), intent(in) :: ctx
integer(4), intent(out), optional :: errcode
end subroutine
!
! [brief]
! this is a generic interface.
! the data stores with compression.
! this subroutine stores internal buffer to stored data.
! When the stored data fills enough size to compress, this subroutine calls cbslf_flush().
! [supported types]
! scalar : logical, character(*)
! +array : integer(4), integer(8), real(4), real(8), complex(4), complex(8) by up to 7-dimensional array
! [arguments]
! ctx : context pointer
! data : write data (array must be allocated)
! errcode : error code
!
interface cbslf_write(ctx, data, errcode)
type(cbslf_context), intent(in) :: ctx
GENERIC_TYPE, intent(in) :: data
integer(4), intent(out), optional :: errcode
end interface
!
! [brief]
! this is a generic interface.
! the data loads with decompression.
! this subroutine decompresses data from a file stream, and loads from internal decompressed buffer.
! [supported types]
! scalar : logical, character(*)
! +array : integer(4), integer(8), real(4), real(8), complex(4), complex(8) by 7-dimensional array
! [arguments]
! ctx : context pointer
! data : write data (array must be allocated)
! errcode : error code
!
interface cbslf_read(ctx, data, errcode)
type(cbslf_context), intent(in) :: ctx
GENERIC_TYPE, intent(out) :: data
integer(4), intent(out), optional :: errcode
end interface
!
! [brief]
! this is a generic interface.
! the data loads/stores with compression/decompression.
! this subroutine calls cbsl_read()/cbsl_write() by context mode to help the implementation of checkpoint/restart in the application.
! [supported types]
! scalar : logical, character(*)
! +array : integer(4), integer(8), real(4), real(8), complex(4), complex(8) by up to 7-dimensional array
! [arguments]
! ctx : context pointer
! data : read/write data (array must be allocated)
! size : byte size of data
! errcode : error code (return value)
!
interface cbslf_record(ctx, data, errcode)
type(cbslf_context), intent(in) :: ctx
GENERIC_TYPE, intent(inout) :: data
integer(4), intent(out), optional :: errcode
end interface
!
! [brief]
! this is a generic interface for allocatable array.
! the data loads/stores with compression/decompression.
! this subroutine calls cbsl_read()/cbsl_write() by context mode to help the implementation of checkpoint/restart in the application.
! this subroutine behaves as like as cbsl_record_heap() in C API.
! an array will be allocated on the memory if it is not allocated.
! [supported types]
! array : integer(4), integer(8), real(4), real(8), complex(4), complex(8) by up to 7-dimensional array
! [arguments]
! ctx : context pointer
! data : read/write data (accepts not allocated array)
! size : byte size of data
! errcode : error code
!
interface cbslf_record_heap(ctx, data, errcode)
type(cbslf_context), intent(in) :: ctx
GENERIC_TYPE, intent(inout) :: data
integer(4), intent(out), optional :: errcode
end interface
!
! [brief]
! gets context mode.
! [arguments]
! ctx : context pointer
! errcode : error code (return value)
! [return]
! success : context mode
!
function cbslf_get_mode(ctx, errcode) result(mode)
type(cbslf_context), intent(in) :: ctx
integer(4), intent(out), optional :: errcode
integer(4) :: mode
end function
!
! [brief]
! sets zstd compression level of serialized data.
! [arguments]
! ctx : context pointer
! clevel : compression level 1-22 (zstd 1.4.0)
! errcode : error code (return value)
!
subroutine cbslf_set_compression_level(ctx, clevel)
type(cbslf_context), intent(in) :: ctx
ingeter(4), intent(in) :: clevel
integer(4), intent(out), optional :: errcode
end subroutine
!
! [brief]
! gets zstd compression level of serialized data.
! [arguments]
! ctx : context pointer
! [return]
! success : compression level 1-22 (zstd 1.4.0)
! fail : -1
!
function cbslf_get_compression_level(ctx, errcode) result(clevel)
type(cbslf_context), intent(in) :: ctx
integer(4), intent(out), optional :: errcode
ingeter(4), :: clevel
end function
```
## Data format
```
BDATA: binary data [1 byte]
BSIZE: total size of binary data [4 bytes]
RSIZE: rank size of a fortran array [4 bytes]
NRANK: number of rank size of a fortran array
sizeof(TYPE): gets byte size of TYPE
Array-value-type: element type of an array
```
### Header
```
[BDATA * 8]: cbsl library version (64-bit integer)
```
### C API
```
Scalar data: HEAD -> [BDATA * sizeof(Scalar)] -> TAIL
Array data : HEAD -> [BSIZE][BDATA * sizeof(Array-value-type) * BSIZE] -> TAIL
```
### Fortran API
```
Scalar data: HEAD -> [BDATA * sizeof(Scalar)] -> TAIL
Array data : HEAD -> [BSIZE][ARRAY_LOWER_BOUNDS][ARRAY_UPPER_BOUNDS][BDATA * sizeof(Array-value-type) * BSIZE] -> TAIL
ARRAY_LOWER_BOUNDS: lower bounds of a fortran array [RSIZE * NRANK]
ARRAY_UPPER_BOUNDS: upper bounds of a fortran array [RSIZE * NRANK]
```