[LTP] [PATCH v2 2/2] doc: Add ground rules page

[Petr Vorel]

Hi Cyril,

Thanks, very nice doc!
Reviewed-by: Petr Vorel <pvorel@suse.cz>

Few more style/typo/grammar notes below. Found by chatgpt, I picked just few of
them which looked to me significant (obviously AI would improve the style, but
lets ignore that).  Feel free to ignore, otherwise just amend before merge.
Labels "typo:" or "grammar:" should probably be fixed.

AI also suggests to use often articles, e.g. for "parent" and "child" (mostly "the",
sometimes "a"), but let's ignore that.

> +We have decided what we will not work around bugs in upstream LTP sources. If a
decided what => decided that

...
> +Why is sleep in tests bad then?
Missing "using", also maybe more formal (it's not a blog post but official doc):
Why is using sleep in tests bad?
> +```````````````````````````````

...
> +The second problem is that this wastes resources and slows down a test run. If
> +you think that adding a sleep to a test is not a big deal, lets have a look at
> +the bigger perspective. There is about 1600 syscall tests in Linux Test

grammar (plural): There is about 1600 => There are about 1600
(You have it wrong also in your blog post.)

> +Project, if 7.5% of them would sleep just for one second, we would end up with
> +two minutes of wasted time per testrun. In practice most of the test, that
> +historically misused sleep for synchronization, waited for much longer just to
> +be sure that things will works even on slower hardware. With sleeps between 2
> +and 5 seconds that puts us somewhere between 4 and 10 minutes which is between
And here "sleeps" is plural, maybe: puts => put.
Or maybe just use "sleep"?

> +13% and 33% of the syscall runtime on an outdated thinkpad, where the run
> +finishes in a bit less than half an hour. It's even worse on newer hardware,
> +because this slowdown will not change no matter how fast your machine is, which
> +is maybe the reason why this was acceptable twenty years ago but it's not now.
> +
> +
> +What to do instead?
> +```````````````````
> +
> +Use proper synchronization.
> +
> +There are different problems and different solutions. Most often test needs to
> +synchronize between child and parent proces.

typo: proces => process

> +
> +The easiest case is that parent needs to wait for a child to finish, that can

that parent => when parent

> +be fixed just be adding a :man2:`waitpid` in the parent which ensures that child is
> +finished before parent runs.
"child is finished" => "child finished" (or "child has finished")

> +
> +Commonly child has to execute certain piece of code before parent can continue.
> +For that LTP library implements checkpoints with simple
> +:c:func:`TST_CHECKPOINT_WAIT()` and :c:func:`TST_CHECKPOINT_WAKE()` functions based
> +on futexes on a piece of shared memory set up by the test library.
> +
> +Another common case is where child must sleep in a syscall before parent can
"where child" => "when child"

> +continue, for which we have a :c:func:`TST_PROCESS_STATE_WAIT()` helper that
> +polls `/proc/$PID/stat`.
> +
> +Less often test needs to wait for an action that is done asynchronously, or a
> +kernel resource deallocation is deferred to a later time. In such cases the

"a kernel resource deallocation is deferred to a later time"
Maybe:
"for kernel resource deallocation that is deferred to a later time"

> +best we can do is to poll. In LTP we ended up with a macro that polls by
> +calling a piece of code in a loop with exponentially increasing sleeps between
> +retries until it succeeds. Which means that instead of sleeping for a maximal
> +time event can possibly take the sleep is capped by twice of the optimal
> +sleeping time while we avoid polling too aggressively.
> +
> +
> +Use runtime checks for kernel features
> +======================================
> +
> +What is and what isn't supported by kernel is determined by the version
> +and configuration of the kernel the systems is currently running on.
grammar (singular): "systems is ... running on." => "system is ... running."

> +That especially means that any checks done during the compilation cannot
> +be used to assume features supported by the kernel the tests end up
> +running on. The compile time checks, done by configure script, are only
> +useful for enabling fallback kernel API definitions when missing, as we
> +do in lapi/ directory.
> +
> +
> +Kernel features and RCs
> +=======================
> +
> +LTP tests or fixes for kernel changes that were not released yet can be posted
grammar (present perfect): "were not released yet can" => "have not yet been released may"

> +to the LTP list for a review but will not be be accepted until respective
"review but will" => "review but they will"

Kind regards,
Petr