MULTICS TECHNICAL BULLETIN MTB-655
To: MTB Distribution
From: Gary C. Dixon
Date: May 7, 1984
Subject: Multics Software Development Guide: An Outline
This MTB proposes that a new manual, the Multics Software
Development Guide (or Dev Guide for short) be written to replace
the current Multics Standards SDN (Order No. AN82). The
audience for the new manual are people writing software for
installation in the Multics System Libraries. Its purpose is to
document standards and techniques for developing correct,
efficient, easy-to-use, easy-to-maintain software for Multics.
The MTB proposes that the Dev Guide be drafted by members of the
Multics Standards and Techniques Committee (MSTC) and other
interested individuals; and that it will be edited by a member of
the documentation unit to unite the individual sections of the
manual into a coherent whole. The manual will be reviewed
several times as it is being written to give everyone who does
system programming work on Multics a chance to participate in the
standards development process.
The MTB is being written by the Multics Standards and Techniques
Committee (MSTC) to gain wider review of their proposed plan to
rewrite the current Standards SDN. You are asked to review and
comment upon the proposals. Comments should be entered via forum
in:
Forum Meeting: >udd>m>meetings>propose_standards (pstd)
(currently a version 1 forum meeting)
System: M
Chairman: GDixon.Multics
|
Change bars are used below to indicate differences between the |
published version of this MTB and the final draft version which |
was reviewed in the pstd forum. |
_________________________________________________________________
Multics Project internal working documentation. Not to be
reproduced or distributed outside the Multics Project.
MTB-655 Dev. Guide Outline
CONTENTS
Page
1) Multics Standards and Techniques Committee . . . 1
2) Problems with the Standards SDN . . . . . . . . 2
3) The New Manual . . . . . . . . . . . . . . . . . 3
4) Procedures for Developing the New Manual . . . . 4
5) Outline for the New Manual . . . . . . . . . . . 5
PART I: INTRODUCTION . . . . . . . . . . . . . . . 8
Section 1: Introduction to this Manual . . . . 8
Section 2: The Multics Software Philosophy . . 8
Section 3: The Software Development Process . . 8
Section 4: Project and Release Planning . . . . 9
Section 5: Software Quality . . . . . . . . . . 9
PART II: GUIDE FOR DEVELOPING PARTICULAR TYPES OF
PROGRAMS . . . . . . . . . . . . . . . . . . . . . 10
Section 6: Commands and Active Functions . . . 10
Section 7: Interactive Subsystems . . . . . . . 11
Section 8: ssu_ Requests and Active Requests . 11
Section 9: Interactive Display Programs . . . . 12
Section 10: Other Subroutines . . . . . . . . . 12
Section 11: Exec_coms, Ted_coms, Teco_coms,
etc. . . . . . . . . . . . . . . . . . . . . . 12
PART III: GUIDE FOR SPECIFIC ASPECTS OF SOFTWARE
DEVELOPMENT . . . . . . . . . . . . . . . . . . . 14
Section 12: Program Attributes and Program
Structure . . . . . . . . . . . . . . . . . . . 14
Section 13: Naming Conventions . . . . . . . . 15
Section 14: Management of Data . . . . . . . . 15
Section 15: Handling Errors, Conditions and
Other Events . . . . . . . . . . . . . . . . . 16
Section 16: PL/I Efficiency Techniques . . . . 17
Section 17: Guidelines for Assembly Language
Programming (ALM) . . . . . . . . . . . . . . . 17
Section 18: Methods of Improving Quality . . . 18
Section 19: Online Info Segment Documentation . 18
Section 20: Documentation in Manuals . . . . . 19
PART IV: SPECIAL PROGRAMMING ENVIRONMENTS . . . . 20
Section 21: Techniques and Standards for
Writing I/O Modules . . . . . . . . . . . . . . 20
Section 22: Techniques for Writing Translators 20
Section 23: Techniques for Writing Gates and
Inner-Ring Programs . . . . . . . . . . . . . . 20
Dev. Guide Outline MTB-655
CONTENTS (cont)
Page
Section 24: Techniques and Standards for
Hardcore Supervisor Programs . . . . . . . . . 21
APPENDICES: . . . . . . . . . . . . . . . . . . . . 21
Appendix A: Table of Registered Names . . . . . 21
Appendix B: System Databases . . . . . . . . . 21
Dev. Guide Outline MTB-655
1) MULTICS STANDARDS AND TECHNIQUES COMMITTEE
The Multics Standards and Techniques Committee (MSTC) is charged
with revising and maintaining the programming standards and
techniques used in Multics system software.(1) The standards are
currently maintained and documented in the Standards System
Designers' Notebook (Standards SDN, Order No. AN82-00).
The committee was created late in 1982 to address the lack of
software development standards for Multics. The Standards SDN
was last published in June 1980, and most of the information in
that edition dates back to the 1976 MTB-291 by Ellie Donner
titled "Draft Programming Standards and Documentation Guide PLM".
The committee found the manual extremely out-of-date, and so
undertook the task of piecemeal updating of the manual, using the
procedure outlined in MAB-055.
That procedure failed to produce any significant improvement in
the Standards SDN. Only a few changes were ever proposed, fewer
still were voted upon by MSTC and none ever made it into an
addendum for the manual. The committee withered primarily due to
the hopelessness of this futile approach for piecemeal updating
of the manual. As a prime designer of the procedure which
failed, I take major responsibility for this failure.
Late in 1983, the increasing corporate and IS emphasis on quality
coupled with the scheduling and quality problems we had with
MR10.2 forced management to face the issue of software
development standards, once again. At the All Multics Managers
meeting in January, 1984, a variety of task forces were set up to
review and document current MDC procedures. The managers agreed
that a usable set of development standards were essential. To
address this need, the MSTC was reactivated. Current committee
members are:
Noah Davids, End User Services Unit
Gary Dixon, Chairman, Software Support Unit
Steve Herbst, Language and Database Management Unit
Chris Jones, Hardcore Unit
Tom Oke, ACTC
Gary Palter, Communications and Networking Unit
Roger Roach, MIT
_________________________________________________________________
(1) For details about the origin and charter of the MSTC, see:
MTB-519, "Documenting System Programming Techiques",
4/7/81 by Gary Dixon
MAB-055, "Multics Standards and Techniques Committee",
8/3/82 by MSTC Members
MTB-655 Dev. Guide Outline
One of the first steps of the reactivated committee was to
consider why the previous committee had failed. The main reason
for the earlier failure was that the magnitude of revisions and
enhancements needed for the Standards SDN was too large to be
handled by proposing new standards one-by-one under the procedure
in MAB-055.
Based upon this analysis, the committee embarked upon the new
approach of wholesale revision/rewriting of the Standards SDN.
The committee is currently working on this revision now.
2) PROBLEMS WITH THE STANDARDS SDN
The current Standards SDN suffers from a variety of problems.
Some of the more notable problems are:
o There are no standards covering use of newer software
facilities (eg, ssu_, video environments).
o The manual is poorly organized, making it difficult to use
as a reference guide, and difficult to determine what
information is present or missing from the manual. Some
topics are discussed in several sections, rather than
grouping similar information together in a single place.
o Major aspects of software development are ignored by that
manual (eg, a description of the software development
process itself, standards and techniques for testing and
auditing).
MSTC members and others who commented on the problems with the
Standards SDN (see the pstd forum chain beginning at [178])
agreed that these problems were insurmountable within the
constraints of the current SDN's organization and stated purpose.
Therefore, MSTC is proposing to write an entirely new manual to
replace the Standards SDN.
Dev. Guide Outline MTB-655
3) THE NEW MANUAL
On April 3, 1984 MSTC voted during a teleconference to accept the
following description for the manual to replace the Standards
SDN:
TITLE:
Multics Software Development Guide
SHORT NAMES:
Development Guide or Dev Guide
AUDIENCE:
People Writing Software to be Installed in the Multics
System Libraries
PURPOSE:
To document techniques and standards for developing
correct, efficient, easy-to-use, easy-to-maintain
software in Multics.
This proposed description of the Dev Guide was formulated during
discussions in the vote_on_standards (vstd) forum, and I refer
the reader to the vstd forum chain beginning at [147] for
details. The main points of discussion were whether the manual
should address a wider audience (such as that proposed by
Margulies in pstd [194]), and whether the terminology used in the
statement of purpose was too vague (ie, terms such as
"standards", "techniques" and "developing software" are not well
defined).
On the audience issue, MSTC felt that the committee was created
solely to deal with a lack of standards for people writing
software to be installed in the Multics System Libraries (eg,
ACTC, MDC, MIT, third party vendors). This group might be called
System Library Developers. Therefore, the committee's efforts
should be devoted primarily to the manual which best serves the
System Library Developer audience. MSTC feels certain that the
resulting Dev Guide will benefit other people developing software
on Multics, as well. However, writing a new manual to serve a
far broader programming audience would be more difficult and
time-consuming. And such a broadly-directed manual would not
adequately serve the needs of System Library Developers.
On the terminology issue, MSTC felt that is possible to define
the structure of the proposed Dev Guide based upon the
committee's current understandings of these terms; and that the
terms can be more exactly defined in one of the early sections of
the manual, which will be written and agreed upon early in the
writing schedule.
MTB-655 Dev. Guide Outline
4) PROCEDURES FOR DEVELOPING THE NEW MANUAL
An outline for the new manual is proposed below in section 5 of
this MTB. The outline shows a manual divided into sections, each
of which deals with a particular aspect of Multics software
development. The following procedure will be used in drafting
these sections, reviewing them, approving them and incorporating
them into the new manual.
Step 1, WRITING:
The writing of each section of the Dev Guide will be
assigned to one or more people. Ideas will be gathered from
the current Standards SDN, from the standards that were
proposed to or adopted by the earlier MSTC, from discussions
in the pstd, vstd and other Multics forum meetings, from
discussions with other developers, from current literature
on Software Engineering and Development, from the results of
the various All Manager meeting task force teams, etc.
Step 2, REVIEW:
Once the first draft of a section is completed, the authors
will make it available for review by announcing its
existence in the pstd forum. Essentially, the author will
be proposing the draft section as a new standard.
Commenting can then occur in pstd, via mail, telephone or
personal conversations, etc. Based upon the level of
comment and controversy, the author may decide to do further
writing (return to Step 1), to hold a formal Design Review
to resolve outstanding issues, or to proceed directly with
Step 3.
Step 3, UPDATE AFTER REVIEW:
The author will incorporate review comments into the draft
section, and announce the final draft in pstd. People will
have a chance to comment in pstd on this final draft, in an
effort to influence MSTC committee members approval or
rejection of the draft section.
Step 4, VOTING:
When several final drafts are available, the MSTC Chairman
will call for individual votes in vstd to accept or reject
each final draft. Voting will be based primarily on the
technical content of the draft (as opposed to the grammar
used, etc). In the case of rejection, MSTC will describe
what changes would make the section acceptable for approval;
the author will be asked to make these changes and to
resubmit the draft for voting again (return to Step 3).
Dev. Guide Outline MTB-655
Step 5, EDITING:
Approved sections of the manual will be given to a Technical
Writer to incorporate into the new manual. The Technical
Writer will make sure proper grammar is used, and will
format the information according to the formatting
conventions established for the manual as a whole. This
will help give the manual a coherent flow.(1) |
|
In addition, the author of the section will submit the |
approved sections for publication as an MTB. This will make |
the new information more widely available, and will allow |
people to begin informally following the new standard. |
Step 6, FINAL VOTING:
When editing of each section is completed, the Technical
Writer will ask for review of the section in pstd to insure
that intent of the original information is maintained in the
edited section. MSTC will then vote to approve the editing
section for incorporation into the manual, or will ask the
Technical Writer to make appropriate changes to section
(return to Step 5).
Step 7, PUBLICATION:
When an adequate number of edited sections have been
approved, the first revision of the new manual will be
published for use by System Library Developers and others.
Subsequently approved sections will be added to the manual
as addenda.
Step 8, MAINTENANCE:
We can expect minor problems, omissions, etc in the
published sections of the manual. These will be dealt with
by proposing changes to the manual in pstd, using the
procedures for approval described in MAB-055. This ongoing
maintenance process will become the steady-state duty of the
MSTC once all sections of the new manual have been
published.
_________________________________________________________________
(1) The formatting conventions for the manual have not been
established yet. Part of MSTC's job in the next month
or so will be to set these formatting conventions. We
feel such conventions are an essential mechanism in
clearly distinguishing between recommendations and
required standards. They will also be helpful in
insuring that the manual discusses why a
recommendation/standard has been set, as well as
defining what it is.
MTB-655 Dev. Guide Outline
5) OUTLINE FOR THE NEW MANUAL
This section describes the outline for the Dev Guide, as it is
now envisioned. The guide is divided into four parts: an
overview of software development; standards for specific types of
programs; standards for specific aspects of programming, and
standards for special programming environments. Each part is
composed of several sections, where each section covers a single
topic.
The outline below describes the titles for each major part and
section of the manual. After the top-level outline, each part or
section is described in more detail, including: a title; a brief
description of the content of the part or section; some possible
major paragraph headings for the sections; and the name of the
person or persons currently assigned to write the section.
Dev. Guide Outline MTB-655
TOP-LEVEL OUTLINE
PART I: INTRODUCTION
Section 1: Introduction to this Manual
Section 2: The Multics Software Philosophy
Section 3: The Software Development Process
Section 4: Project and Release Planning
Section 5: Software Quality
PART II: GUIDE FOR DEVELOPING PARTICULAR TYPES OF
PROGRAMS
Section 6: Commands and Active Functions
Section 7: Interactive Subsystems
Section 8: ssu_ Requests and Active Requests
Section 9: Interactive Display Programs
Section 10: Other Subroutines
Section 11: Exec_coms, Ted_coms, Teco_coms, etc.
PART III: GUIDE FOR SPECIFIC ASPECTS OF PROGRAM
DEVELOPMENT
Section 12: Program Attributes and Program Structure
Section 13: Naming Conventions
Section 14: Management of Data
Section 15: Handling Errors, Conditions and Other Events
Section 16: PL/I Efficiency Techniques
Section 17: Guidelines for Assembly Language Programming
Section 18: Methods of Improving Quality
Section 19: Online Info Segment Documentation
Section 20: Documentation in Manuals
PART IV: SPECIAL PROGRAMMING ENVIRONMENTS
Section 21: Techniques and Standards for Writing I/O
Modules
Section 22: Techniques for Writing Translators
Section 23: Techniques for Writing Gates and Inner-Ring
Programs
Section 24: Techniques and Standards for Hardcore
Supervisor Programs
APPENDICES:
Appendix A: Table of Registered Names
Appendix B: System Databases
MTB-655 Dev. Guide Outline
PART I: INTRODUCTION
The first part of the manual:
- gives an introduction to the manual itself,
- describes the Multics software philosophy;
- describes the software development process;
- describes how software releases and major software projects
are defined and prepared; and
- defines major terminology used throughout the manual.
Section 1: Introduction to this Manual
This section describes the intent of the manual (ie, its
purpose, intended audience, organization) and suggests how
it should be used (ie, primer or reference usage). It also
describes formatting conventions used throughout the manual,
and defines two major terms: standards and techniques.
WRITERS: (no one yet assigned)
PARAGRAPH HEADINGS:
Purpose of this Manual
Standards vs. Techniques
Organization of the Manual
Formatting Conventions
Use as a Primer
Use as a Reference Guide
Section 2: The Multics Software Philosophy
This section reviews major goals and overall philosophies
used in Multics software. This would include philosophy
statements from early Multics design papers (eg, ideas from
Multics: The First Seven Years by Corbato'). It should also
include a brief overview of system organization (ring
protection, organization of supervisor, ring 1, ring 2 and
user ring environments, etc).
WRITERS: (no one assigned yet)
PARAGRAPH HEADINGS: (none formulated yet)
Dev. Guide Outline MTB-655
Section 3: The Software Development Process
This section describes the overall process of software
development, and defines the major terminology of the
software development process. It is based upon the results
of Greg Baryza's Software Development Process Task Team, and
Frank Martinson's Installation Process Task Team.
WRITERS: Task Team Reports edited by Steve Herbst.
PARAGRAPH HEADINGS:
Problem Analysis
Designing a Solution
Design Review
Design Approval
Implementation
Testing
Auditing
Installation
Maintenance
Error Reporting via TRs and Error Lists
Section 4: Project and Release Planning
This section describes procedures for planning major
software development projects, and for integrating a variety
of such projects into a software release. It is based upon
the results of Paula Wood's Project/Release Planning Task
Team.
WRITERS: Task Team Reports, edited by (no one assigned yet).
PARAGRAPH HEADINGS: (none known yet)
Section 5: Software Quality
This section defines software quality using the Quality
College definitions. It basically gives a recap of the
material given in LCPD's recent Quality College classes.
WRITERS: Gary Dixon
PARAGRAPH HEADINGS: (none known yet)
MTB-655 Dev. Guide Outline
PART II: GUIDE FOR DEVELOPING PARTICULAR TYPES OF PROGRAMS
This major part of the manual describes standards and techniques
applicable to specific types of programs. The follow major
program types are considered:
o commands and active functions
o interactive subsystems
o ssu_ requests and active requests
o interactive display environments (eg, xmail)
o other types of subroutines
o exec_coms, ted_coms, teco_coms, etc.
Each program type differs from other types in the areas shown
below. The section describing each major program type will
highlight these areas of difference.
1) method of invocation (eg, by user via command_processor_, or
by another program)
2) interface specification
- function or subroutine
- input parameter attributes
- output parameter attributes
- method of accessing parameters
3) interaction with its caller, and with the user:
- getting input (eg, command_query_)
- printing output
- reporting errors
4) documentation
- documentation for a manual
- info segments
5) other standards and techniques characteristic of one
particular program type.
The sections in this part of the manual will try to
highlight the differences between these major program types,
as well as discussing standards and techniques which pertain
to only one of the program types.
Dev. Guide Outline MTB-655
Section 6: Commands and Active Functions
This section will describe proper methods of writing a
command, an active function, and a procedure which operates
as both a command and an active function.
WRITERS: Steve Herbst, Gary Palter
PARAGRAPH HEADINGS:
Besides discussing the five areas of difference which
distinguish the various major program types, this section
discusses standards for arguments and control arguments and
well as standards for general argument syntax standards and
conventions. Exact headings are yet to be determined.
Section 7: Interactive Subsystems
This section will describe standards and techniques for
interactive subsystems. Subsystems to be covered include
those which use ssu_ (eg, read_mail, send_mail, forum) as
well as those which do not use ssu_ (eg, qedx, ted, probe).
WRITERS: Gary Palter
PARAGRAPH HEADINGS:
Besides discussing the five areas of difference which
distinguish the various major program types, this section
discusses the following topics:
Interruptability (eg, quit/pi)
Recursiveness
When to use ssu_; when not to
Standards for use of ssu_, including:
Standard Requests
Standard Control Args
Abbreviation Processing
Subsystem Exec_coms
Sample ssu_ Subsystem
Section 8: ssu_ Requests and Active Requests
This section discusses standards and techniques for coding
subsystem requests and active requests. While the discuss
will briefly consider non-ssu_ subsystem requests, it
applies primarily to ssu_ requests and active requests.
WRITERS: Gary Palter, Steve Herbst
MTB-655 Dev. Guide Outline
PARAGRAPH HEADINGS: The 5 areas of difference, plus:
Request Naming Conventions (a crossref to Section 13)
Control Argument Naming Conventions (also a crossref)
Request Documentation
Requests which are Subsystems
Requests Which can be Standalone Invocations
Section 9: Interactive Display Programs
This section discusses standards and techniques for special
interactive display subsystems such as xmail and tutorial.
WRITERS: Noah Davids
PARAGRAPH HEADINGS:
What is an Interactive Display Environment?
Using Windows
window_
window_io_
Handling of asynchronous output.
Menus
Designing Menus
Use of menu_
Section 10: Other Subroutines
This section discusses standards and techniques for
subroutines. The main emphasis is on interface design and
argument standards (including standards for structure
arguments), on subroutine attributes (recursive, reducible,
etc), on error handling, etc.
WRITERS: Steve Herbst
PARAGRAPH HEADINGS:
Basically, the five areas of difference.
Section 11: Exec_coms, Ted_coms, Teco_coms, etc.
This section discusses standards and techniques for
exec_coms, ted_coms, teco_coms and the like which are to be
installed in the system. The main emphasis is on the user
interface, handling of errors, storage of data, commenting,
documentation, etc.
WRITERS: Gary Dixon
Dev. Guide Outline MTB-655
PARAGRAPH HEADINGS:
The five areas of difference, plus some others as yet
undetermined.
MTB-655 Dev. Guide Outline
PART III: GUIDE FOR SPECIFIC ASPECTS OF SOFTWARE DEVELOPMENT
This major section of the guide discusses aspects of software
development which are common to all types of programs. The
intent is to group programming aspects common to many different
types of programs into a single place so the user doesn't have to
hunt through many sections of the guide looking for all
information on a particular topic.
Section 12: Program Attributes and Program Structure
This section describes what attributes programs must have,
and how they should be structured.
WRITERS: Gary Dixon
PARAGRAPH HEADINGS:
General Program Attributes
Reentrant
Transparent
Recursive
Reducible
Interruptable
Program Structure
General Layout of a Program
Software Protection Notice
Change History Comments
Declarations and Include Files
Body of the Program
Ordering of Internal Procedures
Comments
Protection Notice and Change History
Interface Description
External Interfaces
Internal Procedure Interfaces
Overview of Algorithm
Summary of Each Section of Code
Line-by-Line Comments
Comments for Declarations
Program Readability
Indentation
Variable Names
Misuse of Initial Attribute
Modularity
Structured Programming and Data Concealing
Compile Unit Size
Bound Segments
Archiving
Binding
Dev. Guide Outline MTB-655
Section 13: Naming Conventions
This section deals with the standards for naming. All
aspects of the naming issue are covered here rather than in
other sections. Other sections may make crossreferences to
pertinent naming standards in this section.
WRITERS: Roger Roach
PARAGRAPH HEADINGS:
Types of Programs
Commands
Active Functions
Subsystem Requests
Subroutines
Exec_coms, Ted_coms, etc
Arguments
Control Arguments
Commands and Active Functions
Subsystem Requests
Program Source Constructs
Variable Names
Structures
Include Files
I/O Switches
Condition Names
System-defined
Software-defined
Storage System Files
Entryname Suffixes
Value Segment Variables
Section 14: Management of Data
This section discusses standards and techniques for all
aspects of data storage and management.
WRITERS: (no one assigned yet, Lindsey Spratt will collaborate)
PARAGRAPH HEADINGS:
How to Store Particular Types of Data
Temporary Storage
Use by Storage Scope
Internal Data Variables
External Data Variables
Passing Data between Program Modules
Use by Storage Class
Automatic
Based
Controlled
Defined
MTB-655 Dev. Guide Outline
Parameter
Static
Temp Segments
PL/I Areas
System-provided
Application-provided
Use of Process Directory vs. Temporary Directories
Permanent Storage System Files
Read/Only Access to Files In each of these,
Segments | cover issues of:
Archives | initiation,
MSFs | termination,
Read/Write Access to Files > truncation,
Segments | bit counts,
Archives | force_write, etc
MSFs /
Data Bases
Lister DBs
MRDS DBs
DM Files
Inner-Ring Files
Use of inner-ring queues
Use of mailboxes
Access by Dynamic Linking
Reference Names
Access by Pathnames
Handling Star and Equals Conventions
Search Lists
Access Assumptions
Access Control
Per Process or Per System Data Segments
Access by Dynamic Linking
Reference Names
Access by Pathname
Avoid Building Pathnames into Programs
Use of create_data_segment
Use of value segments
| Access Considerations
| Discretionary Access
| Locking for Shared Databases
| Nondiscretionary Access Considerations (AIM)
| Access to System Databases and Gates
Section 15: Handling Errors, Conditions and Other Events
This section discusses all aspects of error reporting,
condition handling, error recovery techniques, etc.
Dev. Guide Outline MTB-655
WRITERS: Matt Pierret, Lindsey Spratt
PARAGRAPH HEADINGS:
Events
Conditions
Errors
Status Messages
Conditions
Cleanup Handlers
any_other Handlers
Other System-defined Conditions
Programmer-defined Conditions
Errors
Types of Errors
Correctable by User
Uncorrectable errors (correctable by system
programmer; errors which shouldn't occur)
Impossible Errors (hardware failure)
Error Reporting Mechanisms
Communicating with the User
Quality of Error Messages
Section 16: PL/I Efficiency Techniques
This section recommends techniques for efficient programming
in PL/I programs. The intent is that it will encompass all
information in Section 8 of the current standards manual,
plus other discussions of efficiency as they are identified.
WRITERS: Gary Dixon
PARAGRAPH HEADINGS:
Those in Section 8 of the Standards SDN, plus others as they
are suggested.
Section 17: Guidelines for Assembly Language Programming (ALM)
This section presents standards and techniques for writing
ALM programs. Besides dealing with general ALM programming,
the section specifically covers coding of transfer vectors
and coding of gates.
WRITERS: Chris Jones
MTB-655 Dev. Guide Outline
PARAGRAPH HEADINGS:
When ALM is appropriate
General ALM Coding Standards and Techniques
Register Usage
Assumptions Made by the Assembler
Variable Naming
Calling Conventions
Coding with Macros
Coding of Error Tables
Coding of Transfer Vector Procedures
Coding of Gates
Section 18: Methods of Improving Quality
This section describes the standards and techniques for
improving the quality of one program or a set of programs.
Topics covered include self-auditing, testing and debugging
techniques, metering and performance analysis, and peer
review auditing. Gary Dixon's proposal for auditing (pstd
[277]) would be used as source material for this section.
WRITERS: Noah Davids
PARAGRAPH HEADINGS:
Self-Auditing of Code by the Programmer
Testing and Debugging Programs
| Special Support Code for Testing
| Setting Up a Testing Environment
| Adding Debugging Code
| Programming Techniques for Probing
Metering and Performance Analysis
Peer Auditing of Code
Section 19: Online Info Segment Documentation
This section describes standards and formatting conventions
for info segments. Included are at least 5 kinds of info
segments: command/af info segs, subroutine info segs,
general info (.gi) segments, changes info segments, and
known error info segments (info segments produced from the
error lists for distribution to sites). Also, info segments
for subsystems are described in this section.
This section also describes the various tools available for
producing info segments (eg, validate_info_seg,
input_info_seg, single-sourcing MPM macros, etc).
WRITERS:
Jim Batts (presumably with input from Lee Baldwin)
Dev. Guide Outline MTB-655
PARAGRAPH HEADINGS: (none known yet)
Section 20: Documentation in Manuals
This section describes the standards and formatting
conventions used for Multics manuals. It will reference all
pertinent HIS documentation standards, and will refer the
user to compose macros used to provide standard formats,
etc.
At the current time, Jim Batts isn't sure if this section
should be written, or when we would be ready to write it.
Our documentation methods always seems to be in a state of
change, making them difficult to use, much less to document.
Jim is investigating.
WRITERS: probably Jim Batts
PARAGRAPH HEADINGS: (none known yet)
MTB-655 Dev. Guide Outline
PART IV: SPECIAL PROGRAMMING ENVIRONMENTS
This major part of the manual describes additional standards and
techniques for programs which must run in special environments
(eg, hardcore programs), or for programs which perform similar
functions (eg, translators).
Section 21: Techniques and Standards for Writing I/O Modules
This section describes standards and techniques for coding
iox_ I/O modules. This section with primarily be a cross
reference to the material in the MPM Reference Guide on
writing I/O modules. However, there may also be additional
standards imposed on System Library I/O modules beyond the
techniques recommended in the Ref Guide.
WRITERS: Gary Dixon
PARAGRAPH HEADINGS: xref to MPM Ref Guide
Section 22: Techniques for Writing Translators
This section describes standards and techniques for programs
which are translators (compilers or interpreters). The
section includes a broad spectrum of material, from
discussion of simple translators written using the
reduction_compiler, to use of LALR and other
compiler-generation techniques for more formal translators.
In addition, it sets standards for our language translators
(PL/I, Fortran, Cobol, Pascal, etc).
Work on this section will probably be delayed until 1985,
when UC can allocate man power in their 1985 plan for this
writing effort.
WRITERS: Brian Westcott and UC Personnel
PARAGRAPH HEADINGS: (none known yet)
Section 23: Techniques for Writing Gates and Inner-Ring Programs
This section describes techniques and standards for writing
inner-ring programs (programs which operate inside the user
ring, but outside of ring 0). Topics will include: writing
gates and gate targets, inner ring access control
conventions, things which don't work as expected in an inner
ring (eg, relative pathnames, initial ACLs), etc.
WRITERS: Gary Palter
Dev. Guide Outline MTB-655
PARAGRAPH HEADINGS: (none known yet)
Section 24: Techniques and Standards for Hardcore Supervisor
Programs
This section describes standards and techniques for
programming in the Ring 0 environment, and also in the
Bootload Multics environment.
WRITERS: Chris Jones
PARAGRAPH HEADINGS: (none known yet)
APPENDICES:
The appendices give quick-reference to list of standard items.
Besides the table of registered names in appendix A, future
appendices might include a flowchart of the software development
process, a checklist for auditing, etc. For now, only one
appendix is being proposed.
Appendix A: Table of Registered Names
This appendix lists registered names for control arguments,
suffixes, I/O switches, conditions, value variables, etc.
Associated with each name is a brief description of its
intended use. For control arguments, this description
includes the standard meaning, sample usage, and a
crossreference to other, related control arguments.
WRITERS: Steve Herbst, Lee Baldwin
PARAGRAPH HEADINGS:
Registered Names
Control Arguments
Suffices
I/O Switch Names
Condition Names
Value Segment Variable Names
Appendix B: System Databases
This appendix gives an overview description of major Multics
system databases which might be accessed by system
programmers, including information contained in the
databases, expected access patterns and access requirements.
WRITERS: (none assigned yet)
MTB-655 Dev. Guide Outline
PARAGRAPH HEADINGS:
I'm not sure how much detail to go into in this appendix,
or which databases should be covered. Some possibilities
are:
Supervisor Databases
active_all_rings_data
dseg
kst
pds
prds
sys_info
time_info_
Administrative Databases
SAT
PNT
URF
PMF/PDT
CMF/CDT
Inner-Ring Databases
Mail Table
User-Ring Databases
Stack
Combined Linkage Area
System Free Area
User Free Area
RNT
LOT
ISOT
TTF/TTT
static condition table (SCT)
value segments