From 3a9096aa41f8e32c5f822999979ed15084e650d4 Mon Sep 17 00:00:00 2001 From: Andrew Tridgell <tridge@samba.org> Date: Fri, 15 Jun 2012 11:54:13 +1000 Subject: [PATCH] APM: added longer comment on k_format_version --- ArduPlane/Parameters.h | 35 +++++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/ArduPlane/Parameters.h b/ArduPlane/Parameters.h index 85dd9ab267..4c4cc94e59 100644 --- a/ArduPlane/Parameters.h +++ b/ArduPlane/Parameters.h @@ -9,15 +9,34 @@ // class Parameters { public: - // The version of the layout as described by the parameter enum. - // - // When changing the parameter enum in an incompatible fashion, this - // value should be incremented by one. - // - // The increment will prevent old parameters from being used incorrectly - // by newer code. - // + + /* + The value of k_format_version determines whether the existing + eeprom data is considered valid. You should only change this + value under the following circumstances: + + 1) the meaning of an existing eeprom parameter changes + + 2) the value of an existing k_param_* enum value changes + + Adding a new parameter should _not_ require a change to + k_format_version except under special circumstances. If you + change it anyway then all ArduPlane users will need to reload all + their parameters. We want that to be an extremely rare + thing. Please do not just change it "just in case". + + To determine if a k_param_* value has changed, use the rules of + C++ enums to work out the value of the neighboring enum + values. If you don't know the C++ enum rules then please ask for + help. + */ + + ////////////////////////////////////////////////////////////////// + // STOP!!! DO NOT CHANGE THIS VALUE UNTIL YOU FULLY UNDERSTAND THE + // COMMENTS ABOVE. IF UNSURE, ASK ANOTHER DEVELOPER!!! static const uint16_t k_format_version = 13; + ////////////////////////////////////////////////////////////////// + // The parameter software_type is set up solely for ground station use // and identifies the software type (eg ArduPilotMega versus ArduCopterMega)