From 53fd5ff236aa2f82378a4cd477d0a1a6c7c98074 Mon Sep 17 00:00:00 2001 From: Fabio Utzig Date: Mon, 24 Aug 2020 11:35:45 -0300 Subject: [PATCH] doc: update function references to use :c:func: Following the change to use the C domain for parsing, update all existing :cpp:func: references to :c:func:. Remove the parentheses as well, if used, because they are not needed, this is already known to be a function, and how it is displayed in the documentation later is a semantic decision done by the output builder. Signed-off-by: Fabio Utzig --- doc/guides/bluetooth/bluetooth-arch.rst | 20 +++++----- doc/guides/bluetooth/bluetooth-dev.rst | 8 ++-- doc/guides/debugging/thread-analyzer.rst | 2 +- doc/guides/porting/arch.rst | 30 +++++++-------- doc/reference/bluetooth/connection_mgmt.rst | 10 ++--- doc/reference/bluetooth/gatt.rst | 24 ++++++------ doc/reference/bluetooth/l2cap.rst | 10 ++--- doc/reference/bluetooth/mesh/access.rst | 12 +++--- doc/reference/bluetooth/mesh/core.rst | 2 +- doc/reference/bluetooth/mesh/provisioning.rst | 6 +-- doc/reference/drivers/index.rst | 6 +-- doc/reference/kernel/data_passing/fifos.rst | 12 +++--- doc/reference/kernel/data_passing/lifos.rst | 10 ++--- .../kernel/data_passing/mailboxes.rst | 8 ++-- .../kernel/data_passing/message_queues.rst | 8 ++-- doc/reference/kernel/data_passing/pipes.rst | 6 +-- doc/reference/kernel/data_passing/stacks.rst | 8 ++-- doc/reference/kernel/memory/heap.rst | 22 +++++------ doc/reference/kernel/memory/pools.rst | 16 ++++---- doc/reference/kernel/memory/slabs.rst | 6 +-- doc/reference/kernel/other/atomic.rst | 2 +- doc/reference/kernel/other/float.rst | 22 +++++------ doc/reference/kernel/other/interrupts.rst | 8 ++-- doc/reference/kernel/other/polling.rst | 38 +++++++++---------- doc/reference/kernel/other/ring_buffers.rst | 34 ++++++++--------- doc/reference/kernel/scheduling/index.rst | 24 ++++++------ .../kernel/synchronization/mutexes.rst | 6 +-- .../kernel/synchronization/semaphores.rst | 6 +-- doc/reference/kernel/threads/index.rst | 24 ++++++------ .../kernel/threads/system_threads.rst | 10 ++--- doc/reference/kernel/threads/workqueue.rst | 20 +++++----- doc/reference/kernel/timing/clocks.rst | 26 ++++++------- doc/reference/kernel/timing/timers.rst | 4 +- doc/reference/logging/index.rst | 30 +++++++-------- doc/reference/misc/notify.rst | 2 +- doc/reference/networking/gptp.rst | 4 +- doc/reference/networking/lwm2m.rst | 4 +- doc/reference/networking/net_l2.rst | 14 +++---- doc/reference/networking/net_mgmt.rst | 14 +++---- doc/reference/networking/sockets.rst | 2 +- doc/reference/networking/vlan.rst | 4 +- doc/reference/shell/index.rst | 4 +- doc/reference/terminology.rst | 10 ++--- doc/reference/usermode/kernelobjects.rst | 26 ++++++------- doc/reference/usermode/memory_domain.rst | 30 +++++++-------- doc/releases/release-notes-1.14.rst | 4 +- samples/subsys/console/getchar/README.rst | 4 +- samples/subsys/console/getline/README.rst | 4 +- 48 files changed, 303 insertions(+), 303 deletions(-) diff --git a/doc/guides/bluetooth/bluetooth-arch.rst b/doc/guides/bluetooth/bluetooth-arch.rst index ad75b3684fe..bcba1351479 100644 --- a/doc/guides/bluetooth/bluetooth-arch.rst +++ b/doc/guides/bluetooth/bluetooth-arch.rst @@ -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. diff --git a/doc/guides/bluetooth/bluetooth-dev.rst b/doc/guides/bluetooth/bluetooth-dev.rst index e778423a6ff..3299f1045bb 100644 --- a/doc/guides/bluetooth/bluetooth-dev.rst +++ b/doc/guides/bluetooth/bluetooth-dev.rst @@ -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. diff --git a/doc/guides/debugging/thread-analyzer.rst b/doc/guides/debugging/thread-analyzer.rst index 5df3d49b315..cee4a378bb6 100644 --- a/doc/guides/debugging/thread-analyzer.rst +++ b/doc/guides/debugging/thread-analyzer.rst @@ -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 ************* diff --git a/doc/guides/porting/arch.rst b/doc/guides/porting/arch.rst index dd9eed25f15..9494c64686c 100644 --- a/doc/guides/porting/arch.rst +++ b/doc/guides/porting/arch.rst @@ -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 diff --git a/doc/reference/bluetooth/connection_mgmt.rst b/doc/reference/bluetooth/connection_mgmt.rst index bf406f614e2..3b91b5afeba 100644 --- a/doc/reference/bluetooth/connection_mgmt.rst +++ b/doc/reference/bluetooth/connection_mgmt.rst @@ -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 ************* diff --git a/doc/reference/bluetooth/gatt.rst b/doc/reference/bluetooth/gatt.rst index 4711ec4d5e9..0e9a8db72cb 100644 --- a/doc/reference/bluetooth/gatt.rst +++ b/doc/reference/bluetooth/gatt.rst @@ -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 diff --git a/doc/reference/bluetooth/l2cap.rst b/doc/reference/bluetooth/l2cap.rst index 3c0da1cfc34..4198fabd33d 100644 --- a/doc/reference/bluetooth/l2cap.rst +++ b/doc/reference/bluetooth/l2cap.rst @@ -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 diff --git a/doc/reference/bluetooth/mesh/access.rst b/doc/reference/bluetooth/mesh/access.rst index 80e65b942c1..aeeb56bce89 100644 --- a/doc/reference/bluetooth/mesh/access.rst +++ b/doc/reference/bluetooth/mesh/access.rst @@ -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 diff --git a/doc/reference/bluetooth/mesh/core.rst b/doc/reference/bluetooth/mesh/core.rst index 7d25e942190..8320be23992 100644 --- a/doc/reference/bluetooth/mesh/core.rst +++ b/doc/reference/bluetooth/mesh/core.rst @@ -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. diff --git a/doc/reference/bluetooth/mesh/provisioning.rst b/doc/reference/bluetooth/mesh/provisioning.rst index 89ad0f80107..c0f093ea268 100644 --- a/doc/reference/bluetooth/mesh/provisioning.rst +++ b/doc/reference/bluetooth/mesh/provisioning.rst @@ -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. diff --git a/doc/reference/drivers/index.rst b/doc/reference/drivers/index.rst index bb1f877aa94..2cd31e680e4 100644 --- a/doc/reference/drivers/index.rst +++ b/doc/reference/drivers/index.rst @@ -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 diff --git a/doc/reference/kernel/data_passing/fifos.rst b/doc/reference/kernel/data_passing/fifos.rst index 7086da6adde..80923d8d7a6 100644 --- a/doc/reference/kernel/data_passing/fifos.rst +++ b/doc/reference/kernel/data_passing/fifos.rst @@ -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, diff --git a/doc/reference/kernel/data_passing/lifos.rst b/doc/reference/kernel/data_passing/lifos.rst index 6c53b7efdbb..43599b15b41 100644 --- a/doc/reference/kernel/data_passing/lifos.rst +++ b/doc/reference/kernel/data_passing/lifos.rst @@ -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, diff --git a/doc/reference/kernel/data_passing/mailboxes.rst b/doc/reference/kernel/data_passing/mailboxes.rst index 45ab134045a..6ed6d769158 100644 --- a/doc/reference/kernel/data_passing/mailboxes.rst +++ b/doc/reference/kernel/data_passing/mailboxes.rst @@ -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 diff --git a/doc/reference/kernel/data_passing/message_queues.rst b/doc/reference/kernel/data_passing/message_queues.rst index 9f5d6934f08..9fa837eddd4 100644 --- a/doc/reference/kernel/data_passing/message_queues.rst +++ b/doc/reference/kernel/data_passing/message_queues.rst @@ -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. diff --git a/doc/reference/kernel/data_passing/pipes.rst b/doc/reference/kernel/data_passing/pipes.rst index 94d28100274..c33435f3738 100644 --- a/doc/reference/kernel/data_passing/pipes.rst +++ b/doc/reference/kernel/data_passing/pipes.rst @@ -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. diff --git a/doc/reference/kernel/data_passing/stacks.rst b/doc/reference/kernel/data_passing/stacks.rst index 4f8cceae3f8..97599f720e3 100644 --- a/doc/reference/kernel/data_passing/stacks.rst +++ b/doc/reference/kernel/data_passing/stacks.rst @@ -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. diff --git a/doc/reference/kernel/memory/heap.rst b/doc/reference/kernel/memory/heap.rst index 96436dc0861..b07cac2aeef 100644 --- a/doc/reference/kernel/memory/heap.rst +++ b/doc/reference/kernel/memory/heap.rst @@ -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 ===================== diff --git a/doc/reference/kernel/memory/pools.rst b/doc/reference/kernel/memory/pools.rst index 7ea03af9933..edccb44ebe6 100644 --- a/doc/reference/kernel/memory/pools.rst +++ b/doc/reference/kernel/memory/pools.rst @@ -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 ************** diff --git a/doc/reference/kernel/memory/slabs.rst b/doc/reference/kernel/memory/slabs.rst index 680469b6f48..a446353d8e3 100644 --- a/doc/reference/kernel/memory/slabs.rst +++ b/doc/reference/kernel/memory/slabs.rst @@ -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. diff --git a/doc/reference/kernel/other/atomic.rst b/doc/reference/kernel/other/atomic.rst index 7a177168277..e853f3ccd77 100644 --- a/doc/reference/kernel/other/atomic.rst +++ b/doc/reference/kernel/other/atomic.rst @@ -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. diff --git a/doc/reference/kernel/other/float.rst b/doc/reference/kernel/other/float.rst index 8b99f69d29f..19a2978407c 100644 --- a/doc/reference/kernel/other/float.rst +++ b/doc/reference/kernel/other/float.rst @@ -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 ************** diff --git a/doc/reference/kernel/other/interrupts.rst b/doc/reference/kernel/other/interrupts.rst index d34719b072e..e3d61ad0019 100644 --- a/doc/reference/kernel/other/interrupts.rst +++ b/doc/reference/kernel/other/interrupts.rst @@ -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. diff --git a/doc/reference/kernel/other/polling.rst b/doc/reference/kernel/other/polling.rst index 4828305d83a..a4bb9bb0a31 100644 --- a/doc/reference/kernel/other/polling.rst +++ b/doc/reference/kernel/other/polling.rst @@ -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 diff --git a/doc/reference/kernel/other/ring_buffers.rst b/doc/reference/kernel/other/ring_buffers.rst index 3c618884802..a69d7edf383 100644 --- a/doc/reference/kernel/other/ring_buffers.rst +++ b/doc/reference/kernel/other/ring_buffers.rst @@ -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 diff --git a/doc/reference/kernel/scheduling/index.rst b/doc/reference/kernel/scheduling/index.rst index 659bc0d5ddb..cc02a1d9be8 100644 --- a/doc/reference/kernel/scheduling/index.rst +++ b/doc/reference/kernel/scheduling/index.rst @@ -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 `, 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. diff --git a/doc/reference/kernel/synchronization/mutexes.rst b/doc/reference/kernel/synchronization/mutexes.rst index 57b8ddd5dd9..3c15770f8ea 100644 --- a/doc/reference/kernel/synchronization/mutexes.rst +++ b/doc/reference/kernel/synchronization/mutexes.rst @@ -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. diff --git a/doc/reference/kernel/synchronization/semaphores.rst b/doc/reference/kernel/synchronization/semaphores.rst index 3387ed24626..38839027d52 100644 --- a/doc/reference/kernel/synchronization/semaphores.rst +++ b/doc/reference/kernel/synchronization/semaphores.rst @@ -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. diff --git a/doc/reference/kernel/threads/index.rst b/doc/reference/kernel/threads/index.rst index 29086722451..a0db7927ba3 100644 --- a/doc/reference/kernel/threads/index.rst +++ b/doc/reference/kernel/threads/index.rst @@ -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. diff --git a/doc/reference/kernel/threads/system_threads.rst b/doc/reference/kernel/threads/system_threads.rst index 5adb2ff4221..03c7b6e1266 100644 --- a/doc/reference/kernel/threads/system_threads.rst +++ b/doc/reference/kernel/threads/system_threads.rst @@ -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 diff --git a/doc/reference/kernel/threads/workqueue.rst b/doc/reference/kernel/threads/workqueue.rst index a1c28e150b9..c9951fcfde2 100644 --- a/doc/reference/kernel/threads/workqueue.rst +++ b/doc/reference/kernel/threads/workqueue.rst @@ -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 ************** diff --git a/doc/reference/kernel/timing/clocks.rst b/doc/reference/kernel/timing/clocks.rst index 5e90891e571..4c68d2818f9 100644 --- a/doc/reference/kernel/timing/clocks.rst +++ b/doc/reference/kernel/timing/clocks.rst @@ -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 diff --git a/doc/reference/kernel/timing/timers.rst b/doc/reference/kernel/timing/timers.rst index 286cd07401d..456c6963314 100644 --- a/doc/reference/kernel/timing/timers.rst +++ b/doc/reference/kernel/timing/timers.rst @@ -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. diff --git a/doc/reference/logging/index.rst b/doc/reference/logging/index.rst index c0d7d082272..b69502a557a 100644 --- a/doc/reference/logging/index.rst +++ b/doc/reference/logging/index.rst @@ -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 *********** diff --git a/doc/reference/misc/notify.rst b/doc/reference/misc/notify.rst index f3431a14f6e..ce03602f563 100644 --- a/doc/reference/misc/notify.rst +++ b/doc/reference/misc/notify.rst @@ -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 diff --git a/doc/reference/networking/gptp.rst b/doc/reference/networking/gptp.rst index 37070f79b75..f8c27c141c8 100644 --- a/doc/reference/networking/gptp.rst +++ b/doc/reference/networking/gptp.rst @@ -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 ******* diff --git a/doc/reference/networking/lwm2m.rst b/doc/reference/networking/lwm2m.rst index cfbfc8bf5c5..6f0619612be 100644 --- a/doc/reference/networking/lwm2m.rst +++ b/doc/reference/networking/lwm2m.rst @@ -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). diff --git a/doc/reference/networking/net_l2.rst b/doc/reference/networking/net_l2.rst index 49d862bc221..bbc49f0ca32 100644 --- a/doc/reference/networking/net_l2.rst +++ b/doc/reference/networking/net_l2.rst @@ -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. diff --git a/doc/reference/networking/net_mgmt.rst b/doc/reference/networking/net_mgmt.rst index 75c0e205a3e..9ca990f20c6 100644 --- a/doc/reference/networking/net_mgmt.rst +++ b/doc/reference/networking/net_mgmt.rst @@ -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, diff --git a/doc/reference/networking/sockets.rst b/doc/reference/networking/sockets.rst index 075f0942785..bbc5703496a 100644 --- a/doc/reference/networking/sockets.rst +++ b/doc/reference/networking/sockets.rst @@ -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 diff --git a/doc/reference/networking/vlan.rst b/doc/reference/networking/vlan.rst index 050b4c5983c..5cce838a88b 100644 --- a/doc/reference/networking/vlan.rst +++ b/doc/reference/networking/vlan.rst @@ -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 ` for API usage diff --git a/doc/reference/shell/index.rst b/doc/reference/shell/index.rst index fcd8ddb8f8e..05f519d27ce 100644 --- a/doc/reference/shell/index.rst +++ b/doc/reference/shell/index.rst @@ -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 diff --git a/doc/reference/terminology.rst b/doc/reference/terminology.rst index a36da56b69e..6d5049f1cd3 100644 --- a/doc/reference/terminology.rst +++ b/doc/reference/terminology.rst @@ -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 diff --git a/doc/reference/usermode/kernelobjects.rst b/doc/reference/usermode/kernelobjects.rst index e692e7913bc..7b456383f98 100644 --- a/doc/reference/usermode/kernelobjects.rst +++ b/doc/reference/usermode/kernelobjects.rst @@ -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. diff --git a/doc/reference/usermode/memory_domain.rst b/doc/reference/usermode/memory_domain.rst index faebf945244..1b67b6a8903 100644 --- a/doc/reference/usermode/memory_domain.rst +++ b/doc/reference/usermode/memory_domain.rst @@ -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. diff --git a/doc/releases/release-notes-1.14.rst b/doc/releases/release-notes-1.14.rst index 5fdc441cbc9..b3bf8b1bba3 100644 --- a/doc/releases/release-notes-1.14.rst +++ b/doc/releases/release-notes-1.14.rst @@ -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: diff --git a/samples/subsys/console/getchar/README.rst b/samples/subsys/console/getchar/README.rst index 92eafba9f40..a7b2deee170 100644 --- a/samples/subsys/console/getchar/README.rst +++ b/samples/subsys/console/getchar/README.rst @@ -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 diff --git a/samples/subsys/console/getline/README.rst b/samples/subsys/console/getline/README.rst index 200b89b4e4f..a02efbd57c4 100644 --- a/samples/subsys/console/getline/README.rst +++ b/samples/subsys/console/getline/README.rst @@ -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