Note Driver Interface

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

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.

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