More Description in Example Documentation

[pearson]

The documentation for examples could use to be expanded with more description of the code to help those who are new to Zephyr.

As an example, take the second in the "Classic" examples, "Synchronization":

• Why does it do a k_busy_wait followed by a k_msleep before releasing the semaphore?
• Why are there three ARG_UNUSED dummy variables at the start of each thread function?
• What is the PIN_THREADS define used for, and the k_thread_cpu_mask_clear and k_thread_cpu_mask_enable calls it enables?

For someone new to Zephyr (such as myself), there are many questions that could be answered in an example's documentation rather than through searching the entire set of documentation. Getting up to speed quickly, rather than having to read through more material than is currently needed, can be very useful.

[nashif]

• Why does it do a k_busy_wait followed by a k_msleep before releasing the semaphore?

this is just to simulate some work done by the thread, a sleep will cause an immediate context switch and the thread total runtime will be very close to zero. There is a comment about this in the code.

• Why are there three ARG_UNUSED dummy variables at the start of each thread function?

Thread entry functions can have up to 3 variables, you do not have to use them. If you do not use them, compiler might complain, hence the ARG_UNUSED to let the compiler know not to complain.

• What is the PIN_THREADS define used for, and the k_thread_cpu_mask_clear and k_thread_cpu_mask_enable calls it enables?

On multi-core system you can pin a thread to a specific core, this demonstrates that. Try this with qemu_x86_64.

[pearson]

Hi @nashif . Thanks for your reply, but it's not that I'm asking the questions here -- it's that the kind of information you provided in your reply would be very useful in the documentation for new Zephyr developers to read.

That said, I could keep a list of my questions as I go through, get good answers like you provided here, and add to the documentation. 😄

[nashif]

@pearson yes, I understand. You are welcome to submit any clarifying comments to any samples.