michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Edited synchronous_call.rst for typos, ReST syntax

Browse source 
API notes needed a bit of clarification, fixed typo of file name.

Change-Id: I57438165fb2fc3da796fcde19d58a46862ffbbd9
Signed-off-by: L.S. Cook <leonax.cook@intel.com>
This commit is contained in:
L.S. Cook 2016-02-18 09:07:50 -08:00 • committed by Gerrit Code Review
commit 13d064c58c
1 changed files with 40 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

80
doc/kernel/devices/synchronous_call.rst
View file

@ -1,57 +1,57 @@
.. _synchrounous_call: .. _synchronous_call:
Synchronous call within interrupt based device drivers Synchronous Call
###################################################### ################
Zephyr provides a set of device drivers for various platforms. As a preemptive Zephyr provides a set of device drivers for multiple platforms. Each driver
OS, those are meant to be implemented through an interrupt based mode and not should support an interrupt-based implementation, rather than polling, unless
a polling mode unless the driven hardware does not provide any interrupt the specific hardware does not provide any interrupt.
enabled mechanism.
The higher level calls accessed through devices's specific API, such as i2c.h High-level calls accessed through devices's specific API, such as i2c.h
or spi.h, are meant to be, most of the time, synchronous. Thus these calls or spi.h, are usually intended as synchronous. Thus, these calls should be
should be blocking. blocking.
However, and due to the fact Zephyr provides 2 types of executions context on Due to the fact that Zephyr provides two types of execution contexts (task
a microkernel, drivers need to act accordingly. A nanokernel semaphore cannot and fiber) on a microkernel, drivers need to act accordingly. For example, a
be used if the context is a task for instance. Thus, include/device.h exposes nanokernel semaphore cannot be used when the context is a task, so the
an helper API to handle this case transparently, and no other means should be :file:`include/device.h` exposes a helper API to handle this case transparently;
used instead. no other means ought to be used instead.
Usage of device_sync_call_* API Usage of the device_sync_call_* API
******************************* ***********************************
1 type and 3 inline functions are exposed to solve this issue. Zephyr API exposes 1 type and 3 inline functions to solve this issue.
The device_sync_call_t type ``device_sync_call_t``
=========================== ======================
It provides a nanokernel semaphore, always present in both built types: This type provides a nanokernel semaphore, always present in both nanokernel
nanokernel and microkernel. It is meant to be used within a fiber context. and microkernel use cases. It is meant to be used within a fiber context.
Then, and only on a microkernel type, it will provide a kernel semaphore Then, and only on a microkernel type, it will provide a kernel semaphore
meant to be used within a task context. A boolean marker is used to remember meant to be used within a task context. A boolean marker is used to remember
the caller's context when running a microkernel. the caller's context when running a microkernel.
device_sync_call_init() :cpp:func:`device_sync_call_init()`
======================= ===================================
It initializes the device_sync_call_t type: its semaphores and the marker. This function initializes the ``device_sync_call_t`` type semaphores and the
Such function should be used only once in the device driver's instance life marker. Such function should be used only once in the device driver's instance
time. Thus the driver's initialization function is the best place for calling lifetime. Thus, the driver's initialization function is the best place for
it. calling it.
device_sync_call_wait() :cpp:func:`device_sync_call_wait()`
======================= ===================================
This functions will block - i.e. will perform a "take wait" - on the relevant This function will block - that is, it will perform a "take wait" - on the
semaphore. This will make the exposed driver's API function using it a blocking relevant semaphore. The exposed driver's API function can then be used as a
function, until the relevant semaphore is released by a give. This is therefore blocking function until the relevant semaphore is released by a ``give``.
used to start a synchronous call, until being signaled for synchronization. This is therefore used to start a synchronous call, and waits until being
signaled for synchronization.
device_sync_call_complete() :cpp:func:`device_sync_call_complete()`
=========================== =======================================
This function is used to release the relevant semaphore and thus will unlock This function releases the relevant semaphore and thus will unlock the blocking
the blocking function. This is thus being called in the driver's ISR handler function. Most frequently will it be called in the driver's ISR handler. It is
mostly. This is used to signal the completion of the synchronous call, whatever used to signal the completion of the synchronous call, whatever fate would be
fate would be (error or success). (error or success).