mirror of
https://github.com/apache/nuttx.git
synced 2026-05-29 04:19:37 +08:00
Add documentation for note filters and task trace guides
This commit is contained in:
Nakamura, Yuuichi
committed by
Xiang Xiao
Xiang Xiao
parent
cafe24528c
commit
1472a913a9
@@ -23,3 +23,4 @@ in other header files.
|
||||
paging.rst
|
||||
led.rst
|
||||
iob.rst
|
||||
note.rst
|
||||
|
||||
@@ -0,0 +1,270 @@
|
||||
=====================
|
||||
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 instrumentaiton
|
||||
|
||||
- ``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`` 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.
|
||||
|
||||
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 New Issue
Block a user