Introduction to FSW Documentation

Introduction to FSW Documentation

Overview

The FSW documentation provides access to a diverse and constantly-changing set of information. Some of our documents (e.g., tutorial web pages and formal documentation) are edited manually. Most, however, are derived (i.e., mechanically generated) from other sources of information. As a result, they tend to stay current without active manual intervention.

Most of our documentation is accessible through the web, so the remainder of this tutorial walks through the main FSW web page, section by section.

People

This section provides links to useful management contacts, as well as "The Team", a page that provides information on FSW group members and associated personnel.

Documentation

This section provides links to information on FSW documentation.

The FSW Search Tool provides full-text indexing of FSW web pages, PDF files, etc. It supports Boolean expressions and data-source selection, allowing very precise specification of desired attributes.
The Glossary of Terms attempts to track the many acronyms and specialized terms that FSW uses. Please report any errors or omissions to fsw-web.
You are, of course, reading the "Introduction to FSW Documentation" page. The "Introductions, by topic" section (see below) includes tutorial introductions to various FSW-related topics. The "Overview" tutorials will be useful to anyone who is interested in the FSW effort; other tutorials cover more specialized topics.
The LATDocs repository stores the official documents of the LAT. These are formal statements of LAT specifications, design approaches, etc. The FSW Document Indexes show an FSW-specific subset (arranged by document number or topic), which are of particular relevance to the FSW group. The interactive LATDocs query page allows searching of the entire LAT document collection.
Traveler documents are so named because they "travel" with a given package. User and/or programming manuals are typical examples. The Traveler (package-specific) Documents page provides access to current production versions of these documents, organized by package and project.

Introductions, by topic

These pages provide tutorial introductions (with links to supplementary information) to the goals, resources, and general approach taken by the group. Please review these, before jumping into the other documents:

Flight Software
- Overview - goals, working environment, and organization of the flight software
- Entities - annotated diagram of the principal FSW entities
- CPU Usage - CPU usage notes: EPUs, SIUs, etc.
- Event Filtering - goals and organization of the "event processing" software
Design Philosophy
- Overview - Risk Management, Flexibility, ...
- Memory Leaks - Allocation, Bad Pointers, ...
Development Concepts
- Overview - file management, computer facilities, the development process, ...
- Build Matrix - projects, packages, constituents, files, tags, ...
- File Tree - where everything resides
Development Tools
- Overview - CMT, CMX, CVS, Doxygen, GCC, Graphviz, ...
- CMX - the FSW approach to (semi-)automated code management
- Doxygen - the FSW approach to (semi-)automated code documentation
Document Mechanization
- Overview - objectives, constraints, and design decisions
- Data Flow - how the scripts and files are used
- Diagrams - annotated index of auto-generated diagrams
- #DDF Entries - #DDF Entry Format

Entities

As discussed in the "Entities" tutorial, the FSW group must deal with a substantial number of entities: Requirements, Functions, Tests, Tasks, etc. This section provides pages, where possible, for each instance of each entity. The pages have links to related entities and diagrams showing how a given entity fits into the scheme of things.

Projects, Packages, Constituents, etc.

This area contains most of the FSW web pages. Each Constituent and Interface have multiple pages. All told, there are a few thousand web pages. Fortunately, there are only a few kinds of web pages.

Doxygen
The Doxygen pages are generated from the FSW source code, augmented by specially-formatted comments. Doxygen produces pages for each Constituent/Tag combination, covering data structures, files, interfaces, etc. These pages are indexed in the Doxygen Main Index page, but they are also reachable from the Constituent pages (see below).
Message Code Lookup
The FSW MSG facility encodes assorted information into 32-bit values. Although the code for a given condition tends to remain constant, some details may change between FSW releases. This page allows users to look up all variants of this information, based on a particular code.
The FSW Hierarchy (Package "use" Trees, etc.)
As described in the FSW Build Matrix and FSW File Tree tutorials, the FSW source code base is structured as a hierarchy:
The FSW web pages provide views into several levels of this hierarchy:
- Each Project page (e.g., DAQ) describes the purpose of a particular project. It also lists the included packages, giving short descriptions and links to their Package pages. A project-specific "use" summary provides a pictorial view of the manner in which the project's packages use (and are used by) other packages.
- Each Package page (e.g., CBIO) describes the purpose of a particular package. It also includes a package-specific "use" tree and links to diagrams showing the relationships between the package's Constituents and Interfaces, by Tag. Finally, the page includes links to the relevant Project and Doxygen package index pages, to Doxygen pages for included constituents, to test status pages, and more.
- Doxygen pages cover constituents and files, combining programmer comments with mechanically-derived information (e.g., calling trees, data structure descriptions). See the Doxygen Tutorial for more information.
Several forms of navigation are available for the Project, Package, and Doxygen pages:
- The Doxygen Main Index (described above) displays the currently available versions of each package. Links on this page (e.g., LCB:dev) lead to more specialized pages, displaying links for the available constituent/tag combinations.
  Each of these links, in turn, leads to a Doxygen navigation page, covering a specified "package, version, constituent, tag" combination. Once on this page, you can view the constituent's "Interface", "Compound List", "File List", "Compound Members", or "File Members". A great deal of information is available on these pages, gleaned from both build information and programmer commentary.
- The Package "use" tree begins with a diagram, showing most of the available packages (a few common packages are omitted, for clarity) and indicating how they "use" each other. Each oval is a link to the corresponding Package page. A "Legend" table (located below the diagram) provides short descriptions of packages and links to pages for all current packages and projects.
  An alternate form of this page colors each node, according to its Project. A set of colored icons, below, leads to the corresponding Project pages. Finally, there is a set of time-lapse animations, showing the development of the "use" tree, over time. For more information, see the "use" tree tutorial.
- Three sorted lists provide access to Doxygen pages for particular constituent/tag combinations.

Telecommand and Telemetry Packets

Telemetry and telecommand packets provide the principal external interface to the flight software. From FSW's perspective, (tele)command packets are (mostly) received from the spacecraft and handed off to the appropriate task(s) for processing. Telemetry packets are generated by certain tasks, possibly in response to a telecommand, and sent to the Spacecraft.

These web pages (along with an accompanying PDF version) document the purpose and structure of FSW-related packets, fields, etc. Eventually, they will also document connections to other entities, such as requirements, tests, and packages.

Each packet has its own web page. This page describes the packet, shows its layout, and describes any packet-specific fields. Ancillary pages describe function codes, header formats, etc. These web pages are extensively cross-linked. In addition, index pages provide context and aid in navigation to specific items. For more information, see the Packet Navigation tutorial.