QNX Technical Articles

Date of this edition: May 27, 2021

QNX SDP is a cross-compiling and debugging environment, including an IDE and command-line tools, for building binary images and programs for ARM v7 and v8, and x86 and x86_64 targets running the QNX Neutrino RTOS 7.1. You can install QNX SDP on the following development hosts:

• Microsoft Windows 10 Pro 64-bit, or Windows 8.1 Pro 64-bit
• macOS version 10.14 or 10.15
• Linux Red Hat Enterprise Linux 7 64-bit, or Ubuntu Desktop 18.04 LTS 64-bit, on x86_64 processors (QNX SDP isn't supported on Linux on ARM processors)

Contents

• What's in this update?
• Updates and fixed issues
• Known issues
• Getting started with the documentation
• Technical support

Throughout this document, you may see reference numbers associated with particular issues, changes, etc. When corresponding with our Technical Support staff about a given issue, please quote the relevant reference number. You might also find the reference numbers useful for tracking issues as they become fixed.

What's in this update?

This update includes the following packages, which you'll find under Updates -> QNX Software Development Platform -> Documentation in the Software Center:

To see a list of the contents of a package, right-click it in the QNX Software Center, choose Properties, and then click Package Contents in the Properties window.

Updates and fixed issues

This package includes updates, including enhancements, fixed issues, and clarifications, to the following QNX SDP documents:

• OS Core Components:
  • Building Embedded Systems
  • Customizing a BSP
  • Device Publishers Developer's Guide
  • Migrating to QNX SDP 7.1
  • QDB Developer's Guide
  • SMMUMAN User's Guide
  • System Architecture
• Audio & Graphics:
  • Screen Graphics Subsystem Developer's Guide
  • Video Capture Developer's Guide
• Programming:
  • PCI Server User's Guide
  • QNX Neutrino Programmer's Guide
  • Writing a Resource Manager
• Sensor Framework:
  • Getting Started
• System Security Guide
• Utilities & Libraries:
  • C Library Reference
  • Devctl and Ioctl Commands
  • Utilities Reference

OS Core Components

Building Embedded Systems

• We've corrected the paths for BSP buildfiles.
• We've updated the link to the online BSP documentation.
• We've corrected the path for <sys/syspage.h>.
• We no longer enable the workaround for the Qualcomm Technologies Falkor/Kryo erratum 1003 or the Qualcomm Falkor errata 1009 for Kryo on all Qualcomm chips. If you need to use the workaround, you must now set the AARCH64_CPU_FLAG_KRYO_TLB flag by specifying the -F0x40000 option for the startup.
• We've documented the timer_load_hi, timer_load_max, and timer_prog_time members of the qtime area of the system page.
• We've added a section about LL/SC vs LSE atomic operations to the description of the cpuinfo area of the system page.
• The generic CPU flags (stored in the flags member of the cpuinfo area of the system page) are defined in <sys/syspage.h>, while architecture-specific flags are defined in <arch/syspage.h>. You'll need the values to interpret the output of the pidin syspage command.
• We've corrected the information about the default user ID and group ID for inline files in mkifs buildfiles.
• We've revised the section on using environment variables in an OS image buildfile.
• You can't set the ownership and permissions for implicitly created directories in an OS image buildfile.

Customizing a BSP

• We've corrected the paths for BSP buildfiles.

Device Publishers Developer's Guide

• The aoa member of the device information object holds the version of the Android Open Accessory (AOA) protocol supported by the device, either 1 or 2.
• We've documented the following for the USB launcher server:
  • the device_release, PPS_HUB_ID, and USB_version fields for the device information object
  • the label_raw_string and label_raw_data field for the mount object
• We've added more details about the mount field of the mount object.

Migrating to QNX SDP 7.1

• Note that the vivante blitter is now called nxp-g2d.

QDB Developer's Guide

• We've added more details about the /dev/qdb/customerdb file.

SMMUMAN User's Guide

• We've corrected the sample buildfile for the ARM Renesas R-Car H3 for a safety-related system.

System Architecture

• We've added the QNX Trusted Disk (QTD) to the table of partition types.
• The Power-Safe (fs-qnx6.so) filesystem can be used on any device that supports the listed properties, not just on traditional rotating hard disk drive media.
• You should disable interrupts for as little time as possible (i.e., the minimum time you need to access or deal with the hardware). Failure to do so may result in increased interrupt latency and the inability to meet realtime deadlines.

  Some kernel calls and library routines reenable interrupts. Masked interrupts aren't affected.

Audio & Graphics

Screen Graphics Subsystem Developer's Guide

• If you want to process the graphics.config file, you need to specify the -c option when you start Screen.
• We've added a section on setting the scaling for mtouch.
• We've corrected the description of the count and read_rects arguments for screen_read_display().
• We've updated the description of calib-touch.
• We've added background-alpha to the display parameters in the Configuring Screen chapter.
• We've updated the description of vcapture-demo to reflect some recent changes to the code.
• The maximum value of SCREEN_PROPERTY_SCALE_FACTOR is 30.

Video Capture Developer's Guide

• We've added the new CAPTURE_PROPERTY_DEBUG_ENABLE capture property to the Debugging section of the Video Capture API (capture.h) chapter.

Programming

PCI Server User's Guide

• You can't set the PCI_DEBUG_MODULE environment variable in the configuration file; set it on the command line before or when you start the PCI server.

QNX Neutrino Programmer's Guide

• We've corrected an example in Detecting dumped processes that uses PATH_MAX; its value includes space for a terminating NUL character, so there's no need to add one to it.
• We've corrected a #define statement in the example in the Conforming to standards section of the Compiling and Debugging chapter.
• Note that the /proc interface is intended for gathering information and debugging. Don't use it in production systems to control the behavior of processes and threads.

Writing a Resource Manager

• We've corrected the descriptions of the read64 and write64 members of the resmgr_io_funcs_t structure.
• We've added a section on using the receive buffer as a reply buffer.

Sensor Framework

Getting Started

• We've improved the order of the instructions for building and running the sample applications in the platform-specific guides.
• The Getting Started with the Renesas R-Car V3H Videobox miniPLUS Image chapter now describes the adas_example program.

System Security Guide

• In the Security Matrix chapter and elsewhere in the documentation, we've indicated the QNX Neutrino features that support code signing.
• We've enlarged the list of recommended compiler options in the Compiler defenses section.
• The QCRYPTO_R_INIT_ALREADY error code is no longer used.
• In the Writing a resource manager section, we've updated the default minimum size of ctp->msg_max_size to its 7.1 value (a bit more than 2000 bytes).
• The OPENPAM_DEBUG environment variable is now available to enable PAM debugging messages.
• The information about the required permissions to check when you are troubleshooting a PAM configuration has been updated.
• The version of OpenSSL included with QNX Neutrino now supports the blake3 digest algorithm.
• In the QNX cryptography library reference, we have improved the description of the kbuf and ksize arguments for the qcrypto_*key_to_mem() functions.

Utilities & Libraries

C Library Reference

The following entries are new:

ChannelCreatePulsePool()

Create a channel with a dedicated pool of pulses.

nl_langinfo()

Get information about the language or cultural area defined in the current locale

---

We provide this function for POSIX compatibility, but it isn't adequate for internationalization. We ship the International Components for Unicode libraries (libicu*) that you can use instead. For more information about ICU, see http://site.icu-project.org/home.

---

posix_devctl()

Control a device

setgroupspid()

Set supplementary group IDs for a child process

Other changes include the following:

aio*()

The first time you call an aio*() function, a thread pool is created, making your process multithreaded if it isn't already. Because of this, after a fork() the child can't use any of the aio*() functions if the parent used any of them before the fork().

alloca()

We've corrected the description of this function.

cfgetispeed(), cfgetospeed(), cfsetispeed(), cfsetospeed()

It's safe to call these functions from an interrupt service routine.

ClockId()

We've removed an example that was useful only on single-core systems.

dispatch_create_handle()

You can now specify DISPATCH_FLAG_NOLOCK for the flags argument. In most resource managers, the mapping from message types to message handlers is static for the life of the resource manager, but the lookup must be done on every message. The framework locks and unlocks the mapping data on every message, but if a resource manager is going to have a static mapping, this overhead can be eliminated. Setting the DISPATCH_FLAG_NOLOCK flag tells the dispatch framework that it can safely eliminate those protections; see the entry for dispatch_create_handle() for more details.

dlopen()

Note that the runtime linker gets the values of the following environment variables only when the process is loaded:

• DL_DEBUG
• LD_PRELOAD
• LD_TRAP_ON_ERROR

The dlopen() function examines LD_LIBRARY_PATH every time you call it. (Ref# J2874938)

dprintf()

It isn't safe to call this function from an interrupt service routine.

exec*()

We've corrected some references to the new process image and the new process image file.

fork()

A thread must not hold a forksafe_mutex_t when it invokes fork(), or else a deadlock will occur. The same is true of a pthread_mutex_t that's protected by an at-fork handler.

fs_crypto_domain_add_dynamic()

We've corrected the list of arguments for this function.

fnmatch(), getcwd(), getwd(), readlink()

We've corrected some examples that use PATH_MAX; its value includes space for a terminating NUL character, so there's no need to add one to it.

iofunc_attr_t

In general terms, this structure describes the data and state associated with a service offered by a resource manager.

ionotify()

• We've improved the descriptions of the _NOTIFY_COND_* bits.
• This function corresponds to the Linux epoll() function and BSD's kqueue().

isatty()

We've corrected the example.

mallinfo()

Because the members of the mallinfo structure are of type int, they might overflow if you're working with allocations that are larger than 2 GB. Instead of using mallinfo(), call mallopt() with the MALLOC_STATS command. (Ref# J2896183)

mlock()

Memory that's mapped from a typed-memory file descriptor is implicitly locked. Shared memory objects that are populated with shm_ctl() are implicitly locked, unless you use the SHMCTL_LAZY flag.

mmap()

• We've explained why you should use MAP_SHARED instead of MAP_PRIVATE with MAP_PHYS.
• We've explained why the effects of MAP_SHARED and MAP_PRIVATE with MAP_ANON.
• We've added more details about what MAP_BELOW does.
• On 32- and 64-bit ARM targets, PROT_NOCACHE causes RAM to be mapped as normal noncached, but non-RAM to be mapped as strongly ordered device memory. For finer control, see shm_ctl_special().

MsgDeliverEvent()

• This function gives an error of EINVAL if the priority is greater than 255. It also changes a priority of 0 (which is reserved for the idle thread) to 1.
• We've corrected the example so that it calls MsgRegisterEvent().

MsgSendPulse(), MsgSendPulsePtr()

• These functions give an error of EINVAL if the priority is greater than 255. They also change a priority of 0 (which is reserved for the idle thread) to 1.
• The reentrant versions of these kernel calls return positive error codes.

MsgVerifyEvent_r()

This kernel call returns positive error codes.

MsgWrite(), MsgWritev()

As a client may have overlapping send and reply buffers, you must complete all MsgRead*() operations from a particular send (i.e., a particular rcvid) before initiating any MsgWrite*() operations to that client.

nanosleep()

While it might seem that you can specify a sleep duration down to the nanosecond level, the actual delay is driven by the system clock tick. Assuming the usual default clock tick is 1 ms, the shortest delay you can get from this function is 1.5 ms on average.

nanospin()

This function is essentially a busy-wait loop based on the value returned by ClockCycles().

openfd(), sopenfd()

The access mode is only part of the oflag argument.

pathmgr_link(), pathmgr_symlink()

We've listed some specific error codes for these functions.

posix_spawnattr_setcred()

The user and group IDs that you specify with this function are used to set the saved set user and group IDs.

posix_spawnattr_setstackmax()

You can use the elfnote utility to set the stack size for a process's main thread.

pthread_once()

If init_routine is a cancellation point and is cancelled, the effect on once_control is as if pthread_once() was never called.

procmgr_ability()

The subrange for PROCMGR_AID_MEM_PEER is now peer user IDs.

read()

When this function returns successfully, its return value is the number of bytes actually read and placed in the buffer. POSIX requires that this number never be greater than nbytes, but that depends on the underlying resource manager.

readdir(), readdir_r()

These function no longer indicate an error of EBADF.

recvmsg()

We've corrected the declaration of the msghdr and cmsghdr structures.

resmgr_attach()

This function sets errno to EACCES if security policies are in use and there's no rule to permit the use of that path, or the process is sandboxed and the path is denied.

resmgr_msgwrite(), resmgr_msgwritev()

As a client may have overlapping send and reply buffers, you must complete all MsgRead*() operations from a particular send (i.e., a particular rcvid) before initiating any MsgWrite*() operations to that client.

sched_param

We've corrected the example.

sem_timedwait()

If the semaphore can't be decremented (i.e., if the count is 0), this function blocks until another thread increments the semaphore's count, or until the specified timeout expires.

shm_ctl()

• We've deleted an example that used an unsafe method of sharing memory between two processes.
• We've corrected the descriptions of EBUSY and EINVAL.

shutdown_system(), shutdown_system_with_reason()

We've described the save_logs() function that you can provide in the optional shutdown_nvram.so DLL.

sigevent

We've corrected the syntax for SIGEV_SEM_INIT().

slog2_register()

The page size for the num_pages member of the slog2_buffer_config_t structure is always 4 KB, regardless of the page size used by the memory manager.

stat(), stat64()

These functions can give errors of EAGAIN and ENOMEM.

ThreadCancel()

Don't call this function directly; use pthread_cancel() instead.

ThreadCtl()

The inherit mask that you specify with the _NTO_TCTL_RUNMASK_GET_AND_SET_INHERIT command specifies the runmask to use for the any threads created by this thread, including implicitly by process creation.

thread_pool_control()

This function blocks until the number of threads created is strictly between the range of upper and lower, unless you set THREAD_POOL_CONTROL_NONBLOCK in flags.

TraceEvent()

Don't call TraceEvent() with interrupts disabled; this function reenables interrupts.

usleep()

While it might seem that you can specify a sleep duration down to the nanosecond level, the actual delay is driven by the system clock tick. Assuming the usual default clock tick is 1 ms, the shortest delay you can get from this function is 1.5 ms on average.

vdprintf()

It isn't safe to call this function from an interrupt service routine.

wcscspn(), wcstok(), wcsxfrm

We've corrected the description of these functions.

wcsspn()

This function returns 0 if the first wide character in ws1 isn't in ws2.

Devctl and Ioctl Commands

The following entries are new:

DCMD_SDMMC_GEN_CMD

Send a general command to the device

DCMD_SDMMC_MAN_CMD

Send a manufacturer command to the device

Other changes include the following:

DCMD_DUMPER_GETPATH

We've corrected an example that uses PATH_MAX; its value includes space for a terminating NUL character, so there's no need to add one to it.

DCMD_DUMPER_NOTIFYEVENT

We've corrected the error checking in the example.

Utilities Reference

The following entries are new:

patch

Apply a diff file to an original file

zipcloak

Encrypt or decrypt entries in the zipfile

zipnote

Write the comments in a zipfile to stdout, edit comments, and rename files in a zipfile

zipsplit

Split a zipfile into smaller zipfiles

Other changes include the following:

devc-serusb

We've added more details for the -t and ifaces options.

devh-egalax.so

This driver has been discontinued, so we've removed its entry from the Utilities Reference.

dumper

• We've described the primary and secondary methods of finding the link map.
• The -P option causes dumper to read parts of the process's address space that likely include hardware registers. When these registers are read, it may lead to side effects that can result in undefined and unsafe behavior, including system crashes or hanging.

dumpifs

If you use the -f option with the -b option, the argument of the -f option is treated as a basename, and dumpifs extracts all files with that basename. If you use this option without the -b option, you need to specify the full path of the file.

fs-qnx6.so

The Power-Safe filesystem can be used on any device that supports the listed properties, not just on traditional rotating hard disk drive media.

gcov

If you want to use lcov (which we don't provide) on a Linux host to view coverage data, configure it to work with our version of gcov by adding a line such as the following to your .lcovrc file:

geninfo_gcov_tool=ntox86_64-gcov
  

You need to use version 1.15 or later of lcov.

gdb

• We've documented the set nto-executable command.
• We've added an overview of starting the debugger.

grep

Note that this utility doesn't work with binary files.

ifwatchd

We've described the -P option.

io-blk.so

We've corrected the description of the maxio option.

isend

We've corrected the example.

libcam.so

We've corrected the description of the bounce option.

mkcldr

Note that mkcldr functions only and specifically with qdb, and is used to provide a sqlite collation order for infotainment and multimedia databases (SELECT, ORDER BY, and COLLATE queries of a song or artist, for example). It produces a private, packed format that stores just the sorting aspects of CLDR/ICU and makes it available to qdb as a DLL. For more information, see the QNX Database Developer's Guide.

mkifs

• We've corrected the description of the autolink attribute.
• The global keep-section list affected by the -s option doesn't apply to files in the bootstrap section (such as startup* or procnto); you must use an explicit [keepsection=] attribute for these files.
• We've described the limitations of startup scripts.
• Note that mkifs automatically sets the PFS environment variable.
• We've corrected the information about the default user ID and group ID for inline files.
• We recommend that you not use the type=link attribute to create a link from /tmp to /dev/shmem.
• We've added more details about the keeplinked attribute.

mkxfs

We've clarified the description of the -r option.

procnto

There's a new -x option that control the size of the buffers that the kernel can use when passing small messages.

python

We ship Python for QNX Neutrino targets. The host-side version of Python is included for gdb to use; don't use it for any other purpose.

qcc

• We've described how qcc handles other options.
• We've documented the -print-prog-name option.
• We've improved the example of the -W option.

random

We've documented the -S and -v options.

rsrcdb_query

We've documented the -p option.

secpolgenerate

We've documented the -L option.

seedres

You don't need to run this utility before running pci-bios.

server-monitor

We've documented the -U option.

slay

This utility uses the DCMD_PROC_STOP and DCMD_PROC_RUN devctl() commands when you use it to change a thread's priority or runmask. These commands are intended for debugging; don't use them in production systems.

slmctl

We've documented the -n option, which sets the access point that client applications write control and query commands to. The -p option is for use only with the active command.

slogger2

• We've added a section on redirecting a program's stdout and stderr to slog2 buffers.
• The opcode is a 32-bit value that's made up of a 20-bit major value and a 12-bit minor value.

sockstat

We've described the -v option.

uname

There's a new -k option that displays the kernel version number and the release level of the OS.

wtdkick

When you're using the QNX Hypervisor, the hardware used by wtdkick could be host-physical or guest-physical, depending on where the kicker is running.

Known issues

• The elfnote documentation has the following omission and errors:
  • For the -t option, NT_GNU_BUILD_ID is missing from the list of defined types.
  • If -t specifies a defined type, you are not required to specify -n (the note name is implied).
  • In the examples, the following commands generate errors and will be removed:

    elfnote -nQNX -tQNT_STACK -Fn -m 128k,128k file
    elfnote -nQNX -tQNT_STACK -Fn -m 128k,4k file
    elfnote -n QNX -t QNT_STACK -m 0000020000100000 file
    elfnote -t QNT_STACK -m 0000020000100000 file
    elfnote -t QNT_STACK -m 00,00,02,00,00,10,00,00 file
    elfnote -t QNT_STACK -Fx -m 00,00,02,00,00,10,00,00 file
    elfnote -t QNT_STACK -Fnn -m 131072,4096 file
    elfnote -t QNT_STACK -Fn -m 131072,4096 file
    elfnote -t QNT_STACK -Fn -m 128k,4k file
    elfnote -t QNT_STACK -Fxn -m 00000200,4096 file
    elfnote -t QNT_STACK -Fnx -m 128k,00100000 file
    elfnote -t QNT_STACK -Fnxxxx -m 128k,00,10,00,00 file
      

  (Ref# J2563663)

See also the QNX SDP 7.1 release notes.

Getting started with the documentation

After you've installed QNX SDP, you'll find an extensive set of HTML documentation in the Integrated Development Environment's help system. To start the IDE:

• on Windows, choose QNX > QNX Momentics IDE from the Start menu, or use the desktop icon
• on Linux, run IDE_base_directory/qde, where IDE_base_directory is where you installed the IDE package
• on macOS, click the icon labelled QNX Momentics IDE from the launchpad

The roadmap page contains links to the various HTML booksets that accompany the OS. For a short tutorial that will help you get started, see the Quickstart Guide, then refer to the other documents (System Architecture, QNX Neutrino Programmer's Guide, C Library Reference, Utilities Reference, and so on).

You can install and work with multiple versions of QNX Neutrino. Whether you're using the command line or the IDE, you can choose which version of the OS to build programs for. For more information, see the IDE User's Guide or the QNX Neutrino Programmer's Guide.

Technical support

To obtain technical support for any QNX product, visit the Support area on our website (www.qnx.com). You'll find a wide range of support options, including community forums.