NetBSD Problem Reports
This is a two-step process:
Checking the problem is not already reported, using the Query PR form
Submitting a new problem report, using the Send PR form
Note
If you are not familiar with the submission of problem reports or with send-pr(1) please continue reading and learn more about the details from the following sections.
Details about the bug and problem reporting system
- Introduction
- Searching or Browsing the NetBSD GNATS Database
- Submitting a Bug or Problem Report
- Appending to an existing Problem Report
- What Goes In a Problem Report
- NetBSD Problem Report Fields
- NetBSD Problem Report States
Introduction
Bug and problem reports are essential to making NetBSD a robust, reliable system. We rely on them to inform us of bugs or other deficiencies in the operating system.
We use the GNATS bug tracking system to make sure that no problem report "falls through the cracks". The send-pr(1) program on your NetBSD system is the primary user interface for submitting bug reports to GNATS.
Searching or Browsing the NetBSD GNATS Database
There are two ways to view problem reports from the GNATS database:
- Browse the database summary and its subsidiary pages which have listings of all current problem reports sorted by various criteria. These pages are updated from the master database several times each day.
- Search the database with the query-pr form using your web browser.
Submitting a Bug or Problem Report
It is generally a good idea to search or browse the GNATS database for a problem you're having before you report it yourself. Someone else might have reported it already (and there might already be a solution or workaround in the database).
The best way to submit a problem report is with the send-pr(1) program on your NetBSD system. It provides a form with several fields for you to fill out with your favorite text editor (you might also want to read some advice about what to put in the PR). Once the form is completed, send-pr(1) e-mails the report to the our GNATS server.
When the report reaches the server, it is automatically checked for syntax errors, assigned a new PR number, and cataloged in the GNATS database. Once in the database, the person responsible for the category that the report was submitted to is notified, and a copy of the report is sent to the netbsd-bugs mailing list, or pkgsrc-bugs for the “pkg” category.
In addition, a confirmation of the problem report, including the assigned PR number, is sent back to you. This number can be used to retrieve the PR later. This is sometimes useful because the problem report may contain extensive information on the state of tracking the bug and possible solutions.
Appending to an existing Problem Report
To add additional text to a PR that has already been submitted, just send
e-mail to
<[email protected]>, with a
subject line containing “Re: ”, the PR category, and PR number;
for example:
Subject: Re: kern/5514
The message will automatically be appended to the GNATS database entry, and will automatically be resent to several addresses:
- the person listed as being “responsible” for handling the PR;
- the original submitter of the PR;
- for reports in category “pkg”: the mailing list [email protected]; for others, the mailing list [email protected].
Note that if you do not carbon-copy any other interested parties yourself, they will not receive a copy of your mail. This includes parties that already replied to the PR before, even when you are in fact directly replying to a reply of theirs (see below).
GNATS uses its address in its outgoing messages' "Reply-To" header. The "From" header of GNATS' messages contains the e-mail address of a message's originator.
Note that your e-mail client will (should) ignore the "From" header completely when honoring "Reply-To": this means that when that "From" address is not one of the addresses listed above, you should make sure to explicitly add it to the addressee list of your message. If not, the person whose message you're essentially replying to will not receive a copy of your message.
What Goes In a Problem Report
A database is only as good as the data that goes into it. In general, common sense (assuming such an animal exists) dictates the kind of information that would be most helpful in tracking down and resolving problems in software.
- Include anything you would want to know if you were looking at the report from the other end. There's no need to include every minute detail about your environment, although anything that might be different from someone else's environment should be included (your path, for instance).
- Narratives are often useful, given a certain degree of restraint. If a person responsible for a bug can see that A was executed, and then B and then C, knowing that sequence of events might trigger the realization of an intermediate step that was missing, or an extra step that might have changed the environment enough to cause a visible problem. Again, restraint is always in order ("I set the build running, went to get a cup of coffee (Columbian, cream but no sugar), talked to Sheila on the phone, and then THIS happened...") but be sure to include anything relevant.
- Richard Stallman writes,
This holds true across all problem reporting systems, for computer software or social injustice or motorcycle maintenance. It is especially important in the software field due to the major differences seemingly insignificant changes can make (a changed variable, a missing semicolon, etc.).
The fundamental principle of reporting bugs usefully is this: report all the facts. If you are not sure whether to state a fact or leave it out, state it!
- Submit only one problem with each Problem Report. If you have multiple problems, use multiple PRs. This aids in tracking each problem and also in analyzing the problems associated with a given program.
- It never hurts to do a little research to find out if the bug you've found has already been reported. Most software releases contain lists of known bugs in the Release Notes which come with the software. In addition, it's a good idea to search the NetBSD GNATS problem report database to see if someone already reported the problem you're having (who knows? there might already be a fix or work-around in the database).
- The more closely a PR adheres to the standard format, the less interaction is required by a database administrator to route the information to the proper place. Keep in mind that anything that requires human interaction also requires time that might be better spent in actually fixing the problem. It is therefore in everyone's best interest that the information contained in a PR be as correct as possible (in both format and content) at the time of submission. See a description of the fields in a problem report for more details.
So, the kernel panic'd, and gave you a whole lot of hexadecimal numbers, and halted. It's important for you to report this event, since real operating systems should never crash or panic, unless the computer hardware fails egregiously (there's usually not much an OS can do about hardware failure). That leaves kernel bugs as the other cause of a panic, and we need to track down those bugs and squash them to make NetBSD even more stable and robust than it already is.
The trouble is that the stack dump that the kernel printed is specific to your kernel, and the numbers really have to be converted back into symbol table references so that someone else who doesn't have your system's kernel can get an accurate picture of where it decided to die.
At a minimum, copy down the "PC" numbers and convert them to symbolic references - that's the Program Counter for the computer; where it was executing. Ideally, if you can arrange to cut & paste the whole thing, that's even better.
So, when the kernel gives you this (usually several lines of this):
pc = 0xf80ff430 args = (0x0, 0x41001fe5, 0xf8139c00, 0xf8123d20, 0xf8101e38, 0xf8143800, 0xf8123c68) fp = 0xf8123c68
The PC number is specific to the kernel you were running, and is not likely to be the same as anyone else's kernel, so it must be converted to a symbol reference. To convert a hexadecimal PC value to symbolic reference, use gdb(1), in the following way:
gdb -k /netbsd
x 0xf80ff430
0xf80ff430 <cpu_reboot+196>: 0x40000093
That "<cpureboot+196>" result from gdb(1) is what the people who will work on the problem report will need, so put it (preferably along with the rest of that "args" line) into your problem report.
See problem report #3765 for an example of an exhaustive PR on a kernel panic.
NetBSD Problem Report Fields
Each problem report has several machine-parsable fields in it, to make it possible to process the reports semi-automatically. The values for several of those fields and their definitions are listed below, to help you more clearly specify what's wrong (and hopefully expedite the problem resolution).
In addition to the fields listed below, NetBSD problem reports are assigned to various Categories which reflect the part of the overall software that is thought to be the source of the problem. These categories are roughly split into two types:
- Machine Independent (e.g.
bin,lib,security) - problems in the user level programs, daemons, libraries, and the machine independent parts of the kernel (i.e. those parts that are the same without regard to the particular hardware that NetBSD is running on, and therefore a problem is likely to affect all platforms). - Port Specific (e.g.
port-alpha,port-ofppc,port-sparc) - device driver, or CPU-specific support (i.e. kernel trap handlers) problems that are only going to affect the one kind of machine that the problem occurred on.
The severity of the problem. The accepted values are:
-
critical
The product, component or concept is completely non-operational or some essential functionality is missing (e.g. kernel panic or program core dumps). No workaround is known.
-
serious
The product, component or concept is not working properly or significant functionality is missing. Problems that would otherwise be considered
criticalare ratedseriouswhen a workaround is known. -
non-critical
The product, component or concept is working in general, but lacks features, has irritating behavior, does something wrong, or doesn't match its documentation.
The default value is serious.
How soon the problem report submitter requires a solution. The accepted values are:
The default value is medium.
The class of a problem report can be one of the following:
-
sw-bug
A general software problem (
`sw'stands for "software"). -
doc-bug
A problem with the manual pages or other documentation.
-
change-request
A request for a change from existing behavior that is not a bug ("It's nice, but it would be better if ...").
-
support
A question or request for technical support.
The default value is sw-bug.
NetBSD Problem Report States
Each PR goes through a defined series of states between origination and closure. The submitter of a PR receives notification automatically via E-mail of any state changes.
The initial state of a Problem Report. This means the PR has been filed and the responsible person(s) notified.
The responsible person has analyzed the problem. The analysis should contain a preliminary evaluation of the problem and an estimate of the amount of time and resources necessary to solve the problem. It should also suggest possible workarounds.
The problem has been solved, and the submitter has been given a patch or other fix. The PR remains in this state until the submitter acknowledges that the solution works.
The problem has been confirmed as being solved in -current but needs pullup requests for the appropriate active branches need to be filed with releng. The PR remains in this state until the pullups are requested.
The problem has been confirmed as being solved in -current and pullup requests for the appropriate active branches have been filed with releng. The PR remains in this state until the pullups are completed. The pullup ticket numbers should be entered as part of the state change message so the progress (or lack thereof) can be tracked.
Work on the problem has been postponed. This happens if a timely solution is not possible or is not cost-effective at the present time. The PR continues to exist, though a solution is not being actively sought. If the problem cannot be solved at all, it should be closed rather than suspended.
Work on the problem has been permanently abandoned. This state is for problems where there is no possible way to continue examining the PR, e.g. someone reported that their machine crashed once, in an old version of NetBSD, and could never reproduce it; someone no longer has the hardware needed to reproduce the problem. The purpose of the "dead" state, as distinct from the "closed" state, is so that people searching the database can quickly ascertain that a problem is not known to be fixed.
A Problem Report is closed ("the bug stops here") only when any changes have been integrated, documented, and tested, and the submitter has confirmed the solution.
[Pagetop] [QueryPR] [SendPR] [GNATSsummary]