Note Driver Interface¶

Note driver is the interface to access the instrumentation data. The following devices are provided.

Notectl Device (/dev/notectl)
Noteram Device (/dev/note)

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¶

struct note_filter_mode_s¶

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.

NOTE_FILTER_MODE_FLAG_ENABLE¶

Enable instrumentation

NOTE_FILTER_MODE_FLAG_SYSCALL¶

Enable syscall instrumentation

NOTE_FILTER_MODE_FLAG_IRQ¶

Enable IRQ instrumentaiton
cpuset : (SMP only) Monitor only CPUs in the bitset. Bit 0=CPU0, Bit1=CPU1, etc.

struct note_filter_syscall_s¶

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:

NOTE_FILTER_SYSCALLMASK_SET(nr, s)¶

Set syscall number nr as masked. s specifies the variable of struct note_filter_syscall_s

NOTE_FILTER_SYSCALLMASK_CLR(nr, s)¶

Set syscall number nr as unmasked.

NOTE_FILTER_SYSCALLMASK_ISSET(nr, s)¶

Check whether syscall number nr is masked or not. True if masked.

NOTE_FILTER_SYSCALLMASK_ZERO(s)¶

Clear all masks.

struct note_filter_irq_s¶

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:

NOTE_FILTER_IRQMASK_SET(nr, s)¶

Set IRQ number nr as masked. s specifies the variable of struct note_filter_irq_s

NOTE_FILTER_IRQMASK_CLR(nr, s)¶

Set IRQ number nr as unmasked.

NOTE_FILTER_IRQMASK_ISSET(nr, s)¶

Check whether IRQ number nr is masked or not. True if masked.

NOTE_FILTER_IRQMASK_ZERO(s)¶

Clear all masks.

`/dev/notectl` Ioctls¶

NOTECTL_GETMODE¶

Get note filter mode

Argument: A writable pointer to note_filter_mode_s
Returns: If success, 0 (OK) is returned and current note filter mode is stored into the given pointer. If failed, a negated errno is returned.

NOTECTL_SETMODE¶

Set note filter mode

Argument: A read-only pointer to note_filter_mode_s
Returns: If success, 0 (OK) is returned and the given filter mode is set as the current settings. If failed, a negated errno is returned.

NOTECTL_GETSYSCALLFILTER¶

Get syscall filter setting

Argument: A writable pointer to note_filter_syscall_s
Returns: If success, 0 (OK) is returned and current syscall filter mode is stored into the given pointer. If failed, a negated errno is returned.

NOTECTL_SETSYSCALLFILTER¶

Set syscall filter setting

Argument: A read-only pointer to note_filter_syscall_s
Returns: 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.

NOTECTL_GETIRQFILTER¶

Get IRQ filter setting

Argument: A writable pointer to note_filter_irq_s
Returns: If success, 0 (OK) is returned and current IRQ filter mode is stored into the given pointer. If failed, a negated errno is returned.

NOTECTL_SETIRQFILTER¶

Set IRQ filter setting

Argument: A read-only pointer to note_filter_irq_s
Returns: 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 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¶

struct noteram_get_taskname_s¶

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¶

NOTERAM_CLEAR¶

Clear all contents of the circular buffer

Argument: Ignored
Returns: Always returns 0.

NOTERAM_GETMODE¶

Get overwrite mode

Argument

A writable pointer to unsigned int. The overwrite mode takes one of the following values.

NOTERAM_MODE_OVERWRITE_DISABLE¶: Overwrite mode is disabled. When the buffer is full, accepting the data will be stopped.

NOTERAM_MODE_OVERWRITE_ENABLE¶: Overwrite mode is enabled.

NOTERAM_MODE_OVERWRITE_OVERFLOW¶: Overwrite mode is disabled and the buffer is already full.

Returns

If success, 0 (OK) is returned and current overwrite mode is stored into the given pointer. If failed, a negated errno is returned.

NOTERAM_SETMODE¶

Set overwrite mode

Argument: A read-only pointer to unsigned int.
Returns: If success, 0 (OK) is returned and the given overwriter mode is set as the current settings. If failed, a negated errno is returned.

NOTERAM_GETTASKNAME¶

Get task name string

Argument: A writable pointer to noteram_get_taskname_s
Returns: If success, 0 (OK) is returned and the task name corresponding to given pid is stored into the given pointer. 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¶

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 NOTECTL_GETMODE / NOTECTL_SETMODE ioctls)

Parameters

oldm – A writable pointer to note_filter_mode_s to get current filter mode. If 0, no data is written.
newm – A read-only pointer to note_filter_mode_s which holds the new filter mode. If 0, the filter mode is not updated.

Returns

None

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 NOTECTL_GETSYSCALLFILTER / NOTECTL_SETSYSCALLFILTER ioctls)

Parameters

oldf – A writable pointer to note_filter_syscall_s to get current syscall filter setting. If 0, no data is written.
newf – A read-only pointer to note_filter_syscall_s of the new syscall filter setting. If 0, the setting is not updated.

Returns

None

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 NOTECTL_GETIRQFILTER / NOTECTL_SETIRQFILTER ioctls)

Parameters

oldf – A writable pointer to note_filter_irq_s to get current IRQ filter setting. If 0, no data is written.
newf – A read-only pointer to note_filter_irq_s of the new IRQ filter setting. If 0, the setting is not updated.

Returns

None

Note Driver Interface¶

Notectl Device (/dev/notectl)¶

/dev/notectl Header Files¶

/dev/notectl Data Structures¶

/dev/notectl Ioctls¶

Noteram Device (/dev/note)¶

/dev/note Header Files¶

/dev/note Data Structures¶

/dev/note Ioctls¶

Filter control APIs¶

API description¶

Notectl Device (`/dev/notectl`)¶

`/dev/notectl` Header Files¶

`/dev/notectl` Data Structures¶

`/dev/notectl` Ioctls¶

Noteram Device (`/dev/note`)¶

`/dev/note` Header Files¶

`/dev/note` Data Structures¶

`/dev/note` Ioctls¶