#ident "ide/IP30/README.conventions: $Revision 1.1$"
IP30 convention file
The intent is to have a (short) list of conventions that diag programmers
would follow in order to write new diags and understand better other
programmers' code; this could also be refered to by any programmer
new to ide.
One is welcome to add to it.
general guidelines:
===================
-keep ide small (trim)
comments:
=========
- avoid speedracer and T5, use IP30 and R5000/R10000 instead
- use XXX to mark areas that need more attention
documentation:
==============
- put/update all information in each function header
- presentation doc (maker etc.) in separate dir under IP30
- plans are checked in the tree under "Plan", in the appropriate directory
all files:
==========
- add an ident line at very top. Traditionally we have only added revision
information, but somepeople like to use filename or even rlog info.
for instance:
#ident "$Revision: 1.8 $"
will expand to
#ident "$Revision 1.1$"
when checked out.
- for new files, insert the copyright box
(from clyde:/depot/sgi_info/templates, template.c, template.h,
and template.sh files)
- list of items to do or double-check
- use the beginning of the file name to describe what ASIC is involved:
for instance, ecc_ for ECC related files
new files:
==========
- keep in mind the fact that the code that is to be included into
the field ide should be kept in a separate file so that *only*
this code gets loaded from the library.
- if copying code from another branch, copy the RCS file too on the source
machine in order to save history.
header files:
=============
- at the beginning of each file, use
#ifndef __HEADERFILENNAME_H__
#define __HEADERFILENNAME_H__
at the end
#endif /* __HEADERFILENNAME_H__ */
with double underscores at the beginning/end.
The purpose of those ifdefs is to prevent the same file from being
included multiple times. The double underscore is simply a
convention that keeps the name __HEADERFILENNAME_H__ from colliding
in the compiler namespace.
- all diag header files in ide/IP30/include and ide/godzilla/include
- refer to registers defined in irix/kern/sys irix/kern/sys/RACER (standing for
speedracer specific headers), stand/arcs/include, irix/include,
irix/kern/sys/xtalk.
- define D_reg_name as a value for reg_name used in diags.
controlling diagnostic verbosity:
=================================
- ide provides various levels of verbosity, which can be controlled on
the user command line by typing
>> $report=N
where N is one of six levels of verbosity:
val macro Description
--- --------- ------------------
0 NO_REPORT No reporting -- can be used to disable printing to the
screen for scope loops, etc.
1 SUM Summary -- used to print test results summary
2 ERR Error -- used to indicate that a particular test has
failed. This setting does several things in addition
to printing the test error message:
1. This setting will change the color of the system LED
(on Indigo/Indy/Indigo2 systems) to YELLOW,
indicating failure.
2. Preced the test error message with the string
"\r\t\t\t\t\t\t\t\t- ERROR -\n"
3. Print the test error message, e.g.
"Secondary Cache Address Line test failed"
3 INFO Info -- used to print informative messages as the test
executes
4 VRB Verbose -- Prints verbose error and status messages
5 DEBUG Prints out debug messages (used during development)
- In your test, the syntax to include print messages at various levels
of verbosity is:
msg_printf(report_level, "%s: Text string\n", test_name);
where report_level is one ot the verbosity macros defined above:
SUM, ERR, INFO, VRB, or DEBUG
functions:
==========
- use the beginning of the file name to describe what feature is involved:
for instance, ecc- for ECC related functions
std function frame:
===================
- the function frame is *the* source of all documentation.
provide as much information as possible:
/*****************************************************************************
* Function Call:
* Description:
* Inputs:
* Outputs:
* Return Value:
* Error Handling:
* Side Effects:
* Remarks:
* Debug Status:
****************************************************************************/
macros:
=======
- create a macro when sure that it be called a small number of times, else use a function. This is to keep ide small.
editing:
========
- do not use the mouse buffer for file editing (all tabs are replaced by spaces).
FRUs:
=====
- We need to keep in mind what the FRUs are so that we don't design a module
that does not differenciate between FRUs (unlikely, since the FRUs are
so big).
list:
* CPU module
* system board
* system backplane (may require SSE for this one?)
* gfx board (one piece?)
* PCI expansion card
* other cards
addressing
==========
- we should use compatibility space where appropriate (i.e. for the
memory mapped IO stuff, when accessing heart and bridge),
i.e. PHYS_TO_COMPATK1(physical address).
The rationale for using compatability space on the R4K/R10K in 64-bit mode
is to save on address construction time where we could.
The down side is you need to make sure your phys addr fits in the compat
space, and you don't try to do other operations (KDM_TO_PHYS) on it.
When using this in assembly, the CLI macro should be used instead of LI
to load the constant address.
NOTE: In the docs, the K1 segment information is refered to as ckseg1.
returned values:
================
- all top-level functions (i.e. callable from the ide prompt) should use
REPORT_PASS_OR_FAIL. The internal functions may use 0/1 or d_errors
depending on the case.
