From c79d2ce794766056f80a93f9ea66b6c96dad5857 Mon Sep 17 00:00:00 2001 From: Fabio Utzig Date: Thu, 20 Aug 2020 14:29:47 -0300 Subject: [PATCH] doc: update struct references to use :c:struct: Sphinx>=3.0 includes the `struct` role in the C domain, which provides a specific way to link to structs, while the old :c:type: role should be primary used to typedefs. Update existing references, using :c:type:, :cpp:type: or emphasized symbols that point to structs to use the new role. Signed-off-by: Fabio Utzig --- doc/guides/bluetooth/bluetooth-arch.rst | 2 +- doc/reference/bluetooth/connection_mgmt.rst | 4 ++-- doc/reference/bluetooth/gatt.rst | 12 ++++++------ doc/reference/bluetooth/l2cap.rst | 6 +++--- doc/reference/bluetooth/mesh/access.rst | 4 ++-- doc/reference/bluetooth/mesh/cfg_srv.rst | 2 +- doc/reference/bluetooth/mesh/provisioning.rst | 2 +- doc/reference/kernel/data_passing/fifos.rst | 2 +- doc/reference/kernel/data_passing/lifos.rst | 2 +- doc/reference/kernel/data_passing/mailboxes.rst | 4 ++-- .../kernel/data_passing/message_queues.rst | 2 +- doc/reference/kernel/data_passing/pipes.rst | 2 +- doc/reference/kernel/data_passing/stacks.rst | 2 +- doc/reference/kernel/memory/heap.rst | 8 ++++---- doc/reference/kernel/memory/pools.rst | 4 ++-- doc/reference/kernel/other/polling.rst | 6 +++--- doc/reference/kernel/synchronization/mutexes.rst | 2 +- .../kernel/synchronization/semaphores.rst | 2 +- doc/reference/kernel/threads/index.rst | 2 +- doc/reference/kernel/threads/workqueue.rst | 6 +++--- doc/reference/kernel/timing/clocks.rst | 6 +++--- doc/reference/kernel/timing/timers.rst | 2 +- doc/reference/misc/notify.rst | 4 ++-- doc/reference/networking/lwm2m.rst | 2 +- doc/reference/networking/net_l2.rst | 16 ++++++++-------- doc/reference/networking/net_pkt.rst | 2 +- doc/reference/peripherals/sensor.rst | 8 ++++---- doc/reference/usermode/kernelobjects.rst | 8 ++++---- doc/reference/usermode/memory_domain.rst | 2 +- 29 files changed, 63 insertions(+), 63 deletions(-) diff --git a/doc/guides/bluetooth/bluetooth-arch.rst b/doc/guides/bluetooth/bluetooth-arch.rst index bcba1351479..ff58ee782e1 100644 --- a/doc/guides/bluetooth/bluetooth-arch.rst +++ b/doc/guides/bluetooth/bluetooth-arch.rst @@ -321,7 +321,7 @@ 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 :c:func:`bt_conn_auth_cb_register` -API. The :c:type:`bt_conn_auth_cb` struct that's passed to this API has +API. The :c:struct:`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. For example, if the device does not have an input method but does have a diff --git a/doc/reference/bluetooth/connection_mgmt.rst b/doc/reference/bluetooth/connection_mgmt.rst index 3b91b5afeba..10eb91d08bd 100644 --- a/doc/reference/bluetooth/connection_mgmt.rst +++ b/doc/reference/bluetooth/connection_mgmt.rst @@ -3,7 +3,7 @@ Connection Management ##################### -The Zephyr Bluetooth stack uses an abstraction called :c:type:`bt_conn` +The Zephyr Bluetooth stack uses an abstraction called :c:struct:`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 @@ -16,7 +16,7 @@ longer period of time, since this ensures that the object remains valid to a connection. An application may track connections by registering a -:c:type:`bt_conn_cb` struct using the :c:func:`bt_conn_cb_register` +:c:struct:`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. diff --git a/doc/reference/bluetooth/gatt.rst b/doc/reference/bluetooth/gatt.rst index 0e9a8db72cb..9cba5ba6f00 100644 --- a/doc/reference/bluetooth/gatt.rst +++ b/doc/reference/bluetooth/gatt.rst @@ -8,11 +8,11 @@ GATT layer manages the service database providing APIs for service registration and attribute declaration. Services can be registered using :c:func:`bt_gatt_service_register` API -which takes the :cpp:class:`bt_gatt_service` struct that provides the list of +which takes the :c:struct:`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. -Attributes can be declared using the :cpp:class:`bt_gatt_attr` struct or using +Attributes can be declared using the :c:struct:`bt_gatt_attr` struct or using one of the helper macros: :cpp:func:`BT_GATT_PRIMARY_SERVICE` @@ -62,7 +62,7 @@ Client procedures can be enabled with the configuration option: Discover procedures can be initiated with the use of :c:func:`bt_gatt_discover` API which takes the -:cpp:class:`bt_gatt_discover_params` struct which describes the type of +:c:struct:`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 to NULL allows all attributes to be discovered. @@ -71,19 +71,19 @@ to NULL allows all attributes to be discovered. Caching discovered attributes is not supported. 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 +:c:struct:`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 :c:func:`bt_gatt_write` API and takes -:cpp:class:`bt_gatt_write_params` struct as parameters. In case the write +:c:struct:`bt_gatt_write_params` struct as parameters. In case the write 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 :c:func:`bt_gatt_subscribe` API which takes -:cpp:class:`bt_gatt_subscribe_params` as parameters. Multiple subscriptions to +:c:struct:`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 :c:func:`bt_gatt_unsubscribe` API. diff --git a/doc/reference/bluetooth/l2cap.rst b/doc/reference/bluetooth/l2cap.rst index 4198fabd33d..277c5220833 100644 --- a/doc/reference/bluetooth/l2cap.rst +++ b/doc/reference/bluetooth/l2cap.rst @@ -8,8 +8,8 @@ configuration option: :option:`CONFIG_BT_L2CAP_DYNAMIC_CHANNEL`. This channels support segmentation and reassembly transparently, they also support credit based flow control making it suitable for data streams. -Channels instances are represented by the :cpp:class:`bt_l2cap_chan` struct which -contains the callbacks in the :cpp:class:`bt_l2cap_chan_ops` struct to inform +Channels instances are represented by the :c:struct:`bt_l2cap_chan` struct which +contains the callbacks in the :c:struct:`bt_l2cap_chan_ops` struct to inform when the channel has been connected, disconnected or when the encryption has changed. In addition to that it also contains the ``recv`` callback which is called @@ -26,7 +26,7 @@ it may block if no credits are available, and resuming as soon as more credits are available. Servers can be registered using :c:func:`bt_l2cap_server_register` API passing -the :cpp:class:`bt_l2cap_server` struct which informs what ``psm`` it should +the :c:struct:`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. diff --git a/doc/reference/bluetooth/mesh/access.rst b/doc/reference/bluetooth/mesh/access.rst index aeeb56bce89..18fee2c5307 100644 --- a/doc/reference/bluetooth/mesh/access.rst +++ b/doc/reference/bluetooth/mesh/access.rst @@ -79,9 +79,9 @@ 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`, +* By specifying a set of message parameters in a :c:struct:`bt_mesh_msg_ctx`, and calling :c:func:`bt_mesh_model_send`. -* By setting up a :cpp:type:`bt_mesh_model_pub` structure and calling +* By setting up a :c:struct:`bt_mesh_model_pub` structure and calling :c:func:`bt_mesh_model_publish`. When publishing messages with :c:func:`bt_mesh_model_publish`, the model diff --git a/doc/reference/bluetooth/mesh/cfg_srv.rst b/doc/reference/bluetooth/mesh/cfg_srv.rst index fc1af389f02..cbf6bfe8061 100644 --- a/doc/reference/bluetooth/mesh/cfg_srv.rst +++ b/doc/reference/bluetooth/mesh/cfg_srv.rst @@ -9,7 +9,7 @@ mesh node. It does not have an API of its own, but relies on a :ref:`bluetooth_mesh_models_cfg_cli` to control it. The application can configure the initial parameters of the Configuration -Server model through the :cpp:type:`bt_mesh_cfg_srv` instance passed to +Server model through the :c:struct:`bt_mesh_cfg_srv` instance passed to :c:macro:`BT_MESH_MODEL_CFG_SRV`. Note that if the mesh node stored changes to this configuration in the settings subsystem, the initial values may be overwritten upon loading. diff --git a/doc/reference/bluetooth/mesh/provisioning.rst b/doc/reference/bluetooth/mesh/provisioning.rst index c0f093ea268..3e4f672199a 100644 --- a/doc/reference/bluetooth/mesh/provisioning.rst +++ b/doc/reference/bluetooth/mesh/provisioning.rst @@ -93,7 +93,7 @@ provisionee: actions are listed in :cpp:enum:`bt_mesh_output_action_t`. The application must provide callbacks for the supported authentication -methods in :cpp:type:`bt_mesh_prov`, as well as enabling the supported actions +methods in :c:struct:`bt_mesh_prov`, as well as enabling the supported actions in :cpp:var:`bt_mesh_prov::output_actions` and :cpp:var:`bt_mesh_prov::input_actions`. diff --git a/doc/reference/kernel/data_passing/fifos.rst b/doc/reference/kernel/data_passing/fifos.rst index 80923d8d7a6..aaf1f7b2c63 100644 --- a/doc/reference/kernel/data_passing/fifos.rst +++ b/doc/reference/kernel/data_passing/fifos.rst @@ -62,7 +62,7 @@ Implementation Defining a FIFO =============== -A FIFO is defined using a variable of type :c:type:`k_fifo`. +A FIFO is defined using a variable of type :c:struct:`k_fifo`. It must then be initialized by calling :c:func:`k_fifo_init`. The following code defines and initializes an empty FIFO. diff --git a/doc/reference/kernel/data_passing/lifos.rst b/doc/reference/kernel/data_passing/lifos.rst index 43599b15b41..5f5867f6688 100644 --- a/doc/reference/kernel/data_passing/lifos.rst +++ b/doc/reference/kernel/data_passing/lifos.rst @@ -53,7 +53,7 @@ Implementation Defining a LIFO =============== -A LIFO is defined using a variable of type :c:type:`k_lifo`. +A LIFO is defined using a variable of type :c:struct:`k_lifo`. It must then be initialized by calling :c:func:`k_lifo_init`. The following defines and initializes an empty LIFO. diff --git a/doc/reference/kernel/data_passing/mailboxes.rst b/doc/reference/kernel/data_passing/mailboxes.rst index 6ed6d769158..7611505b2f4 100644 --- a/doc/reference/kernel/data_passing/mailboxes.rst +++ b/doc/reference/kernel/data_passing/mailboxes.rst @@ -118,7 +118,7 @@ Implementation Defining a Mailbox ================== -A mailbox is defined using a variable of type :c:type:`k_mbox`. +A mailbox is defined using a variable of type :c:struct:`k_mbox`. It must then be initialized by calling :c:func:`k_mbox_init`. The following code defines and initializes an empty mailbox. @@ -141,7 +141,7 @@ The following code has the same effect as the code segment above. Message Descriptors =================== -A message descriptor is a structure of type :c:type:`k_mbox_msg`. +A message descriptor is a structure of type :c:struct:`k_mbox_msg`. Only the fields listed below should be used; any other fields are for internal mailbox use only. diff --git a/doc/reference/kernel/data_passing/message_queues.rst b/doc/reference/kernel/data_passing/message_queues.rst index 9fa837eddd4..fb78d9ffcc0 100644 --- a/doc/reference/kernel/data_passing/message_queues.rst +++ b/doc/reference/kernel/data_passing/message_queues.rst @@ -70,7 +70,7 @@ Implementation Defining a Message Queue ======================== -A message queue is defined using a variable of type :c:type:`k_msgq`. +A message queue is defined using a variable of type :c:struct:`k_msgq`. It must then be initialized by calling :c:func:`k_msgq_init`. The following code defines and initializes an empty message queue diff --git a/doc/reference/kernel/data_passing/pipes.rst b/doc/reference/kernel/data_passing/pipes.rst index c33435f3738..1b19375306f 100644 --- a/doc/reference/kernel/data_passing/pipes.rst +++ b/doc/reference/kernel/data_passing/pipes.rst @@ -52,7 +52,7 @@ waiting sender(s). Implementation ************** -A pipe is defined using a variable of type :c:type:`k_pipe` and an +A pipe is defined using a variable of type :c:struct:`k_pipe` and an optional character buffer of type ``unsigned char``. It must then be initialized by calling :c:func:`k_pipe_init`. diff --git a/doc/reference/kernel/data_passing/stacks.rst b/doc/reference/kernel/data_passing/stacks.rst index 97599f720e3..a88580009c4 100644 --- a/doc/reference/kernel/data_passing/stacks.rst +++ b/doc/reference/kernel/data_passing/stacks.rst @@ -55,7 +55,7 @@ Implementation Defining a Stack ================ -A stack is defined using a variable of type :c:type:`k_stack`. +A stack is defined using a variable of type :c:struct:`k_stack`. 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 diff --git a/doc/reference/kernel/memory/heap.rst b/doc/reference/kernel/memory/heap.rst index b07cac2aeef..f7ee86e1b9c 100644 --- a/doc/reference/kernel/memory/heap.rst +++ b/doc/reference/kernel/memory/heap.rst @@ -13,7 +13,7 @@ Creating a Heap =============== The simplest way to define a heap is statically, with the -:c:macro:`K_HEAP_DEFINE` macro. This creates a static :c:type:`k_heap` variable +:c:macro:`K_HEAP_DEFINE` macro. This creates a static :c:struct:`k_heap` variable with a given name that manages a memory region of the specified size. @@ -46,8 +46,8 @@ returned by :c:func:`k_heap_alloc` for the same heap. Freeing a Low Level Heap Allocator ************************ -The underlying implementation of the :c:type:`k_heap` -abstraction is provided a data structure named :c:type:`sys_heap`. This +The underlying implementation of the :c:struct:`k_heap` +abstraction is provided a data structure named :c:struct:`sys_heap`. This implements exactly the same allocation semantics, but provides no kernel synchronization tools. It is available for applications that want to manage their own blocks of memory in @@ -79,7 +79,7 @@ combined with adjacent free blocks to prevent fragmentation. All metadata is stored at the beginning of the contiguous block of heap memory, including the variable-length list of bucket list heads (which depend on heap size). The only external memory required is the -:c:type:`sys_heap` structure itself. +:c:struct:`sys_heap` structure itself. The ``sys_heap`` functions are unsynchronized. Care must be taken by any users to prevent concurrent access. Only one context may be diff --git a/doc/reference/kernel/memory/pools.rst b/doc/reference/kernel/memory/pools.rst index edccb44ebe6..86c0304f4a6 100644 --- a/doc/reference/kernel/memory/pools.rst +++ b/doc/reference/kernel/memory/pools.rst @@ -9,7 +9,7 @@ Memory Pools in current Zephyr code. It still exists for applications which require the specific memory allocation and alignment patterns detailed below, but the default heap implementation (including the - default backend to the k_mem_pool APIs) is now a :c:type:` k_heap` + default backend to the k_mem_pool APIs) is now a :c:struct:`k_heap` allocator, which is a better choice for general purpose code. @@ -119,7 +119,7 @@ Implementation Defining a Memory Pool ====================== -A memory pool is defined using a variable of type :c:type:`k_mem_pool`. +A memory pool is defined using a variable of type :c:struct:`k_mem_pool`. However, since a memory pool also requires a number of variable-size data structures to represent its block sets and the status of its quad-blocks, the kernel does not support the runtime definition of a memory pool. diff --git a/doc/reference/kernel/other/polling.rst b/doc/reference/kernel/other/polling.rst index a4bb9bb0a31..fc0be93b59c 100644 --- a/doc/reference/kernel/other/polling.rst +++ b/doc/reference/kernel/other/polling.rst @@ -68,7 +68,7 @@ Using k_poll() ============== The main API is :c:func:`k_poll`, which operates on an array of poll events -of type :c:type:`k_poll_event`. Each entry in the array represents one +of type :c:struct:`k_poll_event`. Each entry in the array represents one event a call to :c:func:`k_poll` will wait for its condition to be fulfilled. @@ -82,7 +82,7 @@ this). The user **tag** is optional and completely opaque to the API: it is there to help a user to group similar events together. Being optional, it is passed to the static initializer, but not the runtime ones for performance reasons. If using runtime initializers, the user must set it separately in the -:c:type:`k_poll_event` data structure. If an event in the array is to be +:c:struct:`k_poll_event` data structure. If an event in the array is to be ignored, most likely temporarily, its type can be set to K_POLL_TYPE_IGNORE. .. code-block:: c @@ -179,7 +179,7 @@ One of the types of events is :c:macro:`K_POLL_TYPE_SIGNAL`: this is a "direct" signal to a poll event. This can be seen as a lightweight binary semaphore only one thread can wait for. -A poll signal is a separate object of type :c:type:`k_poll_signal` that +A poll signal is a separate object of type :c:struct:`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 :c:func:`k_poll_signal_init`. diff --git a/doc/reference/kernel/synchronization/mutexes.rst b/doc/reference/kernel/synchronization/mutexes.rst index 3c15770f8ea..16253ad2374 100644 --- a/doc/reference/kernel/synchronization/mutexes.rst +++ b/doc/reference/kernel/synchronization/mutexes.rst @@ -93,7 +93,7 @@ Implementation Defining a Mutex ================ -A mutex is defined using a variable of type :c:type:`k_mutex`. +A mutex is defined using a variable of type :c:struct:`k_mutex`. It must then be initialized by calling :c:func:`k_mutex_init`. The following code defines and initializes a mutex. diff --git a/doc/reference/kernel/synchronization/semaphores.rst b/doc/reference/kernel/synchronization/semaphores.rst index 38839027d52..52dc145647d 100644 --- a/doc/reference/kernel/synchronization/semaphores.rst +++ b/doc/reference/kernel/synchronization/semaphores.rst @@ -47,7 +47,7 @@ Implementation Defining a Semaphore ==================== -A semaphore is defined using a variable of type :c:type:`k_sem`. +A semaphore is defined using a variable of type :c:struct:`k_sem`. It must then be initialized by calling :c:func:`k_sem_init`. The following code defines a semaphore, then configures it as a binary diff --git a/doc/reference/kernel/threads/index.rst b/doc/reference/kernel/threads/index.rst index a0db7927ba3..df185e225bc 100644 --- a/doc/reference/kernel/threads/index.rst +++ b/doc/reference/kernel/threads/index.rst @@ -24,7 +24,7 @@ A thread has the following key properties: stack memory regions. * A **thread control block** for private kernel bookkeeping of the thread's - metadata. This is an instance of type :c:type:`k_thread`. + metadata. This is an instance of type :c:struct:`k_thread`. * An **entry point function**, which is invoked when the thread is started. Up to 3 **argument values** can be passed to this function. diff --git a/doc/reference/kernel/threads/workqueue.rst b/doc/reference/kernel/threads/workqueue.rst index c9951fcfde2..e220c7cabc8 100644 --- a/doc/reference/kernel/threads/workqueue.rst +++ b/doc/reference/kernel/threads/workqueue.rst @@ -179,7 +179,7 @@ Implementation Defining a Workqueue ==================== -A workqueue is defined using a variable of type :c:type:`k_work_q`. +A workqueue is defined using a variable of type :c:struct:`k_work_q`. The workqueue is initialized by defining the stack area used by its thread 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 @@ -202,7 +202,7 @@ The following code defines and initializes a workqueue. Submitting a Work Item ====================== -A work item is defined using a variable of type :c:type:`k_work`. +A work item is defined using a variable of type :c:struct:`k_work`. It must then be initialized by calling :c:func:`k_work_init`. An initialized work item can be submitted to the system workqueue by @@ -250,7 +250,7 @@ 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 +:c:struct:`k_delayed_work`. It must then be initialized by calling :c:func:`k_delayed_work_init`. An initialized delayed work item can be submitted to the system workqueue by diff --git a/doc/reference/kernel/timing/clocks.rst b/doc/reference/kernel/timing/clocks.rst index 4c68d2818f9..4518b521ab3 100644 --- a/doc/reference/kernel/timing/clocks.rst +++ b/doc/reference/kernel/timing/clocks.rst @@ -90,8 +90,8 @@ For example: :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 - duration and period. +* Kernel :c:struct:`k_timer` objects must specify delays for + their duration and period. * The kernel ``k_delayed_work`` API provides a timeout parameter indicating when a work queue item will be added to the system queue. @@ -130,7 +130,7 @@ managed in a single, global queue of events. Each event is stored in a double-linked list, with an attendant delta count in ticks from the previous event. The action to take on an event is specified as a callback function pointer provided by the subsystem requesting the -event, along with a ``struct _timeout`` tracking struct that is +event, along with a :c:struct:`_timeout` tracking struct that is expected to be embedded within subsystem-defined data structures (for example: a ``struct wait_q``, or a ``k_tid_t`` thread struct). diff --git a/doc/reference/kernel/timing/timers.rst b/doc/reference/kernel/timing/timers.rst index 456c6963314..787f4e50487 100644 --- a/doc/reference/kernel/timing/timers.rst +++ b/doc/reference/kernel/timing/timers.rst @@ -103,7 +103,7 @@ Implementation Defining a Timer ================ -A timer is defined using a variable of type :c:type:`k_timer`. +A timer is defined using a variable of type :c:struct:`k_timer`. It must then be initialized by calling :c:func:`k_timer_init`. The following code defines and initializes a timer. diff --git a/doc/reference/misc/notify.rst b/doc/reference/misc/notify.rst index ce03602f563..f2ce395b273 100644 --- a/doc/reference/misc/notify.rst +++ b/doc/reference/misc/notify.rst @@ -21,7 +21,7 @@ API. A limitation is that this API is not suitable for :ref:`syscalls` because: -* :c:type:`sys_notify` is not a kernel object; +* :c:struct:`sys_notify` is not a kernel object; * copying the notification content from userspace will break use of :c:macro:`CONTAINER_OF` in the implementing function; * neither the spin-wait nor callback notification methods can be @@ -29,7 +29,7 @@ because: Where a notification is required for an asynchronous operation invoked from a user mode thread the subsystem or driver should provide a syscall -API that uses :c:type:`k_poll_signal` for notification. +API that uses :c:struct:`k_poll_signal` for notification. API Reference ************* diff --git a/doc/reference/networking/lwm2m.rst b/doc/reference/networking/lwm2m.rst index 6f0619612be..860b79526d6 100644 --- a/doc/reference/networking/lwm2m.rst +++ b/doc/reference/networking/lwm2m.rst @@ -247,7 +247,7 @@ Sample usage ************ To use the LwM2M library, start by creating an LwM2M client context -:c:type:`lwm2m_ctx` structure: +:c:struct:`lwm2m_ctx` structure: .. code-block:: c diff --git a/doc/reference/networking/net_l2.rst b/doc/reference/networking/net_l2.rst index bbc49f0ca32..0b9f367eb8a 100644 --- a/doc/reference/networking/net_l2.rst +++ b/doc/reference/networking/net_l2.rst @@ -12,12 +12,12 @@ Overview The L2 stack is designed to hide the whole networking link-layer part and the related device drivers from the upper network stack. This is made -through a :c:type:`net_if` declared in +through a :c:struct:`net_if` declared in :zephyr_file:`include/net/net_if.h`. The upper layers are unaware of implementation details beyond the net_if object and the generic API provided by the L2 layer in -:zephyr_file:`include/net/net_l2.h` as :c:type:`net_l2`. +:zephyr_file:`include/net/net_l2.h` as :c:struct:`net_l2`. Only the L2 layer can talk to the device driver, linked to the net_if object. The L2 layer dictates the API provided by the device driver, @@ -69,13 +69,13 @@ basis. Please refer to :ref:`device_model_api`. There are, however, two differences: -- The driver_api pointer must point to a valid :c:type:`net_if_api` +- The driver_api pointer must point to a valid :c:struct:`net_if_api` pointer. - The network device driver must use ``NET_DEVICE_INIT_INSTANCE()`` or ``ETH_NET_DEVICE_INIT()`` for Ethernet devices. These macros will call the ``DEVICE_AND_API_INIT()`` macro, and also - instantiate a unique :c:type:`net_if` related to the created + instantiate a unique :c:struct:`net_if` related to the created device driver instance. Implementing a network device driver depends on the L2 stack it @@ -116,8 +116,8 @@ Device drivers for IEEE 802.15.4 L2 work basically the same as for Ethernet. What has been described above, especially for ``recv()``, applies here as well. There are two specific differences however: -- It requires a dedicated device driver API: :c:type:`ieee802154_radio_api`, - which overloads :c:type:`net_if_api`. This is because 802.15.4 L2 needs more from the device +- It requires a dedicated device driver API: :c:struct:`ieee802154_radio_api`, + which overloads :c:struct:`net_if_api`. This is because 802.15.4 L2 needs more from the device driver than just ``send()`` and ``recv()`` functions. This dedicated API is declared in :zephyr_file:`include/net/ieee802154_radio.h`. Each and every IEEE 802.15.4 device driver must provide a valid pointer on such @@ -129,8 +129,8 @@ here as well. There are two specific differences however: frame size limitation. But a buffer containing an IPv6/UDP packet might have more than one fragment. IEEE 802.15.4 drivers handle only one buffer at a time. This is why the - :c:type:`ieee802154_radio_api` requires a tx function pointer which differs - from the :c:type:`net_if_api` send function pointer. + :c:struct:`ieee802154_radio_api` requires a tx function pointer which differs + from the :c:struct:`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:type:`net_if` send function. It turn, the implementation diff --git a/doc/reference/networking/net_pkt.rst b/doc/reference/networking/net_pkt.rst index 1714eaef040..1bf0ab9d9d7 100644 --- a/doc/reference/networking/net_pkt.rst +++ b/doc/reference/networking/net_pkt.rst @@ -74,7 +74,7 @@ Buffer allocation ================= The net_pkt object does not define its own buffer, but instead uses an -existing object for this: :c:type:`net_buf`. (See +existing object for this: :c:struct:`net_buf`. (See :ref:`net_buf_interface` for more information). However, it mostly hides the usage of such a buffer because net_pkt brings network awareness to buffer allocation and, as we will see later, its diff --git a/doc/reference/peripherals/sensor.rst b/doc/reference/peripherals/sensor.rst index b7856418a45..46b5c803ada 100644 --- a/doc/reference/peripherals/sensor.rst +++ b/doc/reference/peripherals/sensor.rst @@ -29,7 +29,7 @@ description and units of measurement: Values ====== -Sensor devices return results as :c:type:`sensor_value`. This +Sensor devices return results as :c:struct:`sensor_value`. This representation avoids use of floating point values as they may not be supported on certain setups. @@ -41,7 +41,7 @@ application instructs the driver to fetch a sample of all its channels. Then, individual channels may be read. In the case of channels with multiple axes, they can be read in a single operation by supplying the corresponding :literal:`_XYZ` channel type and a buffer of 3 -:c:type:`sensor_value` objects. This approach ensures consistency +:c:struct:`sensor_value` objects. This approach ensures consistency of channels between reads and efficiency of communication by issuing a single transaction on the underlying bus. @@ -55,7 +55,7 @@ compensates data for both channels. :lines: 12- :linenos: -The example assumes that the returned values have type :c:type:`sensor_value`, +The example assumes that the returned values have type :c:struct:`sensor_value`, which is the case for BME280. A real application supporting multiple sensors should inspect the :c:data:`type` field of the :c:data:`temp` and :c:data:`press` values and use the other fields @@ -90,7 +90,7 @@ include: new data is ready for reading, a channel value has crossed a threshold, or the device has sensed motion. To configure a trigger, an application needs to supply a -:c:type:`sensor_trigger` and a handler function. The structure contains the +:c:struct:`sensor_trigger` and a handler function. The structure contains the trigger type and the channel on which the trigger must be configured. Because most sensors are connected via SPI or I2C busses, it is not possible diff --git a/doc/reference/usermode/kernelobjects.rst b/doc/reference/usermode/kernelobjects.rst index 7b456383f98..121aebb7306 100644 --- a/doc/reference/usermode/kernelobjects.rst +++ b/doc/reference/usermode/kernelobjects.rst @@ -6,7 +6,7 @@ Kernel Objects A kernel object can be one of three classes of data: * A core kernel object, such as a semaphore, thread, pipe, etc. -* A thread stack, which is an array of :c:type:`z_thread_stack_element` +* A thread stack, which is an array of :c:struct:`z_thread_stack_element` and declared with :c:macro:`K_THREAD_STACK_DEFINE()` * A device driver instance (struct device) that belongs to one of a defined set of subsystems @@ -109,14 +109,14 @@ When a system call is made and the kernel is presented with a memory address of what may or may not be a valid kernel object, the address can be validated with a constant-time lookup in this table. -Drivers are a special case. All drivers are instances of :c:type:`device`, but +Drivers are a special case. All drivers are instances of :c:struct:`device`, but it is important to know what subsystem a driver belongs to so that incorrect operations, such as calling a UART API on a sensor driver object, can be prevented. When a device struct is found, its API pointer is examined to determine what subsystem the driver belongs to. The table itself maps kernel object memory addresses to instances of -:c:type:`z_object`, which has all the metadata for that object. This +:c:struct:`z_object`, which has all the metadata for that object. This includes: * A bitfield indicating permissions on that object. All threads have a @@ -250,7 +250,7 @@ Instances of the new struct should now be tracked. Creating New Driver Subsystem Kernel Objects ============================================ -All driver instances are :c:type:`device`. They are differentiated by +All driver instances are :c:struct:`device`. They are differentiated by what API struct they are set to. * In ``scripts/gen_kobject_list.py``, add the name of the API struct for the diff --git a/doc/reference/usermode/memory_domain.rst b/doc/reference/usermode/memory_domain.rst index 1b67b6a8903..6a63b7c5b57 100644 --- a/doc/reference/usermode/memory_domain.rst +++ b/doc/reference/usermode/memory_domain.rst @@ -333,7 +333,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 +:c:struct:`k_mem_domain`. It must then be initialized by calling :c:func:`k_mem_domain_init`. The following code defines and initializes an empty memory domain.