ECLAIR FAQ

We add support for new toolchain releases on a regular basis, giving priority to the most used ones in the embedded system industry. So we ask about which toolchain(s) you are using to make sure our priorities are up-to-date with the needs of our customers and prospects.

There are hundreds of them, too many to be listed here with full details, from all the major suppliers, including ARM®, AndeSoft™ SW Stack, CAES, clang/LLVM and its derivatives, CodeWarrior™, Cosmic Software, Cross WorksT™, ESP-IDF, Emscripten, Freescale™, GCC and its derivatives, Green Hills®, High Tec, IART™, InfineonT™, Intel®, Keil Software®, MPLAB®, MPLAB®, MelexisT™, Microsoft®, MinGW-w64 NXP®, QNX*™, Renesas Electronics, SOFTUNE™, TASKING®, Texas Instruments™, Wind River®, Xilinx™, xPack.

Take a look at this

Under the assumption that you inform us, there are two possibilities:

1. Your toolchain is widely used (or is likely to be in the near future) and you are not in a hurry: it will probably be supported in the next ECLAIR release.
2. All the other cases: we will ask you to contribute to the development costs of its model and to give us a couple of weeks to implement it.

Look at the Number of analysis frames table in the ECLAIR analysis report. Does the number of UNIT frames correspond to the number of translation units in your project? Does the number of PROGRAM frames correspond to the number of executables your linker has produced? In case of a negative answer, Tood hain of the chain as eos been properly intercepted by ECLAIR. See Chapter Intercepting the Toolchain of the ECLAIR User’s Manual.

In case the situation is not clear-cut, consult the Analysis Frames section in the ECLAIR analysis report: here you will find a complete list of the toolchain components’ invocations intercepted by ECLAIR: it you find something missing, check that you have followed the instructions given in Chapter Intercepting the Toolchain of the ECLAIR User’s Manual.

They are the following:

Userbase

The criterion defining the group of users that are allowed to use ECLAIR. There are the following possibilities:

• Per-seat: The userbase is defined by the number of individually-named users who can use any component of ECLAIR, possibly adjusted to take into account the requirements of Jenkins/GitLab/GitHub controllers/instances and agents/runners (see “What are the ECLAIR licensing requirements for Jenkins, GitHub and GitLab?” for more details). BUGSENG does not require customers to communicate the identities of users, except for the users that use BUGSENG support services (see “Maintenance” for more details).
• Per-project: The userbase is defined indirectly as the set of all users working on a specific project for a
  specific purpose.

Term:

The criterion defining for how long the userbase is allowed to use ECLAIR. There are the following possibilities:

• Indefinite-term: Use is allowed for an indefinite amount of time as long as the customer complies to the license agreement. Indefinite-term licenses include one year of support services including updates; such services can be optionally bought at a predetermined price for subsequent years (see “Maintenance” for more details).
• Subscription-based: Use is allowed for one-year time periods. Subscription-based licenses are automatically renewed every year unless they are terminated by one of the parties; they always include support services with updates.

Coverage:

An attribute describing the relationship between the licensed userbase and the customer potential userbase. There are the following possibilities:

Site

The userbase comprises all software developers and all software quality assurance people at a given site, independently from whether, at any given time, they use ECLAIR directly, they use ECLAIR reports, or they do not use ECLAIR and its outputs at all. Here “site” has to be interpreted in its broadest sense: a clearly-delimited and official company department, division or group may qualify as a site. External consultants temporarily working on software development or quality assurance have to be counted.

Multisite

Same as above, set of sites, but for a given provided there IS for a single point of contact all contractual actions, including releases, updates, technical support and payments.

Enterprise

Like multisite when the site or sites covered are the totality of customer sites.

Partial

All other cases.

This is decided on a case-by-case basis, but typically the project should be not-for-profit (independently from the nature of the organizations involved in the project).

There are only two factors:

1. The cardinality of the userbase for which the license is bought at once. BUGSENG operates a volume discount policy: the higher is the number of users, the lower is the cost per user.
2. The licensed features: the price increases as the number of licensed features increases. Some features are bundled with others with no price increase: for instance, the ECLAIR B package is bundled with all MISRA packages with no price increase, even though the price for ECLAIR B, when bought in isolation, is not zero.

Exactly: an enterprise license and a partial license will cost the same if the licensed features are the same and the userbases have the same cardinality.

Such licenses allow the generation of detailed outputs in all supported format for their distribution within the site/multisite/enterprise. For instance, HTML outputs can be published on the internal LAN and onsulted by anyone having access to the LAN using any supported web browser.

In contrast, with a partial license detailed outputs can only be consulted using the ECLAIR analysis results browser. Rich outputs, summary outputs and metric outputs can be generated in any supported format with any license (see “What are the main categories for ECLAIR outputs?” for an explanation of the different output categories).

The main advantage of site/multisite/enterprise licenses is that each human user can obtain, at the customer’s discretion, any kind of license key, thereby relaxing the constraints specified in “Who chooses the license enforcing mechanism(s)?“

There are two license-enforcing mechanisms. What is common to them is that running ECLAIR requires a key. A key can be:

Node-locked: The key is fully implemented in software and is locked to a specific machine. Remote access is not allowed. Transferring a node-locked key, a.k.a. rehosting, is possible with BUGSENG intervention. One node-locked key serves one user.

Detachable: The key is fully implemented in software and can be detached by a (possibly remote) license server. For partial coverage licenses, one detachable key serves three users in the same region (APAC, EMEA, AMER).

The above distinction concerns the technology used to implement keys. An orthogonal distinction is the one between ordinary keys and analysis node keys: the latter are only meaningful in the context of ECLAIR deployment in continuous integration system (see “What are the ECLAIR licensing requirements for Jenkins, GitHub and GitLab?“).

Pros:

1. They are fast: all communications occur within the same machine.
2. The user can use ECLAIR on that machine at any time.

Cons:

1. The user can only use ECLAIR on that machine.
2. If the machine crashes badly, the node-locked key can be lost. It is thus recommended to use hard disk drives supporting SMART (Self-Monitoring, Analysis and Reporting Technology) and to rehost the key at the first sign of disk issues.

Detachable keys can be detached from a pool of available keys for a specified time (up to 9999 days). Once detached, the license is automatically installed on the individual user’s local machine: no further connection with the license manager is required. This can easily support commuters or people on external duties where connection with the license managers is cumbersome or inadvisable. Detaching a license key requires a very small amount of network traffic (10-15 kB) and just a few seconds.

The validity of a detached license key can be extended before expiration. The detached license key can also be returned earlier to the license server. If not explicitly returned, the license key expires on the local machine after the specified time has passed, and automatically re-materializes on the license server.

Pros:

1. They can be easily shared among users, even if they are geographically distributed in the same region (APAC, EMEA, AMER)
2. They are fast: after detach, all communications occur within the same machine.
3. A crash of the recipient machine does not cause loss of the key.

Cons:

1. If the machine hosting the license server crashes badly, the entire pool can be lost. Not a problem if the server is properly maintained and monitored.

The customer does, taking into account that:

• one node-locked key corresponds to one user;
• one detachable key corresponds to three users in the same region (APAC, EMEA, AMER) for partial coverage licenses, but only to one user for site/multisite/enterprise licenses.

Suppose the customer wants to serve 8 users with a partial coverage license; this requirement can be satisfied in all ways indicated in the following table:

A customer with a site/multisite/enterprise license can serve all its users with any combination of keys, with at most one key per user.

The factors in the decision about the number and size of each pool of detachable license keys are the following:

• A detachable license key belongs to one and only one pool and cannot be transferred to a different pool.
• A pool can contain any number of license keys: such a number can be increased at any time, but it cannot be decreased.
• A pool can be rehosted, along with all the detachable license keys it contains, to a new server.
• A machine used as license server can host any number of pools.
• Any machine that is suitable for running ECLAIR may act as a license server, but only reliable machines should be chosen as license servers.

Having more than one pool hosted by the same license server is only advisable as a temporary measure, e.g., because we know some pools will have to be rehosted to a different machine. At the outset, it is best to plan for multiple pools only in the case of multiple license servers, each server hosting one pool.

Multiple license servers allow for the mitigation of failures: if one license server is momentarily offline, another license server may be available. This should not be overdone: if you spread your detachable keys across too many servers, users may incur overhead in finding a server with an available detachable license key. A rule of thumb you can follow for each LAN is the following: if a very reliable and con- tinuously monitored server (e.g., with a RAID disk array and S.M.A.R.T. services) is available, host a pool containing all license keys on that server. Otherwise choose two reasonably reliable machines and divide your detachable license keys into two pools, one for each license server.

Of course, if you have multiple LANs and/or multiple regions, you should first divide your detachable keys by region, then by LAN, then apply the above reasoning for each individual LAN.

For human users, everything can be conveniently done via Sentinel Admin Control Center (Sentinel ACC), which you can access by pointing your browser to http://localhost: 1947/ See this video for a tutorial.

If you want to automate the detaching and canceling operations, the eclair_licman program is what you need.

It works, but take into account that the analysis with ECLAIR of a typical project involves thousands of accesses to the key, so:

• depending on the latency and speed of the network connection between your machine and the license server, the analysis may be significantly slowed down;
• if you do not detach the key, you are subject to race conditions: suppose your analysis requires an hour and 1000 accesses to the key, and that the very last access fails because your colleagues are using all the available keys.

The only sensible case where you do not want to detach the key is when ECLAIR runs in a Docker container and the license server is running on the Docker host.

Sure, you need not lose them: there are hard costs associated with them, so they cannot be replaced for free and replacement requires paperwork as well.

For node-locked keys and pools of detachable keys:

1. Never dispose or reformat or change disks of a machine unless you have already rehosted all node-locked keys and pools of detachable keys hosted by that machine.
2. Especially for large pools of detachable keys, use RAID disk arrays and S.M.A.R.T. services (in general, such large pools should be hosted by machines continuously monitored by competent IT personnel).

Each Jenkins controller and GitHub/GitLab instance requires an ordinary key: this key may be shared with one user working locally on the same machine.

Each Jenkins agent and GitHub/GitLab runner requires a key, which may be an ordinary one or an analysis node key. In the former case, the ordinary key may be shared with one user working locally on the same machine and/or with a Jenkins/GitHub/GitLab controller/instance.

Analysis node keys only allow for the analysis execution and not for the generation of analysis reports (report generation takes place in the Jenkins controller and GitHub/GitLab instance).The cost of each analysis node key contributes to the total cost as the addition of 0.5 users to the userbase.

Examples with Jenkins, equally applicable to GitHub and GitLab:

1. Partial coverage, userbase is n, one user works directly on the Jenkins controller, which is equipped with one ordinary license key, and all Jenkins agents, if any, are on the same machine: no extra keys are required, hence no extra cost for Jenkins.
2. As above, but with Jenkins agents all running in user machines equipped with keys: no extra keys are required, hence no extra cost for Jenkins.
3. Partial coverage, userbase is n, and there are m machines running Jenkins controllers and s ma chines running Jenkins agents that cannot be directly used by any of the n licensed users (for instance, because they are remote and/or they have no display): the cost is as if the userbase cardinality was n + m + s/2.

As the keys for Jenkins/GitHub/GitLab controllers/instances and agents/runners are treated as increments to the userbase, the same volume discount policy applies.

Note that, when the Jenkins controller or GitHub/GitLab instance is equipped with a site/multisite/enterprise license key, users can browse the detailed outputs using any of the supported web browsers even from computers without ECLAIR installed. In contrast, when the Jenkins/GitHub/GitLab controller/instance is equipped with a partial license key, users can only browse the detailed outputs from machines with an ECLAIR installation and a valid license key. This restriction for partial coverage licenses only concerns detailed outputs: all Jenkins users can freely browse the Jenkins’ pages showing the number of ECLAIR reports, their evolution over time, and so on.

Under Windows, go to the %CommonProgramFiles (x86)%\SafeNet Sentinel\Sentinel LDK\ installed\113938\ folder. There you will find one or more files corresponding to the trial license keys you want to get rid of: their names follow a ‹key id›_provisional.v2c pattern. In order to hide them, you can remove the above mentioned files or move them elsewhere (e.g., under a hidden sub- folder you may create for that purpose). Then you should restart the license manager, either by rebooting the machine or by doing the following from an admin prompt:

net stop hasplms

net start hasplms

You can of course do everything from the command line, e.g.:

cd "%CommonProgramFiles(x86)%\SafeNet Sentinel\Sentinel LDK\installed"

cd 113938

mkdir hidden

move *provisional* hidden\

net stop hasplms

net start hasplms

Under Linux, do the following from a superuser shell:

cd /var/hasplm/installed/113938/

mkdir hidden

mv *provisional* hidden/

service aksusbd stop

service aksusbd start

It depends on your ECLAIR license term:

• For indefinite-term licenses, maintenance is included for the first year. Maintenance is an optional service for subsequent years: our customer service will get in touch one month before maintenance expiration with an offer for one-year maintenance renewal.
• For subscription-based licenses, maintenance is included. Our customer service will get in touch one month before license expiry with an offer for license renewal.

Absolutely not: the maintenance service is optional for indefinite-term licenses.

No, all the accounts connected to the maintenance contract will be disabled (not deleted).

Yes, reinstatement of maintenance for ECLAIR licenses is possible, unless your license refers to an ECLAIR version that reached end-of-life.

The cost is the sum of all maintenance fees since last maintenance contract expiration. Write to sales@bugseng.com for a formal quotation.

Upon reinstatement of the maintenance contract, all accounts connected to the contract that were disabled will be re-enabled.

Because with maintenance reinstatement you receive all software updates and improvements implemented while your maintenance was on hold.

They are:

Summary outputs: These outputs contain comprehensive information about the analysis as well as counts of the issues uncovered by the analysis per service, per file, per tag and combinations thereof.

Rich outputs: These outputs contain comprehensive information about the analysis results without going into the detail of each reported program condition. For each individual issue reported by the analysis, these outputs contain: •

• the name of the file where the first code area resides;
• if the report has been tagged (e.g., to capture a MISRA deviation), the tag, along with any documentation associated to the application of the tag to the report (e.g., the justification for a MISRA deviation). These outputs are suitable for the communication to third parties in order, e.g., to precisely sub- stantiate a claim of MISRA compliance.

Detailed outputs: These outputs contain comprehensive information about the analysis results, including all details about each reported program condition (such as a coding rule violation or a possible run-time error). In other words, these output contain all the information required for a proper understanding of each individual issue reported by the analysis, e.g.:

• the exact position in the source of all the involved code areas;
• messages indicating precisely which role each code area plays in the reported program condition;
• in case macros are involved, the source code both before and after preprocessing, and the definitions of the macros involved;
• a path in the program leading to the reported issue;
• if the report has been tagged (e.g., to capture a MISRA deviation), the tag, along with any documentation associated to the application of the tag to the report (e.g., the justification for a MISRA deviation).

Such level of detail, while essential for whoever is in charge of acting upon undesirable program conditions, is undesirable for almost any other application. Moreover, such level of detail can effectively be navigated only via a browser. For this reason, when detailed outputs have to be printed, the level of detail can be decreased. The minimum level of detail for a detailed output is the line number and the message for the first area in the report.

Metric outputs: These outputs contain the values of the metrics collected for each file, function and project.

Pure text, HTML, XML, Word, Excel, LibreOffice Writer, and LibreOffice Calc. In addition, there is an internal protocol used to transmit detailed outputs to the ECLAIR browser.

The dependence is on the license coverage (see “What are the parameters defining ECLAIR license models?“). Taking into account the most used combinations, the answer is contained in the following table, where any denotes any license coverage whereas SME denotes site/multisite/enterprise coverage:

Most likely you overlooked the section of the manual titled “Enabling Links from the ECLAIR User’s Manual to PDF Documents“.

Yes. For example, Word, Excel and LibreOffice allow saving documents in PDF format.

Definitely! But we have to distinguish different cases:

1. You get reports from the B. PARSER or the B. TOOLCHAIN services of ECLAIR and the compiler is failing as well (either because of parse errors or because of illegal compilation options). This splits into two further sub-cases:

a. Failures come from a build phase where the build procedure is testing properties of the toolchain by trial and error. This happens, notably, in the standard build procedure of the Linux kernel. E.g., the build procedure may attempt compiling an empty source file with option -march=cannonlake to check whether such option is supported by the compiler. If it does not, the compiler will fail, and ECLAIR, which accurately matches compiler behavior, will generate a B. TOOLCHAIN report specifying that the retrieval of information from the toolchain has failed. Or the build procedure might, e.g., attempt compilation of

int a[(((char)-1) < 0) ? 1 : -1];

to check whether plain char is signed or unsigned. In the latter case, compilation will fail, and ECLAIR parsing will (correctly!) fail as well and generate a B. PARSER report. These phenomena are thus a byproduct of speculative toolchain use and do not harm correctness of the ECLAIR analysis in any way. You can prevent them by executing the speculative, self- configuring phase of the build outside the ECLAIR environment, only executing the actual build within the ECLAIR environment.

b. Failures come from the actual build, e.g., an header file is not found, or a typo resulted in invalid syntax. The best course of action is to fix the build itself before returning to analysis with ECLAIR. Notice that you may be in this case without having noticed: some build pro- cedures (e.g., some incorporated into popular IDEs) go on with compilation even in the case of parse errors and you may easily miss the fact that your project is not compiling cleanly. (As an aside, any build procedure not stopping at the first toolchain error is very dangerous and ought to be fixed.)

2. You get reports from the B. PARSER service of ECLAIR but the the compiler is not failing. Again, there are two sub-cases:

a. You are using one of the language extensions supported by some compilers that are in sharp contrast with the applicable ISO language standards (e.g., involving a “short long” data type). These cannot be supported by ECLAIR and you would be much better off (as recom- mended by all serious coding standards) by not using such extensions.

b. You have found a defect in ECLAIR: please file an issue on BUGSENG’s issue-tracking system describing precisely your observations and allowing us to reproduce them.