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:
Fabio Utzig 2020-08-24 11:35:45 -03:00 committed by Anas Nashif
commit 53fd5ff236
48 changed files with 303 additions and 303 deletions

View file

@ -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.

View file

@ -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.

View file

@ -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
************* *************

View file

@ -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

View file

@ -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
************* *************

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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.

View file

@ -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.

View file

@ -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

View file

@ -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,

View file

@ -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,

View file

@ -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

View file

@ -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.

View file

@ -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.

View file

@ -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.

View file

@ -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
===================== =====================

View file

@ -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
************** **************

View file

@ -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.

View file

@ -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.

View file

@ -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
************** **************

View file

@ -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.

View file

@ -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

View file

@ -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

View file

@ -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.

View file

@ -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.

View file

@ -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.

View file

@ -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.

View file

@ -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

View file

@ -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
************** **************

View file

@ -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

View file

@ -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.

View file

@ -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
*********** ***********

View file

@ -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

View file

@ -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
******* *******

View file

@ -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).

View file

@ -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.

View file

@ -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,

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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.

View file

@ -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.

View file

@ -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:

View file

@ -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

View file

@ -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