LDS7000 FIRMWARE VERSION CONTROL

lds7kFwVc.doc

Updated: 2011-11-14

Synopsis: describes the LDS7000 version control design, implementation, and use.

This document contains hyperlinks, which target both local and remote sites and documents. By default, Word requires Ctrl+click to follow a link. You can change to simple click (like browser) by Office button > Word Options > Advanced > Editing Options: uncheck "Use CTRL + click to follow hyperlink". You will also find hyperlink movement easier if you add buttons to Word's toolbar by Office button > Word Options > Customize > Choose Commands From All Commands : Back, Forward, and Document Location.

References:

Topics:

NETWORK URL

Many of the open source programs are configured to point to a repository URL. Our shared repository is located under "\\Corpgroup\AUI$" (aka "(AUI$)\\Corpgroup") which is not a legal URL. In Windows this must be mapped to a drive letter and this letter used instead. However, there is no agreement on what this letter should be. DJ maps it to S, YB to K, David McCracken to M. Throughout this document, M is used. You should substitute your own mapping.

To determine or set the mapping on your computer, right click "My Computer" and select Map Network Drive.

REALLY QUICK START

This assumes that you have already installed the MIPS Navigator ICS.

Drive M is used here for \\Corpgroup\AUI$. You should use the correct drive letter for your computer.

SUBVERSION, TORTOISE, ECLIPSE

Subversion is one of the major version control systems in use today, being used on thousands of open source and commercial projects. It is essentially a specialized database manager with a well defined API enabling a variety of user interfaces to be developed by anyone. One UI is the command line client, which is often mistaken as "Subversion" when it is really just the lowest level means of accessing a Subversion database short of writing a program directly to the API. TortoiseSVN provides a GUI interface integrated into Windows Explorer, which makes it very convenient to use. Eclipse Subversive-SVN is a plug-in that serves the same purpose in the Eclipse environment that TortoiseSVN serves in the Windows Explorer environment. All of these UI alternatives are mutually compatible. A Subversion database can be created, maintained, and used by all of them simultaneously.

Many version control systems are designed around the notion of a main trunk of development with occasional temporary branches of development. Subversion is recursive. Any branch can serve as the parent of a new branch, obsoleting the notion of trunk and branch. An original "trunk" may be the focus of most work at first but be eventually superseded as the focus by some later branch. Subversion's recursion makes this infinitely possible without disturbing the existing database design.

Other version control systems capture a version as an operation applied to a code branch. Subversion sequentially numbers every state change of the entire repository, in effect assigning a version number to every change. This could be used to identify released (internally and/or externally) versions on every branch. However, this is potentially confusing because the version number in one branch changes due to code changes in other branches. Subversion supports a more traditional notion of versioning using recursion. To capture a version of a code set, a branch is created from that code set.

There is no difference between a branch created to capture a version and one created to begin a new line of development. Where the limitations of other version control systems implicitly impose order, order in Subversion must be explicitly stated and maintained by the users. Some literature suggests dividing the repository into Trunk, Branch, and Tag folders. Trunk is a folder that contains code under development. Branch contains folders that are semi-independent of the Trunk code. Tag contains version captures. These names are misleading. Everything in the repository is a branch and every branch is potentially a trunk and a branch. Every branch is inherently "tagged".

REPOSITORY DESIGN

In our repository design, the root and Alt branches represent active alternative program designs. Under each are three folders, Src, Ver, and Alt. Src contains the HEAD revision of the code for that branch. Ver contains version capture branches. Alt contains alternative program designs. Src, Ver, and Alt correspond to the Trunk, Tag, and Branch folders suggested by some literature. Alt is recursive; the root is essentially the top level Alt branch.

Only Src folders contain code under active development. Programmers check out and commit to Src. Since every Alt branch has a Src folder, there can be many semi-independent coding venues. No branch is inherently the "main" one. Any folders under Src are part of the program and not elements of the repository. To capture the current version of the code in Src, the Src branch is duplicated in a new branch under Ver. Ver contains only these branches, which may be given any name but are normally named by sequential number. These version branches are archives; the code files in them should not be modified.

Released programs must be built only from code checked out of a version branch. Typically, a released version represents a static condition that does not change for the life of the project. However, sometimes customers go to considerable effort to qualify and accept a particular version only to find, sometimes after years of deployment, a bug that must be fixed. They don't want to even think about the other changes in later versions that may fix the bug. To address this, the version branch is rearranged. The version node is duplicated to a Src folder under the node (Subversion and Tortoise can do this without infinite recursion) and then all of the code in the version node is deleted. A Ver folder is created under the version node. The new Src folder is duplicated in a new "0" folder under Ver, freeing the code in Src for further development. This extended version folder is similar to an Alt but it does not contain an Alt because it may not be used as the root of alternative program designs. If a new independent line of development is based on an old version, it should be created as a copy of that version in a new Alt branch. This rule is not dictated by Subversion or our repository design but simply reflects standard practice.

Once a version node has been converted from a static archive to an active development venue, it may not revert to being static. Its Src folder is forever active. The conversion procedure is somewhat complicated. It could be simplified by initially capturing into a versionName/Src, e.g. 2.0/Src. However, this would complicate the routine procedure of version capture because Subversion and its clients don't do multi-level copying. The version folder would have to be created and then the HEAD Src copied to a Src folder under it. Tortoise and Eclipse-Subversion provide no means for doing such a multi-step capture procedure.

Alternative branches are derived from some pre-existing code set to support code differencing, sharing, and merging, but they are independent lines of development. The programmers can maintain complete independence if they chose. Each branch under an Alt folder is essentially a new repository, complete with Ver, Src, and Alt folders, except that the first version captured is actually the code of the source branch. The second capture marks the real beginning of the alternative code set.

The repository begins life with the creation of real directory Svn7kFw at "\\Corpgroup\AUI$\Touch Apps Internal". This is transformed into a Subversion repository (using a command-line or Tortoise function). All of the folders under this are created in the Subversion database and can be seen only through tools like TortoiseSvn Repo-Browser.

The folders Ver, Src, and Alt are created under Svn7kFw. The Unified code set (u0) is copied and committed to the Src folder. Programmers working on the Unified code will check out and commit code only to this folder but first the base code is captured by copying Svn7kFw\Src to Svn7kFw\Ver\2.0. This is now version 2.0 of the Unified code set. The name "U2.0" is used for discussion. It is not part of the database, which identifies the code set as Svn7kFw/Ver/2.0. The program built from this may be released as any name. In the figure, the copy vector from Svn7kFw/Src to Svn7kFw/Ver/2.0 is labeled u0, identifying this particular code set as the initial version of the Unified code.

The folder Polycom is created under Alt. The folders Ver and Alt are created under Polycom. A Src folder is created under Polycom by duplicating either the Svn7kFw/Src or Svn7kFw/Ver/2.0 branch. At this point the two possible sources contain the same u0 code set. Polycom/Src is copied to Polycom/Ver/2.0. This captures the Polycom base code 2.0, which is still the u0 code set.

All of the u0 code files in Polycom/Src are now replaced by the existing PolycomUnified code set (pu0). Polycom/Src is copied to Polycom/Ver/2.1. The figure labels this copy vector pu0, indicating that it is the real initial PolycomUnified code base. For discussion, Polycom/Ver/2.1 is called version P2.1, but this is not recorded in the database.

This process is repeated to capture the Polycom (not Unified) code base. All of the pu0 code files in Polycom/Src are replaced by the existing Polycom code set (p0). Polycom/Src is then copied to Polycom/Ver/2.2. The figure labels this copy vector p0, indicating that it is the real initial Polycom code base. This is called P2.2 for discussion.

The initial release of the Unified program is U2.0. The initial release of the Polycom program is P2.2. Unified programmers may begin changing the code in Svn7kFw/Src and Polycom programmers the code in Svn7kFw/Alt/Polycom/Src without impinging on the released versions or each others' working code. The Polycom code is "derived" from the PolycomUnified code, which is derived from the Unified code only for the purpose of file comparison and merging. Whether, and to what extent, this is actually done is entirely up to the programmers themselves.

The Svn7kFw/Alt/Polycom/Ver/2.0 code is never released. It is the u0 code base, which could have been copied from Svn7kFw/Src or Svn7kFw/Ver/2.0 as well as from Svn7kFw/Alt/Polycom/Src. In fact, it may not be necessary because of the fact that Polycom/Src is created by duplicating Svn7kFw/Src, establishing a file relationship that is probably permanent. However, capturing this as the first version is cheap and ensures a record of the relationship.

Figure 2 shows the repository state after code changes (in Svn7kFw/Src and Svn7kFw/Ver/2.0) and subsequent version captures. In the illustrated scenario, a U2.1 version is captured by copying some new code set in Svn7kFw/Src to Svn7kFw/Ver/2.1. Additionally, the released U2.0 has required a correction that could not be accommodated by the U2.1 version. This situation is relatively rare and its occurrence so soon would be unlikely in reality. However, it may happen occasionally. Until this situation arises, Svn7kFw/Ver/2.0 is an inactive archive. To active it, Svn7kFw/Ver/2.0 is first copied to Svn7kFw/Ver/2.0/Src and then all of the code files in it are deleted. Svn7kFw/Ver/2.0/Ver folder is created. Svn7kFw/Ver/2.0/Src is copied to Svn7kFw/Ver/2.0/Ver/0, capturing version U2.0.0, which is identical to U2.0. The code in Svn7kFw/Ver/2.0/Src is then modified and copied to Svn7kFw/Ver/2.0/Ver/1, capturing version U2.0.1.

Figure 2 shows a simpler, and more common, scenario for the Polycom version. After some changes, the code in Svn7kFw/Alt/Polycom/Src is copied to Svn7kFw/Alt/Polycom/Ver/2.3, capturing version P2.3, which is really the first change to the original Polycom (p0) code.

TORTOISE USE

1. A new working folder requires no special preparation. Just make a folder and right-click either on the folder or inside it (there seems to be no difference) and select SVN Checkout. Be sure that the URL source is the correct repository and branch and that Tortoise hasn't added a level to your destination (which it seems to do randomly).
2. Working folders can be deleted any time you like. There is no centralized record of your checkout.
3. Tortoise seems to have no explicit command to tell the version that has been checked out to a working folder, but you can find out by right-clicking the folder and selecting TortoisSvn > Repo-browser, which opens on the source node in the repository.

This describes how to maintain a working folder that contains some files other than your source code. Eclipse is just one possibility. In this case it is assumed that the Eclipse Subversion plugin is not installed and you are using Tortoise to access the repository. The Unified code HEAD is used for example. It is assumed that you have copied the shared repository M:\Touch Apps Internal\Svn7kFw to C:\Svn7kFw.

1. If checking out the code to an existing project directory, delete all source files (h, c, ld, s).
2. In Windows Explorer right-click on the project directory and select SVN Checkout. Select URL source file:///C:/Svn7kFw/Src. Make sure that the Checkout directory field shows your project directory without additional depth.
3. In Windows Explorer, browse into the project/working directory. Note that all of the checked out source files have a green checkmark but other files have a gray question mark. For Eclipse alone these are .csettings, .settings, Debug and Release. Additional support files may also be here.
4. Select all of the non source files (left-click plus shift for range or ctrl to add individual files). Right click on one of them. Select TortoiseSvn > Add to Ignore List. Add the items by name. You can also add files by extension if that is appropriate. In Windows Explorer, the excluded items are shown with a gray - icon.
5. The directory now serves as both a Tortoise working folder and as an Eclipse project folder without interference. Eclipse ignores the hidden .svn subdirectory created by Tortoise. You can work on your code in Eclipse as you would in any project directory. You can commit it at any time from Windows Explorer (right-click > SVN Commit).
6. Any new files that you put in the folder will automatically be included in your subsequent SVN commit. This makes it easy to add source files but you have to be careful to exclude new files that you don't want to commit to the repository.
7. After each addition to the excluded files list, you need to update the working folder. Right-click on or in it and select SVN update.

SUBVERSION IN ECLIPSE

For routine use, Eclipse affords a more convenient interface to a Subversion repository than does Tortoise because there is no need to coordinate different tools and venues. The MIPs Navigator is a specific configuration of the open source Eclipse IDE. Eclipse natively supports CVS but requires a plugin for any other version control system. The most common plugin for SVN appears to be subclipse from CollabNet and/or tigris. Most documentation for Subclipse is in Eclipse help. Help > Contents > Subclipse. There is little documentation on the Internet.

The plugin must be the matched to the Eclipse version, which can be found in MIPs Navigator: Help >

M:\Touch Apps Internal\SwDevTools\subclipse1_6_18.

In Eclipse (MIPS Navigator) Help > Install New Software, Add update site

file:///M:\Touch Apps Internal\SwDevTools\\subclipse1_6_18

After this, Eclipse shows several plugins, including subclipse. Select all except Revision Graph, which needs something that we don't have.

Restart Eclipse. It isn't obvious that subclipse has been installed but it is now in online help and is available as a perspective. From Window > Open Perspective > Other, select SVN Repository Exploring to make this perspective a tab along with Debug, C/C++ and any other perspectives that you have selected.

Subclipse lets you name the working/project folder when you check out a branch from the repository. It automatically makes this folder or cleans it if it already exists. The name of this folder is not related to anything in the repository design or source code. You could call it anything except for one problem. Debugging a MIPS-Eclipse project requires a debug configuration, which includes the project folder name. Debug configurations are saved somewhere in the .metadata directory of the Eclipse workspace. They are not under version control. This affords you freedom to name the working/project folder anything you like but, to reuse your existing debug configurations, you need to maintain consistent naming.

If no one ever worked on more than one project at a time, all branches could share a single project name. However, a programmer might want to check out for debugging two branches, for example Polycom and Unified, at the same time in order to compare actual functioning. This would be difficult if they had the same project folder name. Consequently, it is recommended that each Alt project be given a unique working/project folder name. It is also possible, and potentially useful, to create a unique project for versions within an Alt branch. For example, in the initial repository, although the Polycom Unified branch is a version under Polycom, it could be useful to check out and debug both it and Polycom HEAD simultaneously.

Each Eclipse project represents a distinct repository branch, but only a few Eclipse configuration items need to be defined for each. They are:

Note that the Project-Properties items are used for building and are, therefore, recorded in .cproject, which is under version control. You should not change these items in any project that you intend to commit except as a new Alt branch.

The initial project-specific items are:

1. Unified (Svn7kFw/Src): project folder = Unified; executable name = 7kFw
2. PolyUni (Svn7kFw/Alt/Polycom/Ver/2.1): project folder = PolyUni; executable name = LDS7000
3. Polycom (Svn7kFw/Alt/Polycom/Src): project folder = Polycom; executable name = LDS7000

Install both TortoiseSVN and Subclipse before doing this tutorial.

1. Copy the shared repository M:\Touch Apps Internal\Svn7kFw to C:\Svn7kFw.
2. Start MIPS Navigator ICS (Eclipse).
3. Select Help > Help Contents > Subclipse - Subversion Eclipse Plugin. If you don't see this in the menu then you haven't installed Subclipse. Close the help menu.
4. If you haven't already done so, open Window > Open Perspective > Other and select SVN Repository Exploring. Your perspectives tab should already have C/C++ and Debug items. If you don't see these and SVN Repository, pull out the tab to expose all three. Click the SVN Repository item.
5. The SVN Repositories tab in the SVN window is initially blank. Right-click in it and select New > Repository location. Type file:///C:/Svn7kFw in the Location field. Note that the entire repository tree is immediately displayed and can be browsed (like TortoiseSvn > Repo-browser).
6. Right-click Svn7kFw/Src and select Checkout. Subclipse provides a default project name that depends on your Eclipse history and it is probably not what you want, although you can use any name you like. Replace this with Unified because this is the repository's Unified code HEAD. Press OK.
7. Subclipse automatically makes a new project directory in the current workspace and fills it with the checkout code. The default workspace created by MIPS is C:\mips\NavigatorICS\NAVIGATOR-ICS-WORKSPACE but you may have another. With Windows Explorer, browse to this now and see the new Unified folder. Tortoise applies a green checkmark to this folder. Right-click on the folder. Note that the menu includes SVN Update and SVN Commit in addition to TortoiseSVN. As far as Tortoise is concerned, this is a standard working folder with checked out files. Select TortoiseSVN > Repo-browser, which opens on file:///C:/Svn7kFw/Src, the checkout source for this folder. Close Repo-browser.
8. In Windows Explorer, browse into the project/working directory. Tortoise applies a green check mark to all files. Eclipse creates two files, ".project" and ".cproject", which are not standard source files, but since these are under version control, Tortoise recognizes them. If they were not under control, Tortoise would apply a blue question mark to them. Return now to Eclipse.
9. Click the C/C++ item in the view tab. If Project Explorer is not visible, select it by Window > Show View > Project Explorer. The Project Explorer window includes the new Unified project. Subclipse attaches an orange storage icon to the project to indicate that its files are the same as when checked out. This is the same thing as the green check mark in Tortoise.
10. Expand the Unified project. All of its files have an orange storage icon, indicating unchanged files. Subclipse tells for each file, the revision number (1 for all in this case), the date and time of the commit, and the name of the committer.
11. If your MIPS-Eclipse is correctly configured, you can immediately build the Unified project. Highlight it and select Project > Clean or Project > Build Project.
12. In Windows Explorer, browse into your Unified project folder. A new folder called Debug has been created as a result of building the project. Tortoise doesn't know what you want to do with this so it attaches a blue question mark to it. Click on nothing and select TortoiseSVN > Check for modifications. Tortoise lists the Debug folder and everything in it.
13. In Eclipse, expand the Unified project and double-click AFECont.c. Insert "// testing" at the beginning and save the file. The orange icon attached to the file changes to a red and white star as does the icon attached to the project. This is the same thing as the red exclamation mark in Tortoise.
14. Right-click (in Eclipse) on the Unified project and select Team > Commit. The Commit dialog tells that the destination is file:///C:/Svn7kFw/Src, as expected. The Changes list shows Unified and under it AFECont.c. After committing the change, the icons associated with the Unified project and AFECont.c file return to orange stores.
15. With Windows Explorer open in your project folder, right-click on nothing and select SVN Commit. The Tortoise commit dialog doesn't show any source files as having changed but it does list the Debug folder and its contents. All of these are unchecked so they won't be added to the repository but they are a distraction. Abort the commit. Right-click on the Debug folder and select TortoiseSVN > Add to ignore list. Repeat the Tortoise commit. Now Debug and its files are not mentioned.
16. To capture the current Unified version in Eclipse, right-click Unified in the Project Explorer and select Team > Branch/Tag. The Create Branch/Tag dialog shows the Copy to URL as "file:///C:/Svn7kFw". Append to this "/Ver/2.1". It then shows that it is the HEAD of this branch that will be copied (by default) and not whatever is in your working folder. Note that this is essentially identical to the process in Tortoise. Add a comment and finish the tagging.
17. Select the SVN Repository item in the Eclipse view tab. Expand file:///C:/Svn7kFw/Ver to see the new 2.1. Tortoise will also see this. With Windows Explorer open on your project folder, right-click and select TortoiseSVN > Repo-browser. Browse and expand to see the same new branch, which is the captured 2.1 version of the Unified code.
18. Return to Eclipse. Change to C/C++ view. In the Project Explorer window, right-click on AFECont.c and move the cursor to Compare With, opening a sub-menu with a number of available options. If this file were not under version control, the sub-menu would have no enabled options. Select Base Revision. Eclipse reports no differences because you haven't modified the file since the last commit. Similarly, "Latest From Repository" reports no differences.
19. Right-click on AFECont.c in Project Explorer and select Compare With > Branch/Tag. The dialog provides the default reference "file:///C:/Svn7kFw/Src/AFECont.c" but this is the same as "Base Revision" and "Latest". To compare this to version 2.0, you could click the browse button (ellipses) but it is quicker to edit the URL to read "file:///C:/Svn7kFw/Ver/2.0/AFECont.c". Do this and click OK. Eclipse opens a window with side-by-side comparison of the two files. For merging, this is not quite as good as WinMerge but it is much better than TortoiseMerge. Hover over the two right-left arrows in compare window toolbar. Note that one copies all non-conflicting text while the other copies the currently selected text. Eclipse knows that you can't change the repository and doesn't even provide a button for this, unlike TortoiseMerge and WinMerge. Often, it is helpful to get a larger view when comparing and merging but this window is constrained to the edit panel. To expand the compare window, maximize the edit panel by right-clicking its tab area (at the top of the panel) and selecting maximize. If you accidently select minimize instead of maximize or restore, the panel shrinks to side-bar icon, which you can click to restore the edit panel. Click the close mark on the compare window's tab.
20. To compare repository versions, switch Eclipse to SVN Repository view. Right-click on Svn7kFw/Ver/2.1 and select Compare. The dialog provides the same "file:///C:/Svn7kFw/Ver/2.1" URL as reference. Change 2.1 to 2.0 and click OK. The compare window shows that the two differ only in AFECont.c. Double click on this to open the side-by-side compare/merge. Try clicking the various right/left arrows. They are all disabled because you can't edit files that are not checked out.
21. In the repository view, right-click on Svn7kFw/Alt/Polycom/Src. Select Compare and browse to or edit the reference URL to read "file:///C:/Svn7kFw/Src". Click OK to compare the HEAD of Unified and Polycom. Eclipse provides a quick way to compare multiple files and to perform simple merges involving a few but WinMerge is better for big merge efforts. The file compare in Eclipse simply tells you where lines differ without pointing out the detailed differences, forcing you to carefully examine each line. TortoiseMerge provides these details but in a way that is so arcane that it is essentially a new language. WinMerge presents these details when you need and to whatever depth you ask for, providing the detail of TortoiseMerge with the convenience of Eclipse.
22. WinMerge can't be properly integrated into Eclipse or Tortoise. To merge two code sets that differ by as much as Unified and Polycom, it is best to check each out to separate folders (using Tortoise or Eclipse) and invoke WinMerge as a stand-alone program. If you have installed WinMerge you can try this now.
1. In Eclipse SVN repository view, right click Svn7kFw/Alt/Polycom/Src and select Checkout. Name this project Polycom.
2. In Windows Explorer, browse to your Eclipse workspace folder, where you should see the Unified and Polycom project folders.
3. Right-click on the Polycom folder and select WinMerge (it is in the context menu because WinMerge, like Tortoise, is an Explorer extension). The left folder is your Polycom project. Put the path to your Unified project in the right folder field. Uncheck "Include Subfolders".
23. Finish this tutorial by deleting your experiments. This should be done in a certain order to avoid dangling references.
1. In Eclipse Project Explorer window, right-click Unified and select Delete. Check "Permanently delete folder contents" (this includes the folder itself) and click OK. Repeat this with Polycom.
2. Switch to SVN Repository view. Right-click on file:///C:/Svn7kFw and select Discard Location.

CODE BASE PREPARATION

The Unified code base (u0) has been published at:

"M:\Touch Apps Internal\exchange\firmware\Internal Firmware Releases\2011 0701 Unified Base Version". This was later moved to:

"M:\Touch Apps Internal\exchange\firmware\Internal Firmware Releases\Unified Base Versions\2011 0701 Unified Base Version"

This will be captured as U2.0, freeing Svn7kFw/Src for further code development. It will also be captured as the first Polycom version P2.0 for the purpose of comparison and merging.

The Polycom code base of the version sent to Polycom (p0) has been published at:

"M:\Touch Apps Internal\Firmware Released to field\Polycom\2011-0701 Polycom v15 Faster FrontEndFilter\2011-0701 Polycom v15"

This will be captured as P2.2.

A subsequent Polycom code base that has been merged with the Unified version has been published at:

"M:\Touch Apps Internal\exchange\firmware\DJ\Gestures\preliminary\48pin_Polycom_Unified"

This will be captured as P2.1.

Although the PolycomUnified code base (pu0) was developed after the Polycom code base (p0) their order in the repository is reversed. There are two reasons for this. One is that pu0 has more in common with u0 than does p0. 18 of 27sources files are different between p0 and u0 but only 9 are different between pu0 and u0. Thus, in terms of version evolution, pu0 represents a transition between u0 and p0. Secondly, current development plans call for continuing development of the p0 code. This is the code that has been released to the customer, with a promise that the next release will contain a limited set of modifications.

The mismatched files between u0 and pu0 are:

.cproject, .project, communication.h, Gestures.c, Gestures.h, NVRAM_DefaultData.c, singlTch.h, system.h, TouchFind.c

The mismatched files between u0 and p0 are:

.cproject, .project, AFECont.c, Commands.c, communication.c, communication.h, Gestures.c, Gestures.h, globals.c, globals.h, multiTch.c, NVRAM_DefaultData.c, NVRAM_Definition.h, singlTch.c, singlTch.h, system.c, system.h. TouchFind.c

The mismatched files between pu0 and p0 are:

.cproject, AFECont.c, Commands.c, communication.c, communication.h, Gestures.c, globals.c, globals.h, multiTch.c, NVRAM_DefaultData.c, NVRAM_Definition.h, singlTch.c, singlTch.h, system.c, system.h, TouchFind.c

The existing project design separates local H files into their own directory under the one that contains the C files. This serves no purpose and complicates some operations. Subversion allows source directories to be created and deleted but file comparison and merging operations are complicated by directory changes. Therefore, the local include directory will be merged into the main directory in all three code sets before creating the initial repository.

The code sets are prepared for the initial repository creation by moving their H files from the include subdirectory into the main code directory. While it would be possible to change the project settings so that local "." is in the include path, standard practice would indicate changing #include <name.h> statements to #include "name.h". This is done for all files with an awk script and XP command.

The original C files are placed in the subdirectory source. Then instead of modifying them, which is hard, they are just copied into CWD with the changes made on the fly.

The awk script, locinc.awk, is:

The XP command is:

All of the H files in Include are copied to the main code directory. The file mips_regdef.h in the include directory is not referenced in any of the C files but is referenced by starthere.s. The Include directory is removed from the Eclipse project definition by deleting it from both Project > Properties > C/C++ General > Paths and Symbols > Include tab Project Properties > C/C++ Build > Settings > Sourcery G++ Assembler > General > Include Paths.

system.h and NVRAM_Definitions.h contain #include <singlTch.h>. Including headers in headers is generally discouraged. The program builds without errors or warnings if this is removed from system.h but there are many warnings (but no errors) if it is removed from NVRAM_Definitions.h. The implications of these warnings is not obvious. Therefore, these will not be removed from either file but just changed to use quotes instead of brackets. The #include <mips_regdef.h> in starthere.s is changed to use quotes by hand editing.

The standard build (MIPS project) ends after generating name.out, which is an executable under the debugger but is not useful for anything else. For other purposes several other files need to be generated. This has been done by our endstep.bat. This file has resided in Debug, which is the output folder for generated files and should not be used for any kind of source. It should be located in either a tool directory or in the project folder and put under version control. Further, it invokes tools, which themselves reside in Debug. They should be located in a tool folder. Additionally, the batch file unnecessarily embeds the project name, preventing its reuse for different projects without editing.

The original endstep.bat for Polycom is:

The original endstep.bat for Unified is:

The two are identical except for the second argument to LDS7kCodeSafeEncrypter in Unified that isn't in the Polycom version and the generated file name root.

mips-sde-elf-objdump.exe and mips-sde-elf-objcopy.exe are located in the mips installed bin directory, which is normally c:\mips\NavigatorConsole\bin. bin2hex.exe is a common program but has incompatible variants. A variant that does work for us is located in M:\Touch Apps Internal\exchange\firmware. There seems to be no central location for LDS7kCodeSafeEncrypter.exe or BTTSafe.exe but each project's Debug directory contains copies.

SOLUTION

The endstep.bat from Unified\Debug is moved into the source directory and edited to take a command argument for the base file name. It is invoked automatically at the end of normal build by the Eclipse project Properties > C/C++ Build > Settings > Build Steps > post-build steps > command = "..\endstep name". name must match the out name defined in project > Properties > C/C++ Build > Settings > Build Artifact > Artifact name. This requirement is due to endstep.bat operating on %1.out. The endstep.bat for any code set may be changed to accept and produce files with independent names. CWD when this executes is Debug, which is why the command includes "..\" path. Even though the batch file itself is in the source directory, it operates in Debug and only on files in Debug. Although it performs its main task only if given a valid file name (for which name.out exists) argument, it unconditionally deletes all of the expected generated files. This is to prevent old files from being inadvertently used by downstream processes.

The Eclipse project Properties > C/C++ Build > Settings > Build Steps > post-build steps > command is "..\endstep 7kFw" for the Unified branch and "..\endstep LDS7000" for the Polycom and Polycom-Unified branches.

endstep.bat

APPENDIX ONE: CREATING THE REPOSITORY WITH TORTOISE

1. Make real (OS) directory Svn7kFw in "M:\Touch Apps Internal".
2. Convert Svn7kFw to Subversion repository by:
1. In Windows Explorer, right-click on Svn7kFw.
2. From popup menu: TortoiseSvn > Create repository here.
3. Create Svn7kFw/Src by adding the Unified source.
1. Prepare the Unified source by making a temporary real directory called Src and copying *.c, *.h, 7000scrpt.ld, .project, and .cproject files. The latter two files are not program source but they are XML text, which can be fully managed (unlike binary files).
2. Right-click on Svn7kFw.
3. Select TortoiseSvn > Repo-browser.
4. Right-click on file:///M:/Touch Apps Internal/Svn7kFw in Repo-browser.
5. From popup menu select Add folder. Browse to the prepared Src; select it and press ok. For message use "Unified coding venue". This is repository Revision 1 (Subversion increments Revision on every change).
4. Right-click Svn7kFw again (in Repo-browser). Select Create Folder called Ver with message "Unified versions", and Alt with message "Unified alternatives". At this point, the repository Revision is 3.
5. Capture version U2.0 by copying the u0 code from Svn7kFw/Src by duplicating the directory.
1. In Repo-browser right-click on Svn7kFw/Src.
2. From popup menu select Copy to. Type in the destination field file:///M:/Touch Apps Internal/Svn7kFw/Ver/2.0. Message is "Unified code 2.0".
3. Press F5 to update the browser. Otherwise, the new folder doesn't appear, which makes it look like the operation failed.
4. At this point, the repository Revision number is 4. The Unified code version 2.0 can be retrieved from its version branch Svn7kFw/Ver/2.0 or by Svn7kFw/Src revision 4.
6. Create Polycom folder.
1. In Repo-browser, right-click on Alt (file:///M:/Touch Apps Internal/Svn7kFw/Alt).
2. From popup menu select Create Folder. Folder is Polycom with message "Polycom alternate program design".
7. Capture unified code u0 as the first Polycom version.
1. Repeat step 6 used to capture U2.0 but destination is Svn7kFw/Alt/Polycom/Src. The source may be either Svn7kFw/Src or Svn7kFw/Ver/2.0. Message is "Unified 2.0 baseline for Polycom". [rev 6]
2. Create Ver and Alt folders under Polycom (see step 5). Messages are "Polycom versions" and "Polycom alternatives".
3. Copy Polycom/Src to Polycom/Ver/2.0 (procedure similar to step 6). Message is "Polycom 2.0 is Unified 2.0". [rev 9]
8. Prepare Polycom version P2.1. The current version, which is really the u0 (version U2.0) code set, is first checked out just to prepare the Subversion client venue. Then all of the checked out code is discarded and replaced by the Polycom-Unified code set. This is then checked in (committed). Then it is captured into version 2.1.
1. Delete all files (including hidden and folders, e.g. .svn) in a temporary local Src directory. Any directory could be used-- the name is irrelevant-- but it must be completely clean.
2. With TortoiseSVN you don't go to the repository to check out files but to your working (destination) folder.
1. With Windows Explorer in the temporary Src directory, right click. In the popup menu, select SVN checkout.
2. The URL of repository is "file:///M:/Touch Apps Internal/Svn7kFw/Alt/Polycom/Src". This can be typed by hand, copy/pasted from a document, or located through Repo-browser.
3. The Repo-browser affords two ways to copy a URL. In the SVN checkout dialog, pressing the elipsis button to the right of the URL field opens Repo-browser on the most recently browsed location. This doesn't work on the first use of a new repository and can be dangerous if you access multiple repositories because it may lead you to browse the wrong one. The other, less convenient but more reliable method is to open Repro-browser on the correct repository (Svn7kFw in this case) right-click on the desired branch (Polycom/Src) and select Copy URL to clipboard.
3. All of the firmware source files should appear in the temporary Src with a green checkmark, Tortoise's indicator that the files are unchanged the same as the source, i.e. Polycom/Src. If any files don't have a green checkmark, press F5 to refresh the (Windows Explorer) display. A new hidden directory, ".svn" has also been created in your working Src. The creation of this directory and its contents is the only purpose of this first checkout. Delete all (27) of the files in Src. Don't change ".svn".
4. Copy *.c, *.h, 7000scrpt.ld, ".project", ".cproject", and endstep.bat files of the PolycomUnified code set. These are the files from "M:\Touch Apps Internal\exchange\firmware\DJ\Gestures\preliminary\48pin_Polycom_Unified" after eliminating the separate include directory. In Windows Explorer, Tortoise now shows 9 files with a red exclamation mark, indicating that these are different from the baseline. The files that still have a green checkmark are the same in both Unified 2.0 (aka Polycom 2.0) and Polycom 2.1.
5. With Windows Explorer in Src, right click. Select SVN commit. In the commit dialog, note that Tortoise identifies the commit destination as "file://M:/Touch Apps Internal/Svn7kFw/Alt/Polycom/Src" (M is your mapped letter). This cannot be modified. Tortoise also shows the 9 files that have changed, each with a checkmark. Unchecking a file would deselect it from the commit. Leave all checked. Message is "Touch Apps Internal\exchange\firmware\DJ\Gestures\preliminary\48pin_Polycom_Unified with merged includes". Tortoise now shows all of the files in temporary Src with green checkmarks because they now match the repository HEAD. [rev 10]
6. In Repo-browser, right-click Svn7kFw/Alt/Polycom/Src and select Copy to. Destination is file:///M:/Touch Apps Internal/Svn7kFw/Alt/Polycom/Ver/2.1. Message is "Polycom version 2.1 is Touch Apps Internal\exchange\firmware\DJ\Gestures\preliminary\48pin_Polycom_Unified with merged includes". Press F5 to refresh display and confirm creation. [rev 11]
9. Prepare, commit, and capture Polycom 2.2. This procedure is the same as use for version 2.1 except that the initial checkout to the temporary Src is not needed, as the directory is already in the required state and the code set is derived from "Touch Apps Internal\Firmware Released to field\Polycom\2011-0701 Polycom v15 Faster FrontEndFilter\2011-0701 Polycom v15" with the same modifications to eliminate the separate include directory.
1. Delete all of the files in Src. Note that these all have green checkmarks, indicating that they match the HEAD of Polycom/Src.
2. Copy *.c, *.h, 7000scrpt.ld, ".project", and ".cproject" files of the Polycom p0 (not unified) set to Src. Now Tortoise's green checkmarks and red exclamation marks show 16 unmatched files (compared to Polycom 2.1, aka pu0).
3. Right-click in Src and select SVN commit. Message is "Touch Apps Internal\Firmware Released to field\Polycom\2011-0701 Polycom v15 Faster FrontEndFilter\2011-0701 Polycom v15" with merged includes. [rev 12]
4. In Repo-browser, right-click Svn7kFw/Alt/Polycom/Src and select Copy to. Destination is file:///M:/Touch Apps Internal/Svn7kFw/Alt/Polycom/Ver/2.2. Message is "Polycom version 2.2 Touch Apps Internal\Firmware Released to field\Polycom\2011-0701 Polycom v15 Faster FrontEndFilter\2011-0701 Polycom v15 with merged includes". [rev 13]
10. Verify repository creation. This is done for the two HEADs and each of the captured versions by checking out into a clean directory and comparing to the original directories. The temporary Src directory is reused with complete cleansing (including .svn) before each test.
1. At DOS prompt in the Src directory do del . and rd /s .svn. Alternatively, in the GUI delete the entire Src directory and then create it again.
2. In Windows Explorer on Src, right-click and select SVN Checkout.
3. Click the ellipses to the right of the URL field to browse for Svn7kFw/Src. In the repo-browser, with this folder highlighted click OK. The full URL "file:///M:/Touch Apps Internal/Svn7kFw/Src" (with your mapped drive instead of M) appears in the checkout URL.
4. Compare the checked out files to the Unified code set.
5. Repeat steps 11.1 through 11.4 on all of the branches.
1. Compare version U2.0 file:///M:/Touch Apps Internal/Svn7kFw/Ver/2.0 to Unified.
2. Compare P2.0 file:///M:/Touch Apps Internal/Svn7kFw/Alt/Polycom/Ver/2.0 to Unified.
3. Compare P2.1 file:///M:/Touch Apps Internal/Svn7kFw/Alt/Polycom/Ver/2.1 to PolycomUnified code set pu0.
4. Compare P2.2 file:///M:/Touch Apps Internal/Svn7kFw/Alt/Polycom/Ver/2.2 to Polycom code set p0.
5. Compare Polycom/Src file:///M:/Touch Apps Internal/Svn7kFw/Alt/Polycom/Src to Polycom code set p0.

APPENDIX TWO: CREATING THE REPOSITORY WITH SUBVERSION COMMANDS

This is a batch file that creates the initial repository as a local file from a set of three original source folders. The three source folders, Unified, PolyUni, and Polycom contain fully prepared sources, including endstep.bat, .cproject, and .project Eclipse files. The include files have been moved into the source folder.

The repository is created at the same level as the three source files. The batch file is invoked with the URL of this working directory as a parameter to avoid the complexity of DOS path conversion to URL.

APPENDIX THREE: ECLIPSE CONFIGURATION

To debug the program under Eclipse, a matching debug configuration must be defined. If you work on only one project at a time, you only need to define one debug configuration. Debug configurations are not under version control but recorded in the .metadata database in the Eclipse workspace. Consequently, you can't easily import a debug configuration but must create at least one.

The first (or only) configuration is made from the MIPS ICS Application template, which provides both appropriate and inappropriate information. Some information is unique to our hardware and must be added. Additionally, the project folder and executable name are required. To create a debug configuration for a project, highlight that project in the Project Explorer window. Then click on the down arrow next to the bug icon in the toolbar. Select Debug Configurations. It is important to select the project before opening the Debug Configurations even if this is for an entirely new configuration. If a project for which a debug configuration already exists is accidentally highlighted, "new" debug configuration creates another instance of a configuration for the highlighted project.

If you don't have any debug configuration defined then you need to create one based on the MIPS ICS Application template. If you have a functioning debug configuration for a different project, you can clone it. To create from the template, right-click on MIPS ICS Application and select New, but to clone from an existing debug configuration, right-click on that and select Duplicate. Duplicate provides an obviously wrong project name and folder but these would be changed in any case. When cloning a debug configuration it is very important that the source not be in the debug "favorites" list. An error in MIPS-Eclipse causes both the original clone and the modified version to appear in the list forever joined. You can remove them both or include them both but there is no way to put just the one you want in the list. Another manifestation of this error is that modifying a debug configuration causes it to appear in the favorites menu even when it is not originally in the list. When this occurs, the menu item can be removed only by deleting the configuration.

The easiest way to make several debug configurations is to make one original from the MIPS template and then clone it. Be sure that neither box in Debug Configuration > Common > Add to favorites is checked in the original clone source. If you aren't sure, open Debug-Organize favorites and uncheck everything. You can avoid the duplicate favorites problem entirely by not having anything in this list. You can debug any project that has a debug configuration by first selecting it in the Project Explorer window and then clicking the bug icon. Another MIPS-Eclipse error causes the debug favorites list to continue to display items that have been removed. The best policy is to never add anything to this list.

1. To create the Unified debug configuration from the MIPS template.
2. Click on the down arrow next to the bug icon in Eclipse toolbar.
3. Select Debug Configurations.
4. Right-click on MIPS ICS Application.
5. Select New.
6. Main
1. Name := Unified
2. Project := Unified
3. Build Configuration := Use Active
4. C/C++ Application := Debug/7kFw.out
7. Arguments = blank
8. Debugger
1. Target Interface = MIPS Probe(EJTAG/DeepTrace/IFlow)
2. GDB Executable = mips-sde-elf-gdb
3. Launch Preset = Advanced
4. Download Code = checked
5. Reset Action = No Reset
6. Attach After = 7 Seconds
7. Set PC to custom PC/Symbol 0x40
8. Stop at = Main
9. Set endian = Auto
10. Scan For Probes = 42812 <<< Don't type this. Press the "scan for probes" and accept whatever it says. If scan fails then disconnect everything, reconnect and run GUI with 52, 52 2 commands.
11. Configuration name = M4K
12. Device name = mips_m4k

Assuming that you have created the original Unified debug configuration, create PolyUni debug configuration by:

1. Click on the down arrow next to the bug icon in Eclipse toolbar.
2. Select Debug Configurations.
3. Right-click on Unified.
4. Select Duplicate.
5. Main
1. Name := PolyUni
2. Project := PolyUni
3. C/C++ Application := Debug/LDS7000.out

Clone Polycom from PolyUni, replacing the name PolyUni with Polycom.

There are a number of Eclipse configuration settings which, although not strictly related to version control, are useful when code is being shared.