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:
parent
53fd5ff236
commit
c79d2ce794
29 changed files with 63 additions and 63 deletions
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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`.
|
||||||
|
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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.
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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`.
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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`.
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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).
|
||||||
|
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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
|
||||||
*************
|
*************
|
||||||
|
|
|
@ -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
|
||||||
|
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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.
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue