spinlock APIs need documentation

[nordic-krch]

Describe the bug
When using spin lock in a following code:

struct k_spinlock l;
k_spinlock_key_t k;

k = k_spin_lock(&l);

I'm hitting assert in z_spin_lock_valid.

zephyr/include/spinlock.h

Line 79 in 21e0d48

__ASSERT(z_spin_lock_valid(l), "Recursive spinlock");

k_spin_lock is validating lock structure which might not be initialize and validation includes checking one of the fields of uninitialized structure. I'm not sure then if struct k_spinlock should be somehow initialized before being used? If so, i don't see any init function. What about single core case?

[andyross]

Spinlocks are valid when zero-initialized. The normal use case is to put it in bss, but if you want to use a local you can do "struct k_spinlock l = {};". There probably should be a K_SPINLOCK_INITIALIZER macro defined.

[nordic-krch]

seems like spin lock is in general missing any documentation. no doxygen for k_spin_lock and k_spin_unlock:

zephyr/include/spinlock.h

Line 67 in 21e0d48

static ALWAYS_INLINE k_spinlock_key_t k_spin_lock(struct k_spinlock *l)

[nashif]

@andyross can you please add missing documentation?

[thomasthorsen]

I don't think the documentation added in #25092 actually addresses the main issue here:
"I'm not sure then if struct k_spinlock should be somehow initialized before being used?"

There is no init API and there is no part of the added documentation that states the memory must be initialised in any way (as far as I can tell). I encountered this in a spin lock that was allocated by k_malloc, which had actually worked for some time in our system, and then when some code was moved around, it started failing oddly with this, because the pre-existing memory contents happened to be different for the new location. In the old location it just happened to be zero, and nothing bad happened.