How is the DEPRECATED indication handled ?

[fred-r]

Today in the specs, some items are tagged as DPRECATED like the Dfamily for the conditions (only):

Dfamily*	DEPRECATED** Specifies the device family name (for example: STM32F2 Series).

It seems that this criteria is not supported any more.
So, is it more than deprecated, is it removed ?

[jkrech]

@edriouk can you confirm that anything D* except Dvendor and Dname is actually no longer supported in conditions in the RTE Model?
Looking at the currently published packs, there is many using Dfamily and DsubFamily as well as Dvariant as part of conditions.

[edriouk]

We still set Dfamily and DsubFamily for filtering, however they should be completely deprecated.
RteModel needs to be upgraded with corresponding validation to issue an error.
Dvariant is no longer supported in conditions. If a device variant is selected, Dname filtering attribute is set to device's Dvariant value.
Other D* properties such as Dfpu, Dmpu, Dendian, etc. are continued to be supported.

[jkrech]

The meaning of "DEPRECATED" must be different from
a) removed = ignored (dangerous)
b) removed = causing an error => breaking change

[fred-r]

To me we should be even more precise than this:

deprecated: developers are discouraged from using it, a warning is raised by the tool when encountering it and there is a porting period (say 18 months)

At the end of the porting period, we just remove the element from the spec (logged in the change log).

If we do not do that DEPREACTED will stay forever and depending on implementation it may or may not be supported properly...

[edriouk]

I think we need to make use of schema version in the tools.
A tool can define a range of schema versions it supports
If the tool reads a pdsc with schema version outside the supported range, then warning or error should be issued. Semantic version rules can be used to decide about severity.
In particular, removing deprecated elements should be reflected by the major version change => error.
Additionally I would put current PACK.xsd version that is seen during tool build.

BTW, this mechanism could also help in case of unknown elements and attributes.
Open-CMSIS-Pack/devtools#744

[ReinhardKeil]

Actions are:

• create a list of deprecated features
• classify the impact (with a note) of deprecated features into:
  -- affects build
  -- affects web views
  -- affects supportive tools (such as pack installer cannot access an old example)

After this list is available revisit this issue.

[jkrech]

List of deprecated elements and enumerations up until Version 1.7.45

a) using these deprecated items will not fail schema validation against major version 1.
b) these items will be removed from schema major version 2 and above and fail schema validation.
c) tools supporting major version 1 shall gracefully read deprecated items
d) tools implementing major version 1 are expected to retain support for implemented items

DeviceVendorEnum
      <xs:enumeration value="Freescale:78" />
      <xs:enumeration value="Freescale Semiconductor:78" />
      <xs:enumeration value="NXP (founded by Philips):11" />

map to "NXP:11"

DebugLinkEnum
      <xs:enumeration value="cjtag" />

no support implemented

MemoryType
    <xs:attribute name="id" type="MemoryIDTypeEnum" use="optional" />
    <xs:attribute name="init" type="xs:boolean" use="optional" default="0" />

support implemented and will remain

DeviceFeatureType
    <xs:attribute name="count" type="xs:int" use="optional" />

support implemented (Web) and will remain

DeviceFeatureTypeEnum
      <xs:enumeration value="I/O" />
      <xs:enumeration value="D/A" />
      <xs:enumeration value="A/D" />
      <xs:enumeration value="Com" />
      <xs:enumeration value="USB" />
      <xs:enumeration value="Package" />
      <xs:enumeration value="Backup" />

support implemented (Web) and will remain

DfpuEnum
      <xs:enumeration value="0" /> <!-- no FPU implemented -->
      <xs:enumeration value="1" /> <!-- FPU implemented -->

support implemented and will remain

DmpuEnum
     <xs:enumeration value="0" /> <!-- no MPU implemented -->
     <xs:enumeration value="1" /> <!-- MPU implemented -->

support implemented and will remain

DtzEnum
     <xs:enumeration value="1" /> <!-- TZ implemented -->

support implemented and will remain

DsecureEnum
      <xs:enumeration value="0" /> <!-- Non-secure -->
      <xs:enumeration value="1" /> <!-- Secure -->
      <xs:enumeration value="2" /> <!-- TZ-disabled -->

support implemented and will remain

DdspEnum
     <xs:enumeration value="1" /> <!-- DSP instructions implemented -->

support implemented and will remain

FileCategoryType
      <xs:enumeration value="sourceC" /> <!-- deprecated 1.7.15: use language attribute instead -->
      <xs:enumeration value="sourceCpp" /> <!-- deprecated 1.7.15: use language attribute instead -->
      <xs:enumeration value="sourceAsm" /> <!-- deprecated 1.7.15: use language attribute instead -->

support implemented and will remain

FileAttributeType
     <xs:enumeration value="copy" />        <!-- deprecated 1.7.32: should be not used -->
     <xs:enumeration value="interface" />   <!-- deprecated 1.7.32: should be not used -->

support implemented and will remain

FilterType
    <xs:attribute name="Dfamily" type="xs:string" /> <!-- deprecated as they are too weak for filtering -->
    <xs:attribute name="DsubFamily" type="xs:string" /> <!-- deprecated as they are too weak for filtering -->

support implemented and will remain - unexpected behavior will not be updated

BoardReferenceType
    <xs:attribute name="Dvendor"     type="DeviceVendorEnum" use="optional"/> <!-- deprecated in 1.2 -->
    <xs:attribute name="Dname"       type="xs:string"        use="optional"/> <!-- deprecated in 1.2 -->

not supported - mountedDevice is used instead

CompatibleDeviceType
    <xs:attribute name="Dfamily"     type="xs:string"        use="optional" /> <!-- deprecated  -->
    <xs:attribute name="DsubFamily"  type="xs:string"        use="optional" /> <!-- deprecated -->
    <xs:attribute name="Dname"       type="xs:string"        use="optional" /> <!-- use wild card -->

supported and will remain - unexpected results will not be updated

BoardsDevicetype
    <xs:attribute name="Dfamily"     type="xs:string"        use="optional"/> <!-- deprecated -->
    <xs:attribute name="DsubFamily"  type="xs:string"        use="optional"/> <!-- deprecated -->

TBC

FileType
    <xs:attribute name="copy" type="xs:string" use="optional" />

supported and will remain

GeneratorDeviceSelectType
    <xs:attribute name="Dvariant" type="xs:string"        use="optional" /> <!-- deprecated -->

not implemented

GeneratorType
      <xs:element name="command" type="xs:string" minOccurs="0" />
      <xs:element name="arguments" type="GeneratorCommandArgumentsType" minOccurs="0" />

TBC