Appendix: Calling 911

Seeking professional help

No matter how good a developer you are, there are times when you:

In this chapter, we'll look at the resources available when you face these problems.

So you've got a problem…

We'll talk about the first two problems together, because it's often hard to tell which problem you're actually experiencing.

Something no longer works, or doesn't work as expected. What should you do about it?

RTFM

Read the fine manual! While this may seem like an obvious first step, it's amazing the number of people who don't do this!

All the manuals for the Neutrino operating system are online:

Building Embedded Systems

Building Embedded Systems contains all the information you'll need to “embed” Neutrino — that is, to get a Neutrino system up and running. It has chapters on the development environment (how to compile, link, and debug a Neutrino program), building images (how to get a system image created, how to embed this image into a deeply embedded system, how to get it “running” on a supported platform), and some design notes.

Library Reference

The Neutrino Library Reference is the “A through Z” of the C library — use this to find information about each and every function call that's provided by Neutrino's C library. This is the ultimate “authority” on function calls. Often in this book, I've referred you to this library (for example, to find out more about a particular function, such as arguments that aren't commonly used).

System Architecture

A “top-level” architecture document, the System Architecture guide describes the Neutrino system from a high-level view, giving enough details about the implementation that you can get a good idea of what the pieces are and how they all fit together.

Technotes

The Technotes describes special features of Neutrino and may vary from release to release. Take a look at the online version to see what's in the release you currently have.

User's Guide

The QNX Neutrino User's Guide is intended for all users of a QNX Neutrino system, from system administrators to end users. This guide tells you how to:

Utilities Reference

The Utilities Reference is the “A through Z” of the command-line utilities available. It covers all command-line utilities such as grep, make, ls, etc.

Programmer's Guide

The Neutrino Programmer's Guide and this book both describe how to develop applications and resource managers, but from somewhat different perspectives.

Contact technical support

Once you've determined to the best of your abilities that the problem isn't some misunderstanding of the function call or utility you're using, or a mere typo, you may enter the realm of QSS's technical support department. This is nothing to be afraid of — most customers are extremely pleased with the level of technical support they get from QSS.

There are two ways of contacting QNX's technical support group: by phone or via the web. QSS's website (at http://www.qnx.com), has a Community area called Foundry27, at http://community.qnx.com/sf/sfmain/do/home which is full of useful information and files.

Before we talk about which method you should use, there are a few things you can do to make the turnaround time on your bug report much shorter.

Describe the problem

Often customers try to fix the problems themselves by trying various things that come to mind. This is great. Unfortunately, what tends to happen is that customers get frustrated and post messages something like:

I just ran the TCP/IP package connected to a Windows box
and it doesn't work.

What's going on?!?

The very next message from tech support looks like the following (I think they should have a standard template for it, myself):

Can you describe what you mean by "doesn't work"?  Do you mean
the TCP/IP on the QNX side?  Do you mean the TCP/IP on the
Windows box?  What part of TCP/IP doesn't work?  What are you
trying to do?  What versions of the OS, and TCP/IP package do
you have?  What version of Windows?  What TCP/IP package
were you using there?

The moral of the story: if you're having a problem, then you're probably in a hurry for the answer. If you're in a hurry for the answer, supply as much information as possible in your initial post so that someone at QSS can try right away to reproduce the problem.

Here are the things that tech support almost always asks for:

Precise information

To supply this information, state what you had expected to happen, and what actually happened. In our above example, a much better problem description would have been:

I just ran telnet from Neutrino 2.0, patch level "A", to my
Windows box, and, immediately after the login prompt, got a
"Connection closed by foreign host". 

Versions

The next thing that you should supply is the versions of the various commands that you may have been using. This can be done by using the ls and cksum commands. For our example above, you'll want to tell tech support which version of the telnet command you were using, and the version of the TCP/IP protocol stack etc.

# ls -l /usr/bin/telnet /lib/dll/devn-ne2000.so
-rwxrwxr-x  1 root      bin           64220 Jun 22 05:36 /usr/bin/telnet
-rwxrwxr-x  1 root      bin           27428 Jun 22 03:29 /lib/dll/devn-ne2000.so

# cksum /usr/bin/telnet /lib/dll/devn-ne2000.so
1217616014      64220 /usr/bin/telnet
  50089252      27428 /lib/dll/devn-ne2000.so

This gives tech support at least some idea of the dates, sizes, and checksums of some of the products that might be involved in the problem.

If you suspect your problem might be related to a platform-specific interaction, you should of course specify the name, brand, and relevant chipsets used on that particular platform.

Another thing that tech support usually requests, especially if they suspect some problems with insufficient memory, licensing, configuration, etc., is the runtime configuration of your system. You should try to give them an idea of how much memory is installed, how many processes are running, what the approximate load on the system might be, etc.

The more information you have, the faster they can help you.

If you're using a beta…

If you're using a beta version of the product (i.e., you're on QSS's list of beta sites), all the above information is critical, because you'll typically be using different versions of the software than what is released. Note, however, that the technical support department generally doesn't handle telephone support of beta products. The only way to get help on these is to post in the conference or, if the developer has requested direct contact, talk to the developer. Posting is generally the best solution anyway, because then other members of the beta conference can see what problems are out there and can learn what the solution is (i.e., if it's a bug, what the workaround for it is). In any event, the above information is crucial in order to determine which products you have from the beta release and which ones are “stock.”

Also, keep in mind that if you're talking with a developer, they often have a million things on their plates and might not be able to get back to you right away. Sending a friendly “ping” reminder after a few days doesn't hurt. Sending a demanding one after 15 minutes will not gain you any new friends!

An issue that frequently comes up with betas is that you may forget to install an update. Due to the way that the beta process works, missing an update may cause strange behavior on your system. Certain new drivers or resource managers may behave differently towards their respective client programs than they did in previous versions.

In this case, you should ensure (because the support staff will ask!) that you have indeed installed all the beta updates in the order listed.

Reproduce the problem

One of the first things that tech support usually wants to know is, “Does it happen just once in a blue moon, or can you make it happen on demand?”

They don't ask this question idly. If it's a problem that happens infrequently, it's just as serious as a problem that happens regularly. The point is to try to determine how to proceed.

Generally, for problems that happen infrequently, the support staff will recommend that you configure the machine with the operating system and components set up in such a way that when the problem happens again, some form of log will be left around or perhaps the debugger will be invoked so that the problem can be diagnosed later.

For a problem that's easily reproducible, they'll want to reproduce it at QSS so that they can show the developer on a live system. “Hey, look! It dies when I …”

Narrow it down

Even if it's reproducible, tech support most likely doesn't want to see 6000 lines of C code with a problem buried in the middle of it.

In most cases that I've witnessed, a bug can usually be narrowed down to about 20 to 30 lines of C at the most. The only cases where a really large file is actually useful is when reporting bugs with something where you suspect it's a size problem, rather than a library or kernel problem. For example, some utilities may have a default array size that may cause trouble when it needs to resize that array for something bigger. In this case, tech support may ask you for a tar file with everything in it. Luckily, tar files are easy to create. For example, if you're developing your product in /src/projects/xyzzy and they want to see everything in that directory, you can perform the following steps:

# cd /src/projects
# tar cvf xyzzy.tar xyzzy

This will “suck” everything out of the xyzzy directory (and all subdirectories too!) into the file called xyzzy.tar. If this resulting tar file is huge, you can save some download time and disk space by compressing it with gzip:

# gzip -9v xyzzy.tar
xyzzy.tar:       60.2% -- replaced with xyzzy.tar.gz

You'd then send the support people the xyzzy.tar.gz file (generally by ftp rather than as an email attachment :-)).

Training

Finally, several companies offer training courses for QNX products, and QSS offers onsite as well as periodic training at their facility.