mirror of
https://github.com/SCST-project/scst.git
synced 2026-08-25 00:26:43 +00:00
Gleb Chesnokov
e7ad7e093e
The scst_user specification copies ioctl structures and command payloads that predate several ABI extensions. Building a handler from those layouts can select the wrong union member, alignment or completion path. Commit3fc775c75a("EXTENDED COPY support") added remapping payloads. Commitdaee4dcb7e("WRITE SAME command improvements") added WRITE SAME descriptors. Commitd1bd22afd9("scst_user: avoid global locks") left the explicit unregister ioctl as an obsolete no-op. Use scst/include/scst_user.h and scst_user.c as the producer-side source of truth. Synchronize registration, command, reply and subcommand layouts, version checks, reserved fields and ioctl rules. Update the fileio_tgt, stpgd and event guides from current code. Make live-storage and event-consumption risks explicit.
User space FILEIO handler ========================= Version 3.11.0-pre, 29 December 2025 ------------------------------------ fileio_tgt is a user-space disk handler that demonstrates and exercises the SCST scst_user interface. The interface is defined by scst/include/scst_user.h and documented in doc/scst_user_spec.sgml. Build ----- From the repository root, "make usr" builds fileio_tgt and stpgd. To build only this program, run "make -C usr/fileio". Installation is a separate, privileged operation; use the corresponding install target only when system installation is intended. Usage ----- The scst_user kernel module must be loaded before fileio_tgt is started. Running fileio_tgt registers live SCST devices and opens every supplied backing path. Unless read-only mode is selected, initiators can cause writes to those paths. Do not use a real block device or valuable backing file without an explicitly prepared test configuration. fileio_tgt [OPTIONS] name path [name path] ... Each name is the SCST device name used by later access-management operations. Each path is the backing file or device from which the handler determines the virtual device size. Up to the implementation limit, multiple name/path pairs can be registered by one process. The following options are supported: - -b, --block=size: block size; it must be a power of two and at least 512 - -e, --threads=count: number of worker threads - -t, --write_through: write-through mode - -r, --read_only: read-only mode - -o, --direct: open the backing path with O_DIRECT for data I/O - -n, --nullio: NULLIO mode; see scst/README for its safety warning - -c, --nv_cache: NV_CACHE mode; see scst/README for its semantics - -p, --parse=type: "std" (default), "call", or "excpt" - -f, --on_free=type: "ignore" (default) or "call" - -m, --mem_reuse=type: "all" (default), "read", "write", or "none" - -l, --non_blocking: use nonblocking scst_user operations - -I, --vdisk_id=ID: virtual disk ID for multi-target setups - -F, --flush=n: flush the SGV cache every n seconds - -s, --sgv_shared: share the first device's SGV cache - -S, --sgv_single_cache=n: use a single-entry SGV cache with n pages - -P, --sgv_purge_interval=n: set the SGV purge interval in seconds - -u, --unreg_before_close: exercise the obsolete unregister ioctl - -D, --sgv_disable_clustered_pool: disable the clustered SGV pool - -R, --prealloc_buffers=n: preallocate n buffers - -Z, --prealloc_buffer_size=n: preallocated buffer size in KiB - -M, --multi_cmd=v: enable or disable multi-command processing (default 1) - -v, --version: print the program version - -h, --help: print usage information The following options are present only when their corresponding tracing or debug feature is compiled in: - -d, --debug=level: tracing level - -g, --debug_tm_ignore: enable the DEBUG_TM_IGNORE test feature The current option parser and usage() output in usr/fileio/fileio.c are the authoritative command-line reference. Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net