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 <fabio.utzig@nordicsemi.no>
This commit is contained in:
Fabio Utzig 2020-08-20 14:29:47 -03:00 committed by Anas Nashif
commit c79d2ce794
29 changed files with 63 additions and 63 deletions

View file

@ -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 out-of-band channel during the pairing. If the devices have a sufficient
user interface this "channel" is the user itself. The capabilities of user interface this "channel" is the user itself. The capabilities of
the device are registered using the :c:func:`bt_conn_auth_cb_register` the device are registered using the :c:func:`bt_conn_auth_cb_register`
API. The :c:type:`bt_conn_auth_cb` struct that's passed to this API has API. The :c: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 a set of optional callbacks that can be used during the pairing - if the
device lacks some feature the corresponding callback may be set to NULL. device lacks some feature the corresponding callback may be set to NULL.
For example, if the device does not have an input method but does have a For example, if the device does not have an input method but does have a

View file

@ -3,7 +3,7 @@
Connection Management 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 to represent connections to other devices. The internals of this struct
are not exposed to the application, but a limited amount of information are not exposed to the application, but a limited amount of information
(such as the remote address) can be acquired using the (such as the remote address) can be acquired using the
@ -16,7 +16,7 @@ longer period of time, since this ensures that the object remains valid
to a connection. to a connection.
An application may track connections by registering a An application may track connections by registering a
:c:type:`bt_conn_cb` struct using the :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 & API. This struct lets the application define callbacks for connection &
disconnection events, as well as other events related to a connection disconnection events, as well as other events related to a connection
such as a change in the security level or the connection parameters. such as a change in the security level or the connection parameters.

View file

@ -8,11 +8,11 @@ GATT layer manages the service database providing APIs for service registration
and attribute declaration. and attribute declaration.
Services can be registered using :c:func:`bt_gatt_service_register` API Services can be registered using :c:func:`bt_gatt_service_register` API
which takes the :cpp:class:`bt_gatt_service` struct that provides the list of which takes the :c:struct:`bt_gatt_service` struct that provides the list of
attributes the service contains. The helper macro :cpp:func:`BT_GATT_SERVICE` attributes the service contains. The helper macro :cpp:func:`BT_GATT_SERVICE`
can be used to declare a service. can be used to declare a service.
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: one of the helper macros:
:cpp:func:`BT_GATT_PRIMARY_SERVICE` :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 Discover procedures can be initiated with the use of
:c: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 :c:struct:`bt_gatt_discover_params` struct which describes the type of
discovery. The parameters also serves as a filter when setting the ``uuid`` discovery. The parameters also serves as a filter when setting the ``uuid``
field only attributes which matches will be discovered, in contrast setting it field only attributes which matches will be discovered, in contrast setting it
to NULL allows all attributes to be discovered. 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. Caching discovered attributes is not supported.
Read procedures are supported by :c: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 :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: more attributes can be set, though setting multiple handles requires the option:
:option:`CONFIG_BT_GATT_READ_MULTIPLE` :option:`CONFIG_BT_GATT_READ_MULTIPLE`
Write procedures are supported by :c: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 :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` 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 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`. later working similarly to :c:func:`bt_gatt_notify_cb`.
Subscriptions to notification and indication can be initiated with use of Subscriptions to notification and indication can be initiated with use of
:c: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 :c:struct:`bt_gatt_subscribe_params` as parameters. Multiple subscriptions to
the same attribute are supported so there could be multiple ``notify`` callback the same attribute are supported so there could be multiple ``notify`` callback
being triggered for the same attribute. Subscriptions can be removed with use of being triggered for the same attribute. Subscriptions can be removed with use of
:c:func:`bt_gatt_unsubscribe` API. :c:func:`bt_gatt_unsubscribe` API.

View file

@ -8,8 +8,8 @@ configuration option: :option:`CONFIG_BT_L2CAP_DYNAMIC_CHANNEL`. This channels
support segmentation and reassembly transparently, they also support credit support segmentation and reassembly transparently, they also support credit
based flow control making it suitable for data streams. based flow control making it suitable for data streams.
Channels instances are represented by the :cpp:class:`bt_l2cap_chan` struct which Channels instances are represented by the :c:struct:`bt_l2cap_chan` struct which
contains the callbacks in the :cpp:class:`bt_l2cap_chan_ops` struct to inform 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 when the channel has been connected, disconnected or when the encryption has
changed. changed.
In addition to that it also contains the ``recv`` callback which is called In addition to that it also contains the ``recv`` callback which is called
@ -26,7 +26,7 @@ it may block if no credits are available, and resuming as soon as more credits
are available. are available.
Servers can be registered using :c:func:`bt_l2cap_server_register` API passing Servers can be registered using :c:func:`bt_l2cap_server_register` API passing
the :cpp:class:`bt_l2cap_server` struct which informs what ``psm`` it should the :c:struct:`bt_l2cap_server` struct which informs what ``psm`` it should
listen to, the required security level ``sec_level``, and the callback listen to, the required security level ``sec_level``, and the callback
``accept`` which is called to authorize incoming connection requests and ``accept`` which is called to authorize incoming connection requests and
allocate channel instances. allocate channel instances.

View file

@ -79,9 +79,9 @@ Model publication
The models may send messages in two ways: The models may send messages in two ways:
* By specifying a set of message parameters in a :cpp:type:`bt_mesh_msg_ctx`, * By specifying a set of message parameters in a :c:struct:`bt_mesh_msg_ctx`,
and calling :c:func:`bt_mesh_model_send`. and calling :c:func:`bt_mesh_model_send`.
* By setting up a :cpp:type:`bt_mesh_model_pub` structure and calling * By setting up a :c:struct:`bt_mesh_model_pub` structure and calling
:c:func:`bt_mesh_model_publish`. :c:func:`bt_mesh_model_publish`.
When publishing messages with :c:func:`bt_mesh_model_publish`, the model When publishing messages with :c:func:`bt_mesh_model_publish`, the model

View file

@ -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. :ref:`bluetooth_mesh_models_cfg_cli` to control it.
The application can configure the initial parameters of the Configuration 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 :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 this configuration in the settings subsystem, the initial values may be
overwritten upon loading. overwritten upon loading.

View file

@ -93,7 +93,7 @@ provisionee:
actions are listed in :cpp:enum:`bt_mesh_output_action_t`. actions are listed in :cpp:enum:`bt_mesh_output_action_t`.
The application must provide callbacks for the supported authentication 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 in :cpp:var:`bt_mesh_prov::output_actions` and
:cpp:var:`bt_mesh_prov::input_actions`. :cpp:var:`bt_mesh_prov::input_actions`.

View file

@ -62,7 +62,7 @@ Implementation
Defining a FIFO 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`. It must then be initialized by calling :c:func:`k_fifo_init`.
The following code defines and initializes an empty FIFO. The following code defines and initializes an empty FIFO.

View file

@ -53,7 +53,7 @@ Implementation
Defining a LIFO 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`. It must then be initialized by calling :c:func:`k_lifo_init`.
The following defines and initializes an empty LIFO. The following defines and initializes an empty LIFO.

View file

@ -118,7 +118,7 @@ Implementation
Defining a Mailbox 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`. It must then be initialized by calling :c:func:`k_mbox_init`.
The following code defines and initializes an empty mailbox. The following code defines and initializes an empty mailbox.
@ -141,7 +141,7 @@ The following code has the same effect as the code segment above.
Message Descriptors 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 Only the fields listed below should be used; any other fields are for
internal mailbox use only. internal mailbox use only.

View file

@ -70,7 +70,7 @@ Implementation
Defining a Message Queue 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`. It must then be initialized by calling :c:func:`k_msgq_init`.
The following code defines and initializes an empty message queue The following code defines and initializes an empty message queue

View file

@ -52,7 +52,7 @@ waiting sender(s).
Implementation 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 optional character buffer of type ``unsigned char``. It must then be
initialized by calling :c:func:`k_pipe_init`. initialized by calling :c:func:`k_pipe_init`.

View file

@ -55,7 +55,7 @@ Implementation
Defining a Stack 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 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 :c:func:`k_stack_alloc_init`. In the latter case, a buffer is not
provided and it is instead allocated from the calling thread's resource provided and it is instead allocated from the calling thread's resource

View file

@ -13,7 +13,7 @@ Creating a Heap
=============== ===============
The simplest way to define a heap is statically, with the 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 with a given name that manages a memory region of the
specified size. specified size.
@ -46,8 +46,8 @@ returned by :c:func:`k_heap_alloc` for the same heap. Freeing a
Low Level Heap Allocator Low Level Heap Allocator
************************ ************************
The underlying implementation of the :c:type:`k_heap` The underlying implementation of the :c:struct:`k_heap`
abstraction is provided a data structure named :c:type:`sys_heap`. This abstraction is provided a data structure named :c:struct:`sys_heap`. This
implements exactly the same allocation semantics, but implements exactly the same allocation semantics, but
provides no kernel synchronization tools. It is available for provides no kernel synchronization tools. It is available for
applications that want to manage their own blocks of memory in 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 All metadata is stored at the beginning of the contiguous block of
heap memory, including the variable-length list of bucket list heads heap memory, including the variable-length list of bucket list heads
(which depend on heap size). The only external memory required is the (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 The ``sys_heap`` functions are unsynchronized. Care must be taken by
any users to prevent concurrent access. Only one context may be any users to prevent concurrent access. Only one context may be

View file

@ -9,7 +9,7 @@ Memory Pools
in current Zephyr code. It still exists for applications which in current Zephyr code. It still exists for applications which
require the specific memory allocation and alignment patterns require the specific memory allocation and alignment patterns
detailed below, but the default heap implementation (including the 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 allocator, which is a better choice for general purpose
code. code.
@ -119,7 +119,7 @@ Implementation
Defining a Memory Pool 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 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, 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. the kernel does not support the runtime definition of a memory pool.

View file

@ -68,7 +68,7 @@ Using k_poll()
============== ==============
The main API is :c:func:`k_poll`, which operates on an array of poll events The main API is :c:func:`k_poll`, which operates on an array of poll events
of type :c:type:`k_poll_event`. Each entry in the array represents one of type :c: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 event a call to :c:func:`k_poll` will wait for its condition to be
fulfilled. 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 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 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 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. ignored, most likely temporarily, its type can be set to K_POLL_TYPE_IGNORE.
.. code-block:: c .. 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 signal to a poll event. This can be seen as a lightweight binary semaphore only
one thread can wait for. 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 must be attached to a k_poll_event, similar to a semaphore or FIFO. It must
first be initialized either via :c:macro:`K_POLL_SIGNAL_INITIALIZER()` or first be initialized either via :c:macro:`K_POLL_SIGNAL_INITIALIZER()` or
:c:func:`k_poll_signal_init`. :c:func:`k_poll_signal_init`.

View file

@ -93,7 +93,7 @@ Implementation
Defining a Mutex 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`. It must then be initialized by calling :c:func:`k_mutex_init`.
The following code defines and initializes a mutex. The following code defines and initializes a mutex.

View file

@ -47,7 +47,7 @@ Implementation
Defining a Semaphore 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`. It must then be initialized by calling :c:func:`k_sem_init`.
The following code defines a semaphore, then configures it as a binary The following code defines a semaphore, then configures it as a binary

View file

@ -24,7 +24,7 @@ A thread has the following key properties:
stack memory regions. stack memory regions.
* A **thread control block** for private kernel bookkeeping of the thread's * 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. * An **entry point function**, which is invoked when the thread is started.
Up to 3 **argument values** can be passed to this function. Up to 3 **argument values** can be passed to this function.

View file

@ -179,7 +179,7 @@ Implementation
Defining a Workqueue 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 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 and then calling :c:func:`k_work_q_start`. The stack area must be defined
using :c:macro:`K_THREAD_STACK_DEFINE` to ensure it is properly set up in using :c:macro:`K_THREAD_STACK_DEFINE` to ensure it is properly set up in
@ -202,7 +202,7 @@ The following code defines and initializes a workqueue.
Submitting a Work Item 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`. It must then be initialized by calling :c:func:`k_work_init`.
An initialized work item can be submitted to the system workqueue by An initialized work item can be submitted to the system workqueue by
@ -250,7 +250,7 @@ Submitting a Delayed Work Item
============================== ==============================
A delayed work item is defined using a variable of type A delayed work item is defined using a variable of type
:c:type:`k_delayed_work`. It must then be initialized by calling :c:struct:`k_delayed_work`. It must then be initialized by calling
:c:func:`k_delayed_work_init`. :c:func:`k_delayed_work_init`.
An initialized delayed work item can be submitted to the system workqueue by An initialized delayed work item can be submitted to the system workqueue by

View file

@ -90,8 +90,8 @@ For example:
:c:func:`k_queue_get` may provide a timeout after which the :c:func:`k_queue_get` may provide a timeout after which the
routine will return with an error code if no data is available. routine will return with an error code if no data is available.
* Kernel ``struct k_timer`` objects must specify delays for their * Kernel :c:struct:`k_timer` objects must specify delays for
duration and period. their duration and period.
* The kernel ``k_delayed_work`` API provides a timeout parameter * The kernel ``k_delayed_work`` API provides a timeout parameter
indicating when a work queue item will be added to the system queue. 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 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 previous event. The action to take on an event is specified as a
callback function pointer provided by the subsystem requesting the 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 expected to be embedded within subsystem-defined data structures (for
example: a ``struct wait_q``, or a ``k_tid_t`` thread struct). example: a ``struct wait_q``, or a ``k_tid_t`` thread struct).

View file

@ -103,7 +103,7 @@ Implementation
Defining a Timer 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`. It must then be initialized by calling :c:func:`k_timer_init`.
The following code defines and initializes a timer. The following code defines and initializes a timer.

View file

@ -21,7 +21,7 @@ API.
A limitation is that this API is not suitable for :ref:`syscalls` A limitation is that this API is not suitable for :ref:`syscalls`
because: 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 * copying the notification content from userspace will break use of
:c:macro:`CONTAINER_OF` in the implementing function; :c:macro:`CONTAINER_OF` in the implementing function;
* neither the spin-wait nor callback notification methods can be * 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 Where a notification is required for an asynchronous operation invoked
from a user mode thread the subsystem or driver should provide a syscall 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 API Reference
************* *************

View file

@ -247,7 +247,7 @@ Sample usage
************ ************
To use the LwM2M library, start by creating an LwM2M client context 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 .. code-block:: c

View file

@ -12,12 +12,12 @@ Overview
The L2 stack is designed to hide the whole networking link-layer part 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 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`. :zephyr_file:`include/net/net_if.h`.
The upper layers are unaware of implementation details beyond the net_if The upper layers are unaware of implementation details beyond the net_if
object and the generic API provided by the L2 layer in 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 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, 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: 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. pointer.
- The network device driver must use ``NET_DEVICE_INIT_INSTANCE()`` - The network device driver must use ``NET_DEVICE_INIT_INSTANCE()``
or ``ETH_NET_DEVICE_INIT()`` for Ethernet devices. These or ``ETH_NET_DEVICE_INIT()`` for Ethernet devices. These
macros will call the ``DEVICE_AND_API_INIT()`` macro, and also 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. device driver instance.
Implementing a network device driver depends on the L2 stack it 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 Ethernet. What has been described above, especially for ``recv()``, applies
here as well. There are two specific differences however: here as well. There are two specific differences however:
- It requires a dedicated device driver API: :c:type:`ieee802154_radio_api`, - It requires a dedicated device driver API: :c:struct:`ieee802154_radio_api`,
which overloads :c:type:`net_if_api`. This is because 802.15.4 L2 needs more from the device 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 driver than just ``send()`` and ``recv()`` functions. This dedicated API is
declared in :zephyr_file:`include/net/ieee802154_radio.h`. Each and every 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 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 frame size limitation. But a buffer containing an IPv6/UDP packet
might have more than one fragment. IEEE 802.15.4 drivers might have more than one fragment. IEEE 802.15.4 drivers
handle only one buffer at a time. This is why the handle only one buffer at a time. This is why the
:c:type:`ieee802154_radio_api` requires a tx function pointer which differs :c:struct:`ieee802154_radio_api` requires a tx function pointer which differs
from the :c:type:`net_if_api` send function pointer. from the :c:struct:`net_if_api` send function pointer.
Instead, the IEEE 802.15.4 L2, provides a generic Instead, the IEEE 802.15.4 L2, provides a generic
:c:func:`ieee802154_radio_send` meant to be given as :c:func:`ieee802154_radio_send` meant to be given as
:c:type:`net_if` send function. It turn, the implementation :c:type:`net_if` send function. It turn, the implementation

View file

@ -74,7 +74,7 @@ Buffer allocation
================= =================
The net_pkt object does not define its own buffer, but instead uses an 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 :ref:`net_buf_interface` for more information). However, it mostly
hides the usage of such a buffer because net_pkt brings network hides the usage of such a buffer because net_pkt brings network
awareness to buffer allocation and, as we will see later, its awareness to buffer allocation and, as we will see later, its

View file

@ -29,7 +29,7 @@ description and units of measurement:
Values 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 representation avoids use of floating point values as they may not be
supported on certain setups. 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 Then, individual channels may be read. In the case of channels with
multiple axes, they can be read in a single operation by supplying multiple axes, they can be read in a single operation by supplying
the corresponding :literal:`_XYZ` channel type and a buffer of 3 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 of channels between reads and efficiency of communication by issuing a
single transaction on the underlying bus. single transaction on the underlying bus.
@ -55,7 +55,7 @@ compensates data for both channels.
:lines: 12- :lines: 12-
:linenos: :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 which is the case for BME280. A real application
supporting multiple sensors should inspect the :c:data:`type` field of 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 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. threshold, or the device has sensed motion.
To configure a trigger, an application needs to supply a 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. 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 Because most sensors are connected via SPI or I2C busses, it is not possible

View file

@ -6,7 +6,7 @@ Kernel Objects
A kernel object can be one of three classes of data: A kernel object can be one of three classes of data:
* A core kernel object, such as a semaphore, thread, pipe, etc. * 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()` and declared with :c:macro:`K_THREAD_STACK_DEFINE()`
* A device driver instance (struct device) that belongs to one of a defined * A device driver instance (struct device) that belongs to one of a defined
set of subsystems 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 of what may or may not be a valid kernel object, the address can be validated
with a constant-time lookup in this table. 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 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 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 be prevented. When a device struct is found, its API pointer is examined to
determine what subsystem the driver belongs to. determine what subsystem the driver belongs to.
The table itself maps kernel object memory addresses to instances of 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: includes:
* A bitfield indicating permissions on that object. All threads have a * 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 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. what API struct they are set to.
* In ``scripts/gen_kobject_list.py``, add the name of the API struct for the * In ``scripts/gen_kobject_list.py``, add the name of the API struct for the

View file

@ -333,7 +333,7 @@ Create a Memory Domain
---------------------- ----------------------
A memory domain is defined using a variable of type A memory domain is defined using a variable of type
:c:type:`k_mem_domain`. It must then be initialized by calling :c:struct:`k_mem_domain`. It must then be initialized by calling
:c:func:`k_mem_domain_init`. :c:func:`k_mem_domain_init`.
The following code defines and initializes an empty memory domain. The following code defines and initializes an empty memory domain.