170 lines
5.7 KiB
Plaintext
170 lines
5.7 KiB
Plaintext
#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.
|