Aksal/nuttx
3
1
Fork 1
mirror of https://github.com/apache/nuttx.git synced 2026-10-08 14:55:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
nuttx/Documentation/os/drivers/character/note.rst
Vinicius May f6ecf80ebb Documentation: brand new layout for NuttX documentation. 
The documentation grew one page at a time, so the tree follows the
history of who wrote what and not the shape of NuttX. Scheduling is
spread over three places, a driver page can sit above the subsystem
that owns it, and the front page lists everything at the same level.
That is a lot to face when all you want to know is where the scheduler
lives.

This change files every page under the code it describes. It is a move,
not a rewrite: outside the ten pages named below, every page keeps the
text that is already in master, and no page's text is deleted.

What it does:

* Groups the table of contents into nine chapters.
* Moves the OS subsystems under os/: scheduling, memory, drivers,
  filesystem, networking, IPC, interrupts, libs, time.
* Renames the platform pages to the names the source tree uses, and
  derives their tags from the tree instead of by hand.
* Splits guides/ by subject.
* Adds Documentation/redirects.py, with a rule for every page that left
  its old path, so old URLs keep working. The redirect page also carries
  a link's #anchor across to the new page.

Ten pages have text that is new or rewritten. Nine of them are the
landing page of a chapter, which has to exist for the new structure:

    index                  the front page
    os/index               OS Design
    os/scheduling/index    Scheduling
    os/interrupts/index    Interrupts
    os/ipc/index           IPC
    os/time/index          Time and timers
    about/index            About
    developing/index       Developing NuttX
    ReleaseNotes/index     Release notes

The tenth is os/libs/libbuiltin, the only page here with technical
content: libs/libbuiltin/ had no page at all. Five SVG diagrams come
with these pages, hand-written XML with no editor metadata.

Nothing outside Documentation/ is touched.

How it was checked:

* Sphinx builds with -W: no warnings, and no document left outside a
  toctree.
* A script, offered in the PR, proves the narrow claim this rests on.
  For every page outside the ten named above it erases what a move
  touches -- link target, path, tag line, toctree block, table border --
  from the whole old text and the whole new text, and requires the two
  to be byte for byte identical. It also requires every sentence of a
  deleted page to turn up somewhere, and every page that left its old
  path to have a redirect, from a URL that existed, to where its content
  went. It exits non-zero and names the page if any of that is not true,
  and it tests added pages too, so forgetting to declare one cannot make
  it pass.
* An independent audit checked 133 factual claims on these ten pages
  against the tree, one shell command per claim: 130 confirmed, 1
  refuted and fixed here, 2 not checkable.
* tools/checkpatch.sh is clean over the range.

The diff is large because moving a page changes every link that points
to it. Most of it is pure renames, and board pages that gained one tag
line.

Assisted-by: Claude:claude-opus-5
2026-10-08 01:40:54 +08:00

302 lines
8.8 KiB
ReStructuredText
Raw Blame History

=====================
Note Driver Interface
=====================
Note driver is the interface to access the instrumentation data.
The following devices are provided.
- :ref:`notectl`
- :ref:`noteram`
.. _notectl:
Notectl Device (``/dev/notectl``)
=================================
``/dev/notectl`` is the device to control an instrumentation filter in NuttX kernel.
The device has only ioctl function to control the filter.
``/dev/notectl`` Header Files
-----------------------------
The header file ``include/nuttx/note/notectl_driver.h`` provides the interface definitions of the device.
``/dev/notectl`` Data Structures
--------------------------------
.. c:struct:: note_filter_mode_s
.. code-block:: c
struct note_filter_mode_s
{
unsigned int flag; /* Filter mode flag */
#ifdef CONFIG_SMP
unsigned int cpuset; /* The set of monitored CPUs */
#endif
};
- ``flag`` : Filter mode flag. The bitwise OR of the following defines are available.
.. c:macro:: NOTE_FILTER_MODE_FLAG_ENABLE
Enable instrumentation
.. c:macro:: NOTE_FILTER_MODE_FLAG_SYSCALL
Enable syscall instrumentation
.. c:macro:: NOTE_FILTER_MODE_FLAG_IRQ
Enable IRQ instrumentation
- ``cpuset`` : (SMP only) Monitor only CPUs in the bitset. Bit 0=CPU0, Bit1=CPU1, etc.
.. c:struct:: note_filter_syscall_s
.. code-block:: c
struct note_filter_syscall_s
{
uint8_t syscall_mask[];
};
- ``syscall_mask`` : A bitmap array of the syscall filter. If a bit is set, the corresponding syscall is not recorded.
The following helper macros are available:
.. c:macro:: NOTE_FILTER_SYSCALLMASK_SET(nr, s)
Set syscall number `nr` as masked. `s` specifies the variable of `struct note_filter_syscall_s`
.. c:macro:: NOTE_FILTER_SYSCALLMASK_CLR(nr, s)
Set syscall number `nr` as unmasked.
.. c:macro:: NOTE_FILTER_SYSCALLMASK_ISSET(nr, s)
Check whether syscall number `nr` is masked or not. True if masked.
.. c:macro:: NOTE_FILTER_SYSCALLMASK_ZERO(s)
Clear all masks.
.. c:struct:: note_filter_irq_s
.. code-block:: c
struct note_filter_irq_s
{
uint8_t irq_mask[];
};
- ``irq_mask`` : A bitmap array of the IRQ filter. If a bit is set, the corresponding IRQ is not recorded.
The following helper macros are available:
.. c:macro:: NOTE_FILTER_IRQMASK_SET(nr, s)
Set IRQ number `nr` as masked. `s` specifies the variable of `struct note_filter_irq_s`
.. c:macro:: NOTE_FILTER_IRQMASK_CLR(nr, s)
Set IRQ number `nr` as unmasked.
.. c:macro:: NOTE_FILTER_IRQMASK_ISSET(nr, s)
Check whether IRQ number `nr` is masked or not. True if masked.
.. c:macro:: NOTE_FILTER_IRQMASK_ZERO(s)
Clear all masks.
``/dev/notectl`` Ioctls
-----------------------
.. c:macro:: NOTECTL_GETMODE
Get note filter mode
:argument: A writable pointer to :c:struct:`note_filter_mode_s`
:return: If success, 0 (``OK``) is returned and current note filter mode is stored into the given pointer.
If failed, a negated ``errno`` is returned.
.. c:macro:: NOTECTL_SETMODE
Set note filter mode
:argument: A read-only pointer to :c:struct:`note_filter_mode_s`
:return: If success, 0 (``OK``) is returned and the given filter mode is set as the current settings.
If failed, a negated ``errno`` is returned.
.. c:macro:: NOTECTL_GETSYSCALLFILTER
Get syscall filter setting
:argument: A writable pointer to :c:struct:`note_filter_syscall_s`
:return: If success, 0 (``OK``) is returned and current syscall filter mode is stored into the given pointer.
If failed, a negated ``errno`` is returned.
.. c:macro:: NOTECTL_SETSYSCALLFILTER
Set syscall filter setting
:argument: A read-only pointer to :c:struct:`note_filter_syscall_s`
:return: If success, 0 (``OK``) is returned and the given syscall filter mode is set as the current settings.
If failed, a negated ``errno`` is returned.
.. c:macro:: NOTECTL_GETIRQFILTER
Get IRQ filter setting
:argument: A writable pointer to :c:struct:`note_filter_irq_s`
:return: If success, 0 (``OK``) is returned and current IRQ filter mode is stored into the given pointer.
If failed, a negated ``errno`` is returned.
.. c:macro:: NOTECTL_SETIRQFILTER
Set IRQ filter setting
:argument: A read-only pointer to :c:struct:`note_filter_irq_s`
:return: If success, 0 (``OK``) is returned and the given IRQ filter mode is set as the current settings.
If failed, a negated ``errno`` is returned.
.. _noteram:
Noteram Device (``/dev/note``)
==============================
``/dev/note`` is the device to get the trace (instrumentation) data.
The device has read function to get the data and ioctl function to control the buffer mode.
``/dev/note`` Header Files
--------------------------
The header file ``include/nuttx/note/noteram_driver.h`` provides the interface definitions of the device.
``/dev/note`` Data Structures
--------------------------------
.. c:struct:: noteram_get_taskname_s
.. code-block:: c
struct noteram_get_taskname_s
{
pid_t pid;
char taskname[CONFIG_TASK_NAME_SIZE + 1];
};
- ``pid`` : Task ID to get the task name.
- ``taskname`` : The task name string corresponding to given pid.
``/dev/note`` Ioctls
--------------------
.. c:macro:: NOTERAM_CLEAR
Clear all contents of the circular buffer
:argument: Ignored
:return: Always returns 0.
.. c:macro:: NOTERAM_GETMODE
Get overwrite mode
:argument: A writable pointer to ``unsigned int``.
The overwrite mode takes one of the following values.
.. c:macro:: NOTERAM_MODE_OVERWRITE_DISABLE
Overwrite mode is disabled. When the buffer is full, accepting the data will be stopped.
.. c:macro:: NOTERAM_MODE_OVERWRITE_ENABLE
Overwrite mode is enabled.
.. c:macro:: NOTERAM_MODE_OVERWRITE_OVERFLOW
Overwrite mode is disabled and the buffer is already full.
:return: If success, 0 (``OK``) is returned and current overwrite mode is stored into the given pointer.
If failed, a negated ``errno`` is returned.
.. c:macro:: NOTERAM_SETMODE
Set overwrite mode
:argument: A read-only pointer to ``unsigned int``.
:return: If success, 0 (``OK``) is returned and the given overwriter mode is set as the current settings.
If failed, a negated ``errno`` is returned.
.. c:macro:: FIONREAD
Get the number of unread bytes in the buffer
:argument: A writable pointer to ``unsigned int`` to receive the number of unread bytes.
:return: If success, 0 (``OK``) is returned and the number of unread bytes is stored into the given pointer.
If failed, a negated ``errno`` is returned.
.. c:macro:: PIPEIOC_POLLINTHRD
Set the poll threshold for POLLIN event
:argument: An unsigned int value specifying the threshold in bytes. When the unread data in the buffer is greater than or equal to this value, POLLIN will be notified.
:return: If success, 0 (``OK``) is returned and the threshold is set. If failed, a negated ``errno`` is returned.
Filter control APIs
===================
The following APIs are the functions to control note filters directly.
These are kernel APIs and application can use them only in FLAT build.
The header file ``include/nuttx/sched_note.h`` is needed to use the following APIs.
API description
---------------
.. c:function:: void sched_note_filter_mode(struct note_filter_mode_s *oldm, struct note_filter_mode_s *newm);
Set and get note filter mode.
(Same as :c:macro:`NOTECTL_GETMODE` / :c:macro:`NOTECTL_SETMODE` ioctls)
:param oldm: A writable pointer to :c:struct:`note_filter_mode_s` to get current filter mode.
If 0, no data is written.
:param newm: A read-only pointer to :c:struct:`note_filter_mode_s` which holds the new filter mode.
If 0, the filter mode is not updated.
:return: None
.. c:function:: void sched_note_filter_syscall(struct note_filter_syscall_s *oldf, struct note_filter_syscall_s *newf);
Set and get syscall filter setting.
(Same as :c:macro:`NOTECTL_GETSYSCALLFILTER` / :c:macro:`NOTECTL_SETSYSCALLFILTER` ioctls)
:param oldf: A writable pointer to :c:struct:`note_filter_syscall_s` to get current syscall filter setting.
If 0, no data is written.
:param newf: A read-only pointer to :c:struct:`note_filter_syscall_s` of the new syscall filter setting.
If 0, the setting is not updated.
:return: None
.. c:function:: void sched_note_filter_irq(struct note_filter_irq_s *oldf, struct note_filter_irq_s *newf);
Set and get IRQ filter setting.
(Same as :c:macro:`NOTECTL_GETIRQFILTER` / :c:macro:`NOTECTL_SETIRQFILTER` ioctls)
:param oldf: A writable pointer to :c:struct:`note_filter_irq_s` to get current IRQ filter setting.
If 0, no data is written.
:param newf: A read-only pointer to :c:struct:`note_filter_irq_s` of the new IRQ filter setting.
If 0, the setting is not updated.
:return: None
Reference in a new issue View git blame Copy permalink