doc: kernel: fix improper Sphinx C domain usage

pointers per node, and thus has somewhat higher runtime code and

memory space needs.

A :c:struct:`sys_dlist_t` struct may be instantiated by the user in any

A :c:type:`sys_dlist_t` struct may be instantiated by the user in any

accessible memory.  It must be initialized with :c:func:`sys_dlist_init`

or :c:macro:`SYS_DLIST_STATIC_INIT` before use.  The :c:struct:`sys_dnode_t` struct

or :c:macro:`SYS_DLIST_STATIC_INIT` before use.  The :c:type:`sys_dnode_t` struct

is expected to be provided by the user for any nodes added to the

list (typically embedded within the struct to be tracked, as described

above).  It must be initialized in zeroed/bss memory or with

Double-linked List Internals

----------------------------

Internally, the dlist implementation is minimal: the :c:struct:`sys_dlist_t`

struct contains "head" and "tail" pointer fields, the :c:struct:`sys_dnode_t`

Internally, the dlist implementation is minimal: the :c:type:`sys_dlist_t`

struct contains "head" and "tail" pointer fields, the :c:type:`sys_dnode_t`

contains "prev" and "next" pointers, and no other data is stored.  But

in practice the two structs are internally identical, and the list

struct is inserted as a node into the list itself.  This allows for a

Defining a Ring Buffer

======================

A ring buffer is defined using a variable of type :c:type:`ring_buf`.

A ring buffer is defined using a variable of type :c:struct:`ring_buf`.

It must then be initialized by calling :c:func:`ring_buf_init` or

:c:func:`ring_buf_item_init`.

Single-linked List

==================

Zephyr provides a :c:struct:`sys_slist_t` type for storing simple

Zephyr provides a :c:type:`sys_slist_t` type for storing simple

singly-linked list data (i.e. data where each list element stores a

pointer to the next element, but not the previous one).  This supports

constant-time access to the first (head) and last (tail) elements of

requires access to the "previous" pointer and thus can only be

performed in linear time by searching the list.

The :c:struct:`sys_slist_t` struct may be instantiated by the user in any

The :c:type:`sys_slist_t` struct may be instantiated by the user in any

accessible memory.  It should be initialized with either

:c:func:`sys_slist_init` or by static assignment from SYS_SLIST_STATIC_INIT

before use.  Its interior fields are opaque and should not be accessed

The end nodes of a list may be retrieved with

:c:func:`sys_slist_peek_head` and :c:func:`sys_slist_peek_tail`, which will

return NULL if the list is empty, otherwise a pointer to a

:c:struct:`sys_snode_t` struct.

:c:type:`sys_snode_t` struct.

The :c:struct:`sys_snode_t` struct represents the data to be inserted.  In

The :c:type:`sys_snode_t` struct represents the data to be inserted.  In

general, it is expected to be allocated/controlled by the user,

usually embedded within a struct which is to be added to the list.

The container struct pointer may be retrieved from a list node using

:c:macro:`SYS_SLIST_CONTAINER`, passing it the struct name of the

containing struct and the field name of the node.  Internally, the

:c:struct:`sys_snode_t` struct contains only a next pointer, which may be

:c:type:`sys_snode_t` struct contains only a next pointer, which may be

accessed with :c:func:`sys_slist_peek_next`.

Lists may be modified by adding a single node at the head or tail with

----------------------------

The slist code is designed to be minimal and conventional.

Internally, a :c:struct:`sys_slist_t` struct is nothing more than a pair of

"head" and "tail" pointer fields.  And a :c:struct:`sys_snode_t` stores only a

Internally, a :c:type:`sys_slist_t` struct is nothing more than a pair of

"head" and "tail" pointer fields.  And a :c:type:`sys_snode_t` stores only a

single "next" pointer.

.. figure:: slist.png

Flagged List

------------

The :c:struct:`sys_sflist_t` is implemented using the described genlist

The :c:type:`sys_sflist_t` is implemented using the described genlist

template API.  With the exception of symbol naming ("sflist" instead

of "slist") and the additional API described next, it operates in all

ways identically to the slist API.

   the pool with :c:func:`shared_multi_heap_add()`, possibly gathering the

   needed information for the regions from the DT.

2. Each memory region encoded in a :c:type:`shared_multi_heap_region`

2. Each memory region encoded in a :c:struct:`shared_multi_heap_region`

   structure.  This structure is also carrying an opaque and user-defined

   integer value that is used to define the region capabilities (for example:

   cacheability, cpu affinity, etc...)

*********************

The API does not enforce any attributes, but at least it defines the two most

common ones: :c:enum:`SMH_REG_ATTR_CACHEABLE` and :c:enum:`SMH_REG_ATTR_NON_CACHEABLE`

common ones: :c:enumerator:`SMH_REG_ATTR_CACHEABLE` and :c:enumerator:`SMH_REG_ATTR_NON_CACHEABLE`.

.. doxygengroup:: shared_multi_heap

   :project: Zephyr

:c:macro:`K_POLL_EVENT_INITIALIZER()` or :c:func:`k_poll_event_init`, or

the static initializer :c:macro:`K_POLL_EVENT_STATIC_INITIALIZER()`. An object

that matches the **type** specified must be passed to the initializers. The

**mode** *must* be set to :c:macro:`K_POLL_MODE_NOTIFY_ONLY`. The state *must*

be set to :c:macro:`K_POLL_STATE_NOT_READY` (the initializers take care of

this). The user **tag** is optional and completely opaque to the API: it is

**mode** *must* be set to :c:enumerator:`K_POLL_MODE_NOTIFY_ONLY`. The state

*must* be set to :c:macro:`K_POLL_STATE_NOT_READY` (the initializers take care

of 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: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

:c:macro:`K_POLL_TYPE_IGNORE`.

.. code-block:: c