VendorInfo strings should be separated

[cpfister]

http://netmf.codeplex.com/workitem/2438

In the firmware description of the Porting Kit (displayed by MFDeploy>Target>Device Capabilities), the values of the fields for

HalSystemInfo.halVendorInfo

and

ClrInfo.clrVendorInfo

are generated from the same string. Therefore, NETMF adopters cannot include their vendor information without overwriting the CLR vendor reference to Microsoft.

In this context, HalSystemInfo.halVersion is currently defined to be equal to ClrInfo.clrVersion. We would recommend to remove HalSystemInfo.halVersion, since its definition does not provide useful information.

[piwi1263]

Just a question, could we have the situation that the HAL is being produced by company #1 whereas the CLR will be provided by another Company #2 ?

Although this might be a rather exception to the rule. Therefore, I'd suggest to NOT remove that info AND fill them from a different source not being an existing one. Whether it is chosen to fill them equally is up to the situation, but at least you still have the possibility to provide different values for the info blocks.

[cpfister]

@piwi1263 CLR is provided by Microsoft, unlikely but possible that someone changes it. HAL can definitely be created by someone else, writing a new HAL is basically what we did with NETMF for STM32.

So yes, agreed, both vendor info strings make sense, as long as they are settable individually.

A HAL consists of a set of components (drivers). In practice, with our various solutions, we never found that a version number of that set makes any sense. Each component has its own version, and then the solution defines the actually used set of components. So the solution version is important - also for the MFUpdate mechanism.

[piwi1263]

About the HAL, couldn't it be that a company makes a HAL for device #1, publishes it in f.e. January timeframe. Like Cerb 1.1/1.2 from GHI, so customers do buy it and make solutions based upon that. Now there is found an undocumented feature or an update to the hardware, with impact to the HW possibilities. Than you may want to know/check the version of the HW in the deployment because the new written SW does run on the new HW version 1.2 but does not run very well on HW version 1.1 (in this example). And GHI, there is nothing wrong with your HW, it's wunderfull HW to base solution upon. So you may want the possibility to version HAL. Maybe for completion stages of the HAL as well, you may want to publish in steps f.e. the 429 disco, start without the LCD stuff, since that ain't ready yet but that shouldn't hold up the customers from using the board without it. There are definitely more and better scenarios to think of, but I do think the version property does make sense to have it around. Probably not used very often but comes in handy when you need and have one avail. Since we have it already available it could be used. Of course it must be properly filled with meaningful info and if it will be used, time will tell, but having all 0xFF around is not very helpful IMHO.

@smaillet-ms - isn't this related to #115

[smaillet-ms]

@piwi1263 This does appear to be along the same lines as #115
I should think there are a number of various versions that might be useful to an app to be able to adjust to over time. And a consistency in how they are represented makes sense as well. For versions I'd like to recommend using semantic versioning. Which has a well defined form with the ability to verify expectations of compatibility for an app that may be deployed/or updated after a device is manufactured but can't always guarantee that the underlying firmware itself is updated on every device. I have a C# class for handling Semantic version strings and handling all the rules for ordering comparisons we could incorporate into a future release for this. However we'd need to settle on exactly what it is we'd need to attach a version to so that we can expose it properly. So far we've got suggestions for the following:

1. Physical hardware
2. HAL/PAL firmware
3. CLR version

Any others we should think about?

[piwi1263]

At least the ones already in the device capabilities, with not so much meaningful info. And reachable thru normal NetMf managed code. I'd settle for that what you propose.

@cpfister, any additions from your side ?

[cpfister]

@piwi1263 We need to stop thinking of the HAL as one "thing". It is just a name for a bunch of drivers, each of which can evolve independently, and thus would need its own version number if deployed separately.
Moreover, for the same hardware, there may be different drivers, optimized in different ways (e.g. one with a small UART buffer, another one with a large UART buffer).
The only version number that's relevant here is the solution version number, because the solution defines which of the available HAL driver versions and variants have been selected for this particular solution.
Now I think you would like to have something like a hardware version number. That may indeed be missing, e.g. to check whether a firmware update image is compatible with the board's hardware.

[smaillet-ms]

I was thinking that the HAL/PAL firmware version was a "solution" specific version number since they can't be deployed independently (Well I suppose someone could figure out a way to do that, but i's not something standard at this point so any custom approach could have it's own interop support to check whatever it wanted) Technically that could also apply to the CLR but that makes writing portable components and libraries harder as you'd need to be able to discern the CLR runtime version from a vendor specific firmware build number somehow....

[cpfister]

If HAL “version” and PAL “version” fully depend on the solution version, then they are not needed, only confusing. Which is the case, I think. However, the separate vendor strings are still relevant.

Steve, please find attached the document describing how we are dealing with the various version infos etc. Maybe it helps. Making this topic simpler and more logical would be very much appreciated! We spent a long time on this document, to come up with the “minimal viable hack” given the existing properties and the requirements for robust remote firmware updates.

Giving the CLR its own version number makes sense to me, or more precisely the CLR plus system libraries that are released (and thus versioned) by Microsoft as a whole. For example, the version 4.4. In contrast, the solutions for every board – even if they use this very same 4.4 code of Microsoft – can go through arbitrary version numbers. We actually decided to start with version 10.0.0.0 for all our solutions, to avoid the confusion of the older Mountaineer (and GHI and SecretLabs) firmware version numbers, which tried to stay close to the Microsoft release numbers, and obviously fail to do so.

So as far as I can see, it boils down to solution version, CLR/system libraries version, and hardware version.

For vendor infos, we need more strings, as the solution may come from Ingenuity Micro, the CLR from Microsoft, the PAL from Microsoft, the HAL components from Oberon, and the hardware from GHI Electronics. Of course, if HAL components were mixed from different vendors, then the latter would also become difficult. But this seems rare, and it is important for us to not become invisible in terms of marketing in systems that use our HAL components.

[cpfister]

PS
For the firmware update mechanism, we need two well-defined values: hardware-vendor-ID plus solution-version. Ideally also a hardware ID. As we don't update assemblies only, we actually don't need the CLR version for this use case.

[cpfister]

From the mentioned document:

From managed code in NETMF, version information can be accessed via class FirmwareVersion, property Instance, in assembly MFUpdate (MFUpdate.dll), namespace Microsoft.SPOT.MFUpdate, and corresponds to the following fields shown via MFDeploy, menu Target, Device Capabilities:

 FirmwareVersion.Instance.IsBigEndian: not available
 FirmwareVersion.Instance.Version: SolutionReleaseInfo.solutionVersion
 FirmwareVersion.Instance.OemName: SolutionReleaseInfo.solutionVendorInfo
 FirmwareVersion.Instance.Model: HalSystemInfo.modelCode
 FirmwareVersion.Instance.OemId: HalSystemInfo.oemCode
 FirmwareVersion.Instance.SKU: HalSystemInfo.skuCode

It would be great if the naming could be made consistent between managed code and native code (not OemName versus solutionVendorInfo).

[cpfister]

Also from the mentioned document:

The following hardware-related HalSystemInfo fields are stored in the Config region of a NETMF board:
 HalSystemInfo.modelCode
 HalSystemInfo.oemCode
 HalSystemInfo.skuCode
 HalSystemInfo.moduleSerialNumber
 HalSystemInfo.systemSerialNumber
Note: Whenever you overwrite the Config region, make sure to correctly set the hardware-related fields!

Maybe it should be supported - on hardware where this is possible - to move at least some of these values to the actual hardware, out of the Config region. For example, the unique 96 bit ID of an STM32 microcontroller might be used as moduleSerialNumber.

[lt72]

We will move this to 4.5, together with the Configuration sector redesign.