doc: update function references to use :c:func:
Following the change to use the C domain for parsing, update all existing :cpp:func: references to :c:func:. Remove the parentheses as well, if used, because they are not needed, this is already known to be a function, and how it is displayed in the documentation later is a semantic decision done by the output builder. Signed-off-by: Fabio Utzig <fabio.utzig@nordicsemi.no>
This commit is contained in:
parent
a56446051e
commit
53fd5ff236
48 changed files with 303 additions and 303 deletions
|
@ -259,8 +259,8 @@ Peripheral role
|
||||||
Most Zephyr-based BLE devices will most likely be peripheral-role
|
Most Zephyr-based BLE devices will most likely be peripheral-role
|
||||||
devices. This means that they perform connectable advertising and expose
|
devices. This means that they perform connectable advertising and expose
|
||||||
one or more GATT services. After registering services using the
|
one or more GATT services. After registering services using the
|
||||||
:cpp:func:`bt_gatt_service_register` API the application will typically
|
:c:func:`bt_gatt_service_register` API the application will typically
|
||||||
start connectable advertising using the :cpp:func:`bt_le_adv_start` API.
|
start connectable advertising using the :c:func:`bt_le_adv_start` API.
|
||||||
|
|
||||||
There are several peripheral sample applications available in the tree,
|
There are several peripheral sample applications available in the tree,
|
||||||
such as :zephyr_file:`samples/bluetooth/peripheral_hr`.
|
such as :zephyr_file:`samples/bluetooth/peripheral_hr`.
|
||||||
|
@ -277,12 +277,12 @@ client, first performing discovery of available services and then
|
||||||
accessing one or more supported services.
|
accessing one or more supported services.
|
||||||
|
|
||||||
To initially discover a device to connect to the application will likely
|
To initially discover a device to connect to the application will likely
|
||||||
use the :cpp:func:`bt_le_scan_start` API, wait for an appropriate device
|
use the :c:func:`bt_le_scan_start` API, wait for an appropriate device
|
||||||
to be found (using the scan callback), stop scanning using
|
to be found (using the scan callback), stop scanning using
|
||||||
:cpp:func:`bt_le_scan_stop` and then connect to the device using
|
:c:func:`bt_le_scan_stop` and then connect to the device using
|
||||||
:cpp:func:`bt_conn_create_le`. If the central wants to keep
|
:c:func:`bt_conn_create_le`. If the central wants to keep
|
||||||
automatically reconnecting to the peripheral it should use the
|
automatically reconnecting to the peripheral it should use the
|
||||||
:cpp:func:`bt_le_set_auto_conn` API.
|
:c:func:`bt_le_set_auto_conn` API.
|
||||||
|
|
||||||
There are some sample applications for the central role available in the
|
There are some sample applications for the central role available in the
|
||||||
tree, such as :zephyr_file:`samples/bluetooth/central_hr`.
|
tree, such as :zephyr_file:`samples/bluetooth/central_hr`.
|
||||||
|
@ -290,7 +290,7 @@ tree, such as :zephyr_file:`samples/bluetooth/central_hr`.
|
||||||
Observer role
|
Observer role
|
||||||
=============
|
=============
|
||||||
|
|
||||||
An observer role device will use the :cpp:func:`bt_le_scan_start` API to
|
An observer role device will use the :c:func:`bt_le_scan_start` API to
|
||||||
scan for device, but it will not connect to any of them. Instead it will
|
scan for device, but it will not connect to any of them. Instead it will
|
||||||
simply utilize the advertising data of found devices, combining it
|
simply utilize the advertising data of found devices, combining it
|
||||||
optionally with the received signal strength (RSSI).
|
optionally with the received signal strength (RSSI).
|
||||||
|
@ -298,7 +298,7 @@ optionally with the received signal strength (RSSI).
|
||||||
Broadcaster role
|
Broadcaster role
|
||||||
================
|
================
|
||||||
|
|
||||||
A broadcaster role device will use the :cpp:func:`bt_le_adv_start` API to
|
A broadcaster role device will use the :c:func:`bt_le_adv_start` API to
|
||||||
advertise specific advertising data, but the type of advertising will be
|
advertise specific advertising data, but the type of advertising will be
|
||||||
non-connectable, i.e. other device will not be able to connect to it.
|
non-connectable, i.e. other device will not be able to connect to it.
|
||||||
|
|
||||||
|
@ -314,13 +314,13 @@ Security
|
||||||
To achieve a secure relationship between two Bluetooth devices a process
|
To achieve a secure relationship between two Bluetooth devices a process
|
||||||
called pairing is used. This process can either be triggered implicitly
|
called pairing is used. This process can either be triggered implicitly
|
||||||
through the security properties of GATT services, or explicitly using
|
through the security properties of GATT services, or explicitly using
|
||||||
the :cpp:func:`bt_conn_security` API on a connection object.
|
the :c:func:`bt_conn_security` API on a connection object.
|
||||||
|
|
||||||
To achieve a higher security level, and protect against
|
To achieve a higher security level, and protect against
|
||||||
Man-In-The-Middle (MITM) attacks, it is recommended to use some
|
Man-In-The-Middle (MITM) attacks, it is recommended to use some
|
||||||
out-of-band channel during the pairing. If the devices have a sufficient
|
out-of-band channel during the pairing. If the devices have a sufficient
|
||||||
user interface this "channel" is the user itself. The capabilities of
|
user interface this "channel" is the user itself. The capabilities of
|
||||||
the device are registered using the :cpp:func:`bt_conn_auth_cb_register`
|
the device are registered using the :c:func:`bt_conn_auth_cb_register`
|
||||||
API. The :c:type:`bt_conn_auth_cb` struct that's passed to this API has
|
API. The :c:type:`bt_conn_auth_cb` struct that's passed to this API has
|
||||||
a set of optional callbacks that can be used during the pairing - if the
|
a set of optional callbacks that can be used during the pairing - if the
|
||||||
device lacks some feature the corresponding callback may be set to NULL.
|
device lacks some feature the corresponding callback may be set to NULL.
|
||||||
|
|
|
@ -156,10 +156,10 @@ another real or simulated device.
|
||||||
Initialization
|
Initialization
|
||||||
**************
|
**************
|
||||||
|
|
||||||
The Bluetooth subsystem is initialized using the :cpp:func:`bt_enable`
|
The Bluetooth subsystem is initialized using the :c:func:`bt_enable`
|
||||||
function. The caller should ensure that function succeeds by checking
|
function. The caller should ensure that function succeeds by checking
|
||||||
the return code for errors. If a function pointer is passed to
|
the return code for errors. If a function pointer is passed to
|
||||||
:cpp:func:`bt_enable`, the initialization happens asynchronously, and the
|
:c:func:`bt_enable`, the initialization happens asynchronously, and the
|
||||||
completion is notified through the given function.
|
completion is notified through the given function.
|
||||||
|
|
||||||
Bluetooth Application Example
|
Bluetooth Application Example
|
||||||
|
@ -174,8 +174,8 @@ advertising, effectively acting as a Bluetooth Low Energy broadcaster.
|
||||||
:lines: 19-
|
:lines: 19-
|
||||||
:linenos:
|
:linenos:
|
||||||
|
|
||||||
The key APIs employed by the beacon sample are :cpp:func:`bt_enable`
|
The key APIs employed by the beacon sample are :c:func:`bt_enable`
|
||||||
that's used to initialize Bluetooth and then :cpp:func:`bt_le_adv_start`
|
that's used to initialize Bluetooth and then :c:func:`bt_le_adv_start`
|
||||||
that's used to start advertising a specific combination of advertising
|
that's used to start advertising a specific combination of advertising
|
||||||
and scan response data.
|
and scan response data.
|
||||||
|
|
||||||
|
|
|
@ -6,7 +6,7 @@ Thread analyzer
|
||||||
The thread analyzer module enables all the Zephyr options required to track
|
The thread analyzer module enables all the Zephyr options required to track
|
||||||
the thread information, e.g. thread stack size usage.
|
the thread information, e.g. thread stack size usage.
|
||||||
The analysis is performed on demand when the application calls
|
The analysis is performed on demand when the application calls
|
||||||
:cpp:func:`thread_analyzer_run` or :cpp:func:`thread_analyzer_print`.
|
:c:func:`thread_analyzer_run` or :c:func:`thread_analyzer_print`.
|
||||||
|
|
||||||
Configuration
|
Configuration
|
||||||
*************
|
*************
|
||||||
|
|
|
@ -297,7 +297,7 @@ mode if the thread triggered a fatal exception, but not if the thread
|
||||||
gracefully exits its entry point function.
|
gracefully exits its entry point function.
|
||||||
|
|
||||||
This means implementing an architecture-specific version of
|
This means implementing an architecture-specific version of
|
||||||
:cpp:func:`k_thread_abort`, and setting the Kconfig option
|
:c:func:`k_thread_abort`, and setting the Kconfig option
|
||||||
:option:`CONFIG_ARCH_HAS_THREAD_ABORT` as needed for the architecture (e.g. see
|
:option:`CONFIG_ARCH_HAS_THREAD_ABORT` as needed for the architecture (e.g. see
|
||||||
:zephyr_file:`arch/arm/core/aarch32/cortex_m/Kconfig`).
|
:zephyr_file:`arch/arm/core/aarch32/cortex_m/Kconfig`).
|
||||||
|
|
||||||
|
@ -465,7 +465,7 @@ Memory Management
|
||||||
|
|
||||||
If the target platform enables paging and requires drivers to memory-map
|
If the target platform enables paging and requires drivers to memory-map
|
||||||
their I/O regions, :option:`CONFIG_MMU` needs to be enabled and the
|
their I/O regions, :option:`CONFIG_MMU` needs to be enabled and the
|
||||||
:cpp:func:`arch_mem_map()` API implemented.
|
:c:func:`arch_mem_map` API implemented.
|
||||||
|
|
||||||
Stack Objects
|
Stack Objects
|
||||||
*************
|
*************
|
||||||
|
@ -764,25 +764,25 @@ implemented, and the system must enable the :option:`CONFIG_ARCH_HAS_USERSPACE`
|
||||||
option. Please see the documentation for each of these functions for more
|
option. Please see the documentation for each of these functions for more
|
||||||
details:
|
details:
|
||||||
|
|
||||||
* :cpp:func:`arch_buffer_validate()` to test whether the current thread has
|
* :c:func:`arch_buffer_validate` to test whether the current thread has
|
||||||
access permissions to a particular memory region
|
access permissions to a particular memory region
|
||||||
|
|
||||||
* :cpp:func:`arch_user_mode_enter()` which will irreversibly drop a supervisor
|
* :c:func:`arch_user_mode_enter` which will irreversibly drop a supervisor
|
||||||
thread to user mode privileges. The stack must be wiped.
|
thread to user mode privileges. The stack must be wiped.
|
||||||
|
|
||||||
* :cpp:func:`arch_syscall_oops()` which generates a kernel oops when system
|
* :c:func:`arch_syscall_oops` which generates a kernel oops when system
|
||||||
call parameters can't be validated, in such a way that the oops appears to be
|
call parameters can't be validated, in such a way that the oops appears to be
|
||||||
generated from where the system call was invoked in the user thread
|
generated from where the system call was invoked in the user thread
|
||||||
|
|
||||||
* :cpp:func:`arch_syscall_invoke0()` through
|
* :c:func:`arch_syscall_invoke0` through
|
||||||
:cpp:func:`arch_syscall_invoke6()` invoke a system call with the
|
:c:func:`arch_syscall_invoke6` invoke a system call with the
|
||||||
appropriate number of arguments which must all be passed in during the
|
appropriate number of arguments which must all be passed in during the
|
||||||
privilege elevation via registers.
|
privilege elevation via registers.
|
||||||
|
|
||||||
* :cpp:func:`arch_is_user_context()` return nonzero if the CPU is currently
|
* :c:func:`arch_is_user_context` return nonzero if the CPU is currently
|
||||||
running in user mode
|
running in user mode
|
||||||
|
|
||||||
* :cpp:func:`arch_mem_domain_max_partitions_get()` which indicates the max
|
* :c:func:`arch_mem_domain_max_partitions_get` which indicates the max
|
||||||
number of regions for a memory domain. MMU systems have an unlimited amount,
|
number of regions for a memory domain. MMU systems have an unlimited amount,
|
||||||
MPU systems have constraints on this.
|
MPU systems have constraints on this.
|
||||||
|
|
||||||
|
@ -792,21 +792,21 @@ If so, CONFIG_ARCH_MEM_DOMAIN_SYNCHRONOUS_API must be selected by the
|
||||||
architecture and some additional APIs must be implemented. This is common
|
architecture and some additional APIs must be implemented. This is common
|
||||||
on MMU systems and uncommon on MPU systems:
|
on MMU systems and uncommon on MPU systems:
|
||||||
|
|
||||||
* :cpp:func:`arch_mem_domain_thread_add()`
|
* :c:func:`arch_mem_domain_thread_add`
|
||||||
|
|
||||||
* :cpp:func:`arch_mem_domain_thread_remove()`
|
* :c:func:`arch_mem_domain_thread_remove`
|
||||||
|
|
||||||
* :cpp:func:`arch_mem_domain_partition_add()`
|
* :c:func:`arch_mem_domain_partition_add`
|
||||||
|
|
||||||
* :cpp:func:`arch_mem_domain_partition_remove()`
|
* :c:func:`arch_mem_domain_partition_remove`
|
||||||
|
|
||||||
* :cpp:func:`arch_mem_domain_destroy()`
|
* :c:func:`arch_mem_domain_destroy`
|
||||||
|
|
||||||
Please see the doxygen documentation of these APIs for details.
|
Please see the doxygen documentation of these APIs for details.
|
||||||
|
|
||||||
In addition to implementing these APIs, there are some other tasks as well:
|
In addition to implementing these APIs, there are some other tasks as well:
|
||||||
|
|
||||||
* :cpp:func:`_new_thread()` needs to spawn threads with :c:macro:`K_USER` in
|
* :c:func:`_new_thread` needs to spawn threads with :c:macro:`K_USER` in
|
||||||
user mode
|
user mode
|
||||||
|
|
||||||
* On context switch, the outgoing thread's stack memory should be marked
|
* On context switch, the outgoing thread's stack memory should be marked
|
||||||
|
|
|
@ -7,22 +7,22 @@ The Zephyr Bluetooth stack uses an abstraction called :c:type:`bt_conn`
|
||||||
to represent connections to other devices. The internals of this struct
|
to represent connections to other devices. The internals of this struct
|
||||||
are not exposed to the application, but a limited amount of information
|
are not exposed to the application, but a limited amount of information
|
||||||
(such as the remote address) can be acquired using the
|
(such as the remote address) can be acquired using the
|
||||||
:cpp:func:`bt_conn_get_info` API. Connection objects are reference
|
:c:func:`bt_conn_get_info` API. Connection objects are reference
|
||||||
counted, and the application is expected to use the
|
counted, and the application is expected to use the
|
||||||
:cpp:func:`bt_conn_ref` API whenever storing a connection pointer for a
|
:c:func:`bt_conn_ref` API whenever storing a connection pointer for a
|
||||||
longer period of time, since this ensures that the object remains valid
|
longer period of time, since this ensures that the object remains valid
|
||||||
(even if the connection would get disconnected). Similarly the
|
(even if the connection would get disconnected). Similarly the
|
||||||
:cpp:func:`bt_conn_unref` API is to be used when releasing a reference
|
:c:func:`bt_conn_unref` API is to be used when releasing a reference
|
||||||
to a connection.
|
to a connection.
|
||||||
|
|
||||||
An application may track connections by registering a
|
An application may track connections by registering a
|
||||||
:c:type:`bt_conn_cb` struct using the :cpp:func:`bt_conn_cb_register`
|
:c:type:`bt_conn_cb` struct using the :c:func:`bt_conn_cb_register`
|
||||||
API. This struct lets the application define callbacks for connection &
|
API. This struct lets the application define callbacks for connection &
|
||||||
disconnection events, as well as other events related to a connection
|
disconnection events, as well as other events related to a connection
|
||||||
such as a change in the security level or the connection parameters.
|
such as a change in the security level or the connection parameters.
|
||||||
When acting as a central the application will also get hold of the
|
When acting as a central the application will also get hold of the
|
||||||
connection object through the return value of the
|
connection object through the return value of the
|
||||||
:cpp:func:`bt_conn_create_le` API.
|
:c:func:`bt_conn_create_le` API.
|
||||||
|
|
||||||
API Reference
|
API Reference
|
||||||
*************
|
*************
|
||||||
|
|
|
@ -7,7 +7,7 @@ Generic Attribute Profile (GATT)
|
||||||
GATT layer manages the service database providing APIs for service registration
|
GATT layer manages the service database providing APIs for service registration
|
||||||
and attribute declaration.
|
and attribute declaration.
|
||||||
|
|
||||||
Services can be registered using :cpp:func:`bt_gatt_service_register` API
|
Services can be registered using :c:func:`bt_gatt_service_register` API
|
||||||
which takes the :cpp:class:`bt_gatt_service` struct that provides the list of
|
which takes the :cpp:class:`bt_gatt_service` struct that provides the list of
|
||||||
attributes the service contains. The helper macro :cpp:func:`BT_GATT_SERVICE`
|
attributes the service contains. The helper macro :cpp:func:`BT_GATT_SERVICE`
|
||||||
can be used to declare a service.
|
can be used to declare a service.
|
||||||
|
@ -51,17 +51,17 @@ respective operations.
|
||||||
Attribute ``read`` and ``write`` callbacks are called directly from RX Thread
|
Attribute ``read`` and ``write`` callbacks are called directly from RX Thread
|
||||||
thus it is not recommended to block for long periods of time in them.
|
thus it is not recommended to block for long periods of time in them.
|
||||||
|
|
||||||
Attribute value changes can be notified using :cpp:func:`bt_gatt_notify` API,
|
Attribute value changes can be notified using :c:func:`bt_gatt_notify` API,
|
||||||
alternatively there is :cpp:func:`bt_gatt_notify_cb` where is is possible to
|
alternatively there is :c:func:`bt_gatt_notify_cb` where is is possible to
|
||||||
pass a callback to be called when it is necessary to know the exact instant when
|
pass a callback to be called when it is necessary to know the exact instant when
|
||||||
the data has been transmitted over the air. Indications are supported by
|
the data has been transmitted over the air. Indications are supported by
|
||||||
:cpp:func:`bt_gatt_indicate` API.
|
:c:func:`bt_gatt_indicate` API.
|
||||||
|
|
||||||
Client procedures can be enabled with the configuration option:
|
Client procedures can be enabled with the configuration option:
|
||||||
:option:`CONFIG_BT_GATT_CLIENT`
|
:option:`CONFIG_BT_GATT_CLIENT`
|
||||||
|
|
||||||
Discover procedures can be initiated with the use of
|
Discover procedures can be initiated with the use of
|
||||||
:cpp:func:`bt_gatt_discover` API which takes the
|
:c:func:`bt_gatt_discover` API which takes the
|
||||||
:cpp:class:`bt_gatt_discover_params` struct which describes the type of
|
:cpp:class:`bt_gatt_discover_params` struct which describes the type of
|
||||||
discovery. The parameters also serves as a filter when setting the ``uuid``
|
discovery. The parameters also serves as a filter when setting the ``uuid``
|
||||||
field only attributes which matches will be discovered, in contrast setting it
|
field only attributes which matches will be discovered, in contrast setting it
|
||||||
|
@ -70,23 +70,23 @@ to NULL allows all attributes to be discovered.
|
||||||
.. note::
|
.. note::
|
||||||
Caching discovered attributes is not supported.
|
Caching discovered attributes is not supported.
|
||||||
|
|
||||||
Read procedures are supported by :cpp:func:`bt_gatt_read` API which takes the
|
Read procedures are supported by :c:func:`bt_gatt_read` API which takes the
|
||||||
:cpp:class:`bt_gatt_read_params` struct as parameters. In the parameters one or
|
:cpp:class:`bt_gatt_read_params` struct as parameters. In the parameters one or
|
||||||
more attributes can be set, though setting multiple handles requires the option:
|
more attributes can be set, though setting multiple handles requires the option:
|
||||||
:option:`CONFIG_BT_GATT_READ_MULTIPLE`
|
:option:`CONFIG_BT_GATT_READ_MULTIPLE`
|
||||||
|
|
||||||
Write procedures are supported by :cpp:func:`bt_gatt_write` API and takes
|
Write procedures are supported by :c:func:`bt_gatt_write` API and takes
|
||||||
:cpp:class:`bt_gatt_write_params` struct as parameters. In case the write
|
:cpp:class:`bt_gatt_write_params` struct as parameters. In case the write
|
||||||
operation don't require a response :cpp:func:`bt_gatt_write_without_response`
|
operation don't require a response :c:func:`bt_gatt_write_without_response`
|
||||||
or :cpp:func:`bt_gatt_write_without_response_cb` APIs can be used, with the
|
or :c:func:`bt_gatt_write_without_response_cb` APIs can be used, with the
|
||||||
later working similarly to ``bt_gatt_notify_cb``.
|
later working similarly to :c:func:`bt_gatt_notify_cb`.
|
||||||
|
|
||||||
Subscriptions to notification and indication can be initiated with use of
|
Subscriptions to notification and indication can be initiated with use of
|
||||||
:cpp:func`bt_gatt_subscribe` API which takes
|
:c:func:`bt_gatt_subscribe` API which takes
|
||||||
:cpp:class:`bt_gatt_subscribe_params` as parameters. Multiple subscriptions to
|
:cpp:class:`bt_gatt_subscribe_params` as parameters. Multiple subscriptions to
|
||||||
the same attribute are supported so there could be multiple ``notify`` callback
|
the same attribute are supported so there could be multiple ``notify`` callback
|
||||||
being triggered for the same attribute. Subscriptions can be removed with use of
|
being triggered for the same attribute. Subscriptions can be removed with use of
|
||||||
:cpp:func:`bt_gatt_unsubscribe()` API.
|
:c:func:`bt_gatt_unsubscribe` API.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
When subscriptions are removed ``notify`` callback is called with the data
|
When subscriptions are removed ``notify`` callback is called with the data
|
||||||
|
|
|
@ -15,24 +15,24 @@ changed.
|
||||||
In addition to that it also contains the ``recv`` callback which is called
|
In addition to that it also contains the ``recv`` callback which is called
|
||||||
whenever an incoming data has been received. Data received this way can be
|
whenever an incoming data has been received. Data received this way can be
|
||||||
marked as processed by returning 0 or using
|
marked as processed by returning 0 or using
|
||||||
:cpp:func:`bt_l2cap_chan_recv_complete` API if processing is asynchronous.
|
:c:func:`bt_l2cap_chan_recv_complete` API if processing is asynchronous.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
The ``recv`` callback is called directly from RX Thread thus it is not
|
The ``recv`` callback is called directly from RX Thread thus it is not
|
||||||
recommended to block for long periods of time.
|
recommended to block for long periods of time.
|
||||||
|
|
||||||
For sending data the :cpp:func:`bt_l2cap_chan_send` API can be used noting that
|
For sending data the :c:func:`bt_l2cap_chan_send` API can be used noting that
|
||||||
it may block if no credits are available, and resuming as soon as more credits
|
it may block if no credits are available, and resuming as soon as more credits
|
||||||
are available.
|
are available.
|
||||||
|
|
||||||
Servers can be registered using :cpp:func:`bt_l2cap_server_register` API passing
|
Servers can be registered using :c:func:`bt_l2cap_server_register` API passing
|
||||||
the :cpp:class:`bt_l2cap_server` struct which informs what ``psm`` it should
|
the :cpp:class:`bt_l2cap_server` struct which informs what ``psm`` it should
|
||||||
listen to, the required security level ``sec_level``, and the callback
|
listen to, the required security level ``sec_level``, and the callback
|
||||||
``accept`` which is called to authorize incoming connection requests and
|
``accept`` which is called to authorize incoming connection requests and
|
||||||
allocate channel instances.
|
allocate channel instances.
|
||||||
|
|
||||||
Client channels can be initiated with use of :cpp:func:`bt_l2cap_chan_connect`
|
Client channels can be initiated with use of :c:func:`bt_l2cap_chan_connect`
|
||||||
API and can be disconnected with the :cpp:func:`bt_l2cap_chan_disconnect` API.
|
API and can be disconnected with the :c:func:`bt_l2cap_chan_disconnect` API.
|
||||||
Note that the later can also disconnect channel instances created by servers.
|
Note that the later can also disconnect channel instances created by servers.
|
||||||
|
|
||||||
API Reference
|
API Reference
|
||||||
|
|
|
@ -21,7 +21,7 @@ element instantiating all the models required for a single aspect of the
|
||||||
supported behavior.
|
supported behavior.
|
||||||
|
|
||||||
The node's element and model structure is specified in the node composition
|
The node's element and model structure is specified in the node composition
|
||||||
data, which is passed to :cpp:func:`bt_mesh_init()` during initialization. The
|
data, which is passed to :c:func:`bt_mesh_init` during initialization. The
|
||||||
Bluetooth SIG have defined a set of foundation models (see
|
Bluetooth SIG have defined a set of foundation models (see
|
||||||
:ref:`bluetooth_mesh_models`) and a set of models for implementing common
|
:ref:`bluetooth_mesh_models`) and a set of models for implementing common
|
||||||
behavior in the `Bluetooth Mesh Model Specification
|
behavior in the `Bluetooth Mesh Model Specification
|
||||||
|
@ -80,11 +80,11 @@ Model publication
|
||||||
The models may send messages in two ways:
|
The models may send messages in two ways:
|
||||||
|
|
||||||
* By specifying a set of message parameters in a :cpp:type:`bt_mesh_msg_ctx`,
|
* By specifying a set of message parameters in a :cpp:type:`bt_mesh_msg_ctx`,
|
||||||
and calling :cpp:func:`bt_mesh_model_send()`.
|
and calling :c:func:`bt_mesh_model_send`.
|
||||||
* By setting up a :cpp:type:`bt_mesh_model_pub` structure and calling
|
* By setting up a :cpp:type:`bt_mesh_model_pub` structure and calling
|
||||||
:cpp:func:`bt_mesh_model_publish()`.
|
:c:func:`bt_mesh_model_publish`.
|
||||||
|
|
||||||
When publishing messages with :cpp:func:`bt_mesh_model_publish()`, the model
|
When publishing messages with :c:func:`bt_mesh_model_publish`, the model
|
||||||
will use the publication parameters configured by the
|
will use the publication parameters configured by the
|
||||||
:ref:`bluetooth_mesh_models_cfg_srv`. This is the recommended way to send
|
:ref:`bluetooth_mesh_models_cfg_srv`. This is the recommended way to send
|
||||||
unprompted model messages, as it passes the responsibility of selecting
|
unprompted model messages, as it passes the responsibility of selecting
|
||||||
|
@ -115,7 +115,7 @@ in total. Models may extend models that extend others, creating an "extension
|
||||||
tree". All models in an extension tree share a single subscription list per
|
tree". All models in an extension tree share a single subscription list per
|
||||||
element it spans.
|
element it spans.
|
||||||
|
|
||||||
Model extensions are done by calling :cpp:func:`bt_mesh_model_extend()` during
|
Model extensions are done by calling :c:func:`bt_mesh_model_extend` during
|
||||||
initialization. A model can only be extended by one other model, and
|
initialization. A model can only be extended by one other model, and
|
||||||
extensions cannot be circular. Note that binding of node states and other
|
extensions cannot be circular. Note that binding of node states and other
|
||||||
relationships between the models must be defined by the model implementations.
|
relationships between the models must be defined by the model implementations.
|
||||||
|
@ -131,7 +131,7 @@ Mesh models may have data associated with each model instance that needs to be
|
||||||
stored persistently. The access API provides a mechanism for storing this
|
stored persistently. The access API provides a mechanism for storing this
|
||||||
data, leveraging the internal model instance encoding scheme. Models can store
|
data, leveraging the internal model instance encoding scheme. Models can store
|
||||||
one user defined data entry per instance by calling
|
one user defined data entry per instance by calling
|
||||||
:cpp:func:`bt_mesh_model_data_store()`. To be able to read out the data the
|
:c:func:`bt_mesh_model_data_store`. To be able to read out the data the
|
||||||
next time the device reboots, the model's
|
next time the device reboots, the model's
|
||||||
:cpp:var:`bt_mesh_model_cb::settings_set()` callback must be populated. This
|
:cpp:var:`bt_mesh_model_cb::settings_set()` callback must be populated. This
|
||||||
callback gets called when model specific data is found in the persistent
|
callback gets called when model specific data is found in the persistent
|
||||||
|
|
|
@ -17,7 +17,7 @@ either send messages or poll the Friend node for any incoming messages.
|
||||||
|
|
||||||
The radio control and polling is managed automatically by the mesh stack, but
|
The radio control and polling is managed automatically by the mesh stack, but
|
||||||
the LPN API allows the application to trigger the polling at any time through
|
the LPN API allows the application to trigger the polling at any time through
|
||||||
:cpp:func:`bt_mesh_lpn_poll()`. The LPN operation parameters, including poll
|
:c:func:`bt_mesh_lpn_poll`. The LPN operation parameters, including poll
|
||||||
interval, poll event timing and Friend requirements is controlled through the
|
interval, poll event timing and Friend requirements is controlled through the
|
||||||
:option:`CONFIG_BT_MESH_LOW_POWER` option and related configuration options.
|
:option:`CONFIG_BT_MESH_LOW_POWER` option and related configuration options.
|
||||||
|
|
||||||
|
|
|
@ -29,10 +29,10 @@ Beaconing
|
||||||
To start the provisioning process, the unprovisioned device must first start
|
To start the provisioning process, the unprovisioned device must first start
|
||||||
broadcasting the Unprovisioned Beacon. This makes it visible to nearby
|
broadcasting the Unprovisioned Beacon. This makes it visible to nearby
|
||||||
provisioners, which can initiate the provisioning. To indicate that the device
|
provisioners, which can initiate the provisioning. To indicate that the device
|
||||||
needs to be provisioned, call :cpp:func:`bt_mesh_prov_enable()`. The device
|
needs to be provisioned, call :c:func:`bt_mesh_prov_enable`. The device
|
||||||
starts broadcasting the Unprovisioned Beacon with the device UUID and the
|
starts broadcasting the Unprovisioned Beacon with the device UUID and the
|
||||||
``OOB information`` field, as specified in the ``prov`` parameter passed to
|
``OOB information`` field, as specified in the ``prov`` parameter passed to
|
||||||
:cpp:func:`bt_mesh_init`. Additionally, a Uniform Resource Identifier (URI)
|
:c:func:`bt_mesh_init`. Additionally, a Uniform Resource Identifier (URI)
|
||||||
may be specified, which can point the provisioner to the location of some Out
|
may be specified, which can point the provisioner to the location of some Out
|
||||||
Of Band information, such as the device's public key or an authentication
|
Of Band information, such as the device's public key or an authentication
|
||||||
value database. The URI is advertised in a separate beacon, with a URI hash
|
value database. The URI is advertised in a separate beacon, with a URI hash
|
||||||
|
@ -106,7 +106,7 @@ sequence should be repeated after a delay of three seconds or more.
|
||||||
When an Input OOB action is selected, the user should be prompted when the
|
When an Input OOB action is selected, the user should be prompted when the
|
||||||
application receives the :cpp:var:`bt_mesh_prov::input` callback. The user
|
application receives the :cpp:var:`bt_mesh_prov::input` callback. The user
|
||||||
response should be fed back to the Provisioning API through
|
response should be fed back to the Provisioning API through
|
||||||
:cpp:func:`bt_mesh_input_string()` or :cpp:func:`bt_mesh_input_number()`. If
|
:c:func:`bt_mesh_input_string` or :c:func:`bt_mesh_input_number`. If
|
||||||
no user response is recorded within 60 seconds, the Provisioning process is
|
no user response is recorded within 60 seconds, the Provisioning process is
|
||||||
aborted.
|
aborted.
|
||||||
|
|
||||||
|
|
|
@ -384,7 +384,7 @@ leading zeroes or sign (e.g. 32), or an equivalent symbolic name (e.g.
|
||||||
``CONFIG_KERNEL_INIT_PRIORITY_DEFAULT + 5``).
|
``CONFIG_KERNEL_INIT_PRIORITY_DEFAULT + 5``).
|
||||||
|
|
||||||
Drivers and other system utilities can determine whether startup is
|
Drivers and other system utilities can determine whether startup is
|
||||||
still in pre-kernel states by using the :cpp:func:`k_is_pre_kernel()`
|
still in pre-kernel states by using the :c:func:`k_is_pre_kernel`
|
||||||
function.
|
function.
|
||||||
|
|
||||||
System Drivers
|
System Drivers
|
||||||
|
@ -442,7 +442,7 @@ DTS and do not need any RAM-based storage for it.
|
||||||
|
|
||||||
For drivers that may need to deal with this situation, a set of
|
For drivers that may need to deal with this situation, a set of
|
||||||
APIs under the DEVICE_MMIO scope are defined, along with a mapping function
|
APIs under the DEVICE_MMIO scope are defined, along with a mapping function
|
||||||
:cpp:func:`device_map()`.
|
:c:func:`device_map`.
|
||||||
|
|
||||||
Device Model Drivers with one MMIO region
|
Device Model Drivers with one MMIO region
|
||||||
=========================================
|
=========================================
|
||||||
|
@ -580,7 +580,7 @@ Drivers that do not use DTS
|
||||||
===========================
|
===========================
|
||||||
|
|
||||||
Some drivers may not obtain the MMIO physical address from DTS, such as
|
Some drivers may not obtain the MMIO physical address from DTS, such as
|
||||||
is the case with PCI-E. In this case the :cpp:func:`device_map()` function
|
is the case with PCI-E. In this case the :c:func:`device_map` function
|
||||||
may be used directly:
|
may be used directly:
|
||||||
|
|
||||||
.. code-block:: C
|
.. code-block:: C
|
||||||
|
|
|
@ -29,7 +29,7 @@ the first word of an item for use as a pointer to the next data item in
|
||||||
the queue. Consequently, a data item that holds N bytes of application
|
the queue. Consequently, a data item that holds N bytes of application
|
||||||
data requires N+4 (or N+8) bytes of memory. There are no alignment or
|
data requires N+4 (or N+8) bytes of memory. There are no alignment or
|
||||||
reserved space requirements for data items if they are added with
|
reserved space requirements for data items if they are added with
|
||||||
:cpp:func:`k_fifo_alloc_put()`, instead additional memory is temporarily
|
:c:func:`k_fifo_alloc_put`, instead additional memory is temporarily
|
||||||
allocated from the calling thread's resource pool.
|
allocated from the calling thread's resource pool.
|
||||||
|
|
||||||
A data item may be **added** to a FIFO by a thread or an ISR.
|
A data item may be **added** to a FIFO by a thread or an ISR.
|
||||||
|
@ -63,7 +63,7 @@ Defining a FIFO
|
||||||
===============
|
===============
|
||||||
|
|
||||||
A FIFO is defined using a variable of type :c:type:`k_fifo`.
|
A FIFO is defined using a variable of type :c:type:`k_fifo`.
|
||||||
It must then be initialized by calling :cpp:func:`k_fifo_init()`.
|
It must then be initialized by calling :c:func:`k_fifo_init`.
|
||||||
|
|
||||||
The following code defines and initializes an empty FIFO.
|
The following code defines and initializes an empty FIFO.
|
||||||
|
|
||||||
|
@ -85,7 +85,7 @@ The following code has the same effect as the code segment above.
|
||||||
Writing to a FIFO
|
Writing to a FIFO
|
||||||
=================
|
=================
|
||||||
|
|
||||||
A data item is added to a FIFO by calling :cpp:func:`k_fifo_put()`.
|
A data item is added to a FIFO by calling :c:func:`k_fifo_put`.
|
||||||
|
|
||||||
The following code builds on the example above, and uses the FIFO
|
The following code builds on the example above, and uses the FIFO
|
||||||
to send data to one or more consumer threads.
|
to send data to one or more consumer threads.
|
||||||
|
@ -113,9 +113,9 @@ to send data to one or more consumer threads.
|
||||||
}
|
}
|
||||||
|
|
||||||
Additionally, a singly-linked list of data items can be added to a FIFO
|
Additionally, a singly-linked list of data items can be added to a FIFO
|
||||||
by calling :cpp:func:`k_fifo_put_list()` or :cpp:func:`k_fifo_put_slist()`.
|
by calling :c:func:`k_fifo_put_list` or :c:func:`k_fifo_put_slist`.
|
||||||
|
|
||||||
Finally, a data item can be added to a FIFO with :cpp:func:`k_fifo_alloc_put()`.
|
Finally, a data item can be added to a FIFO with :c:func:`k_fifo_alloc_put`.
|
||||||
With this API, there is no need to reserve space for the kernel's use in
|
With this API, there is no need to reserve space for the kernel's use in
|
||||||
the data item, instead additional memory will be allocated from the calling
|
the data item, instead additional memory will be allocated from the calling
|
||||||
thread's resource pool until the item is read.
|
thread's resource pool until the item is read.
|
||||||
|
@ -123,7 +123,7 @@ thread's resource pool until the item is read.
|
||||||
Reading from a FIFO
|
Reading from a FIFO
|
||||||
===================
|
===================
|
||||||
|
|
||||||
A data item is removed from a FIFO by calling :cpp:func:`k_fifo_get()`.
|
A data item is removed from a FIFO by calling :c:func:`k_fifo_get`.
|
||||||
|
|
||||||
The following code builds on the example above, and uses the FIFO
|
The following code builds on the example above, and uses the FIFO
|
||||||
to obtain data items from a producer thread,
|
to obtain data items from a producer thread,
|
||||||
|
|
|
@ -29,7 +29,7 @@ the first word of an item for use as a pointer to the next data item in the
|
||||||
queue. Consequently, a data item that holds N bytes of application data
|
queue. Consequently, a data item that holds N bytes of application data
|
||||||
requires N+4 (or N+8) bytes of memory. There are no alignment or reserved
|
requires N+4 (or N+8) bytes of memory. There are no alignment or reserved
|
||||||
space requirements for data items if they are added with
|
space requirements for data items if they are added with
|
||||||
:cpp:func:`k_lifo_alloc_put()`, instead additional memory is temporarily
|
:c:func:`k_lifo_alloc_put`, instead additional memory is temporarily
|
||||||
allocated from the calling thread's resource pool.
|
allocated from the calling thread's resource pool.
|
||||||
|
|
||||||
A data item may be **added** to a LIFO by a thread or an ISR.
|
A data item may be **added** to a LIFO by a thread or an ISR.
|
||||||
|
@ -54,7 +54,7 @@ Defining a LIFO
|
||||||
===============
|
===============
|
||||||
|
|
||||||
A LIFO is defined using a variable of type :c:type:`k_lifo`.
|
A LIFO is defined using a variable of type :c:type:`k_lifo`.
|
||||||
It must then be initialized by calling :cpp:func:`k_lifo_init()`.
|
It must then be initialized by calling :c:func:`k_lifo_init`.
|
||||||
|
|
||||||
The following defines and initializes an empty LIFO.
|
The following defines and initializes an empty LIFO.
|
||||||
|
|
||||||
|
@ -76,7 +76,7 @@ The following code has the same effect as the code segment above.
|
||||||
Writing to a LIFO
|
Writing to a LIFO
|
||||||
=================
|
=================
|
||||||
|
|
||||||
A data item is added to a LIFO by calling :cpp:func:`k_lifo_put()`.
|
A data item is added to a LIFO by calling :c:func:`k_lifo_put`.
|
||||||
|
|
||||||
The following code builds on the example above, and uses the LIFO
|
The following code builds on the example above, and uses the LIFO
|
||||||
to send data to one or more consumer threads.
|
to send data to one or more consumer threads.
|
||||||
|
@ -103,7 +103,7 @@ to send data to one or more consumer threads.
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
A data item can be added to a LIFO with :cpp:func:`k_lifo_alloc_put()`.
|
A data item can be added to a LIFO with :c:func:`k_lifo_alloc_put`.
|
||||||
With this API, there is no need to reserve space for the kernel's use in
|
With this API, there is no need to reserve space for the kernel's use in
|
||||||
the data item, instead additional memory will be allocated from the calling
|
the data item, instead additional memory will be allocated from the calling
|
||||||
thread's resource pool until the item is read.
|
thread's resource pool until the item is read.
|
||||||
|
@ -111,7 +111,7 @@ thread's resource pool until the item is read.
|
||||||
Reading from a LIFO
|
Reading from a LIFO
|
||||||
===================
|
===================
|
||||||
|
|
||||||
A data item is removed from a LIFO by calling :cpp:func:`k_lifo_get()`.
|
A data item is removed from a LIFO by calling :c:func:`k_lifo_get`.
|
||||||
|
|
||||||
The following code builds on the example above, and uses the LIFO
|
The following code builds on the example above, and uses the LIFO
|
||||||
to obtain data items from a producer thread,
|
to obtain data items from a producer thread,
|
||||||
|
|
|
@ -119,7 +119,7 @@ Defining a Mailbox
|
||||||
==================
|
==================
|
||||||
|
|
||||||
A mailbox is defined using a variable of type :c:type:`k_mbox`.
|
A mailbox is defined using a variable of type :c:type:`k_mbox`.
|
||||||
It must then be initialized by calling :cpp:func:`k_mbox_init()`.
|
It must then be initialized by calling :c:func:`k_mbox_init`.
|
||||||
|
|
||||||
The following code defines and initializes an empty mailbox.
|
The following code defines and initializes an empty mailbox.
|
||||||
|
|
||||||
|
@ -486,12 +486,12 @@ The receiving thread must then respond as follows:
|
||||||
the mailbox has already completed data retrieval and deleted the message.
|
the mailbox has already completed data retrieval and deleted the message.
|
||||||
|
|
||||||
* If the message descriptor size is non-zero and the receiving thread still
|
* If the message descriptor size is non-zero and the receiving thread still
|
||||||
wants to retrieve the data, the thread must call :cpp:func:`k_mbox_data_get()`
|
wants to retrieve the data, the thread must call :c:func:`k_mbox_data_get`
|
||||||
and supply a message buffer large enough to hold the data. The mailbox copies
|
and supply a message buffer large enough to hold the data. The mailbox copies
|
||||||
the data into the message buffer and deletes the message.
|
the data into the message buffer and deletes the message.
|
||||||
|
|
||||||
* If the message descriptor size is non-zero and the receiving thread does *not*
|
* If the message descriptor size is non-zero and the receiving thread does *not*
|
||||||
want to retrieve the data, the thread must call :cpp:func:`k_mbox_data_get()`.
|
want to retrieve the data, the thread must call :c:func:`k_mbox_data_get`.
|
||||||
and specify a message buffer of :c:macro:`NULL`. The mailbox deletes
|
and specify a message buffer of :c:macro:`NULL`. The mailbox deletes
|
||||||
the message without copying the data.
|
the message without copying the data.
|
||||||
|
|
||||||
|
@ -550,7 +550,7 @@ A receiving thread may choose to retrieve message data into a memory block,
|
||||||
rather than a message buffer. This is done in much the same way as retrieving
|
rather than a message buffer. This is done in much the same way as retrieving
|
||||||
data subsequently into a message buffer --- the receiving thread first
|
data subsequently into a message buffer --- the receiving thread first
|
||||||
receives the message without its data, then retrieves the data by calling
|
receives the message without its data, then retrieves the data by calling
|
||||||
:cpp:func:`k_mbox_data_block_get()`. The mailbox fills in the block descriptor
|
:c:func:`k_mbox_data_block_get`. The mailbox fills in the block descriptor
|
||||||
supplied by the receiving thread, allowing the thread to access the data.
|
supplied by the receiving thread, allowing the thread to access the data.
|
||||||
The mailbox also deletes the received message, since data retrieval
|
The mailbox also deletes the received message, since data retrieval
|
||||||
has been completed. The receiving thread is then responsible for freeing
|
has been completed. The receiving thread is then responsible for freeing
|
||||||
|
|
|
@ -71,7 +71,7 @@ Defining a Message Queue
|
||||||
========================
|
========================
|
||||||
|
|
||||||
A message queue is defined using a variable of type :c:type:`k_msgq`.
|
A message queue is defined using a variable of type :c:type:`k_msgq`.
|
||||||
It must then be initialized by calling :cpp:func:`k_msgq_init()`.
|
It must then be initialized by calling :c:func:`k_msgq_init`.
|
||||||
|
|
||||||
The following code defines and initializes an empty message queue
|
The following code defines and initializes an empty message queue
|
||||||
that is capable of holding 10 items, each of which is 12 bytes long.
|
that is capable of holding 10 items, each of which is 12 bytes long.
|
||||||
|
@ -102,7 +102,7 @@ that the macro defines both the message queue and its buffer.
|
||||||
Writing to a Message Queue
|
Writing to a Message Queue
|
||||||
==========================
|
==========================
|
||||||
|
|
||||||
A data item is added to a message queue by calling :cpp:func:`k_msgq_put()`.
|
A data item is added to a message queue by calling :c:func:`k_msgq_put`.
|
||||||
|
|
||||||
The following code builds on the example above, and uses the message queue
|
The following code builds on the example above, and uses the message queue
|
||||||
to pass data items from a producing thread to one or more consuming threads.
|
to pass data items from a producing thread to one or more consuming threads.
|
||||||
|
@ -132,7 +132,7 @@ producing thread throws away all existing data so the newer data can be saved.
|
||||||
Reading from a Message Queue
|
Reading from a Message Queue
|
||||||
============================
|
============================
|
||||||
|
|
||||||
A data item is taken from a message queue by calling :cpp:func:`k_msgq_get()`.
|
A data item is taken from a message queue by calling :c:func:`k_msgq_get`.
|
||||||
|
|
||||||
The following code builds on the example above, and uses the message queue
|
The following code builds on the example above, and uses the message queue
|
||||||
to process data items generated by one or more producing threads.
|
to process data items generated by one or more producing threads.
|
||||||
|
@ -155,7 +155,7 @@ to process data items generated by one or more producing threads.
|
||||||
Peeking into a Message Queue
|
Peeking into a Message Queue
|
||||||
============================
|
============================
|
||||||
|
|
||||||
A data item is read from a message queue by calling :cpp:func:`k_msgq_peek()`.
|
A data item is read from a message queue by calling :c:func:`k_msgq_peek`.
|
||||||
|
|
||||||
The following code peeks into the message queue to read the data item at the
|
The following code peeks into the message queue to read the data item at the
|
||||||
head of the queue that is generated by one or more producing threads.
|
head of the queue that is generated by one or more producing threads.
|
||||||
|
|
|
@ -54,7 +54,7 @@ Implementation
|
||||||
|
|
||||||
A pipe is defined using a variable of type :c:type:`k_pipe` and an
|
A pipe is defined using a variable of type :c:type:`k_pipe` and an
|
||||||
optional character buffer of type ``unsigned char``. It must then be
|
optional character buffer of type ``unsigned char``. It must then be
|
||||||
initialized by calling :cpp:func:`k_pipe_init()`.
|
initialized by calling :c:func:`k_pipe_init`.
|
||||||
|
|
||||||
The following code defines and initializes an empty pipe that has a ring
|
The following code defines and initializes an empty pipe that has a ring
|
||||||
buffer capable of holding 100 bytes and is aligned to a 4-byte boundary.
|
buffer capable of holding 100 bytes and is aligned to a 4-byte boundary.
|
||||||
|
@ -80,7 +80,7 @@ that that macro defines both the pipe and its ring buffer.
|
||||||
Writing to a Pipe
|
Writing to a Pipe
|
||||||
=================
|
=================
|
||||||
|
|
||||||
Data is added to a pipe by calling :cpp:func:`k_pipe_put()`.
|
Data is added to a pipe by calling :c:func:`k_pipe_put`.
|
||||||
|
|
||||||
The following code builds on the example above, and uses the pipe to pass
|
The following code builds on the example above, and uses the pipe to pass
|
||||||
data from a producing thread to one or more consuming threads. If the pipe's
|
data from a producing thread to one or more consuming threads. If the pipe's
|
||||||
|
@ -126,7 +126,7 @@ waits for a specified amount of time.
|
||||||
Reading from a Pipe
|
Reading from a Pipe
|
||||||
===================
|
===================
|
||||||
|
|
||||||
Data is read from the pipe by calling :cpp:func:`k_pipe_get()`.
|
Data is read from the pipe by calling :c:func:`k_pipe_get`.
|
||||||
|
|
||||||
The following code builds on the example above, and uses the pipe to
|
The following code builds on the example above, and uses the pipe to
|
||||||
process data items generated by one or more producing threads.
|
process data items generated by one or more producing threads.
|
||||||
|
|
|
@ -56,8 +56,8 @@ Defining a Stack
|
||||||
================
|
================
|
||||||
|
|
||||||
A stack is defined using a variable of type :c:type:`k_stack`.
|
A stack is defined using a variable of type :c:type:`k_stack`.
|
||||||
It must then be initialized by calling :cpp:func:`k_stack_init()` or
|
It must then be initialized by calling :c:func:`k_stack_init` or
|
||||||
:cpp:func:`k_stack_alloc_init()`. In the latter case, a buffer is not
|
:c:func:`k_stack_alloc_init`. In the latter case, a buffer is not
|
||||||
provided and it is instead allocated from the calling thread's resource
|
provided and it is instead allocated from the calling thread's resource
|
||||||
pool.
|
pool.
|
||||||
|
|
||||||
|
@ -86,7 +86,7 @@ that the macro defines both the stack and its array of data values.
|
||||||
Pushing to a Stack
|
Pushing to a Stack
|
||||||
==================
|
==================
|
||||||
|
|
||||||
A data item is added to a stack by calling :cpp:func:`k_stack_push()`.
|
A data item is added to a stack by calling :c:func:`k_stack_push`.
|
||||||
|
|
||||||
The following code builds on the example above, and shows how a thread
|
The following code builds on the example above, and shows how a thread
|
||||||
can create a pool of data structures by saving their memory addresses
|
can create a pool of data structures by saving their memory addresses
|
||||||
|
@ -109,7 +109,7 @@ in a stack.
|
||||||
Popping from a Stack
|
Popping from a Stack
|
||||||
====================
|
====================
|
||||||
|
|
||||||
A data item is taken from a stack by calling :cpp:func:`k_stack_pop()`.
|
A data item is taken from a stack by calling :c:func:`k_stack_pop`.
|
||||||
|
|
||||||
The following code builds on the example above, and shows how a thread
|
The following code builds on the example above, and shows how a thread
|
||||||
can dynamically allocate an unused data structure.
|
can dynamically allocate an unused data structure.
|
||||||
|
|
|
@ -18,12 +18,12 @@ with a given name that manages a memory region of the
|
||||||
specified size.
|
specified size.
|
||||||
|
|
||||||
Heaps can also be created to manage arbitrary regions of
|
Heaps can also be created to manage arbitrary regions of
|
||||||
application-controlled memory using :cpp:func:`k_heap_init()`.
|
application-controlled memory using :c:func:`k_heap_init`.
|
||||||
|
|
||||||
Allocating Memory
|
Allocating Memory
|
||||||
=================
|
=================
|
||||||
|
|
||||||
Memory can be allocated from a heap using :cpp:func:`k_heap_alloc()`,
|
Memory can be allocated from a heap using :c:func:`k_heap_alloc`,
|
||||||
passing it the address of the heap object and the number of bytes
|
passing it the address of the heap object and the number of bytes
|
||||||
desired. This functions similarly to standard C ``malloc()``,
|
desired. This functions similarly to standard C ``malloc()``,
|
||||||
returning a NULL pointer on an allocation failure.
|
returning a NULL pointer on an allocation failure.
|
||||||
|
@ -37,10 +37,10 @@ sleep before returning, or else one of the constant timeout values
|
||||||
Releasing Memory
|
Releasing Memory
|
||||||
================
|
================
|
||||||
|
|
||||||
Memory allocated with :cpp:func:`k_heap_alloc()` must be released using
|
Memory allocated with :c:func:`k_heap_alloc` must be released using
|
||||||
:cpp:func:`k_heap_free()`. Similar to standard C ``free()``, the pointer
|
:c:func:`k_heap_free`. Similar to standard C ``free()``, the pointer
|
||||||
provided must be either a ``NULL`` value or a pointer previously
|
provided must be either a ``NULL`` value or a pointer previously
|
||||||
returned by :cpp:func:`k_heap_alloc()` for the same heap. Freeing a
|
returned by :c:func:`k_heap_alloc` for the same heap. Freeing a
|
||||||
``NULL`` value is defined to have no effect.
|
``NULL`` value is defined to have no effect.
|
||||||
|
|
||||||
Low Level Heap Allocator
|
Low Level Heap Allocator
|
||||||
|
@ -100,7 +100,7 @@ System Heap
|
||||||
|
|
||||||
The :dfn:`system heap` is a predefined memory allocator that allows
|
The :dfn:`system heap` is a predefined memory allocator that allows
|
||||||
threads to dynamically allocate memory from a common memory region in
|
threads to dynamically allocate memory from a common memory region in
|
||||||
a :cpp:func:`malloc()`-like manner.
|
a :c:func:`malloc`-like manner.
|
||||||
|
|
||||||
Only a single system heap is be defined. Unlike other heaps or memory
|
Only a single system heap is be defined. Unlike other heaps or memory
|
||||||
pools, the system heap cannot be directly referenced using its
|
pools, the system heap cannot be directly referenced using its
|
||||||
|
@ -110,12 +110,12 @@ The size of the system heap is configurable to arbitrary sizes,
|
||||||
subject to space availability.
|
subject to space availability.
|
||||||
|
|
||||||
A thread can dynamically allocate a chunk of heap memory by calling
|
A thread can dynamically allocate a chunk of heap memory by calling
|
||||||
:cpp:func:`k_malloc()`. The address of the allocated chunk is
|
:c:func:`k_malloc`. The address of the allocated chunk is
|
||||||
guaranteed to be aligned on a multiple of pointer sizes. If a suitable
|
guaranteed to be aligned on a multiple of pointer sizes. If a suitable
|
||||||
chunk of heap memory cannot be found :c:macro:`NULL` is returned.
|
chunk of heap memory cannot be found :c:macro:`NULL` is returned.
|
||||||
|
|
||||||
When the thread is finished with a chunk of heap memory it can release
|
When the thread is finished with a chunk of heap memory it can release
|
||||||
the chunk back to the system heap by calling :cpp:func:`k_free()`.
|
the chunk back to the system heap by calling :c:func:`k_free`.
|
||||||
|
|
||||||
Defining the Heap Memory Pool
|
Defining the Heap Memory Pool
|
||||||
=============================
|
=============================
|
||||||
|
@ -131,7 +131,7 @@ the link stage if the size specified can not be supported.
|
||||||
Allocating Memory
|
Allocating Memory
|
||||||
=================
|
=================
|
||||||
|
|
||||||
A chunk of heap memory is allocated by calling :cpp:func:`k_malloc()`.
|
A chunk of heap memory is allocated by calling :c:func:`k_malloc`.
|
||||||
|
|
||||||
The following code allocates a 200 byte chunk of heap memory, then fills it
|
The following code allocates a 200 byte chunk of heap memory, then fills it
|
||||||
with zeros. A warning is issued if a suitable chunk is not obtained.
|
with zeros. A warning is issued if a suitable chunk is not obtained.
|
||||||
|
@ -154,7 +154,7 @@ since that is the closest matching size supported by the heap memory pool.
|
||||||
Releasing Memory
|
Releasing Memory
|
||||||
================
|
================
|
||||||
|
|
||||||
A chunk of heap memory is released by calling :cpp:func:`k_free()`.
|
A chunk of heap memory is released by calling :c:func:`k_free`.
|
||||||
|
|
||||||
The following code allocates a 75 byte chunk of memory, then releases it
|
The following code allocates a 75 byte chunk of memory, then releases it
|
||||||
once it is no longer needed. (A 256 byte memory block from the heap memory
|
once it is no longer needed. (A 256 byte memory block from the heap memory
|
||||||
|
@ -172,7 +172,7 @@ Suggested Uses
|
||||||
==============
|
==============
|
||||||
|
|
||||||
Use the heap memory pool to dynamically allocate memory in a
|
Use the heap memory pool to dynamically allocate memory in a
|
||||||
:cpp:func:`malloc()`-like manner.
|
:c:func:`malloc`-like manner.
|
||||||
|
|
||||||
Configuration Options
|
Configuration Options
|
||||||
=====================
|
=====================
|
||||||
|
|
|
@ -141,7 +141,7 @@ as well as its buffer.
|
||||||
Allocating a Memory Block
|
Allocating a Memory Block
|
||||||
=========================
|
=========================
|
||||||
|
|
||||||
A memory block is allocated by calling :cpp:func:`k_mem_pool_alloc()`.
|
A memory block is allocated by calling :c:func:`k_mem_pool_alloc`.
|
||||||
|
|
||||||
The following code builds on the example above, and waits up to 100 milliseconds
|
The following code builds on the example above, and waits up to 100 milliseconds
|
||||||
for a 200 byte memory block to become available, then fills it with zeroes.
|
for a 200 byte memory block to become available, then fills it with zeroes.
|
||||||
|
@ -161,15 +161,15 @@ since that is the closest matching size supported by the memory pool.
|
||||||
printf("Memory allocation time-out");
|
printf("Memory allocation time-out");
|
||||||
}
|
}
|
||||||
|
|
||||||
Memory blocks may also be allocated with :cpp:func:`malloc()`-like semantics
|
Memory blocks may also be allocated with :c:func:`malloc`-like semantics
|
||||||
using :cpp:func:`k_mem_pool_malloc()`. Such allocations must be freed with
|
using :c:func:`k_mem_pool_malloc`. Such allocations must be freed with
|
||||||
:cpp:func:`k_free()`.
|
:c:func:`k_free`.
|
||||||
|
|
||||||
Releasing a Memory Block
|
Releasing a Memory Block
|
||||||
========================
|
========================
|
||||||
|
|
||||||
A memory block is released by calling either :cpp:func:`k_mem_pool_free()`
|
A memory block is released by calling either :c:func:`k_mem_pool_free`
|
||||||
or :cpp:func:`k_free()`, depending on how it was allocated.
|
or :c:func:`k_free`, depending on how it was allocated.
|
||||||
|
|
||||||
The following code builds on the example above, and allocates a 75 byte
|
The following code builds on the example above, and allocates a 75 byte
|
||||||
memory block, then releases it once it is no longer needed. (A 256 byte
|
memory block, then releases it once it is no longer needed. (A 256 byte
|
||||||
|
@ -195,12 +195,12 @@ as items are placed in the queue.
|
||||||
Such memory allocations are drawn from memory pools that are assigned to
|
Such memory allocations are drawn from memory pools that are assigned to
|
||||||
a thread. By default, a thread in the system has no resource pool and
|
a thread. By default, a thread in the system has no resource pool and
|
||||||
any allocations made on its behalf will fail. The supervisor-mode only
|
any allocations made on its behalf will fail. The supervisor-mode only
|
||||||
:cpp:func:`k_thread_resource_pool_assign()` will associate any implicit
|
:c:func:`k_thread_resource_pool_assign` will associate any implicit
|
||||||
kernel-side allocations to the target thread with the provided memory pool,
|
kernel-side allocations to the target thread with the provided memory pool,
|
||||||
and any children of that thread will inherit this assignment.
|
and any children of that thread will inherit this assignment.
|
||||||
|
|
||||||
If a system heap exists, threads may alternatively have their resources
|
If a system heap exists, threads may alternatively have their resources
|
||||||
drawn from it using the :cpp:func:`k_thread_system_pool_assign()` API.
|
drawn from it using the :c:func:`k_thread_system_pool_assign` API.
|
||||||
|
|
||||||
Suggested Uses
|
Suggested Uses
|
||||||
**************
|
**************
|
||||||
|
|
|
@ -68,7 +68,7 @@ Defining a Memory Slab
|
||||||
======================
|
======================
|
||||||
|
|
||||||
A memory slab is defined using a variable of type :c:type:`k_mem_slab`.
|
A memory slab is defined using a variable of type :c:type:`k_mem_slab`.
|
||||||
It must then be initialized by calling :cpp:func:`k_mem_slab_init()`.
|
It must then be initialized by calling :c:func:`k_mem_slab_init`.
|
||||||
|
|
||||||
The following code defines and initializes a memory slab that has 6 blocks
|
The following code defines and initializes a memory slab that has 6 blocks
|
||||||
that are 400 bytes long, each of which is aligned to a 4-byte boundary..
|
that are 400 bytes long, each of which is aligned to a 4-byte boundary..
|
||||||
|
@ -93,7 +93,7 @@ that the macro defines both the memory slab and its buffer.
|
||||||
Allocating a Memory Block
|
Allocating a Memory Block
|
||||||
=========================
|
=========================
|
||||||
|
|
||||||
A memory block is allocated by calling :cpp:func:`k_mem_slab_alloc()`.
|
A memory block is allocated by calling :c:func:`k_mem_slab_alloc`.
|
||||||
|
|
||||||
The following code builds on the example above, and waits up to 100 milliseconds
|
The following code builds on the example above, and waits up to 100 milliseconds
|
||||||
for a memory block to become available, then fills it with zeroes.
|
for a memory block to become available, then fills it with zeroes.
|
||||||
|
@ -113,7 +113,7 @@ A warning is printed if a suitable block is not obtained.
|
||||||
Releasing a Memory Block
|
Releasing a Memory Block
|
||||||
========================
|
========================
|
||||||
|
|
||||||
A memory block is released by calling :cpp:func:`k_mem_slab_free()`.
|
A memory block is released by calling :c:func:`k_mem_slab_free`.
|
||||||
|
|
||||||
The following code builds on the example above, and allocates a memory block,
|
The following code builds on the example above, and allocates a memory block,
|
||||||
then releases it once it is no longer needed.
|
then releases it once it is no longer needed.
|
||||||
|
|
|
@ -70,7 +70,7 @@ However, you can also define an N-bit array of atomic variables using
|
||||||
:c:macro:`ATOMIC_DEFINE`.
|
:c:macro:`ATOMIC_DEFINE`.
|
||||||
|
|
||||||
A single bit in array of atomic variables can be manipulated using
|
A single bit in array of atomic variables can be manipulated using
|
||||||
the APIs listed at the end of this section that end with :cpp:func:`_bit`.
|
the APIs listed at the end of this section that end with :c:func:`_bit`.
|
||||||
|
|
||||||
The following code shows how a set of 200 flag bits can be implemented
|
The following code shows how a set of 200 flag bits can be implemented
|
||||||
using an array of atomic variables.
|
using an array of atomic variables.
|
||||||
|
|
|
@ -87,7 +87,7 @@ using one of the techniques listed below.
|
||||||
:c:macro:`K_FP_REGS` option to :c:macro:`K_THREAD_DEFINE`.
|
:c:macro:`K_FP_REGS` option to :c:macro:`K_THREAD_DEFINE`.
|
||||||
|
|
||||||
* A dynamically-created ARM thread can be pretagged by passing the
|
* A dynamically-created ARM thread can be pretagged by passing the
|
||||||
:c:macro:`K_FP_REGS` option to :cpp:func:`k_thread_create()`.
|
:c:macro:`K_FP_REGS` option to :c:func:`k_thread_create`.
|
||||||
|
|
||||||
Pretagging a thread with the :c:macro:`K_FP_REGS` option instructs the
|
Pretagging a thread with the :c:macro:`K_FP_REGS` option instructs the
|
||||||
MPU-based stack protection mechanism to properly configure the size of
|
MPU-based stack protection mechanism to properly configure the size of
|
||||||
|
@ -113,7 +113,7 @@ architecture, minimizing interrupt latency, when the floating
|
||||||
point context is active.
|
point context is active.
|
||||||
|
|
||||||
If an ARM thread does not require use of the floating point registers any
|
If an ARM thread does not require use of the floating point registers any
|
||||||
more, it can call :cpp:func:`k_float_disable()`. This instructs the kernel
|
more, it can call :c:func:`k_float_disable`. This instructs the kernel
|
||||||
not to save or restore its FP context during thread context switching.
|
not to save or restore its FP context during thread context switching.
|
||||||
|
|
||||||
ARCv2 architecture
|
ARCv2 architecture
|
||||||
|
@ -127,10 +127,10 @@ following techniques.
|
||||||
:c:macro:`K_FP_REGS` option to :c:macro:`K_THREAD_DEFINE`.
|
:c:macro:`K_FP_REGS` option to :c:macro:`K_THREAD_DEFINE`.
|
||||||
|
|
||||||
* A dynamically-created ARC thread can be tagged by passing the
|
* A dynamically-created ARC thread can be tagged by passing the
|
||||||
:c:macro:`K_FP_REGS` to :cpp:func:`k_thread_create()`.
|
:c:macro:`K_FP_REGS` to :c:func:`k_thread_create`.
|
||||||
|
|
||||||
If an ARC thread does not require use of the floating point registers any
|
If an ARC thread does not require use of the floating point registers any
|
||||||
more, it can call :cpp:func:`k_float_disable()`. This instructs the kernel
|
more, it can call :c:func:`k_float_disable`. This instructs the kernel
|
||||||
not to save or restore its FP context during thread context switching.
|
not to save or restore its FP context during thread context switching.
|
||||||
|
|
||||||
During thread context switching the ARC kernel saves the *callee-saved*
|
During thread context switching the ARC kernel saves the *callee-saved*
|
||||||
|
@ -155,13 +155,13 @@ following techniques:
|
||||||
:c:macro:`K_FP_REGS` option to :c:macro:`K_THREAD_DEFINE`.
|
:c:macro:`K_FP_REGS` option to :c:macro:`K_THREAD_DEFINE`.
|
||||||
|
|
||||||
* A dynamically-created RISC-V thread can be tagged by passing the
|
* A dynamically-created RISC-V thread can be tagged by passing the
|
||||||
:c:macro:`K_FP_REGS` to :cpp:func:`k_thread_create()`.
|
:c:macro:`K_FP_REGS` to :c:func:`k_thread_create`.
|
||||||
|
|
||||||
* A running RISC-V thread can be tagged by calling :cpp:func:`k_float_enable()`.
|
* A running RISC-V thread can be tagged by calling :c:func:`k_float_enable`.
|
||||||
This function can only be called from the thread itself.
|
This function can only be called from the thread itself.
|
||||||
|
|
||||||
If a RISC-V thread no longer requires the use of the floating point registers,
|
If a RISC-V thread no longer requires the use of the floating point registers,
|
||||||
it can call :cpp:func:`k_float_disable()`. This instructs the kernel not to
|
it can call :c:func:`k_float_disable`. This instructs the kernel not to
|
||||||
save or restore its FP context during thread context switching. This function
|
save or restore its FP context during thread context switching. This function
|
||||||
can only be called from the thread itself.
|
can only be called from the thread itself.
|
||||||
|
|
||||||
|
@ -211,19 +211,19 @@ pretag a thread using one of the techniques listed below.
|
||||||
|
|
||||||
* A dynamically-created x86 thread can be pretagged by passing the
|
* A dynamically-created x86 thread can be pretagged by passing the
|
||||||
:c:macro:`K_FP_REGS` or :c:macro:`K_SSE_REGS` option to
|
:c:macro:`K_FP_REGS` or :c:macro:`K_SSE_REGS` option to
|
||||||
:cpp:func:`k_thread_create()`.
|
:c:func:`k_thread_create`.
|
||||||
|
|
||||||
* An already-created x86 thread can pretag itself once it has started
|
* An already-created x86 thread can pretag itself once it has started
|
||||||
by passing the :c:macro:`K_FP_REGS` or :c:macro:`K_SSE_REGS` option to
|
by passing the :c:macro:`K_FP_REGS` or :c:macro:`K_SSE_REGS` option to
|
||||||
:cpp:func:`k_float_enable()`.
|
:c:func:`k_float_enable`.
|
||||||
|
|
||||||
If an x86 thread uses the floating point registers infrequently it can call
|
If an x86 thread uses the floating point registers infrequently it can call
|
||||||
:cpp:func:`k_float_disable()` to remove its tagging as an FPU user or SSE user.
|
:c:func:`k_float_disable` to remove its tagging as an FPU user or SSE user.
|
||||||
This eliminates the need for the kernel to take steps to preserve
|
This eliminates the need for the kernel to take steps to preserve
|
||||||
the contents of the floating point registers during context switches
|
the contents of the floating point registers during context switches
|
||||||
when there is no need to do so.
|
when there is no need to do so.
|
||||||
When the thread again needs to use the floating point registers it can re-tag
|
When the thread again needs to use the floating point registers it can re-tag
|
||||||
itself as an FPU user or SSE user by calling :cpp:func:`k_float_enable()`.
|
itself as an FPU user or SSE user by calling :c:func:`k_float_enable`.
|
||||||
|
|
||||||
Implementation
|
Implementation
|
||||||
**************
|
**************
|
||||||
|
|
|
@ -53,7 +53,7 @@ nesting support is enabled.
|
||||||
.. important::
|
.. important::
|
||||||
Many kernel APIs can be used only by threads, and not by ISRs. In cases
|
Many kernel APIs can be used only by threads, and not by ISRs. In cases
|
||||||
where a routine may be invoked by both threads and ISRs the kernel
|
where a routine may be invoked by both threads and ISRs the kernel
|
||||||
provides the :cpp:func:`k_is_in_isr()` API to allow the routine to
|
provides the :c:func:`k_is_in_isr` API to allow the routine to
|
||||||
alter its behavior depending on whether it is executing as part of
|
alter its behavior depending on whether it is executing as part of
|
||||||
a thread or as part of an ISR.
|
a thread or as part of an ISR.
|
||||||
|
|
||||||
|
@ -211,7 +211,7 @@ Defining a regular ISR
|
||||||
======================
|
======================
|
||||||
|
|
||||||
An ISR is defined at runtime by calling :c:macro:`IRQ_CONNECT`. It must
|
An ISR is defined at runtime by calling :c:macro:`IRQ_CONNECT`. It must
|
||||||
then be enabled by calling :cpp:func:`irq_enable()`.
|
then be enabled by calling :c:func:`irq_enable`.
|
||||||
|
|
||||||
.. important::
|
.. important::
|
||||||
IRQ_CONNECT() is not a C function and does some inline assembly magic
|
IRQ_CONNECT() is not a C function and does some inline assembly magic
|
||||||
|
@ -245,7 +245,7 @@ The following code defines and enables an ISR.
|
||||||
Since the :c:macro:`IRQ_CONNECT` macro requires that all its parameters be
|
Since the :c:macro:`IRQ_CONNECT` macro requires that all its parameters be
|
||||||
known at build time, in some cases this may not be acceptable. It is also
|
known at build time, in some cases this may not be acceptable. It is also
|
||||||
possible to install interrupts at runtime with
|
possible to install interrupts at runtime with
|
||||||
:cpp:func:`irq_connect_dynamic()`. It is used in exactly the same way as
|
:c:func:`irq_connect_dynamic`. It is used in exactly the same way as
|
||||||
:c:macro:`IRQ_CONNECT`:
|
:c:macro:`IRQ_CONNECT`:
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
@ -424,7 +424,7 @@ On x86 when an interrupt or exception vector is executed by the CPU, there is
|
||||||
no foolproof way to determine which vector was fired, so a software ISR table
|
no foolproof way to determine which vector was fired, so a software ISR table
|
||||||
indexed by IRQ line is not used. Instead, the :c:macro:`IRQ_CONNECT` call
|
indexed by IRQ line is not used. Instead, the :c:macro:`IRQ_CONNECT` call
|
||||||
creates a small assembly language function which calls the common interrupt
|
creates a small assembly language function which calls the common interrupt
|
||||||
code in :cpp:func:`_interrupt_enter` with the ISR and parameter as arguments.
|
code in :c:func:`_interrupt_enter` with the ISR and parameter as arguments.
|
||||||
It is the address of this assembly interrupt stub which gets placed in the IDT.
|
It is the address of this assembly interrupt stub which gets placed in the IDT.
|
||||||
For interrupts declared with :c:macro:`IRQ_DIRECT_CONNECT` the parameterless
|
For interrupts declared with :c:macro:`IRQ_DIRECT_CONNECT` the parameterless
|
||||||
ISR is placed directly in the IDT.
|
ISR is placed directly in the IDT.
|
||||||
|
|
|
@ -13,8 +13,8 @@ to be fulfilled.
|
||||||
Concepts
|
Concepts
|
||||||
********
|
********
|
||||||
|
|
||||||
The polling API's main function is :cpp:func:`k_poll()`, which is very similar
|
The polling API's main function is :c:func:`k_poll`, which is very similar
|
||||||
in concept to the POSIX :cpp:func:`poll()` function, except that it operates on
|
in concept to the POSIX :c:func:`poll` function, except that it operates on
|
||||||
kernel objects rather than on file descriptors.
|
kernel objects rather than on file descriptors.
|
||||||
|
|
||||||
The polling API allows a single thread to wait concurrently for one or more
|
The polling API allows a single thread to wait concurrently for one or more
|
||||||
|
@ -46,19 +46,19 @@ to the user's discretion.
|
||||||
Apart from the kernel objects, there is also a **poll signal** pseudo-object
|
Apart from the kernel objects, there is also a **poll signal** pseudo-object
|
||||||
type that be directly signaled.
|
type that be directly signaled.
|
||||||
|
|
||||||
The :cpp:func:`k_poll()` function returns as soon as one of the conditions it
|
The :c:func:`k_poll` function returns as soon as one of the conditions it
|
||||||
is waiting for is fulfilled. It is possible for more than one to be fulfilled
|
is waiting for is fulfilled. It is possible for more than one to be fulfilled
|
||||||
when :cpp:func:`k_poll()` returns, if they were fulfilled before
|
when :c:func:`k_poll` returns, if they were fulfilled before
|
||||||
:cpp:func:`k_poll()` was called, or due to the preemptive multi-threading
|
:c:func:`k_poll` was called, or due to the preemptive multi-threading
|
||||||
nature of the kernel. The caller must look at the state of all the poll events
|
nature of the kernel. The caller must look at the state of all the poll events
|
||||||
in the array to figured out which ones were fulfilled and what actions to take.
|
in the array to figured out which ones were fulfilled and what actions to take.
|
||||||
|
|
||||||
Currently, there is only one mode of operation available: the object is not
|
Currently, there is only one mode of operation available: the object is not
|
||||||
acquired. As an example, this means that when :cpp:func:`k_poll()` returns and
|
acquired. As an example, this means that when :c:func:`k_poll` returns and
|
||||||
the poll event states that the semaphore is available, the caller of
|
the poll event states that the semaphore is available, the caller of
|
||||||
:cpp:func:`k_poll()` must then invoke :cpp:func:`k_sem_take()` to take
|
:c:func:`k_poll()` must then invoke :c:func:`k_sem_take` to take
|
||||||
ownership of the semaphore. If the semaphore is contested, there is no
|
ownership of the semaphore. If the semaphore is contested, there is no
|
||||||
guarantee that it will be still available when :cpp:func:`k_sem_give()` is
|
guarantee that it will be still available when :c:func:`k_sem_give` is
|
||||||
called.
|
called.
|
||||||
|
|
||||||
Implementation
|
Implementation
|
||||||
|
@ -67,13 +67,13 @@ Implementation
|
||||||
Using k_poll()
|
Using k_poll()
|
||||||
==============
|
==============
|
||||||
|
|
||||||
The main API is :cpp:func:`k_poll()`, which operates on an array of poll events
|
The main API is :c:func:`k_poll`, which operates on an array of poll events
|
||||||
of type :c:type:`k_poll_event`. Each entry in the array represents one
|
of type :c:type:`k_poll_event`. Each entry in the array represents one
|
||||||
event a call to :cpp:func:`k_poll()` will wait for its condition to be
|
event a call to :c:func:`k_poll` will wait for its condition to be
|
||||||
fulfilled.
|
fulfilled.
|
||||||
|
|
||||||
They can be initialized using either the runtime initializers
|
They can be initialized using either the runtime initializers
|
||||||
:c:macro:`K_POLL_EVENT_INITIALIZER()` or :cpp:func:`k_poll_event_init()`, or
|
:c:macro:`K_POLL_EVENT_INITIALIZER()` or :c:func:`k_poll_event_init`, or
|
||||||
the static initializer :c:macro:`K_POLL_EVENT_STATIC_INITIALIZER()`. An object
|
the static initializer :c:macro:`K_POLL_EVENT_STATIC_INITIALIZER()`. An object
|
||||||
that matches the **type** specified must be passed to the initializers. The
|
that matches the **type** specified must be passed to the initializers. The
|
||||||
**mode** *must* be set to :c:macro:`K_POLL_MODE_NOTIFY_ONLY`. The state *must*
|
**mode** *must* be set to :c:macro:`K_POLL_MODE_NOTIFY_ONLY`. The state *must*
|
||||||
|
@ -118,18 +118,18 @@ or at runtime
|
||||||
|
|
||||||
|
|
||||||
After the events are initialized, the array can be passed to
|
After the events are initialized, the array can be passed to
|
||||||
:cpp:func:`k_poll()`. A timeout can be specified to wait only for a specified
|
:c:func:`k_poll`. A timeout can be specified to wait only for a specified
|
||||||
amount of time, or the special values :c:macro:`K_NO_WAIT` and
|
amount of time, or the special values :c:macro:`K_NO_WAIT` and
|
||||||
:c:macro:`K_FOREVER` to either not wait or wait until an event condition is
|
:c:macro:`K_FOREVER` to either not wait or wait until an event condition is
|
||||||
satisfied and not sooner.
|
satisfied and not sooner.
|
||||||
|
|
||||||
Only one thread can poll on a semaphore or a FIFO at a time. If a second thread
|
Only one thread can poll on a semaphore or a FIFO at a time. If a second thread
|
||||||
tries to poll on the same semaphore or FIFO, :cpp:func:`k_poll()` immediately
|
tries to poll on the same semaphore or FIFO, :c:func:`k_poll` immediately
|
||||||
returns with the return value -:c:macro:`EADDRINUSE`. In that case, if other
|
returns with the return value -:c:macro:`EADDRINUSE`. In that case, if other
|
||||||
conditions passed to :cpp:func:`k_poll` were met, their state will be set in
|
conditions passed to :c:func:`k_poll` were met, their state will be set in
|
||||||
the corresponding poll event.
|
the corresponding poll event.
|
||||||
|
|
||||||
In case of success, :cpp:func:`k_poll()` returns 0. If it times out, it returns
|
In case of success, :c:func:`k_poll` returns 0. If it times out, it returns
|
||||||
-:c:macro:`EAGAIN`.
|
-:c:macro:`EAGAIN`.
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
@ -152,7 +152,7 @@ In case of success, :cpp:func:`k_poll()` returns 0. If it times out, it returns
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
When :cpp:func:`k_poll()` is called in a loop, the events state must be reset
|
When :c:func:`k_poll` is called in a loop, the events state must be reset
|
||||||
to :c:macro:`K_POLL_STATE_NOT_READY` by the user.
|
to :c:macro:`K_POLL_STATE_NOT_READY` by the user.
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
@ -182,7 +182,7 @@ one thread can wait for.
|
||||||
A poll signal is a separate object of type :c:type:`k_poll_signal` that
|
A poll signal is a separate object of type :c:type:`k_poll_signal` that
|
||||||
must be attached to a k_poll_event, similar to a semaphore or FIFO. It must
|
must be attached to a k_poll_event, similar to a semaphore or FIFO. It must
|
||||||
first be initialized either via :c:macro:`K_POLL_SIGNAL_INITIALIZER()` or
|
first be initialized either via :c:macro:`K_POLL_SIGNAL_INITIALIZER()` or
|
||||||
:cpp:func:`k_poll_signal_init()`.
|
:c:func:`k_poll_signal_init`.
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
|
@ -192,7 +192,7 @@ first be initialized either via :c:macro:`K_POLL_SIGNAL_INITIALIZER()` or
|
||||||
k_poll_signal_init(&signal);
|
k_poll_signal_init(&signal);
|
||||||
}
|
}
|
||||||
|
|
||||||
It is signaled via the :cpp:func:`k_poll_signal_raise()` function. This function
|
It is signaled via the :c:func:`k_poll_signal_raise` function. This function
|
||||||
takes a user **result** parameter that is opaque to the API and can be used to
|
takes a user **result** parameter that is opaque to the API and can be used to
|
||||||
pass extra information to the thread waiting on the event.
|
pass extra information to the thread waiting on the event.
|
||||||
|
|
||||||
|
@ -259,7 +259,7 @@ If the signal is to be polled in a loop, *both* its event state and its
|
||||||
Suggested Uses
|
Suggested Uses
|
||||||
**************
|
**************
|
||||||
|
|
||||||
Use :cpp:func:`k_poll()` to consolidate multiple threads that would be pending
|
Use :c:func:`k_poll` to consolidate multiple threads that would be pending
|
||||||
on one object each, saving possibly large amounts of stack space.
|
on one object each, saving possibly large amounts of stack space.
|
||||||
|
|
||||||
Use a poll signal as a lightweight binary semaphore if only one thread pends on
|
Use a poll signal as a lightweight binary semaphore if only one thread pends on
|
||||||
|
|
|
@ -42,15 +42,15 @@ Data item mode
|
||||||
A **data item mode** ring buffer instance is declared using
|
A **data item mode** ring buffer instance is declared using
|
||||||
:cpp:func:`RING_BUF_ITEM_DECLARE_POW2()` or
|
:cpp:func:`RING_BUF_ITEM_DECLARE_POW2()` or
|
||||||
:cpp:func:`RING_BUF_ITEM_DECLARE_SIZE()` and accessed using
|
:cpp:func:`RING_BUF_ITEM_DECLARE_SIZE()` and accessed using
|
||||||
:cpp:func:`ring_buf_item_put()` and :cpp:func:`ring_buf_item_get()`.
|
:c:func:`ring_buf_item_put` and :c:func:`ring_buf_item_get`.
|
||||||
|
|
||||||
A ring buffer **data item** is an array of 32-bit words from 0 to 1020 bytes
|
A ring buffer **data item** is an array of 32-bit words from 0 to 1020 bytes
|
||||||
in length. When a data item is **enqueued** (:cpp:func:`ring_buf_item_put()`)
|
in length. When a data item is **enqueued** (:c:func:`ring_buf_item_put`)
|
||||||
its contents are copied to the data buffer, along with its associated metadata
|
its contents are copied to the data buffer, along with its associated metadata
|
||||||
values (which occupy one additional 32-bit word). If the ring buffer has
|
values (which occupy one additional 32-bit word). If the ring buffer has
|
||||||
insufficient space to hold the new data item the enqueue operation fails.
|
insufficient space to hold the new data item the enqueue operation fails.
|
||||||
|
|
||||||
A data items is **dequeued** (:cpp:func:`ring_buf_item_get()`) from a ring
|
A data items is **dequeued** (:c:func:`ring_buf_item_get`) from a ring
|
||||||
buffer by removing the oldest enqueued item. The contents of the dequeued data
|
buffer by removing the oldest enqueued item. The contents of the dequeued data
|
||||||
item, as well as its two metadata values, are copied to areas supplied by the
|
item, as well as its two metadata values, are copied to areas supplied by the
|
||||||
retriever. If the ring buffer is empty, or if the data array supplied by the
|
retriever. If the ring buffer is empty, or if the data array supplied by the
|
||||||
|
@ -62,30 +62,30 @@ Byte mode
|
||||||
|
|
||||||
A **byte mode** ring buffer instance is declared using
|
A **byte mode** ring buffer instance is declared using
|
||||||
:cpp:func:`RING_BUF_DECLARE_SIZE()` and accessed using:
|
:cpp:func:`RING_BUF_DECLARE_SIZE()` and accessed using:
|
||||||
:cpp:func:`ring_buf_put_claim()`, :cpp:func:`ring_buf_put_finish()`,
|
:c:func:`ring_buf_put_claim`, :c:func:`ring_buf_put_finish`,
|
||||||
:cpp:func:`ring_buf_get_claim()`, :cpp:func:`ring_buf_get_finish()`,
|
:c:func:`ring_buf_get_claim`, :c:func:`ring_buf_get_finish`,
|
||||||
:cpp:func:`ring_buf_put()` and :cpp:func:`ring_buf_get()`.
|
:c:func:`ring_buf_put` and :c:func:`ring_buf_get`.
|
||||||
|
|
||||||
Data can be copied into the ring buffer (see
|
Data can be copied into the ring buffer (see
|
||||||
:cpp:func:`ring_buf_put()`) or ring buffer memory can be used
|
:c:func:`ring_buf_put`) or ring buffer memory can be used
|
||||||
directly by the user. In the latter case, the operation is split into three stages:
|
directly by the user. In the latter case, the operation is split into three stages:
|
||||||
|
|
||||||
1. allocating the buffer (:cpp:func:`ring_buf_put_claim()`) when
|
1. allocating the buffer (:c:func:`ring_buf_put_claim`) when
|
||||||
user requests the destination location where data can be written.
|
user requests the destination location where data can be written.
|
||||||
#. writing the data by the user (e.g. buffer written by DMA).
|
#. writing the data by the user (e.g. buffer written by DMA).
|
||||||
#. indicating the amount of data written to the provided buffer
|
#. indicating the amount of data written to the provided buffer
|
||||||
(:cpp:func:`ring_buf_put_finish()`). The amount
|
(:c:func:`ring_buf_put_finish`). The amount
|
||||||
can be less than or equal to the allocated amount.
|
can be less than or equal to the allocated amount.
|
||||||
|
|
||||||
Data can be retrieved from a ring buffer through copying
|
Data can be retrieved from a ring buffer through copying
|
||||||
(see :cpp:func:`ring_buf_get()`) or accessed directly by address. In the latter
|
(see :c:func:`ring_buf_get`) or accessed directly by address. In the latter
|
||||||
case, the operation is split
|
case, the operation is split
|
||||||
into three stages:
|
into three stages:
|
||||||
|
|
||||||
1. retrieving source location with valid data written to a ring buffer
|
1. retrieving source location with valid data written to a ring buffer
|
||||||
(see :cpp:func:`ring_buf_get_claim()`).
|
(see :c:func:`ring_buf_get_claim`).
|
||||||
#. processing data
|
#. processing data
|
||||||
#. freeing processed data (see :cpp:func:`ring_buf_get_finish()`).
|
#. freeing processed data (see :c:func:`ring_buf_get_finish`).
|
||||||
The amount freed can be less than or equal or to the retrieved amount.
|
The amount freed can be less than or equal or to the retrieved amount.
|
||||||
|
|
||||||
Concurrency
|
Concurrency
|
||||||
|
@ -118,7 +118,7 @@ Defining a Ring Buffer
|
||||||
======================
|
======================
|
||||||
|
|
||||||
A ring buffer is defined using a variable of type :c:type:`ring_buf`.
|
A ring buffer is defined using a variable of type :c:type:`ring_buf`.
|
||||||
It must then be initialized by calling :cpp:func:`ring_buf_init()`.
|
It must then be initialized by calling :c:func:`ring_buf_init`.
|
||||||
|
|
||||||
The following code defines and initializes an empty **data item mode** ring
|
The following code defines and initializes an empty **data item mode** ring
|
||||||
buffer (which is part of a larger data structure). The ring buffer's data buffer
|
buffer (which is part of a larger data structure). The ring buffer's data buffer
|
||||||
|
@ -173,7 +173,7 @@ Enqueuing Data
|
||||||
==============
|
==============
|
||||||
|
|
||||||
A data item is added to a ring buffer by calling
|
A data item is added to a ring buffer by calling
|
||||||
:cpp:func:`ring_buf_item_put()`.
|
:c:func:`ring_buf_item_put`.
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
|
@ -201,7 +201,7 @@ can be specified.
|
||||||
}
|
}
|
||||||
|
|
||||||
Bytes are copied to a **byte mode** ring buffer by calling
|
Bytes are copied to a **byte mode** ring buffer by calling
|
||||||
:cpp:func:`ring_buf_put()`.
|
:c:func:`ring_buf_put`.
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
|
@ -241,7 +241,7 @@ Retrieving Data
|
||||||
===============
|
===============
|
||||||
|
|
||||||
A data item is removed from a ring buffer by calling
|
A data item is removed from a ring buffer by calling
|
||||||
:cpp:func:`ring_buf_item_get()`.
|
:c:func:`ring_buf_item_get`.
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
|
@ -264,7 +264,7 @@ A data item is removed from a ring buffer by calling
|
||||||
}
|
}
|
||||||
|
|
||||||
Data bytes are copied out from a **byte mode** ring buffer by calling
|
Data bytes are copied out from a **byte mode** ring buffer by calling
|
||||||
:cpp:func:`ring_buf_get()`. For example:
|
:c:func:`ring_buf_get`. For example:
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
|
|
|
@ -17,11 +17,11 @@ opportunity to change the identity of the current thread. These points
|
||||||
are called **reschedule points**. Some potential reschedule points are:
|
are called **reschedule points**. Some potential reschedule points are:
|
||||||
|
|
||||||
- transition of a thread to the :ref:`ready state <thread_states>`, for
|
- transition of a thread to the :ref:`ready state <thread_states>`, for
|
||||||
example by :cpp:func:`k_sem_give` or :cpp:func:`k_thread_start`
|
example by :c:func:`k_sem_give` or :c:func:`k_thread_start`
|
||||||
- transition of a thread from running state to a suspended or waiting
|
- transition of a thread from running state to a suspended or waiting
|
||||||
state, for example by :cpp:func:`k_sem_take` or :cpp:func:`k_sleep`
|
state, for example by :c:func:`k_sem_take` or :c:func:`k_sleep`
|
||||||
- return to thread context after processing an interrupt
|
- return to thread context after processing an interrupt
|
||||||
- when a running thread invokes :cpp:func:`k_yield()`
|
- when a running thread invokes :c:func:`k_yield`
|
||||||
|
|
||||||
Whenever the scheduler changes the identity of the current thread,
|
Whenever the scheduler changes the identity of the current thread,
|
||||||
or when execution of the current thread is replaced by an ISR,
|
or when execution of the current thread is replaced by an ISR,
|
||||||
|
@ -123,14 +123,14 @@ To overcome such problems, a cooperative thread can voluntarily relinquish
|
||||||
the CPU from time to time to permit other threads to execute.
|
the CPU from time to time to permit other threads to execute.
|
||||||
A thread can relinquish the CPU in two ways:
|
A thread can relinquish the CPU in two ways:
|
||||||
|
|
||||||
* Calling :cpp:func:`k_yield()` puts the thread at the back of the scheduler's
|
* Calling :c:func:`k_yield` puts the thread at the back of the scheduler's
|
||||||
prioritized list of ready threads, and then invokes the scheduler.
|
prioritized list of ready threads, and then invokes the scheduler.
|
||||||
All ready threads whose priority is higher or equal to that of the
|
All ready threads whose priority is higher or equal to that of the
|
||||||
yielding thread are then allowed to execute before the yielding thread is
|
yielding thread are then allowed to execute before the yielding thread is
|
||||||
rescheduled. If no such ready threads exist, the scheduler immediately
|
rescheduled. If no such ready threads exist, the scheduler immediately
|
||||||
reschedules the yielding thread without context switching.
|
reschedules the yielding thread without context switching.
|
||||||
|
|
||||||
* Calling :cpp:func:`k_sleep()` makes the thread unready for a specified
|
* Calling :c:func:`k_sleep` makes the thread unready for a specified
|
||||||
time period. Ready threads of *all* priorities are then allowed to execute;
|
time period. Ready threads of *all* priorities are then allowed to execute;
|
||||||
however, there is no guarantee that threads whose priority is lower
|
however, there is no guarantee that threads whose priority is lower
|
||||||
than that of the sleeping thread will actually be scheduled before
|
than that of the sleeping thread will actually be scheduled before
|
||||||
|
@ -162,7 +162,7 @@ are measured in system clock ticks. The time slice size is configurable,
|
||||||
but this size can be changed while the application is running.
|
but this size can be changed while the application is running.
|
||||||
|
|
||||||
At the end of every time slice, the scheduler checks to see if the current
|
At the end of every time slice, the scheduler checks to see if the current
|
||||||
thread is preemptible and, if so, implicitly invokes :cpp:func:`k_yield()`
|
thread is preemptible and, if so, implicitly invokes :c:func:`k_yield`
|
||||||
on behalf of the thread. This gives other ready threads of the same priority
|
on behalf of the thread. This gives other ready threads of the same priority
|
||||||
the opportunity to execute before the current thread is scheduled again.
|
the opportunity to execute before the current thread is scheduled again.
|
||||||
If no threads of equal priority are ready, the current thread remains
|
If no threads of equal priority are ready, the current thread remains
|
||||||
|
@ -187,13 +187,13 @@ Scheduler Locking
|
||||||
|
|
||||||
A preemptible thread that does not wish to be preempted while performing
|
A preemptible thread that does not wish to be preempted while performing
|
||||||
a critical operation can instruct the scheduler to temporarily treat it
|
a critical operation can instruct the scheduler to temporarily treat it
|
||||||
as a cooperative thread by calling :cpp:func:`k_sched_lock()`. This prevents
|
as a cooperative thread by calling :c:func:`k_sched_lock`. This prevents
|
||||||
other threads from interfering while the critical operation is being performed.
|
other threads from interfering while the critical operation is being performed.
|
||||||
|
|
||||||
Once the critical operation is complete the preemptible thread must call
|
Once the critical operation is complete the preemptible thread must call
|
||||||
:cpp:func:`k_sched_unlock()` to restore its normal, preemptible status.
|
:c:func:`k_sched_unlock` to restore its normal, preemptible status.
|
||||||
|
|
||||||
If a thread calls :cpp:func:`k_sched_lock()` and subsequently performs an
|
If a thread calls :c:func:`k_sched_lock` and subsequently performs an
|
||||||
action that makes it unready, the scheduler will switch the locking thread out
|
action that makes it unready, the scheduler will switch the locking thread out
|
||||||
and allow other threads to execute. When the locking thread again
|
and allow other threads to execute. When the locking thread again
|
||||||
becomes the current thread, its non-preemptible status is maintained.
|
becomes the current thread, its non-preemptible status is maintained.
|
||||||
|
@ -240,14 +240,14 @@ very high priority threads and should not be used as such.
|
||||||
Thread Sleeping
|
Thread Sleeping
|
||||||
===============
|
===============
|
||||||
|
|
||||||
A thread can call :cpp:func:`k_sleep()` to delay its processing
|
A thread can call :c:func:`k_sleep` to delay its processing
|
||||||
for a specified time period. During the time the thread is sleeping
|
for a specified time period. During the time the thread is sleeping
|
||||||
the CPU is relinquished to allow other ready threads to execute.
|
the CPU is relinquished to allow other ready threads to execute.
|
||||||
Once the specified delay has elapsed the thread becomes ready
|
Once the specified delay has elapsed the thread becomes ready
|
||||||
and is eligible to be scheduled once again.
|
and is eligible to be scheduled once again.
|
||||||
|
|
||||||
A sleeping thread can be woken up prematurely by another thread using
|
A sleeping thread can be woken up prematurely by another thread using
|
||||||
:cpp:func:`k_wakeup()`. This technique can sometimes be used
|
:c:func:`k_wakeup`. This technique can sometimes be used
|
||||||
to permit the secondary thread to signal the sleeping thread
|
to permit the secondary thread to signal the sleeping thread
|
||||||
that something has occurred *without* requiring the threads
|
that something has occurred *without* requiring the threads
|
||||||
to define a kernel synchronization object, such as a semaphore.
|
to define a kernel synchronization object, such as a semaphore.
|
||||||
|
@ -258,7 +258,7 @@ Waking up a thread that is not sleeping is allowed, but has no effect.
|
||||||
Busy Waiting
|
Busy Waiting
|
||||||
============
|
============
|
||||||
|
|
||||||
A thread can call :cpp:func:`k_busy_wait()` to perform a ``busy wait``
|
A thread can call :c:func:`k_busy_wait` to perform a ``busy wait``
|
||||||
that delays its processing for a specified time period
|
that delays its processing for a specified time period
|
||||||
*without* relinquishing the CPU to another ready thread.
|
*without* relinquishing the CPU to another ready thread.
|
||||||
|
|
||||||
|
|
|
@ -94,7 +94,7 @@ Defining a Mutex
|
||||||
================
|
================
|
||||||
|
|
||||||
A mutex is defined using a variable of type :c:type:`k_mutex`.
|
A mutex is defined using a variable of type :c:type:`k_mutex`.
|
||||||
It must then be initialized by calling :cpp:func:`k_mutex_init()`.
|
It must then be initialized by calling :c:func:`k_mutex_init`.
|
||||||
|
|
||||||
The following code defines and initializes a mutex.
|
The following code defines and initializes a mutex.
|
||||||
|
|
||||||
|
@ -116,7 +116,7 @@ The following code has the same effect as the code segment above.
|
||||||
Locking a Mutex
|
Locking a Mutex
|
||||||
===============
|
===============
|
||||||
|
|
||||||
A mutex is locked by calling :cpp:func:`k_mutex_lock()`.
|
A mutex is locked by calling :c:func:`k_mutex_lock`.
|
||||||
|
|
||||||
The following code builds on the example above, and waits indefinitely
|
The following code builds on the example above, and waits indefinitely
|
||||||
for the mutex to become available if it is already locked by another thread.
|
for the mutex to become available if it is already locked by another thread.
|
||||||
|
@ -139,7 +139,7 @@ available, and gives a warning if the mutex does not become available.
|
||||||
Unlocking a Mutex
|
Unlocking a Mutex
|
||||||
=================
|
=================
|
||||||
|
|
||||||
A mutex is unlocked by calling :cpp:func:`k_mutex_unlock()`.
|
A mutex is unlocked by calling :c:func:`k_mutex_unlock`.
|
||||||
|
|
||||||
The following code builds on the example above,
|
The following code builds on the example above,
|
||||||
and unlocks the mutex that was previously locked by the thread.
|
and unlocks the mutex that was previously locked by the thread.
|
||||||
|
|
|
@ -48,7 +48,7 @@ Defining a Semaphore
|
||||||
====================
|
====================
|
||||||
|
|
||||||
A semaphore is defined using a variable of type :c:type:`k_sem`.
|
A semaphore is defined using a variable of type :c:type:`k_sem`.
|
||||||
It must then be initialized by calling :cpp:func:`k_sem_init()`.
|
It must then be initialized by calling :c:func:`k_sem_init`.
|
||||||
|
|
||||||
The following code defines a semaphore, then configures it as a binary
|
The following code defines a semaphore, then configures it as a binary
|
||||||
semaphore by setting its count to 0 and its limit to 1.
|
semaphore by setting its count to 0 and its limit to 1.
|
||||||
|
@ -71,7 +71,7 @@ The following code has the same effect as the code segment above.
|
||||||
Giving a Semaphore
|
Giving a Semaphore
|
||||||
==================
|
==================
|
||||||
|
|
||||||
A semaphore is given by calling :cpp:func:`k_sem_give()`.
|
A semaphore is given by calling :c:func:`k_sem_give`.
|
||||||
|
|
||||||
The following code builds on the example above, and gives the semaphore to
|
The following code builds on the example above, and gives the semaphore to
|
||||||
indicate that a unit of data is available for processing by a consumer thread.
|
indicate that a unit of data is available for processing by a consumer thread.
|
||||||
|
@ -89,7 +89,7 @@ indicate that a unit of data is available for processing by a consumer thread.
|
||||||
Taking a Semaphore
|
Taking a Semaphore
|
||||||
==================
|
==================
|
||||||
|
|
||||||
A semaphore is taken by calling :cpp:func:`k_sem_take()`.
|
A semaphore is taken by calling :c:func:`k_sem_take`.
|
||||||
|
|
||||||
The following code builds on the example above, and waits up to 50 milliseconds
|
The following code builds on the example above, and waits up to 50 milliseconds
|
||||||
for the semaphore to be given.
|
for the semaphore to be given.
|
||||||
|
|
|
@ -86,7 +86,7 @@ prior to returning, since the kernel does *not* reclaim them automatically.
|
||||||
ability to respawn a thread that terminates.
|
ability to respawn a thread that terminates.
|
||||||
|
|
||||||
In some cases a thread may want to sleep until another thread terminates.
|
In some cases a thread may want to sleep until another thread terminates.
|
||||||
This can be accomplished with the :cpp:func:`k_thread_join()` API. This
|
This can be accomplished with the :c:func:`k_thread_join` API. This
|
||||||
will block the calling thread until either the timeout expires, the target
|
will block the calling thread until either the timeout expires, the target
|
||||||
thread self-exits, or the target thread aborts (either due to a
|
thread self-exits, or the target thread aborts (either due to a
|
||||||
k_thread_abort() call or triggering a fatal error).
|
k_thread_abort() call or triggering a fatal error).
|
||||||
|
@ -99,7 +99,7 @@ automatically aborts a thread if the thread triggers a fatal error condition,
|
||||||
such as dereferencing a null pointer.
|
such as dereferencing a null pointer.
|
||||||
|
|
||||||
A thread can also be aborted by another thread (or by itself)
|
A thread can also be aborted by another thread (or by itself)
|
||||||
by calling :cpp:func:`k_thread_abort()`. However, it is typically preferable
|
by calling :c:func:`k_thread_abort`. However, it is typically preferable
|
||||||
to signal a thread to terminate itself gracefully, rather than aborting it.
|
to signal a thread to terminate itself gracefully, rather than aborting it.
|
||||||
|
|
||||||
As with thread termination, the kernel does not reclaim shared resources
|
As with thread termination, the kernel does not reclaim shared resources
|
||||||
|
@ -113,16 +113,16 @@ Thread Suspension
|
||||||
==================
|
==================
|
||||||
|
|
||||||
A thread can be prevented from executing for an indefinite period of time
|
A thread can be prevented from executing for an indefinite period of time
|
||||||
if it becomes **suspended**. The function :cpp:func:`k_thread_suspend()`
|
if it becomes **suspended**. The function :c:func:`k_thread_suspend`
|
||||||
can be used to suspend any thread, including the calling thread.
|
can be used to suspend any thread, including the calling thread.
|
||||||
Suspending a thread that is already suspended has no additional effect.
|
Suspending a thread that is already suspended has no additional effect.
|
||||||
|
|
||||||
Once suspended, a thread cannot be scheduled until another thread calls
|
Once suspended, a thread cannot be scheduled until another thread calls
|
||||||
:cpp:func:`k_thread_resume()` to remove the suspension.
|
:c:func:`k_thread_resume` to remove the suspension.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
A thread can prevent itself from executing for a specified period of time
|
A thread can prevent itself from executing for a specified period of time
|
||||||
using :cpp:func:`k_sleep()`. However, this is different from suspending
|
using :c:func:`k_sleep`. However, this is different from suspending
|
||||||
a thread since a sleeping thread becomes executable automatically when the
|
a thread since a sleeping thread becomes executable automatically when the
|
||||||
time limit is reached.
|
time limit is reached.
|
||||||
|
|
||||||
|
@ -174,7 +174,7 @@ require their regions to be of some power of two in size, and aligned to its
|
||||||
own size.
|
own size.
|
||||||
|
|
||||||
Becasue of this, portable code can't simply pass an arbitrary character buffer
|
Becasue of this, portable code can't simply pass an arbitrary character buffer
|
||||||
to :cpp:func:`k_thread_create()`. Special macros exist to instantiate stacks,
|
to :c:func:`k_thread_create`. Special macros exist to instantiate stacks,
|
||||||
prefixed with ``K_KERNEL_STACK`` and ``K_THREAD_STACK``.
|
prefixed with ``K_KERNEL_STACK`` and ``K_THREAD_STACK``.
|
||||||
|
|
||||||
Kernel-only Stacks
|
Kernel-only Stacks
|
||||||
|
@ -317,8 +317,8 @@ it chooses. The default custom data value for a thread is zero.
|
||||||
By default, thread custom data support is disabled. The configuration option
|
By default, thread custom data support is disabled. The configuration option
|
||||||
:option:`CONFIG_THREAD_CUSTOM_DATA` can be used to enable support.
|
:option:`CONFIG_THREAD_CUSTOM_DATA` can be used to enable support.
|
||||||
|
|
||||||
The :cpp:func:`k_thread_custom_data_set()` and
|
The :c:func:`k_thread_custom_data_set` and
|
||||||
:cpp:func:`k_thread_custom_data_get()` functions are used to write and read
|
:c:func:`k_thread_custom_data_get` functions are used to write and read
|
||||||
a thread's custom data, respectively. A thread can only access its own
|
a thread's custom data, respectively. A thread can only access its own
|
||||||
custom data, and not that of another thread.
|
custom data, and not that of another thread.
|
||||||
|
|
||||||
|
@ -357,7 +357,7 @@ Spawning a Thread
|
||||||
=================
|
=================
|
||||||
|
|
||||||
A thread is spawned by defining its stack area and its thread control block,
|
A thread is spawned by defining its stack area and its thread control block,
|
||||||
and then calling :cpp:func:`k_thread_create()`.
|
and then calling :c:func:`k_thread_create`.
|
||||||
|
|
||||||
The stack area must be defined using :c:macro:`K_THREAD_STACK_DEFINE` or
|
The stack area must be defined using :c:macro:`K_THREAD_STACK_DEFINE` or
|
||||||
:c:macro:`K_KERNEL_STACK_DEFINE` to ensure it is properly set up in memory.
|
:c:macro:`K_KERNEL_STACK_DEFINE` to ensure it is properly set up in memory.
|
||||||
|
@ -413,7 +413,7 @@ The following code has the same effect as the code segment above.
|
||||||
MY_PRIORITY, 0, 0);
|
MY_PRIORITY, 0, 0);
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
The delay parameter to :cpp:func:`k_thread_create()` is a
|
The delay parameter to :c:func:`k_thread_create` is a
|
||||||
:c:type:`k_timeout_t` value, so :c:macro:`K_NO_WAIT` means to start the
|
:c:type:`k_timeout_t` value, so :c:macro:`K_NO_WAIT` means to start the
|
||||||
thread immediately. The corresponding parameter to :c:macro:`K_THREAD_DEFINE`
|
thread immediately. The corresponding parameter to :c:macro:`K_THREAD_DEFINE`
|
||||||
is a duration in integral milliseconds, so the equivalent argument is 0.
|
is a duration in integral milliseconds, so the equivalent argument is 0.
|
||||||
|
@ -422,7 +422,7 @@ User Mode Constraints
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
This section only applies if :option:`CONFIG_USERSPACE` is enabled, and a user
|
This section only applies if :option:`CONFIG_USERSPACE` is enabled, and a user
|
||||||
thread tries to create a new thread. The :c:func:`k_thread_create()` API is
|
thread tries to create a new thread. The :c:func:`k_thread_create` API is
|
||||||
still used, but there are additional constraints which must be met or the
|
still used, but there are additional constraints which must be met or the
|
||||||
calling thread will be terminated:
|
calling thread will be terminated:
|
||||||
|
|
||||||
|
@ -449,7 +449,7 @@ Dropping Permissions
|
||||||
|
|
||||||
If :option:`CONFIG_USERSPACE` is enabled, a thread running in supervisor mode
|
If :option:`CONFIG_USERSPACE` is enabled, a thread running in supervisor mode
|
||||||
may perform a one-way transition to user mode using the
|
may perform a one-way transition to user mode using the
|
||||||
:cpp:func:`k_thread_user_mode_enter()` API. This is a one-way operation which
|
:c:func:`k_thread_user_mode_enter` API. This is a one-way operation which
|
||||||
will reset and zero the thread's stack memory. The thread will be marked
|
will reset and zero the thread's stack memory. The thread will be marked
|
||||||
as non-essential.
|
as non-essential.
|
||||||
|
|
||||||
|
|
|
@ -14,7 +14,7 @@ The kernel spawns the following system threads:
|
||||||
|
|
||||||
**Main thread**
|
**Main thread**
|
||||||
This thread performs kernel initialization, then calls the application's
|
This thread performs kernel initialization, then calls the application's
|
||||||
:cpp:func:`main()` function (if one is defined).
|
:c:func:`main` function (if one is defined).
|
||||||
|
|
||||||
By default, the main thread uses the highest configured preemptible thread
|
By default, the main thread uses the highest configured preemptible thread
|
||||||
priority (i.e. 0). If the kernel is not configured to support preemptible
|
priority (i.e. 0). If the kernel is not configured to support preemptible
|
||||||
|
@ -22,9 +22,9 @@ The kernel spawns the following system threads:
|
||||||
priority (i.e. -1).
|
priority (i.e. -1).
|
||||||
|
|
||||||
The main thread is an essential thread while it is performing kernel
|
The main thread is an essential thread while it is performing kernel
|
||||||
initialization or executing the application's :cpp:func:`main()` function;
|
initialization or executing the application's :c:func:`main` function;
|
||||||
this means a fatal system error is raised if the thread aborts. If
|
this means a fatal system error is raised if the thread aborts. If
|
||||||
:cpp:func:`main()` is not defined, or if it executes and then does a normal
|
:c:func:`main` is not defined, or if it executes and then does a normal
|
||||||
return, the main thread terminates normally and no error is raised.
|
return, the main thread terminates normally and no error is raised.
|
||||||
|
|
||||||
**Idle thread**
|
**Idle thread**
|
||||||
|
@ -53,11 +53,11 @@ Implementation
|
||||||
Writing a main() function
|
Writing a main() function
|
||||||
=========================
|
=========================
|
||||||
|
|
||||||
An application-supplied :cpp:func:`main()` function begins executing once
|
An application-supplied :c:func:`main` function begins executing once
|
||||||
kernel initialization is complete. The kernel does not pass any arguments
|
kernel initialization is complete. The kernel does not pass any arguments
|
||||||
to the function.
|
to the function.
|
||||||
|
|
||||||
The following code outlines a trivial :cpp:func:`main()` function.
|
The following code outlines a trivial :c:func:`main` function.
|
||||||
The function used by a real application can be as complex as needed.
|
The function used by a real application can be as complex as needed.
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
|
@ -124,11 +124,11 @@ the work item is always processed by the workqueue and cannot be canceled.
|
||||||
Triggered Work
|
Triggered Work
|
||||||
**************
|
**************
|
||||||
|
|
||||||
The :cpp:func:`k_work_poll_submit()` interface schedules a triggered work
|
The :c:func:`k_work_poll_submit` interface schedules a triggered work
|
||||||
item in response to a **poll event** (see :ref:`polling_v2`), that will
|
item in response to a **poll event** (see :ref:`polling_v2`), that will
|
||||||
call a user-defined function when a monitored resource becomes available
|
call a user-defined function when a monitored resource becomes available
|
||||||
or poll signal is raised, or a timeout occurs.
|
or poll signal is raised, or a timeout occurs.
|
||||||
In contrast to :cpp:func:`k_poll()`, the triggered work does not require
|
In contrast to :c:func:`k_poll`, the triggered work does not require
|
||||||
a dedicated thread waiting or actively polling for a poll event.
|
a dedicated thread waiting or actively polling for a poll event.
|
||||||
|
|
||||||
A triggered work item is a standard work item that has the following
|
A triggered work item is a standard work item that has the following
|
||||||
|
@ -181,7 +181,7 @@ Defining a Workqueue
|
||||||
|
|
||||||
A workqueue is defined using a variable of type :c:type:`k_work_q`.
|
A workqueue is defined using a variable of type :c:type:`k_work_q`.
|
||||||
The workqueue is initialized by defining the stack area used by its thread
|
The workqueue is initialized by defining the stack area used by its thread
|
||||||
and then calling :cpp:func:`k_work_q_start()`. The stack area must be defined
|
and then calling :c:func:`k_work_q_start`. The stack area must be defined
|
||||||
using :c:macro:`K_THREAD_STACK_DEFINE` to ensure it is properly set up in
|
using :c:macro:`K_THREAD_STACK_DEFINE` to ensure it is properly set up in
|
||||||
memory.
|
memory.
|
||||||
|
|
||||||
|
@ -203,11 +203,11 @@ Submitting a Work Item
|
||||||
======================
|
======================
|
||||||
|
|
||||||
A work item is defined using a variable of type :c:type:`k_work`.
|
A work item is defined using a variable of type :c:type:`k_work`.
|
||||||
It must then be initialized by calling :cpp:func:`k_work_init()`.
|
It must then be initialized by calling :c:func:`k_work_init`.
|
||||||
|
|
||||||
An initialized work item can be submitted to the system workqueue by
|
An initialized work item can be submitted to the system workqueue by
|
||||||
calling :cpp:func:`k_work_submit()`, or to a specified workqueue by
|
calling :c:func:`k_work_submit`, or to a specified workqueue by
|
||||||
calling :cpp:func:`k_work_submit_to_queue()`.
|
calling :c:func:`k_work_submit_to_queue`.
|
||||||
|
|
||||||
The following code demonstrates how an ISR can offload the printing
|
The following code demonstrates how an ISR can offload the printing
|
||||||
of error messages to the system workqueue. Note that if the ISR attempts
|
of error messages to the system workqueue. Note that if the ISR attempts
|
||||||
|
@ -251,13 +251,13 @@ Submitting a Delayed Work Item
|
||||||
|
|
||||||
A delayed work item is defined using a variable of type
|
A delayed work item is defined using a variable of type
|
||||||
:c:type:`k_delayed_work`. It must then be initialized by calling
|
:c:type:`k_delayed_work`. It must then be initialized by calling
|
||||||
:cpp:func:`k_delayed_work_init()`.
|
:c:func:`k_delayed_work_init`.
|
||||||
|
|
||||||
An initialized delayed work item can be submitted to the system workqueue by
|
An initialized delayed work item can be submitted to the system workqueue by
|
||||||
calling :cpp:func:`k_delayed_work_submit()`, or to a specified workqueue by
|
calling :c:func:`k_delayed_work_submit`, or to a specified workqueue by
|
||||||
calling :cpp:func:`k_delayed_work_submit_to_queue()`. A delayed work item
|
calling :c:func:`k_delayed_work_submit_to_queue`. A delayed work item
|
||||||
that has been submitted but not yet consumed by its workqueue can be canceled
|
that has been submitted but not yet consumed by its workqueue can be canceled
|
||||||
by calling :cpp:func:`k_delayed_work_cancel()`.
|
by calling :c:func:`k_delayed_work_cancel`.
|
||||||
|
|
||||||
Suggested Uses
|
Suggested Uses
|
||||||
**************
|
**************
|
||||||
|
|
|
@ -20,14 +20,14 @@ understood, though they may not match the precision of the underlying
|
||||||
hardware perfectly.
|
hardware perfectly.
|
||||||
|
|
||||||
The kernel presents a "cycle" count via the
|
The kernel presents a "cycle" count via the
|
||||||
:cpp:func:`k_cycle_get_32()` API. The intent is that this counter
|
:c:func:`k_cycle_get_32` API. The intent is that this counter
|
||||||
represents the fastest cycle counter that the operating system is able
|
represents the fastest cycle counter that the operating system is able
|
||||||
to present to the user (for example, a CPU cycle counter) and that the
|
to present to the user (for example, a CPU cycle counter) and that the
|
||||||
read operation is very fast. The expectation is that very sensitive
|
read operation is very fast. The expectation is that very sensitive
|
||||||
application code might use this in a polling manner to achieve maximal
|
application code might use this in a polling manner to achieve maximal
|
||||||
precision. The frequency of this counter is required to be steady
|
precision. The frequency of this counter is required to be steady
|
||||||
over time, and is available from
|
over time, and is available from
|
||||||
:cpp:func:`sys_clock_hw_cycles_per_sec()` (which on almost all
|
:c:func:`sys_clock_hw_cycles_per_sec` (which on almost all
|
||||||
platforms is a runtime constant that evaluates to
|
platforms is a runtime constant that evaluates to
|
||||||
CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC).
|
CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC).
|
||||||
|
|
||||||
|
@ -53,10 +53,10 @@ Control of rounding is provided, and each conversion is available in
|
||||||
"near" (round to nearest). Finally the output precision can be
|
"near" (round to nearest). Finally the output precision can be
|
||||||
specified as either 32 or 64 bits.
|
specified as either 32 or 64 bits.
|
||||||
|
|
||||||
For example: :cpp:func:`k_ms_to_ticks_ceil32()` will convert a
|
For example: :c:func:`k_ms_to_ticks_ceil32` will convert a
|
||||||
millisecond input value to the next higher number of ticks, returning
|
millisecond input value to the next higher number of ticks, returning
|
||||||
a result truncated to 32 bits of precision; and
|
a result truncated to 32 bits of precision; and
|
||||||
:cpp:func:`k_cyc_to_us_floor64()` will convert a measured cycle count
|
:c:func:`k_cyc_to_us_floor64` will convert a measured cycle count
|
||||||
to an elapsed number of microseconds in a full 64 bits of precision.
|
to an elapsed number of microseconds in a full 64 bits of precision.
|
||||||
See the reference documentation for the full enumeration of conversion
|
See the reference documentation for the full enumeration of conversion
|
||||||
routines.
|
routines.
|
||||||
|
@ -70,14 +70,14 @@ Uptime
|
||||||
======
|
======
|
||||||
|
|
||||||
The kernel tracks a system uptime count on behalf of the application.
|
The kernel tracks a system uptime count on behalf of the application.
|
||||||
This is available at all times via :cpp:func:`k_uptime_get()`, which
|
This is available at all times via :c:func:`k_uptime_get`, which
|
||||||
provides an uptime value in milliseconds since system boot. This is
|
provides an uptime value in milliseconds since system boot. This is
|
||||||
expected to be the utility used by most portable application code.
|
expected to be the utility used by most portable application code.
|
||||||
|
|
||||||
The internal tracking, however, is as a 64 bit integer count of ticks.
|
The internal tracking, however, is as a 64 bit integer count of ticks.
|
||||||
Apps with precise timing requirements (that are willing to do their
|
Apps with precise timing requirements (that are willing to do their
|
||||||
own conversions to portable real time units) may access this with
|
own conversions to portable real time units) may access this with
|
||||||
:cpp:func:`k_uptime_ticks()`.
|
:c:func:`k_uptime_ticks`.
|
||||||
|
|
||||||
Timeouts
|
Timeouts
|
||||||
========
|
========
|
||||||
|
@ -86,8 +86,8 @@ The Zephyr kernel provides many APIs with a "timeout" parameter.
|
||||||
Conceptually, this indicates the time at which an event will occur.
|
Conceptually, this indicates the time at which an event will occur.
|
||||||
For example:
|
For example:
|
||||||
|
|
||||||
* Kernel blocking operations like :cpp:func:`k_sem_take()` or
|
* Kernel blocking operations like :c:func:`k_sem_take` or
|
||||||
:cpp:func:`k_queue_get()` may provide a timeout after which the
|
:c:func:`k_queue_get` may provide a timeout after which the
|
||||||
routine will return with an error code if no data is available.
|
routine will return with an error code if no data is available.
|
||||||
|
|
||||||
* Kernel ``struct k_timer`` objects must specify delays for their
|
* Kernel ``struct k_timer`` objects must specify delays for their
|
||||||
|
@ -223,7 +223,7 @@ and minimal. But some notes are important to detail:
|
||||||
driver, not the kernel.
|
driver, not the kernel.
|
||||||
|
|
||||||
* The next timeout value passed back to the driver via
|
* The next timeout value passed back to the driver via
|
||||||
:cpp:func:`z_clock_set_timeout()` is done identically for every CPU.
|
:c:func:`z_clock_set_timeout` is done identically for every CPU.
|
||||||
So by default, every CPU will see simultaneous timer interrupts for
|
So by default, every CPU will see simultaneous timer interrupts for
|
||||||
every event, even though by definition only one of them should see a
|
every event, even though by definition only one of them should see a
|
||||||
non-zero ticks argument to ``z_clock_announce()``. This is probably
|
non-zero ticks argument to ``z_clock_announce()``. This is probably
|
||||||
|
@ -244,7 +244,7 @@ tracked independently on each CPU in an SMP context.
|
||||||
|
|
||||||
Because there may be no other hardware available to drive timeslicing,
|
Because there may be no other hardware available to drive timeslicing,
|
||||||
Zephyr multiplexes the existing timer driver. This means that the
|
Zephyr multiplexes the existing timer driver. This means that the
|
||||||
value passed to :cpp:func:`z_clock_set_timeout()` may be clamped to a
|
value passed to :c:func:`z_clock_set_timeout` may be clamped to a
|
||||||
smaller value than the current next timeout when a time sliced thread
|
smaller value than the current next timeout when a time sliced thread
|
||||||
is currently scheduled.
|
is currently scheduled.
|
||||||
|
|
||||||
|
@ -340,7 +340,7 @@ code. For example, consider this design:
|
||||||
|
|
||||||
This code requires that the timeout value be inspected, which is no
|
This code requires that the timeout value be inspected, which is no
|
||||||
longer possible. For situations like this, the new API provides an
|
longer possible. For situations like this, the new API provides an
|
||||||
internal :cpp:func:`z_timeout_end_calc()` routine that converts an
|
internal :c:func:`z_timeout_end_calc` routine that converts an
|
||||||
arbitrary timeout to the uptime value in ticks at which it will
|
arbitrary timeout to the uptime value in ticks at which it will
|
||||||
expire. So such a loop might look like:
|
expire. So such a loop might look like:
|
||||||
|
|
||||||
|
@ -362,7 +362,7 @@ expire. So such a loop might look like:
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
Note that :cpp:func:`z_timeout_end_calc()` returns values in units of
|
Note that :c:func:`z_timeout_end_calc` returns values in units of
|
||||||
ticks, to prevent conversion aliasing, is always presented at 64 bit
|
ticks, to prevent conversion aliasing, is always presented at 64 bit
|
||||||
uptime precision to prevent rollover bugs, handles special
|
uptime precision to prevent rollover bugs, handles special
|
||||||
:c:macro:`K_FOREVER` naturally (as ``UINT64_MAX``), and works
|
:c:macro:`K_FOREVER` naturally (as ``UINT64_MAX``), and works
|
||||||
|
@ -371,7 +371,7 @@ identically for absolute timeouts as well as conventional ones.
|
||||||
But some care is still required for subsystems that use it. Note that
|
But some care is still required for subsystems that use it. Note that
|
||||||
delta timeouts need to be interpreted relative to a "current time",
|
delta timeouts need to be interpreted relative to a "current time",
|
||||||
and obviously that time is the time of the call to
|
and obviously that time is the time of the call to
|
||||||
:cpp:func:`z_timeout_end_calc()`. But the user expects that the time is
|
:c:func:`z_timeout_end_calc`. But the user expects that the time is
|
||||||
the time they passed the timeout to you. Care must be taken to call
|
the time they passed the timeout to you. Care must be taken to call
|
||||||
this function just once, as synchronously as possible to the timeout
|
this function just once, as synchronously as possible to the timeout
|
||||||
creation in user code. It should not be used on a "stored" timeout
|
creation in user code. It should not be used on a "stored" timeout
|
||||||
|
|
|
@ -104,7 +104,7 @@ Defining a Timer
|
||||||
================
|
================
|
||||||
|
|
||||||
A timer is defined using a variable of type :c:type:`k_timer`.
|
A timer is defined using a variable of type :c:type:`k_timer`.
|
||||||
It must then be initialized by calling :cpp:func:`k_timer_init()`.
|
It must then be initialized by calling :c:func:`k_timer_init`.
|
||||||
|
|
||||||
The following code defines and initializes a timer.
|
The following code defines and initializes a timer.
|
||||||
|
|
||||||
|
@ -222,7 +222,7 @@ amount of time.
|
||||||
Use a timer to determine whether or not a specified amount of time has
|
Use a timer to determine whether or not a specified amount of time has
|
||||||
elapsed. In particular, timers should be used when higher precision
|
elapsed. In particular, timers should be used when higher precision
|
||||||
and/or unit control is required than that afforded by the simpler
|
and/or unit control is required than that afforded by the simpler
|
||||||
``k_sleep()`` and ``k_usleep()`` calls.
|
:c:func:`k_sleep` and :c:func:`k_usleep` calls.
|
||||||
|
|
||||||
Use a timer to perform other work while carrying out operations
|
Use a timer to perform other work while carrying out operations
|
||||||
involving time limits.
|
involving time limits.
|
||||||
|
|
|
@ -133,7 +133,7 @@ of the log macro call. Note that it can lead to errors when logger is used in
|
||||||
the interrupt context.
|
the interrupt context.
|
||||||
|
|
||||||
:option:`CONFIG_LOG_PROCESS_TRIGGER_THRESHOLD`: When number of buffered log
|
:option:`CONFIG_LOG_PROCESS_TRIGGER_THRESHOLD`: When number of buffered log
|
||||||
messages reaches the threshold dedicated thread (see :cpp:func:`log_thread_set`)
|
messages reaches the threshold dedicated thread (see :c:func:`log_thread_set`)
|
||||||
is waken up. If :option:`CONFIG_LOG_PROCESS_THREAD` is enabled then this
|
is waken up. If :option:`CONFIG_LOG_PROCESS_THREAD` is enabled then this
|
||||||
threshold is used by the internal thread.
|
threshold is used by the internal thread.
|
||||||
|
|
||||||
|
@ -295,7 +295,7 @@ Logger can be controlled using API defined in
|
||||||
:zephyr_file:`include/logging/log_ctrl.h`. Logger must be initialized before it can be
|
:zephyr_file:`include/logging/log_ctrl.h`. Logger must be initialized before it can be
|
||||||
used. Optionally, user can provide function which returns timestamp value. If
|
used. Optionally, user can provide function which returns timestamp value. If
|
||||||
not provided, :c:macro:`k_cycle_get_32` is used for timestamping.
|
not provided, :c:macro:`k_cycle_get_32` is used for timestamping.
|
||||||
:cpp:func:`log_process` function is used to trigger processing of one log
|
:c:func:`log_process` function is used to trigger processing of one log
|
||||||
message (if pending). Function returns true if there is more messages pending.
|
message (if pending). Function returns true if there is more messages pending.
|
||||||
|
|
||||||
Following snippet shows how logger can be processed in simple forever loop.
|
Following snippet shows how logger can be processed in simple forever loop.
|
||||||
|
@ -316,7 +316,7 @@ Following snippet shows how logger can be processed in simple forever loop.
|
||||||
}
|
}
|
||||||
|
|
||||||
Logger controlling API contains also functions for run time reconfiguration of
|
Logger controlling API contains also functions for run time reconfiguration of
|
||||||
the logger. If run time filtering is enabled the :cpp:func:`log_filter_set` can
|
the logger. If run time filtering is enabled the :c:func:`log_filter_set` can
|
||||||
be used to change maximal severity level for given module. Module is identified
|
be used to change maximal severity level for given module. Module is identified
|
||||||
by source ID and domain ID. Source ID can be retrieved if source name is known
|
by source ID and domain ID. Source ID can be retrieved if source name is known
|
||||||
by iterating through all registered sources.
|
by iterating through all registered sources.
|
||||||
|
@ -336,9 +336,9 @@ Logger panic
|
||||||
In case of error condition system usually can no longer rely on scheduler or
|
In case of error condition system usually can no longer rely on scheduler or
|
||||||
interrupts. In that situation deferred log message processing is not an option.
|
interrupts. In that situation deferred log message processing is not an option.
|
||||||
Logger controlling API provides a function for entering into panic mode
|
Logger controlling API provides a function for entering into panic mode
|
||||||
(:cpp:func:`log_panic`) which should be called in such situation.
|
(:c:func:`log_panic`) which should be called in such situation.
|
||||||
|
|
||||||
When :cpp:func:`log_panic()` is called, logger sends _panic_ notification to
|
When :c:func:`log_panic` is called, logger sends _panic_ notification to
|
||||||
all active backends. It is backend responsibility to react. Backend should
|
all active backends. It is backend responsibility to react. Backend should
|
||||||
switch to blocking, synchronous mode (stop using interrupts) or disable itself.
|
switch to blocking, synchronous mode (stop using interrupts) or disable itself.
|
||||||
Once all backends are notified, logger flushes all buffered messages. Since
|
Once all backends are notified, logger flushes all buffered messages. Since
|
||||||
|
@ -440,7 +440,7 @@ copies of strings. The buffer size and count is configurable
|
||||||
:option:`CONFIG_LOG_STRDUP_BUF_COUNT`).
|
:option:`CONFIG_LOG_STRDUP_BUF_COUNT`).
|
||||||
|
|
||||||
|
|
||||||
If a string argument is transient, the user must call cpp:func:`log_strdup` to
|
If a string argument is transient, the user must call :c:func:`log_strdup` to
|
||||||
duplicate the passed string into a buffer from the pool. See the examples below.
|
duplicate the passed string into a buffer from the pool. See the examples below.
|
||||||
If a strdup buffer cannot be allocated, a warning message is logged and an error
|
If a strdup buffer cannot be allocated, a warning message is logged and an error
|
||||||
code returned indicating :option:`CONFIG_LOG_STRDUP_BUF_COUNT` should be
|
code returned indicating :option:`CONFIG_LOG_STRDUP_BUF_COUNT` should be
|
||||||
|
@ -456,7 +456,7 @@ increased. Buffers are freed together with the log message.
|
||||||
When :option:`CONFIG_LOG_DETECT_MISSED_STRDUP` is enabled logger will scan
|
When :option:`CONFIG_LOG_DETECT_MISSED_STRDUP` is enabled logger will scan
|
||||||
each log message and report if string format specifier is found and string
|
each log message and report if string format specifier is found and string
|
||||||
address is not in read only memory section or does not belong to memory pool
|
address is not in read only memory section or does not belong to memory pool
|
||||||
dedicated to string duplicates. It indictes that cpp:func:`log_strdup` is
|
dedicated to string duplicates. It indictes that :c:func:`log_strdup` is
|
||||||
missing in a call to log a message, such as ``LOG_INF``.
|
missing in a call to log a message, such as ``LOG_INF``.
|
||||||
|
|
||||||
Logger backends
|
Logger backends
|
||||||
|
@ -465,22 +465,22 @@ Logger backends
|
||||||
Logger supports up to 9 concurrent backends. Logger backend interface consists
|
Logger supports up to 9 concurrent backends. Logger backend interface consists
|
||||||
of two functions:
|
of two functions:
|
||||||
|
|
||||||
- :cpp:func:`log_backend_put` - backend gets log message.
|
- :c:func:`log_backend_put` - backend gets log message.
|
||||||
- :cpp:func:`log_backend_panic` - on that call backend is notified that it must
|
- :c:func:`log_backend_panic` - on that call backend is notified that it must
|
||||||
switch to panic (synchronous) mode. If backend cannot support synchronous,
|
switch to panic (synchronous) mode. If backend cannot support synchronous,
|
||||||
interrupt-less operation (e.g. network) it should stop any processing.
|
interrupt-less operation (e.g. network) it should stop any processing.
|
||||||
|
|
||||||
The log message contains a reference counter tracking how many backends are
|
The log message contains a reference counter tracking how many backends are
|
||||||
processing the message. On receiving a message backend must claim it by calling
|
processing the message. On receiving a message backend must claim it by calling
|
||||||
:cpp:func:`log_msg_get()` on that message which increments a reference counter.
|
:c:func:`log_msg_get` on that message which increments a reference counter.
|
||||||
Once message is processed, backend puts back the message
|
Once message is processed, backend puts back the message
|
||||||
(:cpp:func:`log_msg_put()`) decrementing a reference counter. On last
|
(:c:func:`log_msg_put`) decrementing a reference counter. On last
|
||||||
:cpp:func:`log_msg_put`, when reference counter reaches 0, message is returned
|
:c:func:`log_msg_put`, when reference counter reaches 0, message is returned
|
||||||
to the pool. It is up to the backend how message is processed. If backend
|
to the pool. It is up to the backend how message is processed. If backend
|
||||||
intends to format message into the string, helper function for that are
|
intends to format message into the string, helper function for that are
|
||||||
available in :zephyr_file:`include/logging/log_output.h`.
|
available in :zephyr_file:`include/logging/log_output.h`.
|
||||||
|
|
||||||
Example message formatted using :cpp:func:`log_output_msg_process`.
|
Example message formatted using :c:func:`log_output_msg_process`.
|
||||||
|
|
||||||
.. code-block:: console
|
.. code-block:: console
|
||||||
|
|
||||||
|
@ -489,7 +489,7 @@ Example message formatted using :cpp:func:`log_output_msg_process`.
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
The message pool can be starved if a backend does not call
|
The message pool can be starved if a backend does not call
|
||||||
:cpp:func:`log_msg_put` when it is done processing a message. The logger
|
:c:func:`log_msg_put` when it is done processing a message. The logger
|
||||||
core has no means to force messages back to the pool if they're still marked
|
core has no means to force messages back to the pool if they're still marked
|
||||||
as in use (with a non-zero reference counter).
|
as in use (with a non-zero reference counter).
|
||||||
|
|
||||||
|
@ -510,7 +510,7 @@ Example message formatted using :cpp:func:`log_output_msg_process`.
|
||||||
Logger backends are registered to the logger using
|
Logger backends are registered to the logger using
|
||||||
:c:macro:`LOG_BACKEND_DEFINE` macro. The macro creates an instance in the
|
:c:macro:`LOG_BACKEND_DEFINE` macro. The macro creates an instance in the
|
||||||
dedicated memory section. Backends can be dynamically enabled
|
dedicated memory section. Backends can be dynamically enabled
|
||||||
(:cpp:func:`log_backend_enable`) and disabled.
|
(:c:func:`log_backend_enable`) and disabled.
|
||||||
|
|
||||||
Limitations
|
Limitations
|
||||||
***********
|
***********
|
||||||
|
|
|
@ -5,7 +5,7 @@ Asynchronous Notification APIs
|
||||||
|
|
||||||
Zephyr APIs often include :ref:`api_term_async` functions where an
|
Zephyr APIs often include :ref:`api_term_async` functions where an
|
||||||
operation is initiated and the application needs to be informed when it
|
operation is initiated and the application needs to be informed when it
|
||||||
completes, and whether it succeeded. Using :cpp:func:`k_poll()` is
|
completes, and whether it succeeded. Using :c:func:`k_poll` is
|
||||||
often a good method, but some application architectures may be more
|
often a good method, but some application architectures may be more
|
||||||
suited to a callback notification, and operations like enabling clocks
|
suited to a callback notification, and operations like enabling clocks
|
||||||
and power rails may need to be invoked before kernel functions are
|
and power rails may need to be invoked before kernel functions are
|
||||||
|
|
|
@ -54,8 +54,8 @@ Application interfaces
|
||||||
Only two Application Interfaces as defined in section 9 of the standard
|
Only two Application Interfaces as defined in section 9 of the standard
|
||||||
are available:
|
are available:
|
||||||
|
|
||||||
- ``ClockTargetPhaseDiscontinuity`` interface (:cpp:func:`gptp_register_phase_dis_cb()`)
|
- ``ClockTargetPhaseDiscontinuity`` interface (:c:func:`gptp_register_phase_dis_cb`)
|
||||||
- ``ClockTargetEventCapture`` interface (:cpp:func:`gptp_event_capture()`)
|
- ``ClockTargetEventCapture`` interface (:c:func:`gptp_event_capture`)
|
||||||
|
|
||||||
Testing
|
Testing
|
||||||
*******
|
*******
|
||||||
|
|
|
@ -355,7 +355,7 @@ to connect as well as set the ``Manufacturer`` and ``Reboot`` resources in the
|
||||||
lwm2m_engine_register_exec_callback("3/0/4", device_reboot_cb);
|
lwm2m_engine_register_exec_callback("3/0/4", device_reboot_cb);
|
||||||
|
|
||||||
Lastly, we start the LwM2M RD client (which in turn starts the LwM2M engine).
|
Lastly, we start the LwM2M RD client (which in turn starts the LwM2M engine).
|
||||||
The second parameter of :c:func:`lwm2m_rd_client_start()` is the client
|
The second parameter of :c:func:`lwm2m_rd_client_start` is the client
|
||||||
endpoint name. This is important as it needs to be unique per LwM2M server:
|
endpoint name. This is important as it needs to be unique per LwM2M server:
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
@ -398,7 +398,7 @@ resource. Lastly, set the client identity and PSK resources.
|
||||||
/* Set the client pre-shared key (PSK) */
|
/* Set the client pre-shared key (PSK) */
|
||||||
lwm2m_engine_set_opaque("0/0/5", (void *)client_psk, sizeof(client_psk));
|
lwm2m_engine_set_opaque("0/0/5", (void *)client_psk, sizeof(client_psk));
|
||||||
|
|
||||||
Before calling :c:func:`lwm2m_rd_client_start()` assign the tls_tag # where the
|
Before calling :c:func:`lwm2m_rd_client_start` assign the tls_tag # where the
|
||||||
LwM2M library should store the DTLS information prior to connection (normally a
|
LwM2M library should store the DTLS information prior to connection (normally a
|
||||||
value of 1 is ok here).
|
value of 1 is ok here).
|
||||||
|
|
||||||
|
|
|
@ -40,7 +40,7 @@ more details. The generic L2 API has these functions:
|
||||||
|
|
||||||
- ``recv()``: All device drivers, once they receive a packet which they put
|
- ``recv()``: All device drivers, once they receive a packet which they put
|
||||||
into a :c:type:`net_pkt`, will push this buffer to the network
|
into a :c:type:`net_pkt`, will push this buffer to the network
|
||||||
stack via :c:func:`net_recv_data()`. At this point, the network
|
stack via :c:func:`net_recv_data`. At this point, the network
|
||||||
stack does not know what to do with it. Instead, it passes the
|
stack does not know what to do with it. Instead, it passes the
|
||||||
buffer along to the L2 stack's ``recv()`` function for handling.
|
buffer along to the L2 stack's ``recv()`` function for handling.
|
||||||
The L2 stack does what it needs to do with the packet, for example, parsing
|
The L2 stack does what it needs to do with the packet, for example, parsing
|
||||||
|
@ -91,12 +91,12 @@ Ethernet device driver
|
||||||
On reception, it is up to the device driver to fill-in the network packet with
|
On reception, it is up to the device driver to fill-in the network packet with
|
||||||
as many data buffers as required. The network packet itself is a
|
as many data buffers as required. The network packet itself is a
|
||||||
:c:type:`net_pkt` and should be allocated through
|
:c:type:`net_pkt` and should be allocated through
|
||||||
:c:func:`net_pkt_rx_alloc_with_buffer()`. Then all data buffers will be
|
:c:func:`net_pkt_rx_alloc_with_buffer`. Then all data buffers will be
|
||||||
automatically allocated and filled by :c:func:`net_pkt_write()`.
|
automatically allocated and filled by :c:func:`net_pkt_write`.
|
||||||
|
|
||||||
After all the network data has been received, the device driver needs to
|
After all the network data has been received, the device driver needs to
|
||||||
call :c:func:`net_recv_data()`. If that call fails, it will be up to the
|
call :c:func:`net_recv_data`. If that call fails, it will be up to the
|
||||||
device driver to unreference the buffer via :c:func:`net_pkt_unref()`.
|
device driver to unreference the buffer via :c:func:`net_pkt_unref`.
|
||||||
|
|
||||||
On sending, the device driver send function will be called, and it is up to
|
On sending, the device driver send function will be called, and it is up to
|
||||||
the device driver to send the network packet all at once, with all the buffers.
|
the device driver to send the network packet all at once, with all the buffers.
|
||||||
|
@ -132,9 +132,9 @@ here as well. There are two specific differences however:
|
||||||
:c:type:`ieee802154_radio_api` requires a tx function pointer which differs
|
:c:type:`ieee802154_radio_api` requires a tx function pointer which differs
|
||||||
from the :c:type:`net_if_api` send function pointer.
|
from the :c:type:`net_if_api` send function pointer.
|
||||||
Instead, the IEEE 802.15.4 L2, provides a generic
|
Instead, the IEEE 802.15.4 L2, provides a generic
|
||||||
:c:func:`ieee802154_radio_send()` meant to be given as
|
:c:func:`ieee802154_radio_send` meant to be given as
|
||||||
:c:type:`net_if` send function. It turn, the implementation
|
:c:type:`net_if` send function. It turn, the implementation
|
||||||
of :c:func:`ieee802154_radio_send()` will ensure the same behavior:
|
of :c:func:`ieee802154_radio_send` will ensure the same behavior:
|
||||||
sending one buffer at a time through :c:type:`ieee802154_radio_api` tx
|
sending one buffer at a time through :c:type:`ieee802154_radio_api` tx
|
||||||
function, and unreferencing the network packet
|
function, and unreferencing the network packet
|
||||||
only when all the transmission were successful.
|
only when all the transmission were successful.
|
||||||
|
|
|
@ -22,7 +22,7 @@ by eliminating code at build time for management routines that are not
|
||||||
used. Distinct and statically defined APIs for network management
|
used. Distinct and statically defined APIs for network management
|
||||||
procedures are not used. Instead, defined procedure handlers are
|
procedures are not used. Instead, defined procedure handlers are
|
||||||
registered by using a :c:macro:`NET_MGMT_REGISTER_REQUEST_HANDLER`
|
registered by using a :c:macro:`NET_MGMT_REGISTER_REQUEST_HANDLER`
|
||||||
macro. Procedure requests are done through a single :cpp:func:`net_mgmt()` API
|
macro. Procedure requests are done through a single :c:func:`net_mgmt` API
|
||||||
that invokes the registered handler for the corresponding request.
|
that invokes the registered handler for the corresponding request.
|
||||||
|
|
||||||
The current implementation is experimental and may change and improve
|
The current implementation is experimental and may change and improve
|
||||||
|
@ -38,7 +38,7 @@ implied, and the specific management procedure being requested. The
|
||||||
available procedure requests depend on what has been implemented in
|
available procedure requests depend on what has been implemented in
|
||||||
the stack.
|
the stack.
|
||||||
|
|
||||||
To avoid extra cost, all :cpp:func:`net_mgmt()` calls are direct. Though this
|
To avoid extra cost, all :c:func:`net_mgmt` calls are direct. Though this
|
||||||
may change in a future release, it will not affect the users of this
|
may change in a future release, it will not affect the users of this
|
||||||
function.
|
function.
|
||||||
|
|
||||||
|
@ -51,11 +51,11 @@ your callback is invoked. The callback will have to be unique for a
|
||||||
pair of layer and code, whereas on the command part it will be a mask of
|
pair of layer and code, whereas on the command part it will be a mask of
|
||||||
events.
|
events.
|
||||||
|
|
||||||
Two functions are available, :cpp:func:`net_mgmt_add_event_callback()` for
|
Two functions are available, :c:func:`net_mgmt_add_event_callback` for
|
||||||
registering the callback function, and
|
registering the callback function, and
|
||||||
:cpp:func:`net_mgmt_del_event_callback()`
|
:c:func:`net_mgmt_del_event_callback`
|
||||||
for unregistering a callback. A helper function,
|
for unregistering a callback. A helper function,
|
||||||
:cpp:func:`net_mgmt_init_event_callback()`, can
|
:c:func:`net_mgmt_init_event_callback`, can
|
||||||
be used to ease the initialization of the callback structure.
|
be used to ease the initialization of the callback structure.
|
||||||
|
|
||||||
When an event occurs that matches a callback's event set, the
|
When an event occurs that matches a callback's event set, the
|
||||||
|
@ -69,7 +69,7 @@ same callback function, if desired.
|
||||||
layer and layer code. A callback handler function **must** check
|
layer and layer code. A callback handler function **must** check
|
||||||
the event code (passed as an argument) against the specific network
|
the event code (passed as an argument) against the specific network
|
||||||
events it will handle, **regardless** of how many events were in the
|
events it will handle, **regardless** of how many events were in the
|
||||||
set passed to :cpp:func:`net_mgmt_init_event_callback()`.
|
set passed to :c:func:`net_mgmt_init_event_callback`.
|
||||||
|
|
||||||
(False positives can occur for events which have the same layer and
|
(False positives can occur for events which have the same layer and
|
||||||
layer code.)
|
layer code.)
|
||||||
|
@ -145,7 +145,7 @@ This new management procedure could then be called by using:
|
||||||
Signaling a network event
|
Signaling a network event
|
||||||
*************************
|
*************************
|
||||||
|
|
||||||
You can signal a specific network event using the :cpp:func:`net_mgmt_notify()`
|
You can signal a specific network event using the :c:func:`net_mgmt_notify`
|
||||||
function and provide the network event code. See
|
function and provide the network event code. See
|
||||||
:zephyr_file:`include/net/net_mgmt.h` for details. As for the management request
|
:zephyr_file:`include/net/net_mgmt.h` for details. As for the management request
|
||||||
code, event code can be also found on specific L2 technology mgmt headers,
|
code, event code can be also found on specific L2 technology mgmt headers,
|
||||||
|
|
|
@ -34,7 +34,7 @@ config option and implements the following operations: ``socket()``, ``close()``
|
||||||
|
|
||||||
Based on the namespacing requirements above, these operations are by
|
Based on the namespacing requirements above, these operations are by
|
||||||
default exposed as functions with ``zsock_`` prefix, e.g.
|
default exposed as functions with ``zsock_`` prefix, e.g.
|
||||||
:c:func:`zsock_socket()` and :c:func:`zsock_close()`. If the config option
|
:c:func:`zsock_socket` and :c:func:`zsock_close`. If the config option
|
||||||
:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined, all the functions
|
:option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined, all the functions
|
||||||
will be also exposed as aliases without the prefix. This includes the
|
will be also exposed as aliases without the prefix. This includes the
|
||||||
functions like ``close()`` and ``fcntl()`` (which may conflict with
|
functions like ``close()`` and ``fcntl()`` (which may conflict with
|
||||||
|
|
|
@ -31,10 +31,10 @@ one network interface without VLAN support, and two with VLAN support, the
|
||||||
|
|
||||||
Even if VLAN is enabled in a :file:`prj.conf` file, the VLAN needs to be
|
Even if VLAN is enabled in a :file:`prj.conf` file, the VLAN needs to be
|
||||||
activated at runtime by the application. The VLAN API provides a
|
activated at runtime by the application. The VLAN API provides a
|
||||||
:cpp:func:`net_eth_vlan_enable()` function to do that. The application needs
|
:c:func:`net_eth_vlan_enable` function to do that. The application needs
|
||||||
to give the network interface and desired VLAN tag as a parameter to that
|
to give the network interface and desired VLAN tag as a parameter to that
|
||||||
function. The VLAN tagging for a given network interface can be disabled by a
|
function. The VLAN tagging for a given network interface can be disabled by a
|
||||||
:cpp:func:`net_eth_vlan_disable()` function. The application needs to configure
|
:c:func:`net_eth_vlan_disable` function. The application needs to configure
|
||||||
the VLAN network interface itself, such as setting the IP address, etc.
|
the VLAN network interface itself, such as setting the IP address, etc.
|
||||||
|
|
||||||
See also the :ref:`VLAN sample application <vlan-sample>` for API usage
|
See also the :ref:`VLAN sample application <vlan-sample>` for API usage
|
||||||
|
|
|
@ -205,7 +205,7 @@ handler) are passed as arguments. Characters within parentheses are treated
|
||||||
as one argument. If shell wont find a handler it will display an error message.
|
as one argument. If shell wont find a handler it will display an error message.
|
||||||
|
|
||||||
Commands can be also executed from a user application using any active backend
|
Commands can be also executed from a user application using any active backend
|
||||||
and a function :cpp:func:`shell_execute_cmd`, as shown in this example:
|
and a function :c:func:`shell_execute_cmd`, as shown in this example:
|
||||||
|
|
||||||
.. code-block:: c
|
.. code-block:: c
|
||||||
|
|
||||||
|
@ -249,7 +249,7 @@ Simple command handler implementation:
|
||||||
return 0;
|
return 0;
|
||||||
}
|
}
|
||||||
|
|
||||||
Function :cpp:func:`shell_fprintf` or the shell print macros:
|
Function :c:func:`shell_fprintf` or the shell print macros:
|
||||||
:c:macro:`shell_print`, :c:macro:`shell_info`, :c:macro:`shell_warn` and
|
:c:macro:`shell_print`, :c:macro:`shell_info`, :c:macro:`shell_warn` and
|
||||||
:c:macro:`shell_error` can be used from the command handler or from threads,
|
:c:macro:`shell_error` can be used from the command handler or from threads,
|
||||||
but not from an interrupt context. Instead, interrupt handlers should use
|
but not from an interrupt context. Instead, interrupt handlers should use
|
||||||
|
|
|
@ -80,7 +80,7 @@ sleep.
|
||||||
|
|
||||||
This attribute does not imply the function will sleep unconditionally,
|
This attribute does not imply the function will sleep unconditionally,
|
||||||
but that the operation may require an invoking thread that would have to
|
but that the operation may require an invoking thread that would have to
|
||||||
suspend, wait, or invoke :cpp:func:`k_yield()` before it can complete
|
suspend, wait, or invoke :c:func:`k_yield` before it can complete
|
||||||
its operation. This behavior may be mediated by **no-wait**.
|
its operation. This behavior may be mediated by **no-wait**.
|
||||||
|
|
||||||
Functions that are **sleep** are implicitly **reschedule**.
|
Functions that are **sleep** are implicitly **reschedule**.
|
||||||
|
@ -109,7 +109,7 @@ long as it can be completed immediately, and to return an error code
|
||||||
rather than sleep if it cannot.
|
rather than sleep if it cannot.
|
||||||
|
|
||||||
It is use of the no-wait feature that allows functions like
|
It is use of the no-wait feature that allows functions like
|
||||||
:cpp:func:`k_sem_take` to be invoked from ISRs, since it is not
|
:c:func:`k_sem_take` to be invoked from ISRs, since it is not
|
||||||
permitted to sleep in interrupt context.
|
permitted to sleep in interrupt context.
|
||||||
|
|
||||||
A function with a no-wait path does not imply that taking that path
|
A function with a no-wait path does not imply that taking that path
|
||||||
|
@ -159,9 +159,9 @@ or :c:func:`SYS_INIT()` calls that may be invoked with ``PRE_KERNEL_1``
|
||||||
or ``PRE_KERNEL_2`` initialization levels.
|
or ``PRE_KERNEL_2`` initialization levels.
|
||||||
|
|
||||||
Generally a function that is **pre-kernel-ok** checks
|
Generally a function that is **pre-kernel-ok** checks
|
||||||
:cpp:func:`k_is_pre_kernel` when determining whether it can fulfill its
|
:c:func:`k_is_pre_kernel` when determining whether it can fulfill its
|
||||||
required behavior. In many cases it would also check
|
required behavior. In many cases it would also check
|
||||||
:cpp:func:`k_is_in_isr` so it can be **isr-ok** as well.
|
:c:func:`k_is_in_isr` so it can be **isr-ok** as well.
|
||||||
|
|
||||||
.. _api_term_async:
|
.. _api_term_async:
|
||||||
|
|
||||||
|
@ -184,7 +184,7 @@ Explanation
|
||||||
Be aware that **async** is orthogonal to context-switching. Some APIs
|
Be aware that **async** is orthogonal to context-switching. Some APIs
|
||||||
may provide completion information through a callback, but may suspend
|
may provide completion information through a callback, but may suspend
|
||||||
while waiting for the resource necessary to initiate the operation; an
|
while waiting for the resource necessary to initiate the operation; an
|
||||||
example is :cpp:func:`spi_transceive_async`.
|
example is :c:func:`spi_transceive_async`.
|
||||||
|
|
||||||
If a function is both **no-wait** and **async** then selecting the
|
If a function is both **no-wait** and **async** then selecting the
|
||||||
no-wait path only guarantees that the function will not sleep. It does
|
no-wait path only guarantees that the function will not sleep. It does
|
||||||
|
|
|
@ -76,20 +76,20 @@ Dynamic Objects
|
||||||
|
|
||||||
Kernel objects may also be allocated at runtime if
|
Kernel objects may also be allocated at runtime if
|
||||||
:option:`CONFIG_DYNAMIC_OBJECTS` is enabled. In this case, the
|
:option:`CONFIG_DYNAMIC_OBJECTS` is enabled. In this case, the
|
||||||
:cpp:func:`k_object_alloc()` API may be used to instantiate an object from
|
:c:func:`k_object_alloc` API may be used to instantiate an object from
|
||||||
the calling thread's resource pool. Such allocations may be freed in two
|
the calling thread's resource pool. Such allocations may be freed in two
|
||||||
ways:
|
ways:
|
||||||
|
|
||||||
* Supervisor threads may call :cpp:func:`k_object_free()` to force a dynamic
|
* Supervisor threads may call :c:func:`k_object_free` to force a dynamic
|
||||||
object to be released.
|
object to be released.
|
||||||
|
|
||||||
* If an object's references drop to zero (which happens when no threads have
|
* If an object's references drop to zero (which happens when no threads have
|
||||||
permissions on it) the object will be automatically freed. User threads
|
permissions on it) the object will be automatically freed. User threads
|
||||||
may drop their own permission on an object with
|
may drop their own permission on an object with
|
||||||
:cpp:func:`k_object_release()`, and their permissions are automatically
|
:c:func:`k_object_release`, and their permissions are automatically
|
||||||
cleared when a thread terminates. Supervisor threads may additionally
|
cleared when a thread terminates. Supervisor threads may additionally
|
||||||
revoke references for another thread using
|
revoke references for another thread using
|
||||||
:cpp:func:`k_object_access_revoke()`.
|
:c:func:`k_object_access_revoke`.
|
||||||
|
|
||||||
Because permissions are also used for reference counting, it is important for
|
Because permissions are also used for reference counting, it is important for
|
||||||
supervisor threads to acquire permissions on objects they are using even though
|
supervisor threads to acquire permissions on objects they are using even though
|
||||||
|
@ -140,7 +140,7 @@ Supervisor Thread Access Permission
|
||||||
Supervisor threads can access any kernel object. However, permissions for
|
Supervisor threads can access any kernel object. However, permissions for
|
||||||
supervisor threads are still tracked for two reasons:
|
supervisor threads are still tracked for two reasons:
|
||||||
|
|
||||||
* If a supervisor thread calls :cpp:func:`k_thread_user_mode_enter()`, the
|
* If a supervisor thread calls :c:func:`k_thread_user_mode_enter`, the
|
||||||
thread will then run in user mode with any permissions it had been granted
|
thread will then run in user mode with any permissions it had been granted
|
||||||
(in many cases, by itself) when it was a supervisor thread.
|
(in many cases, by itself) when it was a supervisor thread.
|
||||||
|
|
||||||
|
@ -162,17 +162,17 @@ ways to do this.
|
||||||
|
|
||||||
* A thread that has permission on an object, or is running in supervisor mode,
|
* A thread that has permission on an object, or is running in supervisor mode,
|
||||||
may grant permission on that object to another thread via the
|
may grant permission on that object to another thread via the
|
||||||
:c:func:`k_object_access_grant()` API. The convenience function
|
:c:func:`k_object_access_grant` API. The convenience function
|
||||||
:c:func:`k_thread_access_grant()` may also be used, which accepts a
|
:c:func:`k_thread_access_grant` may also be used, which accepts a
|
||||||
NULL-terminated list of kernel objects and calls
|
NULL-terminated list of kernel objects and calls
|
||||||
:c:func:`k_object_access_grant()` on each of them. The thread being granted
|
:c:func:`k_object_access_grant` on each of them. The thread being granted
|
||||||
permission, or the object whose access is being granted, do not need to be in
|
permission, or the object whose access is being granted, do not need to be in
|
||||||
an initialized state. If the caller is from user mode, the caller must have
|
an initialized state. If the caller is from user mode, the caller must have
|
||||||
permissions on both the kernel object and the target thread object.
|
permissions on both the kernel object and the target thread object.
|
||||||
|
|
||||||
* Supervisor threads may declare a particular kernel object to be a public
|
* Supervisor threads may declare a particular kernel object to be a public
|
||||||
object, usable by all current and future threads with the
|
object, usable by all current and future threads with the
|
||||||
:c:func:`k_object_access_all_grant()` API. You must assume that any
|
:c:func:`k_object_access_all_grant` API. You must assume that any
|
||||||
untrusted or exploited code will then be able to access the object. Use
|
untrusted or exploited code will then be able to access the object. Use
|
||||||
this API with caution!
|
this API with caution!
|
||||||
|
|
||||||
|
@ -181,16 +181,16 @@ ways to do this.
|
||||||
access to a set of kernel objects at boot time.
|
access to a set of kernel objects at boot time.
|
||||||
|
|
||||||
Once a thread has been granted access to an object, such access may be
|
Once a thread has been granted access to an object, such access may be
|
||||||
removed with the :c:func:`k_object_access_revoke()` API. This API is not
|
removed with the :c:func:`k_object_access_revoke` API. This API is not
|
||||||
available to user threads, however user threads may use
|
available to user threads, however user threads may use
|
||||||
:c:func:`k_object_release()` to relinquish their own permissions on an
|
:c:func:`k_object_release` to relinquish their own permissions on an
|
||||||
object.
|
object.
|
||||||
|
|
||||||
API calls from supervisor mode to set permissions on kernel objects that are
|
API calls from supervisor mode to set permissions on kernel objects that are
|
||||||
not being tracked by the kernel will be no-ops. Doing the same from user mode
|
not being tracked by the kernel will be no-ops. Doing the same from user mode
|
||||||
will result in a fatal error for the calling thread.
|
will result in a fatal error for the calling thread.
|
||||||
|
|
||||||
Objects allocated with :cpp:func:`k_object_alloc()` implicitly grant
|
Objects allocated with :c:func:`k_object_alloc` implicitly grant
|
||||||
permission on the allocated object to the calling thread.
|
permission on the allocated object to the calling thread.
|
||||||
|
|
||||||
Initialization State
|
Initialization State
|
||||||
|
@ -210,7 +210,7 @@ Some objects will be implicitly initialized at boot:
|
||||||
is run by the kernel early in the boot process.
|
is run by the kernel early in the boot process.
|
||||||
|
|
||||||
If a kernel object is initialized with a private static initializer, the object
|
If a kernel object is initialized with a private static initializer, the object
|
||||||
must have :c:func:`z_object_init()` called on it at some point by a supervisor
|
must have :c:func:`z_object_init` called on it at some point by a supervisor
|
||||||
thread, otherwise the kernel will consider the object uninitialized if accessed
|
thread, otherwise the kernel will consider the object uninitialized if accessed
|
||||||
by a user thread. This is very uncommon, typically only for kernel objects that
|
by a user thread. This is very uncommon, typically only for kernel objects that
|
||||||
are embedded within some larger struct and initialized statically.
|
are embedded within some larger struct and initialized statically.
|
||||||
|
|
|
@ -85,48 +85,48 @@ A small subset of kernel APIs, invoked as system calls, require heap memory
|
||||||
allocations. This memory is used only by the kernel and is not accessible
|
allocations. This memory is used only by the kernel and is not accessible
|
||||||
directly by user mode. In order to use these system calls, invoking threads
|
directly by user mode. In order to use these system calls, invoking threads
|
||||||
must assign themselves to a resource pool, which is a k_mem_pool object.
|
must assign themselves to a resource pool, which is a k_mem_pool object.
|
||||||
Memory is drawn from a thread's resource pool using :c:func:`z_thread_malloc()`
|
Memory is drawn from a thread's resource pool using :c:func:`z_thread_malloc`
|
||||||
and freed with :c:func:`k_free()`.
|
and freed with :c:func:`k_free`.
|
||||||
|
|
||||||
The APIs which use resource pools are as follows, with any alternatives
|
The APIs which use resource pools are as follows, with any alternatives
|
||||||
noted for users who do not want heap allocations within their application:
|
noted for users who do not want heap allocations within their application:
|
||||||
|
|
||||||
- :c:func:`k_stack_alloc_init()` sets up a k_stack with its storage
|
- :c:func:`k_stack_alloc_init` sets up a k_stack with its storage
|
||||||
buffer allocated out of a resource pool instead of a buffer provided by the
|
buffer allocated out of a resource pool instead of a buffer provided by the
|
||||||
user. An alternative is to declare k_stacks that are automatically
|
user. An alternative is to declare k_stacks that are automatically
|
||||||
initialized at boot with :c:macro:`K_STACK_DEFINE()`, or to initialize the
|
initialized at boot with :c:macro:`K_STACK_DEFINE()`, or to initialize the
|
||||||
k_stack in supervisor mode with :c:func:`k_stack_init()`.
|
k_stack in supervisor mode with :c:func:`k_stack_init`.
|
||||||
|
|
||||||
- :c:func:`k_pipe_alloc_init()` sets up a k_pipe object with its
|
- :c:func:`k_pipe_alloc_init` sets up a k_pipe object with its
|
||||||
storage buffer allocated out of a resource pool instead of a buffer provided
|
storage buffer allocated out of a resource pool instead of a buffer provided
|
||||||
by the user. An alternative is to declare k_pipes that are automatically
|
by the user. An alternative is to declare k_pipes that are automatically
|
||||||
initialized at boot with :c:macro:`K_PIPE_DEFINE()`, or to initialize the
|
initialized at boot with :c:macro:`K_PIPE_DEFINE()`, or to initialize the
|
||||||
k_pipe in supervisor mode with :c:func:`k_pipe_init()`.
|
k_pipe in supervisor mode with :c:func:`k_pipe_init`.
|
||||||
|
|
||||||
- :c:func:`k_msgq_alloc_init()` sets up a k_msgq object with its
|
- :c:func:`k_msgq_alloc_init` sets up a k_msgq object with its
|
||||||
storage buffer allocated out of a resource pool instead of a buffer provided
|
storage buffer allocated out of a resource pool instead of a buffer provided
|
||||||
by the user. An alternative is to declare a k_msgq that is automatically
|
by the user. An alternative is to declare a k_msgq that is automatically
|
||||||
initialized at boot with :c:macro:`K_MSGQ_DEFINE()`, or to initialize the
|
initialized at boot with :c:macro:`K_MSGQ_DEFINE()`, or to initialize the
|
||||||
k_msgq in supervisor mode with :c:func:`k_msgq_init()`.
|
k_msgq in supervisor mode with :c:func:`k_msgq_init`.
|
||||||
|
|
||||||
- :c:func:`k_poll()` when invoked from user mode, needs to make a kernel-side
|
- :c:func:`k_poll` when invoked from user mode, needs to make a kernel-side
|
||||||
copy of the provided events array while waiting for an event. This copy is
|
copy of the provided events array while waiting for an event. This copy is
|
||||||
freed when :c:func:`k_poll()` returns for any reason.
|
freed when :c:func:`k_poll` returns for any reason.
|
||||||
|
|
||||||
- :c:func:`k_queue_alloc_prepend()` and :c:func:`k_queue_alloc_append()`
|
- :c:func:`k_queue_alloc_prepend` and :c:func:`k_queue_alloc_append`
|
||||||
allocate a container structure to place the data in, since the internal
|
allocate a container structure to place the data in, since the internal
|
||||||
bookkeeping information that defines the queue cannot be placed in the
|
bookkeeping information that defines the queue cannot be placed in the
|
||||||
memory provided by the user.
|
memory provided by the user.
|
||||||
|
|
||||||
- :c:func:`k_object_alloc()` allows for entire kernel objects to be
|
- :c:func:`k_object_alloc` allows for entire kernel objects to be
|
||||||
dynamically allocated at runtime and a usable pointer to them returned to
|
dynamically allocated at runtime and a usable pointer to them returned to
|
||||||
the caller.
|
the caller.
|
||||||
|
|
||||||
The relevant API is :c:func:`k_thread_resource_pool_assign()` which assigns
|
The relevant API is :c:func:`k_thread_resource_pool_assign` which assigns
|
||||||
a k_mem_pool to draw these allocations from for the target thread.
|
a k_mem_pool to draw these allocations from for the target thread.
|
||||||
|
|
||||||
If the system heap is enabled, then the system heap may be used with
|
If the system heap is enabled, then the system heap may be used with
|
||||||
:c:func:`k_thread_system_pool_assign()`, but it is preferable for different
|
:c:func:`k_thread_system_pool_assign`, but it is preferable for different
|
||||||
logical applications running on the system to have their own pools.
|
logical applications running on the system to have their own pools.
|
||||||
|
|
||||||
Memory Domains
|
Memory Domains
|
||||||
|
@ -334,7 +334,7 @@ Create a Memory Domain
|
||||||
|
|
||||||
A memory domain is defined using a variable of type
|
A memory domain is defined using a variable of type
|
||||||
:c:type:`k_mem_domain`. It must then be initialized by calling
|
:c:type:`k_mem_domain`. It must then be initialized by calling
|
||||||
:cpp:func:`k_mem_domain_init()`.
|
:c:func:`k_mem_domain_init`.
|
||||||
|
|
||||||
The following code defines and initializes an empty memory domain.
|
The following code defines and initializes an empty memory domain.
|
||||||
|
|
||||||
|
|
|
@ -924,7 +924,7 @@ Libraries / Subsystems
|
||||||
- Added :c:macro:`LOG_PANIC()` call to the fault handlers to ensure that
|
- Added :c:macro:`LOG_PANIC()` call to the fault handlers to ensure that
|
||||||
logs are output on fault
|
logs are output on fault
|
||||||
- Added mechanism for handling logging of transient strings. See
|
- Added mechanism for handling logging of transient strings. See
|
||||||
:cpp:func:`log_strdup`
|
:c:func:`log_strdup`
|
||||||
- Added support for up to 15 arguments in the log message
|
- Added support for up to 15 arguments in the log message
|
||||||
- Added optional function name prefix in the log message
|
- Added optional function name prefix in the log message
|
||||||
- Changed logging thread priority to the lowest application priority
|
- Changed logging thread priority to the lowest application priority
|
||||||
|
@ -937,7 +937,7 @@ Libraries / Subsystems
|
||||||
- net
|
- net
|
||||||
- SWO
|
- SWO
|
||||||
- Xtensa Sim
|
- Xtensa Sim
|
||||||
- Changed default timestamp source function to :cpp:func:`k_uptime_get_32`
|
- Changed default timestamp source function to :c:func:`k_uptime_get_32`
|
||||||
|
|
||||||
* Shell:
|
* Shell:
|
||||||
|
|
||||||
|
|
|
@ -6,9 +6,9 @@ console_getchar() Sample Application
|
||||||
Overview
|
Overview
|
||||||
********
|
********
|
||||||
|
|
||||||
This example shows how to use :cpp:func:`console_getchar()` function.
|
This example shows how to use :c:func:`console_getchar` function.
|
||||||
Similar to the well-known ANSI C getchar() function,
|
Similar to the well-known ANSI C getchar() function,
|
||||||
:cpp:func:`console_getchar()` either returns the next available input
|
:c:func:`console_getchar` either returns the next available input
|
||||||
character or blocks waiting for one. Using this function, it should be
|
character or blocks waiting for one. Using this function, it should be
|
||||||
fairly easy to port existing ANSI C, POSIX, or Linux applications which
|
fairly easy to port existing ANSI C, POSIX, or Linux applications which
|
||||||
process console input character by character. The sample also allows to
|
process console input character by character. The sample also allows to
|
||||||
|
|
|
@ -6,9 +6,9 @@ console_getline() Sample Application
|
||||||
Overview
|
Overview
|
||||||
********
|
********
|
||||||
|
|
||||||
This example shows how to use :cpp:func:`console_getline()` function.
|
This example shows how to use :c:func:`console_getline` function.
|
||||||
Similar to the well-known ANSI C gets() and fgets() functions,
|
Similar to the well-known ANSI C gets() and fgets() functions,
|
||||||
:cpp:func:`console_getline()` either returns the next available input
|
:c:func:`console_getline` either returns the next available input
|
||||||
line or blocks waiting for one. Using this function, it should be fairly
|
line or blocks waiting for one. Using this function, it should be fairly
|
||||||
easy to port existing ANSI C, POSIX, or Linux applications which process
|
easy to port existing ANSI C, POSIX, or Linux applications which process
|
||||||
console input line by line. The sample also allows to see details of how
|
console input line by line. The sample also allows to see details of how
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue