Embedding help into your binaries

Since QNX Neutrino is designed primarily to be deployed on embedded systems but also maintain many of the self-hosted characteristics that makes development on those platforms efficient (no-reboots, easy access, familiar cmd line tools) its help system is dually organized. There is a rich set of standard documentation (HTML or PDF) for the operating system, its programming environment, various libraries and utility functions.

However, since that documentation is not always at hand when you want to run a quick command* each target binary (ls, find, pidin etc) also contains an embedded text segment that holds a description on how to use the utility. In order to get at this information, you use the imaginatively named use utility.

For example, I never remember all the options to the find utility. If I were on a target then I could type in:

 % use find 
find  - find files (POSIX) 
find  ... [operand_expression] 
Operand expressions: 
...

In some ways this information is equivalent to unix style man pages, but since it is embedded directly into the binaries you never have to do any fancy configuration to prune information in (or out). Compared to rooting through and finding the utilities you use and then pruning the man pages appropriately, this is wicked easy.

In addition to the usage type of information, you can also print out build version information that is included with QNX binaries:

 % use -i find 
NAME=find 
DESCRIPTION=find files 
DATE=2004/12/16-00:01:41-EST 
STATE=Stable 
HOST=uberbuild 
USER=toolsbuild 
VERSION=6.3.0SP1 
TAGID=329

If you are ever contacting QNX support, this is great stuff to send them so that they can match up your binaries directly with the source for a given release if need be.

Under Neutrino the usage information is stuffed into two different ELF sections of the binary.

 % ntox86-objdump -h find 
/usr/bin/find:     file format elf32-i386 
Sections: 
Idx Name          Size      VMA       LMA       File off  Algn 
... 
 19 QNX_usage     00004fb7  00000000  00000000  0000d304  2**0 
                  CONTENTS, READONLY 
 20 QNX_info      00000085  00000000  00000000  000122bb  2**0 
                  CONTENTS, READONLY

This approach is a double edged sword. On the one hand it means you don’t pay a memory penalty when loading the process since the QNX loader knows that these sections aren’t executable and basically ignores them. Since they are standard ELF sections, you can use all of the standard binary manipulation tools to work with them. The downside of this is that these sections can be removed by utilities such as strip, although the Neutrino image build process, using mkifs will preserve these sections in the OS filesystem image.

The cool thing is that this information stuffing isn’t something just reserved for QNX utilities and shared objects! It can be added to any Neutrino binary via the usemsg utility. There is no set format for the general usage section (QNX_usage), so you can put whatever you like there. The convention is to put command line parameter explanations and example invocations in this free form text section. The information section (QNX_info) is a structured key=value area and has a date and time field that is automatically updated when information is added. It is easy to use this technique to integrate notes that can be easily retrieved on both host and target systems.

% use -i ./a.out 
No info available in ./a.out. 
% usemsg -i qnx=cool ./a.out 
% use -i ./a.out 
NAME=a.out 
DATE=2007-03-25EDT-20:06:24 
QNX=cool

Use messages are definitely a handy bit of infrastructure that make things just a bit easier for you to work with and manage your system software.


* For example working remotely connected to a customer site with no development environment at hand.

Advertisements

1 comment so far

  1. Mario on

    Wow awesome information. I didn’t know about the use -i stuff. Time to modify the makefile ;-)


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: