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