mirror of
https://github.com/SCST-project/scst.git
synced 2026-08-31 21:29:08 +00:00
Gleb Chesnokov
38823eb5e2
SCST spans a kernel core, transport drivers, user-space programs and configuration tools. Each area has different ABI, build, validation and safety constraints, but the repository has no persistent guidance for automated contributors. Add a root AGENTS.md with cross-component contracts and nested files for components with independent boundaries. Record authoritative sources, generated files, compatibility policy and destructive workflows so changes start from the correct context and avoid live storage state.
44 lines
2.1 KiB
Markdown
44 lines
2.1 KiB
Markdown
# SCST User-Space Programs
|
|
|
|
## Ownership and interfaces
|
|
|
|
This directory owns C programs that consume SCST kernel/user interfaces:
|
|
|
|
- `fileio/` implements a user-space device handler over `/dev/scst_user`.
|
|
`scst/include/scst_user.h` and
|
|
`scst/src/dev_handlers/scst_user.c` own the kernel side of that ABI.
|
|
- `stpgd/` consumes SCST events and dispatches ALUA state transitions through
|
|
`scst_on_stpg`. `events/` is a small event-API example and is not part of the
|
|
default `usr/Makefile` build/install set.
|
|
- `scst/include/scst_event.h` and `scst/src/scst_event.c` own the event ABI.
|
|
|
|
These programs do not own generic SCST configuration, backend kernel handler
|
|
semantics, or target transport protocols.
|
|
|
|
## Change boundaries
|
|
|
|
- Update user and kernel producers/consumers together for any ioctl, event,
|
|
structure layout, command/subcommand, flag, error, or version change. Keep
|
|
fixed-width types, 32/64-bit compatibility, interface versioning where
|
|
present, and ownership/reuse rules for shared buffers and commands.
|
|
- For `fileio`, trace registration, memory mapping/allocation, command receive,
|
|
execution, completion, exception, abort, and unregister paths before changing
|
|
lifetime behavior. Use current code and `doc/scst_user_spec.sgml`; do not
|
|
rely on the document alone.
|
|
- For `stpgd`, treat event filtering and the external helper invocation as a
|
|
cluster/control boundary. Changes may alter ALUA state on multiple nodes.
|
|
|
|
## Generated files, validation, and safety
|
|
|
|
`fileio_tgt`, `stpgd`, the optional `events` binary, `.depend*`, objects, and
|
|
installed files are generated artifacts. Build through `usr/Makefile` or the
|
|
focused top-level `make usr`; the default build covers `fileio` and `stpgd`,
|
|
not `events`. These programs use `CC` directly; kernel `ARCH` and
|
|
`CROSS_COMPILE` settings do not by themselves select a user-space cross
|
|
compiler. There is no local unit-test target.
|
|
|
|
Do not run these programs against `/dev/scst_user`, install them, invoke
|
|
`scst_on_stpg`, or change ALUA/cluster state without explicit authorization.
|
|
Do not point a handler at a real backing file or block device unless the exact
|
|
storage and destructive-test scope are approved.
|