michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: update function references to use :c:func:

Browse source 
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
Download patch file Download diff file Expand all files Collapse all files

20
doc/guides/bluetooth/bluetooth-arch.rst
View file

@ -259,8 +259,8 @@ Peripheral role
Most Zephyr-based BLE devices will most likely be peripheral-role
devices. This means that they perform connectable advertising and expose
one or more GATT services. After registering services using the
:cpp:func:`bt_gatt_service_register` API the application will typically
start connectable advertising using the :cpp:func:`bt_le_adv_start` API.
:c:func:`bt_gatt_service_register` API the application will typically
start connectable advertising using the :c:func:`bt_le_adv_start` API.
There are several peripheral sample applications available in the tree,
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.
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
:cpp: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_le_scan_stop` and then connect to the device using
:c:func:`bt_conn_create_le`. If the central wants to keep
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
tree, such as :zephyr_file:`samples/bluetooth/central_hr`.
@ -290,7 +290,7 @@ tree, such as :zephyr_file:`samples/bluetooth/central_hr`.
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
simply utilize the advertising data of found devices, combining it
optionally with the received signal strength (RSSI).
@ -298,7 +298,7 @@ optionally with the received signal strength (RSSI).
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
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
called pairing is used. This process can either be triggered implicitly
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
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
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
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.

8
doc/guides/bluetooth/bluetooth-dev.rst
View file

@ -156,10 +156,10 @@ another real or simulated device.
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
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.
Bluetooth Application Example
@ -174,8 +174,8 @@ advertising, effectively acting as a Bluetooth Low Energy broadcaster.
:lines: 19-
:linenos:
The key APIs employed by the beacon sample are :cpp:func:`bt_enable`
that's used to initialize Bluetooth and then :cpp:func:`bt_le_adv_start`
The key APIs employed by the beacon sample are :c:func:`bt_enable`
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
and scan response data.

2
doc/guides/debugging/thread-analyzer.rst
View file

@ -6,7 +6,7 @@ Thread analyzer
The thread analyzer module enables all the Zephyr options required to track
the thread information, e.g. thread stack size usage.
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
*************

30
doc/guides/porting/arch.rst
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.
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
: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
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
*************
@ -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
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
* :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.
* :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
generated from where the system call was invoked in the user thread
* :cpp:func:`arch_syscall_invoke0()` through
:cpp:func:`arch_syscall_invoke6()` invoke a system call with the
* :c:func:`arch_syscall_invoke0` through
:c:func:`arch_syscall_invoke6` invoke a system call with the
appropriate number of arguments which must all be passed in during the
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
* :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,
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
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.
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
* On context switch, the outgoing thread's stack memory should be marked

10
doc/reference/bluetooth/connection_mgmt.rst
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
are not exposed to the application, but a limited amount of information
(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
: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
(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.
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 &
disconnection events, as well as other events related to a connection
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
connection object through the return value of the
:cpp:func:`bt_conn_create_le` API.
:c:func:`bt_conn_create_le` API.
API Reference
*************

24
doc/reference/bluetooth/gatt.rst
View file

@ -7,7 +7,7 @@ Generic Attribute Profile (GATT)
GATT layer manages the service database providing APIs for service registration
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
attributes the service contains. The helper macro :cpp:func:`BT_GATT_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
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,
alternatively there is :cpp:func:`bt_gatt_notify_cb` where is is possible to
Attribute value changes can be notified using :c:func:`bt_gatt_notify` API,
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
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:
:option:`CONFIG_BT_GATT_CLIENT`
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
discovery. The parameters also serves as a filter when setting the ``uuid``
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::
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
more attributes can be set, though setting multiple handles requires the option:
: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
operation don't require a response :cpp:func:`bt_gatt_write_without_response`
or :cpp:func:`bt_gatt_write_without_response_cb` APIs can be used, with the
later working similarly to ``bt_gatt_notify_cb``.
operation don't require a response :c:func:`bt_gatt_write_without_response`
or :c:func:`bt_gatt_write_without_response_cb` APIs can be used, with the
later working similarly to :c:func:`bt_gatt_notify_cb`.
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
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
:cpp:func:`bt_gatt_unsubscribe()` API.
:c:func:`bt_gatt_unsubscribe` API.
.. note::
When subscriptions are removed ``notify`` callback is called with the data

10
doc/reference/bluetooth/l2cap.rst
View file

@ -15,24 +15,24 @@ changed.
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
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::
The ``recv`` callback is called directly from RX Thread thus it is not
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
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
listen to, the required security level ``sec_level``, and the callback
``accept`` which is called to authorize incoming connection requests and
allocate channel instances.
Client channels can be initiated with use of :cpp:func:`bt_l2cap_chan_connect`
API and can be disconnected with the :cpp:func:`bt_l2cap_chan_disconnect` API.
Client channels can be initiated with use of :c:func:`bt_l2cap_chan_connect`
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.
API Reference

12
doc/reference/bluetooth/mesh/access.rst
View file

@ -21,7 +21,7 @@ element instantiating all the models required for a single aspect of the
supported behavior.
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
:ref:`bluetooth_mesh_models`) and a set of models for implementing common
behavior in the `Bluetooth Mesh Model Specification
@ -80,11 +80,11 @@ Model publication
The models may send messages in two ways:
* 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
: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
:ref:`bluetooth_mesh_models_cfg_srv`. This is the recommended way to send
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
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
extensions cannot be circular. Note that binding of node states and other
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
data, leveraging the internal model instance encoding scheme. Models can store
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
: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

2
doc/reference/bluetooth/mesh/core.rst
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 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
:option:`CONFIG_BT_MESH_LOW_POWER` option and related configuration options.

6
doc/reference/bluetooth/mesh/provisioning.rst
View file

@ -29,10 +29,10 @@ Beaconing
To start the provisioning process, the unprovisioned device must first start
broadcasting the Unprovisioned Beacon. This makes it visible to nearby
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
``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
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
@ -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
application receives the :cpp:var:`bt_mesh_prov::input` callback. The user
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
aborted.

6
doc/reference/drivers/index.rst
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``).
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.
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
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
=========================================
@ -580,7 +580,7 @@ Drivers that do not use DTS
===========================
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:
.. code-block:: C

12
doc/reference/kernel/data_passing/fifos.rst
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 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
: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.
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`.
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.
@ -85,7 +85,7 @@ The following code has the same effect as the code segment above.
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
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
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
the data item, instead additional memory will be allocated from the calling
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
===================
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
to obtain data items from a producer thread,

10
doc/reference/kernel/data_passing/lifos.rst
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
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
: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.
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`.
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.
@ -76,7 +76,7 @@ The following code has the same effect as the code segment above.
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
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
the data item, instead additional memory will be allocated from the calling
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
===================
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
to obtain data items from a producer thread,

8
doc/reference/kernel/data_passing/mailboxes.rst
View file

@ -119,7 +119,7 @@ Defining a Mailbox
==================
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.
@ -486,12 +486,12 @@ The receiving thread must then respond as follows:
the mailbox has already completed data retrieval and deleted the message.
* 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
the data into the message buffer and deletes the message.
* 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
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
data subsequently into a message buffer --- the receiving thread first
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.
The mailbox also deletes the received message, since data retrieval
has been completed. The receiving thread is then responsible for freeing

8
doc/reference/kernel/data_passing/message_queues.rst
View file

@ -71,7 +71,7 @@ Defining a Message Queue
========================
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
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
==========================
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
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
============================
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
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
============================
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
head of the queue that is generated by one or more producing threads.

6
doc/reference/kernel/data_passing/pipes.rst
View file

@ -54,7 +54,7 @@ Implementation
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
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
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
=================
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
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
===================
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
process data items generated by one or more producing threads.

8
doc/reference/kernel/data_passing/stacks.rst
View file

@ -56,8 +56,8 @@ Defining a 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
:cpp:func:`k_stack_alloc_init()`. In the latter case, a buffer is not
It must then be initialized by calling :c:func:`k_stack_init` or
: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
pool.
@ -86,7 +86,7 @@ that the macro defines both the stack and its array of data values.
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
can create a pool of data structures by saving their memory addresses
@ -109,7 +109,7 @@ in 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
can dynamically allocate an unused data structure.

22
doc/reference/kernel/memory/heap.rst
View file

@ -18,12 +18,12 @@ with a given name that manages a memory region of the
specified size.
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
=================
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
desired. This functions similarly to standard C ``malloc()``,
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
================
Memory allocated with :cpp:func:`k_heap_alloc()` must be released using
:cpp:func:`k_heap_free()`. Similar to standard C ``free()``, the pointer
Memory allocated with :c:func:`k_heap_alloc` must be released using
:c:func:`k_heap_free`. Similar to standard C ``free()``, the pointer
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.
Low Level Heap Allocator
@ -100,7 +100,7 @@ System Heap
The :dfn:`system heap` is a predefined memory allocator that allows
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
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.
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
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
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
=============================
@ -131,7 +131,7 @@ the link stage if the size specified can not be supported.
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
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
================
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
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
:cpp:func:`malloc()`-like manner.
:c:func:`malloc`-like manner.
Configuration Options
=====================

16
doc/reference/kernel/memory/pools.rst
View file

@ -141,7 +141,7 @@ as well as its buffer.
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
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");
}
Memory blocks may also be allocated with :cpp:func:`malloc()`-like semantics
using :cpp:func:`k_mem_pool_malloc()`. Such allocations must be freed with
:cpp:func:`k_free()`.
Memory blocks may also be allocated with :c:func:`malloc`-like semantics
using :c:func:`k_mem_pool_malloc`. Such allocations must be freed with
:c:func:`k_free`.
Releasing a Memory Block
========================
A memory block is released by calling either :cpp:func:`k_mem_pool_free()`
or :cpp:func:`k_free()`, depending on how it was allocated.
A memory block is released by calling either :c:func:`k_mem_pool_free`
or :c:func:`k_free`, depending on how it was allocated.
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
@ -195,12 +195,12 @@ as items are placed in the queue.
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
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,
and any children of that thread will inherit this assignment.
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
**************

6
doc/reference/kernel/memory/slabs.rst
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`.
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
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
=========================
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
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
========================
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,
then releases it once it is no longer needed.

2
doc/reference/kernel/other/atomic.rst
View file

@ -70,7 +70,7 @@ However, you can also define an N-bit array of atomic variables using
:c:macro:`ATOMIC_DEFINE`.
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
using an array of atomic variables.

22
doc/reference/kernel/other/float.rst
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`.
* 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
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.
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.
ARCv2 architecture
@ -127,10 +127,10 @@ following techniques.
:c:macro:`K_FP_REGS` option to :c:macro:`K_THREAD_DEFINE`.
* 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
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.
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`.
* 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.
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
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
: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
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
: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
the contents of the floating point registers during context switches
when there is no need to do so.
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
**************

8
doc/reference/kernel/other/interrupts.rst
View file

@ -53,7 +53,7 @@ nesting support is enabled.
.. important::
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
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
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
then be enabled by calling :cpp:func:`irq_enable()`.
then be enabled by calling :c:func:`irq_enable`.
.. important::
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
known at build time, in some cases this may not be acceptable. It is also
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`:
.. 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
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
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.
For interrupts declared with :c:macro:`IRQ_DIRECT_CONNECT` the parameterless
ISR is placed directly in the IDT.

38
doc/reference/kernel/other/polling.rst
View file

@ -13,8 +13,8 @@ to be fulfilled.
Concepts
********
The polling API's main function is :cpp:func:`k_poll()`, which is very similar
in concept to the POSIX :cpp:func:`poll()` function, except that it operates on
The polling API's main function is :c:func:`k_poll`, which is very similar
in concept to the POSIX :c:func:`poll` function, except that it operates on
kernel objects rather than on file descriptors.
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
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
when :cpp:func:`k_poll()` returns, if they were fulfilled before
:cpp:func:`k_poll()` was called, or due to the preemptive multi-threading
when :c:func:`k_poll` returns, if they were fulfilled before
: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
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
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
: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
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.
Implementation
@ -67,13 +67,13 @@ Implementation
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
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.
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
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*
@ -118,18 +118,18 @@ or at runtime
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
:c:macro:`K_FOREVER` to either not wait or wait until an event condition is
satisfied and not sooner.
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
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.
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`.
.. 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.
.. 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
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
:cpp:func:`k_poll_signal_init()`.
:c:func:`k_poll_signal_init`.
.. code-block:: c
@ -192,7 +192,7 @@ first be initialized either via :c:macro:`K_POLL_SIGNAL_INITIALIZER()` or
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
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
**************
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.
Use a poll signal as a lightweight binary semaphore if only one thread pends on

34
doc/reference/kernel/other/ring_buffers.rst
View file

@ -42,15 +42,15 @@ Data item mode
A **data item mode** ring buffer instance is declared using
:cpp:func:`RING_BUF_ITEM_DECLARE_POW2()` or
: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
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
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.
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
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
@ -62,30 +62,30 @@ Byte mode
A **byte mode** ring buffer instance is declared using
:cpp:func:`RING_BUF_DECLARE_SIZE()` and accessed using:
:cpp:func:`ring_buf_put_claim()`, :cpp:func:`ring_buf_put_finish()`,
:cpp:func:`ring_buf_get_claim()`, :cpp:func:`ring_buf_get_finish()`,
:cpp:func:`ring_buf_put()` and :cpp:func:`ring_buf_get()`.
:c:func:`ring_buf_put_claim`, :c:func:`ring_buf_put_finish`,
:c:func:`ring_buf_get_claim`, :c:func:`ring_buf_get_finish`,
:c:func:`ring_buf_put` and :c:func:`ring_buf_get`.
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:
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.
#. writing the data by the user (e.g. buffer written by DMA).
#. 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.
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
into three stages:
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
#. 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.
Concurrency
@ -118,7 +118,7 @@ Defining a Ring Buffer
======================
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
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
:cpp:func:`ring_buf_item_put()`.
:c:func:`ring_buf_item_put`.
.. code-block:: c
@ -201,7 +201,7 @@ can be specified.
}
Bytes are copied to a **byte mode** ring buffer by calling
:cpp:func:`ring_buf_put()`.
:c:func:`ring_buf_put`.
.. code-block:: c
@ -241,7 +241,7 @@ Retrieving Data
===============
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
@ -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
:cpp:func:`ring_buf_get()`. For example:
:c:func:`ring_buf_get`. For example:
.. code-block:: c

24
doc/reference/kernel/scheduling/index.rst
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:
- 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
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
- 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,
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.
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.
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
rescheduled. If no such ready threads exist, the scheduler immediately
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;
however, there is no guarantee that threads whose priority is lower
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.
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
the opportunity to execute before the current thread is scheduled again.
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 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.
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
and allow other threads to execute. When the locking thread again
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
===============
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
the CPU is relinquished to allow other ready threads to execute.
Once the specified delay has elapsed the thread becomes ready
and is eligible to be scheduled once again.
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
that something has occurred *without* requiring the threads
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
============
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
*without* relinquishing the CPU to another ready thread.

6
doc/reference/kernel/synchronization/mutexes.rst
View file

@ -94,7 +94,7 @@ Defining a 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.
@ -116,7 +116,7 @@ The following code has the same effect as the code segment above.
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
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
=================
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,
and unlocks the mutex that was previously locked by the thread.

6
doc/reference/kernel/synchronization/semaphores.rst
View file

@ -48,7 +48,7 @@ Defining a Semaphore
====================
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
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
==================
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
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
==================
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
for the semaphore to be given.

24
doc/reference/kernel/threads/index.rst
View file

@ -86,7 +86,7 @@ prior to returning, since the kernel does *not* reclaim them automatically.
ability to respawn a thread that 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
thread self-exits, or the target thread aborts (either due to a
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.
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.
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
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.
Suspending a thread that is already suspended has no additional effect.
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::
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
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.
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``.
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
:option:`CONFIG_THREAD_CUSTOM_DATA` can be used to enable support.
The :cpp:func:`k_thread_custom_data_set()` and
:cpp:func:`k_thread_custom_data_get()` functions are used to write and read
The :c:func:`k_thread_custom_data_set` and
: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
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,
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
: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);
.. 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
thread immediately. The corresponding parameter to :c:macro:`K_THREAD_DEFINE`
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
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
calling thread will be terminated:
@ -449,7 +449,7 @@ Dropping Permissions
If :option:`CONFIG_USERSPACE` is enabled, a thread running in supervisor mode
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
as non-essential.

10
doc/reference/kernel/threads/system_threads.rst
View file

@ -14,7 +14,7 @@ The kernel spawns the following system threads:
**Main thread**
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
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).
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
: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.
**Idle thread**
@ -53,11 +53,11 @@ Implementation
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
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.
.. code-block:: c

20
doc/reference/kernel/threads/workqueue.rst
View file

@ -124,11 +124,11 @@ the work item is always processed by the workqueue and cannot be canceled.
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
call a user-defined function when a monitored resource becomes available
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 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`.
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
memory.
@ -203,11 +203,11 @@ Submitting a Work Item
======================
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
calling :cpp:func:`k_work_submit()`, or to a specified workqueue by
calling :cpp:func:`k_work_submit_to_queue()`.
calling :c:func:`k_work_submit`, or to a specified workqueue by
calling :c:func:`k_work_submit_to_queue`.
The following code demonstrates how an ISR can offload the printing
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
: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
calling :cpp: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`, or to a specified workqueue by
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
by calling :cpp:func:`k_delayed_work_cancel()`.
by calling :c:func:`k_delayed_work_cancel`.
Suggested Uses
**************

26
doc/reference/kernel/timing/clocks.rst
View file

@ -20,14 +20,14 @@ understood, though they may not match the precision of the underlying
hardware perfectly.
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
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
application code might use this in a polling manner to achieve maximal
precision. The frequency of this counter is required to be steady
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
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
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
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.
See the reference documentation for the full enumeration of conversion
routines.
@ -70,14 +70,14 @@ Uptime
======
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
expected to be the utility used by most portable application code.
The internal tracking, however, is as a 64 bit integer count of ticks.
Apps with precise timing requirements (that are willing to do their
own conversions to portable real time units) may access this with
:cpp:func:`k_uptime_ticks()`.
:c:func:`k_uptime_ticks`.
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.
For example:
* Kernel blocking operations like :cpp:func:`k_sem_take()` or
:cpp:func:`k_queue_get()` may provide a timeout after which the
* Kernel blocking operations like :c:func:`k_sem_take` or
:c:func:`k_queue_get` may provide a timeout after which the
routine will return with an error code if no data is available.
* 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.
* 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
every event, even though by definition only one of them should see a
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,
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
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
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
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
uptime precision to prevent rollover bugs, handles special
: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
delta timeouts need to be interpreted relative to a "current time",
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
this function just once, as synchronously as possible to the timeout
creation in user code. It should not be used on a "stored" timeout

4
doc/reference/kernel/timing/timers.rst
View file

@ -104,7 +104,7 @@ Defining a 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.
@ -222,7 +222,7 @@ amount of time.
Use a timer to determine whether or not a specified amount of time has
elapsed. In particular, timers should be used when higher precision
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
involving time limits.

30
doc/reference/logging/index.rst
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.
: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
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
used. Optionally, user can provide function which returns timestamp value. If
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.
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
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
by source ID and domain ID. Source ID can be retrieved if source name is known
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
interrupts. In that situation deferred log message processing is not an option.
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
switch to blocking, synchronous mode (stop using interrupts) or disable itself.
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`).
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.
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
@ -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
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
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``.
Logger backends
@ -465,22 +465,22 @@ Logger backends
Logger supports up to 9 concurrent backends. Logger backend interface consists
of two functions:
- :cpp: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_put` - backend gets log message.
- :c:func:`log_backend_panic` - on that call backend is notified that it must
switch to panic (synchronous) mode. If backend cannot support synchronous,
interrupt-less operation (e.g. network) it should stop any processing.
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
: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
(:cpp: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`) decrementing a reference counter. On last
: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
intends to format message into the string, helper function for that are
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
@ -489,7 +489,7 @@ Example message formatted using :cpp:func:`log_output_msg_process`.
.. note::
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
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
:c:macro:`LOG_BACKEND_DEFINE` macro. The macro creates an instance in the
dedicated memory section. Backends can be dynamically enabled
(:cpp:func:`log_backend_enable`) and disabled.
(:c:func:`log_backend_enable`) and disabled.
Limitations
***********

2
doc/reference/misc/notify.rst
View file

@ -5,7 +5,7 @@ Asynchronous Notification APIs
Zephyr APIs often include :ref:`api_term_async` functions where an
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
suited to a callback notification, and operations like enabling clocks
and power rails may need to be invoked before kernel functions are

4
doc/reference/networking/gptp.rst
View file

@ -54,8 +54,8 @@ Application interfaces
Only two Application Interfaces as defined in section 9 of the standard
are available:
- ``ClockTargetPhaseDiscontinuity`` interface (:cpp:func:`gptp_register_phase_dis_cb()`)
- ``ClockTargetEventCapture`` interface (:cpp:func:`gptp_event_capture()`)
- ``ClockTargetPhaseDiscontinuity`` interface (:c:func:`gptp_register_phase_dis_cb`)
- ``ClockTargetEventCapture`` interface (:c:func:`gptp_event_capture`)
Testing
*******

4
doc/reference/networking/lwm2m.rst
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);
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:
.. code-block:: c
@ -398,7 +398,7 @@ resource. Lastly, set the client identity and PSK resources.
/* Set the client pre-shared key (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
value of 1 is ok here).

14
doc/reference/networking/net_l2.rst
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
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
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
@ -91,12 +91,12 @@ Ethernet device driver
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
:c:type:`net_pkt` and should be allocated through
:c:func:`net_pkt_rx_alloc_with_buffer()`. Then all data buffers will be
automatically allocated and filled by :c:func:`net_pkt_write()`.
:c:func:`net_pkt_rx_alloc_with_buffer`. Then all data buffers will be
automatically allocated and filled by :c:func:`net_pkt_write`.
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
device driver to unreference the buffer via :c:func:`net_pkt_unref()`.
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`.
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.
@ -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
from the :c:type:`net_if_api` send function pointer.
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
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
function, and unreferencing the network packet
only when all the transmission were successful.

14
doc/reference/networking/net_mgmt.rst
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
procedures are not used. Instead, defined procedure handlers are
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.
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
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
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
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
:cpp:func:`net_mgmt_del_event_callback()`
:c:func:`net_mgmt_del_event_callback`
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.
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
the event code (passed as an argument) against the specific network
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
layer code.)
@ -145,7 +145,7 @@ This new management procedure could then be called by using:
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
: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,

2
doc/reference/networking/sockets.rst
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
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
will be also exposed as aliases without the prefix. This includes the
functions like ``close()`` and ``fcntl()`` (which may conflict with

4
doc/reference/networking/vlan.rst
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
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
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.
See also the :ref:`VLAN sample application <vlan-sample>` for API usage

4
doc/reference/shell/index.rst
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.
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
@ -249,7 +249,7 @@ Simple command handler implementation:
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_error` can be used from the command handler or from threads,
but not from an interrupt context. Instead, interrupt handlers should use

10
doc/reference/terminology.rst
View file

@ -80,7 +80,7 @@ sleep.
This attribute does not imply the function will sleep unconditionally,
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**.
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.
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.
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.
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
: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:
@ -184,7 +184,7 @@ Explanation
Be aware that **async** is orthogonal to context-switching. Some APIs
may provide completion information through a callback, but may suspend
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
no-wait path only guarantees that the function will not sleep. It does

26
doc/reference/usermode/kernelobjects.rst
View file

@ -76,20 +76,20 @@ Dynamic Objects
Kernel objects may also be allocated at runtime if
: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
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.
* 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
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
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
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 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
(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,
may grant permission on that object to another thread via the
: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_object_access_grant` API. The convenience function
:c:func:`k_thread_access_grant` may also be used, which accepts a
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
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.
* Supervisor threads may declare a particular kernel object to be a public
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
this API with caution!
@ -181,16 +181,16 @@ ways to do this.
access to a set of kernel objects at boot time.
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
: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.
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
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.
Initialization State
@ -210,7 +210,7 @@ Some objects will be implicitly initialized at boot:
is run by the kernel early in the boot process.
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
by a user thread. This is very uncommon, typically only for kernel objects that
are embedded within some larger struct and initialized statically.

30
doc/reference/usermode/memory_domain.rst
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
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.
Memory is drawn from a thread's resource pool using :c:func:`z_thread_malloc()`
and freed with :c:func:`k_free()`.
Memory is drawn from a thread's resource pool using :c:func:`z_thread_malloc`
and freed with :c:func:`k_free`.
The APIs which use resource pools are as follows, with any alternatives
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
user. An alternative is to declare k_stacks that are automatically
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
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
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
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
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
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
bookkeeping information that defines the queue cannot be placed in the
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
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.
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.
Memory Domains
@ -334,7 +334,7 @@ Create a Memory Domain
A memory domain is defined using a variable of type
: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.

4
doc/releases/release-notes-1.14.rst
View file

@ -924,7 +924,7 @@ Libraries / Subsystems
- Added :c:macro:`LOG_PANIC()` call to the fault handlers to ensure that
logs are output on fault
- 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 optional function name prefix in the log message
- Changed logging thread priority to the lowest application priority
@ -937,7 +937,7 @@ Libraries / Subsystems
- net
- SWO
- 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:

4
samples/subsys/console/getchar/README.rst
View file

@ -6,9 +6,9 @@ console_getchar() Sample Application
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,
: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
fairly easy to port existing ANSI C, POSIX, or Linux applications which
process console input character by character. The sample also allows to

4
samples/subsys/console/getline/README.rst
View file

@ -6,9 +6,9 @@ console_getline() Sample Application
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,
: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
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