What Docs Should I Read?

In this chapter...

Is there a documentation map?
What should I read first?
Each doc has its own keyword index
Where key features are documented
Related reading

Is there a documentation map?

To help you find your way around the vast amount of material included in your QNX Momentics documentation set, we've provided a documentation roadmap.

Bookset overview

The complete QNX Momentics documentation set contains the following books, arranged here under each main component:

In the following sections, titles such as User's Guide or Library Reference without any qualifier always assume "QNX Neutrino." For specific components, the appropriate qualifier always precedes such titles (e.g. Photon Programmer's Guide, IDE User's Guide, etc.).

Integrated Development Environment (Professional Edition only)

IDE User's Guide: Describes the QNX Momentics Integrated Development Environment, how to set up and start using the tools to build Neutrino-based target systems, etc.

QNX Neutrino Realtime Operating System

System Architecture: Describes the concepts and architecture of the QNX Neutrino microkernel, resource managers, processes, threads, message-passing services, and more. This is a must-read!
User's Guide: Explains how to interact with a running Neutrino system. Covers both Photon and text-mode interfaces, as well as various system-administration topics.
Programmer's Guide: Tells you how to get started writing programs, including interrupt handlers, resource managers, etc.
Building Embedded Systems: Tells you how to get the OS running on your target embedded system, write an IPL, customize a startup program, etc.
Utilities Reference: Describes the Neutrino configuration files, utilities, and manager processes you'll use during development and at runtime. See the Utilities Summary chapter in the reference for a listing of all the entries by category.
Library Reference: Describes the C library data types and functions, including POSIX threads, kernel calls, resource manager functions, etc. See the Summary of Functions chapter in the reference for a listing of all the functions by category.
Technical Notes: Deals with a series of topics (e.g. IP tunneling) that aren't covered in the basic docset.

Photon microGUI

Photon Programmer's Guide: Gives you a hands-on tour of the Photon Application Builder (PhAB). You'll learn how to quickly assemble a GUI from predefined widgets, link the GUI to an application, and generate C source to bring the GUI to life.
Multimedia Developer's Guide: Describes the multimedia architecture for developers who wish to write multimedia plugins.
Photon Library Reference: Provides concise descriptions of Photon's and PhAB's global data structures and functions.
Widget Reference: Contains guidelines for programming widgets, along with concise descriptions of all global data structures, resources, and convenience functions associated with widgets. It also gives you practical examples of how to use Photon widgets and widget functions.
Building Custom Widgets: Explains how to create a custom widget and how to bind it into PhAB. If you need a widget whose features extend the standard capabilities of the Photon widget library, this guide is for you.

BSPs, DDKs, and specialty tools

BSP Guides: Describe how to get Neutrino running on your target board. You'll find a separate doc for each BSP that you've installed. We support boards in these processor families: ARM/XScale, MIPS, PowerPC, SH-4, and x86. You can download binaries for the BSPs from our website, http://www.qnx.com/; for information about BSP source, contact your sales representative.
DDK Guides: DDK guides describe how to write drivers for QNX Neutrino. You'll find a separate DDK doc for audio, character, graphics, input, network, and Universal Serial Bus (USB) devices. You can download the DDKs from our website, but you'll find the documentation in the QNX Momentics docset.
System Analysis Toolkit User's Guide: The System Analysis Toolkit (SAT) guide describes how to use the SAT with our instrumented microkernel. You can log every communication and state change within the microkernel, including interrupts, all parameters/return values from kernel calls, and scheduling decisions, resulting in a deeper and more detailed analysis of system elements. You can even perform kernel-level diagnostics remotely.
Photon Multilingual Input: Tells you how to input Chinese, Japanese, and Korean characters in Photon.
Phindows Connectivity: Tells you how to access Photon from a Windows machine.
TDKs: The release notes (see ${QNX_TARGET}/etc/readme/tdk) for each TDK indicate the relevant documentation.

Dinkum C and C++ documentation

Dinkum C++ Library: A conforming implementation of the Standard C++ library.
Dinkum C99 Library: A conforming implementation of the Standard C library, as revised in 1999.
Dinkum EC++ Library: A conforming implementation of the Embedded C++ library as specified by the Embedded C++ Technical Committee.

What should I read first?

Many people simply don't read manuals cover to cover. They often browse or search the docs for a specific topic, usually for information on how to do a certain task. But if you want to approach your tasks with enough knowledge to work effectively, it's a good idea to start with the System Architecture guide. That handy book doesn't really tell you how to do anything, but it will help you understand Neutrino's unique features, particularly its message-based interprocess communication (IPC) and microkernel architecture.

Once you know how Neutrino works, you'll then want to know how to work with it. Which doc you'll need next depends on when you need it.

During development (on your host)

Most (but not all) of the docs in the bookset are geared towards developing your Neutrino-based applications. Of these development docs, some are how-to guides, some are reference works.

Some docs are useful during development as well as at runtime. For instance, the Utilities Reference is a comprehensive doc that includes descriptions of both "development" utilities (e.g. make), which you wouldn't normally use on your target, as well as "runtime" programs (e.g. devc-sersci), which you would run only on your target.

Here are the main how-to guides and their corresponding reference books:

How-to guide:	Companion reference:
IDE User's Guide	Utilities Reference (for underlying command-line utilities, such as `make`); Library Reference for API
QNX Neutrino User's Guide	Utilities Reference
Programmer's Guide	Library Reference
Photon Programmer's Guide	Photon Library Reference; Photon Widget Reference
Building Embedded Systems	Utilities Reference; Library Reference

If you've already developed applications with QNX Momentics 6.2.1, see the 6.3.0 and 6.2.1 Compatibility notes. You can find the latest version of this document on our website: http://www.qnx.com/. Log into your myQNX account, then go to the Download Center.

At runtime (on your target)

The most runtime-oriented doc in your bookset is the Neutrino User's Guide, which describes how to use and interact with a running Neutrino system. The book covers both Photon and text-mode interfaces, as well as various system-administration topics.

Other runtime-oriented docs include the Utilities Reference and the IDE User's Guide (for information on diagnostic tools you'd use on a running system).

Each doc has its own keyword index

Nearly every book in the QNX Momentics documentation set has its own keyword index. At the top and bottom of every page of a doc, you'll find an icon that's linked to the keyword index file (keywords-all.html):

[Index]

Here's a quick way to get to the keyword index files of all the QNX Momentics online docs:

Audio DDK -- index
Audio Developer's Guide -- index
Building Custom Widgets -- index
Building Embedded Systems -- index
Character DDK -- index
Graphics DDK -- index
High Availability Toolkit Developer's Guide -- index
IDE User's Guide -- index
Input DDK -- index
Library Reference -- index
Network DDK -- index
Photon Library Reference -- index
Photon Programmer's Guide -- index
Photon Widget Reference -- index
Programmer's Guide -- index
System Analysis Toolkit User's Guide -- index
System Architecture -- index
USB DDK -- index
User's Guide -- index
Utilities Reference -- index
Welcome to QNX Momentics -- index
Widget Reference -- index

Where key features are documented

The following list may help you learn which doc to turn to when you want information on certain key features or components of the OS and tools.

The System Architecture guide is conspicuous by its absence in this list, simply because there's no point in repeating a reference to the guide for practically every topic listed here!

Audio support: Audio Developer's Guide (for writing audio applications); Audio DDK (for writing audio device drivers); io-audio manager in Utilities Reference; deva-* drivers in Utilities Reference.
BSPs: Each BSP that you install includes documentation; see the BSP installation notes.
Buildfiles: Making an OS Image in Building Embedded Systems; mkifs in Utilities Reference.
CD-ROM: Working with Filesystems in User's Guide; cam-cdrom.so in Utilities Reference.
Channels: Channel*, Msg*, and Connect* in Library Reference; Writing a Resource Manager in Programmer's Guide.
Compiling: Developing C/C++ Programs in IDE User's Guide; Compiling and Debugging in Programmer's Guide; make and qcc in Utilities Reference.
Compression: Making an OS Image in Building Embedded Systems; deflate in Utilities Reference.
Data server: Setting Up an Embedded Web Server in User's Guide; ds in Utilities Reference.
DDKs: Driver Development Kits (DDKs). You'll find the documentation in the QNX Momentics docset, but if you want the DDKs, you must download them from our website.
Debugger: Debugging Programs in IDE User's Guide; Compiling and Debugging in Programmer's Guide; gdb and other debugging utilities in Utilities Reference.
Device management: devctl() in Library Reference; Writing a Resource Manager in Programmer's Guide; dev* drivers in Utilities Reference.
Editors: IDE Concepts in IDE User's Guide; Using Editors in User's Guide; elvis, ped, qed, sed, and vi in Utilities Reference.
Embedded systems: Building Embedded Systems.
Endian issues: Freedom from Hardware and Platform Dependencies in Programmer's Guide.
Environment, configuring: Controlling How Neutrino Starts and Configuring Your Environment chapters in User's Guide.
Environment variables: Commonly Used Environment Variables appendix in Utilities Reference; environ() in Library Reference; Using the Photon microGUI and Configuring Your Environment chapters in User's Guide.
Event handling (OS): MsgDeliverEvent() in Library Reference; Writing an Interrupt Handler in Programmer's Guide.
Event handling (Photon): Events in Photon Programmer's Guide; phrelay in Utilities Reference.
File handling: creat() (and related functions via its see also section) in Library Reference; basename, cat, etc. in Utilities Reference (see "File and directory manipulation" in the Utilities Summary).
Filesystems: Working with Filesystems in User's Guide.
Fonts: Fonts chapter and Photon in Embedded Systems appendix in Photon Programmer's Guide.
Graphics: Graphics DDK; devg-* drivers in Utilities Reference.
Hardware: Connecting Hardware in User's Guide.
HID (human input devices): hidview and devh-* drivers in Utilities Reference.
Helpviewer (Photon): Using the Photon microGUI in User's Guide; helpviewer in Utilities Reference.
I/O management: iofunc*, Interrupt*, and open() (and related functions via open()'s see also section) in Library Reference; Writing a Resource Manager in Programmer's Guide.
IPC (interprocess communication): pthread_mutex*, SyncMutex*, sem_*, SyncSem*, pthread_cond*, and SyncCondvar* in Library Reference. See also "Message Passing" below.
IPL (initial program loader): Writing an IPL Program in Building Embedded Systems.
Images (OS): Making an OS Image in Building Embedded Systems; mkifs in Utilities Reference.
Images (Photon): Raw Drawing and Animation in Photon Programmer's Guide.
Input: Input DDK; devh-* and devi-* drivers in Utilities Reference.
Instrumented kernel: System Analysis Toolkit User's Guide.
Interrupt handling: InterruptAttach() (and related functions in its see also section) in Library Reference.
Kernel calls: Channel*, Clock*, Connect*, Debug*, Interrupt*, Msg*, Sched*, Signal*, Sync*, Thread*, Timer*, and TraceEvent() in Library Reference.
Keyboard support: Using the Command Line in User's Guide; mkkbd (and related utilities in its see also section) in Utilities Reference.
Libraries: Compiling and Debugging in Programmer's Guide; Building OS and Flash Images in IDE User's Guide.
Linker: Compiling and Debugging in Programmer's Guide; qcc (and related utilities in its see also section) in Utilities Reference.
Makefile structure: Developing C/C++ Programs in IDE User's Guide; Conventions for Makefiles and Directories in Programmer's Guide.
Memory management: mem*, mmap*, posix_mem*, and malloc() in Library Reference; Heap Analysis: Making Memory Errors a Thing of the Past in Programmer's Guide; Finding Memory Errors in IDE User's Guide.
Message passing: Msg*, Connect*, and Channel* in Library Reference. See also "IPC" above.
Message queues: mq_* in Library Reference.
Native networking (Qnet): See "Transparent distributed processing."
Network drivers: Network DDK; devn-* drivers in Utilities Reference.
Package filesystem: Working with Filesystems in User's Guide; fs-pkg in Utilities Reference.
Permissions (on files, directories): Managing User Accounts and Working with Files chapters in User's Guide; chmod(), stat(), and umask() in Library Reference; chmod in Utilities Reference.
Power management: Power Management User's Guide; InterruptHookIdle() in Library Reference.
Process manager: procnto* in Utilities Reference; procmgr_* in Library Reference.
Processes: Processes in Programmer's Guide; exec*, fork*, and spawn* in Library Reference.
Profiler (application): Profiling an Application in IDE User's Guide.
Profiler (system): Analyzing Your System with Kernel Tracing in IDE User's Guide.
Pulses: MsgSendPulse(), MsgReceivePulse(), and pulse_* in Library Reference; "Handling private messages and pulses" in the chapter on writing resource managers in the Programmer's Guide.
QoS (Quality of Service): "Quality of Service and multiple paths" in the Native Networking (Qnet) chapter in System Architecture; netmgr_ndtostr() in Library Reference.
RAM disk: io-blk.so (using ramdisk=size option), devb-ram, and devf-ram in Utilities Reference.
Realtime scheduling: Sched* functions and sched_param structure in Library Reference.
Resource management: Writing a Resource Manager in Programmer's Guide; resmgr_* and iofunc_* in Library Reference.
SMP: Developing SMP Systems in Programmer's Guide; procnto* in Utilities Reference.
Self-hosted development: Compiling and Debugging in Programmer's Guide.
Signal handling: sigaction() (and related functions via its see also section) in Library Reference.
Startup programs: Customizing Image Startup Programs in Building Embedded Systems; startup-* in Utilities Reference.
Synchronization: Sync* in Library Reference.
System information: pidin and sin in Utilities Reference; Analyzing Your System with Kernel Tracing in IDE User's Guide; Fine-Tuning Your System in User's Guide.
Target agent (qconn): qconn in Utilities Reference; IDE Concepts in IDE User's Guide.
Threads: pthread_* and Thread* in Library Reference; Programming Overview in Programmer's Guide.
Time: Configuring Your Environment in User's Guide; Clock* and time() (and related functions via their see also sections) in Library Reference.
Timestamps (for files): touch in Utilities Reference; utime() (and related functions via its see also section) in Library Reference.
Timers: alarm(), Timer*, and timer_* in Library Reference.
Transparent distributed processing: Using Qnet for Transparent Distributed Processing in User's Guide; Transparent Distributed Processing via Qnet in Programmer's Guide; npm-qnet.so in Utilities Reference; netmgr_* in Library Reference.
USB: Connecting Hardware in User's Guide; devu-*, devh-usb.so, devi-hid, and io-usb in Utilities Reference; USB DDK.
Unicode: "Wide-character functions" in the Summary of Functions chapter of the Library Reference; Unicode Multilingual Support in Photon Programmer's Guide.
Version control: Managing Source Code in IDE User's Guide; cvs in Utilities Reference.
Web server (slinger): Setting Up an Embedded Web Server in User's Guide; slinger in Utilities Reference.
XIP (execute in place): Building OS and Flash Images in IDE User's Guide; Writing an IPL Program in Building Embedded Systems.