platform_dct.h File Reference

Data Structures
struct	platform_dct_bt_config_t
struct	platform_dct_ota2_config_t
struct	platform_dct_p2p_config_t

Detailed Description

Defines Device Configuration Table (DCT) structures

Instructions for adding to the DCT

1) Basic Rules:

--> Fill to end platform_data_dct_t on an 8-byte boundary so that app_dct is 8-byte aligned <–

WE CANNOT CHANGE THE LAYOUT OF platform_dct_header_t FROM THE SDK VERSION THE BOOTLOADER WAS BUILT WITH DO NOT ADD OR REMOVE ANY FIELDS OR STRUCTURES BETWEEN platform_dct_header_t AND platform_dct_version_t !!!

The Bootloader only knows about platform_dct_header_t for the SDK it was built upon.
The Bootloader is not upgrade-able, so platform_dct_header_t MUST match the platform_dct_header_t
and all fields be used in the same manner as the Bootloader's SDK.

--> DO NOT ADD OR REMOVE ANY FIELDS OR STRUCTURES BETWEEN platform_dct_header_t AND platform_dct_version_t !!! <–

If you need to add something that you believe should be in platform_dct_header_t.
see if it makes sense to put the field into platform_dct_version_h. Doing this will make
maintenance much much simpler.

---> ONLY ADD DATA TO THE END of platform_dct_data_t after platform_dct_version_h !!! <—

Changing fields in existing structures (or new structures to the end of platform_dct_data_t) will require code to update from the previous version of the DCT to the new version you are creating.

All sub-structures MUST be a multiple of 4 bytes in size.

All previously optional sub-structures are always defined. This simplifies updating SDKs in the future.

If you are adding an "optional" structure, see how bt, p2p, and ota2 are handled below using flags to indicate if the structures are in use or not. WICED_DCT_INCLUDE_BT_CONFIG WICED_DCT_INCLUDE_P2P_CONFIG WICED_DCT_INCLUDE_OTA2_CONFIG

---> ONLY ADD DATA TO THE END of platform_dct_data_t after platform_dct_version_h !!! <—

2) Steps to ADD data to the end of platform_dct_data_t

• Encapsulate the new data in a new structure - name it "misc" or "additional"
• Add the new structure inside platform_dct_data_t, after the last structure (currently platform_dct_version_t)
• Add a new DCT_BOOTLOADER_SDK_CURRENT to the #defines below and comment changes
• Add code to platform_dct_external_common.c :: wiced_dct_external_dct_update AND platform_dct_internal_common.c :: wiced_dct_internal_dct_update to support changes from the previous DCT version to the current DCT version
• Add support to call the upgrade routine in wiced_dct_external_common.c and wiced_dct_internal_common.c in functions wiced_dct_external_dct_update() and wiced_dct_internal_dct_update().

3) If you are deprecating a field in an existing structure

• change the name of the field to "deprecated_xxxx" where xxx is the previous field's name
• This will keep the documentation of the change as part of the code
• You may re-use a deprecated field (rename it, but keep the deprecated name in a comment )

4) If you must change fields in an existing DCT structure

• THE CHANGES MUST NOT CHANGE THE SIZE OF THE STRUCTURE !!!!
• provide the previous structure define with the SDK version at the end of the structure name. See the file platform_dct_old_sdk.h in this directory. The SDK in the name is when the struct was last changed. So if the structure hasn't changed since SDK-3.6.0, the old copy of the structure will be: platform_dct_type_t becomes platform_dct_type_sdk_3_6_0_t
• modify the current structure with your new changes
• Add a new DCT_BOOTLOADER_SDK_CURRENT to the #defines below and comment changes
• Add code to platform_dct_external_common.c :: wiced_dct_external_dct_update AND platform_dct_internal_common.c :: wiced_dct_internal_dct_update to support changes from the previous DCT version to the current DCT version
• Add support to call the upgrade routine in wiced_dct_external_common.c and wiced_dct_internal_common.c in functions wiced_dct_external_dct_update() and wiced_dct_internal_dct_update().

Instructions for an application that is going to be upgraded on a system built with an older SDK.

• Define the SDK used when the ORIGINAL bootloader was built on the command line ex: ./make <applicaiton>-<platform> UPDATE_FROM_SDK=3_3_1
• Define the optional substructures (if used) when upgrading an SDK before SDK-3.6.x //: TODO: which rev are we releasing this update to?