NGIMS-FSW-52-BP NGIMS Flight Software Build Procedures Prepared By: Michael Paulkovich, Lead NGIMS Software Engineer for Hasso B. Niemann, Paul Mahaffy, NASA/GSFC Code 915 Laboratory for Planetary Atmospheres January 17, 2002 Rev 0 Table Of Contents PURPOSE 4 BACKGROUND 4 I. Starting a new release 5 1. CVS Checkout 5 2 Re-establish Executable File Attributes 5 3. Change version numbers in project, library 5 4. Set new version number in "intvec" files 6 5. Create Tartan Ada library 6 6. Make all 6 II. Developing a new feature 8 1. Create CVS branch 8 2. Checkout working directory 8 3. Once working, merge back into main CVS branch 8 4. V&V 8 III. Development and test cycle 9 1. Recompile changes, do first link 9 2. Get the AMB addresses 9 3. Relink 9 4. Programmer tests 9 5. Code review and CVS checkin 9 6. Validation tests 9 IV. Clean release for new load image 10 0. Increment Version 10 1. CVS-review & clean-up 10 2. Build adascope version 10 3. Get AMB addresses 10 4. Final adascope link 11 5. Build firmware version 11 6. Final firmware link 11 7. cvs_review & tag 11 8. Make PROMs 11 9. Testing 13 9.1 Failed any Test 13 9.2 Passed All Tests 13 10. Build Reference Copy 13 11. Create New Library, Repeat 14 12. Burn new Flight PROMs 14 V. Patching Current Version 14 1. Analyze area to patch using Adascope version 14 1.1 Load 14 1.2 Determine Address 15 2. Write patch for Adascope version 15 3. Test patch with Adascope version 15 4. Analyze and patch using Load-Image version 15 5. Write and test patch as TC Patch script 15 6. Write patch as addendum to Alt Boot file 16 VI. Generating Firmware Image 16 1. Generate the Adascope build 16 2. Final firmware link 16 3. cvs_review & tag 17 4. Make PROMs 17 5. Test 18 6. When done testing 18 7. Burn new Flight PROMs 18 VII. Generating Alt Boot Image 19 1. Build Alt Boot Image 19 2. Version, reboot count & checksum 19 VIII. Uploading Alt Boot Image 20 PURPOSE This document provides detailed steps for NGIMS Flight Software Build Procedures. Generation of each new build is documented in WOAs, which are maintained in document NGIMS-FSW-34-WOA. NGIMS/TADS Build Process on inms1, TADS v4.3.2.1 BACKGROUND Host Computer The source files and Ada Compilation system are maintained on Sun computer inms1, a Unix machine with the following uname -a information: SunOS inms1 5.3 Generic_101318-91 sun4m sparc Login Login as gcms. Password is the English language word for the German word Sonde (lower case), followed by a hyphen. Source Files Source files are in /home/ngims/build_x.x.x. The alias ccc changes you to this dirctory. The Concurrent Versions System (CVS) tools are used for most of the configuration and version management. Refer to http://www.cvshome.org. Process Overview WAO# Task 1 Starting a new release 2 Developing a new feature 3 Development and test cycle 4 Clean release for new load image 5 Patching Current Version 6 Generating Firmware Image 7 Generating Alt Boot Image 8 Uploading new FSW ? Type-ins on the host computer are shown in this document in fixed-width Courier Font. I. Starting a new release Usage. This task is to be performed after a version has been released, and work is to continue on a new compilation of the source. 1. CVS Checkout This will pull the latest files from CVS, whatever the tag was. Note that another possibility is to use the -r option to check-out a specific "tagged" revision. See: http://www.cvshome.org/docs/manual/cvs_16.html#SEC122 Then change to that directory: cd build_v.r 2 Re-establish Executable File Attributes chmod a+x set_exes.cmd set_exes.cmd Get out of emacs, cd to build_v.r, get back in emacs. 3. Change version numbers in project, library Edit .adalibrc, createlib.cmd to change version numbers in project, library. E.g.: setprj build_3_8_0_prj setlib build_3_8_0_prj:ngimslib.root WRITE BUFFERS 4. Set new version number in "intvec" files intvec_firmware.asm -- @FFFF (checksum) place 0FFFF intvec.asm -- @FFFF (checksum) place 0AAAA In this way the TM will show AAAA for checksum whenever the adascope (download) version is used. (Otherwise it will show FFFF or the real checksum, once determined for the Alt Boot version.) 5. Create Tartan Ada library createlib.cmd 6. Make all make (this step takes about 15 min) 6.1 Verify rebuild properties Build "firmware" (or Alt Boot) image: make_firmware.cmd (change addresses as per amb_prom_defaults_firmware.asm described later in this doc) makevers.cmd vvrr Sanity Check: ls -l nf_vvrr.xtof [from previous build directory] ls -l nf_vvrr.xtof [from new build directory] (file sizes should be same) Address check: runsim nf_vvrr (displayed addresses should match file amb_prom_defaults_firmware.asm) Complete check: Verify .xtof matches previous build exactly: Prev Version Dump: runsim nf_vvrr dump_vvrr.diff (should be no diffs) DO THE SAME WITH FIRMWARE (ALT BOOT) VERSION II. Developing a new feature Usage. This task is to be performed when multiple programmers are involved in code enhancements, and a new feature (e.g. S/C Potential Compensation) is desired to be developed by one team independently, eventually to be merged in with all teams' efforts. 1. Create CVS branch cvs-review (in directory from which you want to branch) Select CVS | Create Branch Provide branch name (e.g. Working_SEDS) Could cd to the proper directory and cvs tag -b 2. Checkout working directory cd ~/ cvs checkout -d adaptive -r working_adaptive NGIMS_1 Rest as above for new release 3. Once working, merge back into main CVS branch cvs-review build_r.v select CVS | merge working_adaptive Resolve conflicts, commit. 4. V&V Run V&V, Baseline, all appropriate tests (refer to NGIMS-FSW-01, §2.3). III. Development and test cycle Usage. TBS. 1. Recompile changes, do first link make 2. Get the AMB addresses runsim ngims -- automatically does: read("display_config_addresses.cmd") Insert addresses into amb_prom_defaults_adascope.asm Write Buffer! Note that these overlays were originally generated from AMB spreadsheet data generated by the test and cal team. 3. Relink make 4. Programmer tests Test until programmers are satisfied. 5. Code review and CVS checkin emacs cvs-review 6. Validation tests Run V&V suite until test team is satisfied. IV. Clean release for new load image Usage. Perform this task when programmers are satisfied with a new recompiled version of the source code. Preferably, programmers have performed the complete V&V test. The object libraries for the new release must be cleaned, the code rebuilt, and CM steps (CVS) performed. Then new files for PROMs (if for the firmware) and/or for the Alt Boot image will be generated. 0. Increment Version ONLY when releasing a new load image (burning PROM firmware or making an Alt Boot EEPROM image), increment version number in intvec_firmware.asm, near end. Make sure it's never higher than 4919h (see intvec_firmware and NGIMS-FSW-27, "Alt Boot documentation"). 1. CVS-review & clean-up cvs-review Clean up code comments; Document Work Request numbers in cvs change comments. 2. Build adascope version 2.1 Clean library make clean 2.2 make all make all 3. Get AMB addresses runsim ngims -- automatically does: read("display_config_addresses.cmd") Insert addresses into amb_prom_defaults_adascope.asm WRITE BUFFER! 4. Final adascope link make 5. Build firmware version make_firmware.cmd runsim ngims_firmware Put amb addresses in amb_prom_defaults_firmware.asm WRITE BUFFER! Again with new addresses inserted: make_firmware.cmd runsim ngims_firmware read("promcheck.cmd") Take the hex value in R2 and put it at address FFFF in intvec_firmware.asm at the end of the file (label PROMCHK) -- don't forget HEX mode (use leading zero). WRITE BUFFER! 6. Final firmware link make_firmware.cmd runsim ngims_firmware Compare to addresses in amb_prom_defaults_firmware.asm; should not have changed. 7. cvs_review & tag cvs_review Tag from CVS menu e.g. as build_3_v_rr. WAIT! Watch screen for error messages, ok when "(run)" changes to back to ready. 8. Make PROMs (If not making PROMs, but need Alt Boot image see Section VII, then skip down to step 9.) Note that any changes to Ada AMB code requires a MAKE step. Overlays for all AMBs would allow us to not have to do that. a) If purpose of new version was AMB changes or "PROM patch," diff memory with previous build #pppp: i. Prev Version Dump: If NOT previously done: runsim nf_pppp dump_vvrr.diff Analyze the .diff file and understand all diffs. For the AMB review -- iv) print the following: - dump_vvrr.diff - amb_prom_defaults_firmware.asm (to show addresses) - intvec_firmware.lst - config_tables.ads & .adb - qp_config.ads v) build & print for memory map: runsim ngims_firmware From Adascope prompt: .log("nf_addrs_vvrr.log") .read("display_aux_addrs.cmd") quit b) Make unique name for Intel image and associated Tartan files: makevers.cmd vvrr (This will prefix with "nf_" for "NGIMS Firmware" and "na" for Adascope version.) c) Burn PROMs copy .i16 file to fd, load onto prom burner pc transfer file, set version# using Edit mode at address FFFE if not already there burn, install eeproms on breadboard, see that it works set analyzer to see actual prom checksum burn again and set checksum at FFFF make flight PROMs. 9. Testing Run programmer tests, V&V script, Baseline Test, etc. Refer to GSFC/NGIMS-915-FSW-01 (Code 915 FSW Development Procedures), §2.5 ("Flight Software Testing"). 9.1 Failed any Test If any tests fail, the software has to be fixed; then start again from the first event in this task. 9.2 Passed All Tests If all tests pass, the software can be released to users (e.g. for Beta Testing). Continue with task 10 below, and then Procedure VI (for firmware) and/or VII (for Alt Boot). 10. Build Reference Copy Purpose of the "reference copy" - TBS Once done testing, check out reference copy of code from cvs: cd to above where you want the directory (if in build directory, cd ..) cvs -r checkout -d build_v.r.mm -r build_v_r_mm NGIMS_1 cd build_v.r.mm chmod a+w .adalibrc chmod a+w createlib.cmd Edit .adalibrc to add _mm to project name. Edit createlib.cmd to change v.r to v.r.mm and v_r to v_r_mm. WRITE BUFFERS. Rebuild: chmod a+x set_exes.cmd set_exes.cmd 11. Create New Library, Repeat createlib.cmd Do IV. 2.2 through IV. 9. Compare *.i16 -- should be no differences. 12. Burn new Flight PROMs If applicable, the integration team using the FM should burn new Flight PROMs. V. Patching Current Version To implement a software change that is not too "major," the currently compiled release of the software can be "patched." The process involves analyzing the location of the desired change in source code, then a sort of "reverse engineering" for determining the RAM address of the assembly code produced by the compiler for that section of source code. A patch is tested most easily using the "download" (Adascope) version of the software. Since the download version uses a different "kernel" (interrupt vectors and bootstrap), that version differs slightly from the Flight (firmware or Alt Boot) version. The differences (aside from the kernel) are largely only in addresses. Once the patch is debugged satisfactorily, it is re-written (addresses changed) for the "firmware" build and re-tested. 1. Analyze area to patch using Adascope version 1.1 Load Load the Adascope version of the code to be patched into the TADS Adascope 1750 simulator. For this example let's assume the compiled version that is being patched is v3.7.07, and the Adascope load image is na_3707.xtof. type: runsim na_3707 This uses the "runsim" script to invoke adascope1750a and load na_3707.xtof into simulated 1750 RAM. 1.2 Determine Address Disassemble the area of interest (using the .listi Adascope command) and determine the addresses affected. Some code, such as data initialization, is executed during elaboration (Ada program initialization) and one can not use listi to find the address. The elaboration location can still be determined if you know the address of the data being initialized. Download the program to the breadboard, set the logic analyzer on that address, and typically the first write operation to the address will lead you to the elaboration code. Once the addresses to patch are determined we go to the next step, below. 2. Write patch for Adascope version Write the patch (use a patch form from the Sotware Management Plan if desired) and write an Adascope script to load the patch for the Adascope version of the program. 3. Test patch with Adascope version Load the Adascope version of the program into the breadboard via RS-232: debugtgt na_3707 Load the patch script (using the .read Adascope command). Verify by disassembling the area(s) of the patch. Test (.run) the patch. 4. Analyze and patch using Load-Image version Perform similar steps as above, but using the "firmware" version of the build (e.g. nf_3707.xtof); typically the build is loaded into memory via Alt Boot (load v3.7.07 to EEPROM, then perform the Alt Boot). The patch must be loaded via telecommand instead of Adascope script as described below. 5. Write and test patch as TC Patch script * Convert the patch to a SCSim script or GSE script. * If EEPROM is not loaded with the desired Alt Boot version of the program (v3.7.07 in our example), download it. Section VIII describes that process. * Turn on the breadboard; ensure the Alt Boot version is indeed the one running (by verifying Version Number in TM). * Run the script to load the patch. * Test the patch. 6. Write patch as addendum to Alt Boot file Refer to the Release Description Document for v3.7.08 (NGIMS-FSW-47-RDD), which contains a textbook example of this task. The Release Description Document for v3.7.09 (NGIMS-FSW-50-RDD) also contains an example, where a somewhat subtle change to the source code, not easily analyzed via disassembly, is implemented. When the patch is written as an addendum to the Alt Boot file, one must remember to: - set proper FSW Version in EEPROM - set proper version in RAM - set EEPROM checksum. These procedures are documented in the referenced RDDs and in GSFC/NGIMS-FSW-27 (Alt Boot Description). 7. Test addendum to Alt Boot file Refer to the test procedures. VI. Generating Firmware Image This procedure is to be run when PROM firmware chips are to be burned. 1. Generate the Adascope build Follow procedures for generating the Adascope build in section IV, then: make_firmware.cmd runsim ngims_firmware Put amb addresses in amb_prom_defaults_firmware.asm. WRITE BUFFER! make_firmware.cmd runsim ngims_firmware read("promcheck.cmd") Take the hex value in R2 and put it at address FFFF in intvec_firmware.asm at the end of the file (label PROMCHK) -- don't forget HEX mode (use leading zero). WRITE BUFFER! 2. Final firmware link make_firmware.cmd runsim ngims_firmware Compare to addresses in amb_prom_defaults_firmware.asm; should not have changed. 3. cvs_review & tag cvs_review, tag from CVS menu as e.g. build_3_v_rr. WAIT! Watch screen for error messages, ok when "(run)" changes to back to ready. 4. Make PROMs Note that any changes to Ada AMB code requires a MAKE step. Overlays for all AMBs would allow us to not have to do that. a) If purpose of new version was AMB changes or "PROM patch," diff memory with previous build #pppp: i. Prev Version Dump: If NOT previously done: runsim nf_pppp dump_vvrr.diff analyze the .diff file and understand all diffs. For the AMB review -- iv) print the following files: dump_vvrr.diff amb_prom_defaults_firmware.asm (to show addresses) intvec_firmware.lst config_tables.ads & .adb qp_config.ads v) build & print for memory map: runsim ngims_firmware .log("nf_addrs_vvrr.log") .read("display_aux_addrs.cmd") quit b) Make unique name for Intel image and associated Tartan files: makevers.cmd vvrr (It will prefix with "nf_" for "NGIMS Firmware" and "na" for Adascope version.) c) Burn PROMs * copy .i16 file to fd, load onto prom burner pc * transfer file, set version# using Edit mode at address FFFE if not already there * burn, install eeproms on breadboard, see that it works * set analyzer to see actual prom checksum * burn again and set checksum at FFFF * make flight proms. 5. Test Test the PROMs in the breadboard FC. 6. When done testing Check out reference copy of code from cvs: cd to above where you want the directory (if in build directory, cd ..) cvs -r checkout -d build_v.r.mm -r build_v_r_mm NGIMS_1 cd build_v.r.mm chmod a+w .adalibrc chmod a+w createlib.cmd Edit .adalibrc to add _mm to project name. Edit createlib.cmd to change v.r to v.r.mm and v_r to v_r_mm. WRITE BUFFERS. Rebuild: chmod a+x set_exes.cmd set_exes.cmd createlib.cmd Do steps IV. 2.2 through IV. 6. Compare *.i16 -- should be no differences. 7. Burn new Flight PROMs Integration team using the FM should burn new Flight PROMs if applicable. VII. Generating Alt Boot Image This procedure is to be run when an Alt Boot image is to be generated for upload to EEPROM. 1. Build Alt Boot Image For "Alt Boot" aka EEPROM CTB (Copy-Table Boot) Load Image from (e.g.) nf_3322.xtof is created as follows: runsim nf_3322