Subject: [Capwap] Proposed Text for Issue 237: Changes to firmware download process

From: "Pat Calhoun (pacalhou)" <[email-masked]>
Date: Thu, 25 Jan 2007 06:22:16 -0800

The following text addresses issue 237. 

2.3.1.  CAPWAP Protocol State Transitions
[...]
   Join to DTLS Teardown (p):  This transition occurs when the join
      process failed.

      WTP:  This state transition occurs when the WTP receives a Join
         Response with a Result Code message element containing an
         error, or if the Image Identifier provided by the AC in the
         Join Response differs from the WTP's currently running firmware
         version and the WTP has the requested image in its non-volatile
         memory.  This causes the WTP to initiate the DTLSShutdown
         command (see Section 2.3.2.1).

      AC:  This state transition occurs when the AC transmits a Join
         Response with a Result Code message element containing an
         error.  This causes the AC to initiate the DTLSShutdown command
         (see Section 2.3.2.1).
[...]

   Configure to Image Data (r):  This state transition is used by the
      WTP and the AC to download executable firmware.

      WTP:  The WTP enters the Image Data state when it successfully
         comletes DTLS session establishment, and determines that the
         Image Identifier provided by the AC in the Join Request differs
         from its currently running firmware, and that the WTP does not
         have the requested firmware in its non-volatile memory.  The
         WTP transmits the Image Data Request (see Section 9.1) message
         requesting that a download of the AC's latest firmware be
         initiated.

      AC:  This state transition occurs when the AC receives the Image
         Data Request message from the WTP.  The AC must transmit an
         Image Data Response message (see Section 9.2) to the WTP, which
         includes a portion of the firmware. 

4.5.  CAPWAP Protocol Message Elements
[...]
   Image Identifier                                     25

4.5.25.  Image Identifier

   The image Identifier message element is sent by the AC to the WTP and
   is used to indicate the expected active software version that is to
   be run on the WTP.  The value is a variable length UTF-8 encoded
   string, which is NOT zero terminated.

      0                   1                   2                   3
      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                       Vendor Identifier                       |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                          Value...
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Type:   25 for Image Identifier

   Length:   >= 1

   Value:   A variable length UTF-8 encoded string containing the
      firmware identifier to be run on the WTP.

4.5.31.  Result Code
[...]
      11 Reset Failure (Firmware Write Error)

4.5.37.  WTP Descriptor
[...]
   Type:   The following values are supported.  The Hardware Version,
      Active Software Version, and Boot Version values MUST be included.
      Zero or more Other Software Version values MAY be included.

      0 - Hardware Version:   The WTP's hardware version number.

      1 - Active Software Version:   The WTP's running Firmware version
         number.

      2 - Boot Version:   The WTP's boot loader's version number.

      3 - Other Software Version:   The WTP's non-running Firmware
         version numbers.

6.2.  Join Response
[...]
   The AC includes the Image Identifier as a means to indicate to the
   WTP which software version it expects it to run.  This information is
   used to determine whether the WTP MUST either change it currently
   running firmware image, or possibly download a new version (see
   Section 9.1).

[...]
   The following message element MUST be included in the Join Response
   message.

   o  AC Descriptor, see Section 4.5.1

   o  Image Identifier, see Section 4.5.25

8.5.  Configuration Update Request
[...]
   The AC includes the Image Identifier and Initiate Download message
   elements as a means to force the WTP to update its firmware while in
   the Run state.  The WTP MAY proceed to download the requested
   firmware if it determines the version specified in the Image
   Identifier message element is not in its non-volatile storage (see
   Section 9.1).

   One or more of the following message elements MAY be included in the
   Configuration Update message.
[...]
   o  Image Identifier, see Section 4.5.25

   o  Initiate Download, see Section 4.5.26

9.1.  Image Data Request

   The Image Data Request message is used to update firmware on the WTP.
   This message and its companion response message are used by the AC to
   ensure that the image being run on each WTP is appropriate.

   Image Data Request messages are exchanged between the WTP and the AC
   to download a new firmware image to the WTP.  When a WTP or AC
   receives an Image Data Request message it will respond with an Image
   Data Response message.  The message elements contained within the
   Image Data Request message are required to determine the intent of
   the request.

   The decision that new firmware is to be downloaded to the WTP can
   occur in one of two methods:

      When the WTP joins the AC, the Join Response includes the Image
      Identifier message element, which informs the WTP of the firmware
      it is expected to run. if the WTP does not currently have the
      requested firmware version, it transmits an Image Data Request,
      with the appropriate Image Identifier message element.  If the WTP
      already has the requested firmware, it simply resets.

      Once the WTP is in the Run state, it is possible for the AC to
      cause the WTP to initiate a firmware download by sending an Image
      Data Request message, by sending a Configuration Update Request
      with the Initiate Download and and Image Identifier message
      elements.  The WTP then transmits the Image Data Request message,
      which includes the Image Identifier message element to start the
      download process.  Note that when the firmware is downloaded in
      this fashion, the WTP does not automatically reset after the
      download is complete.  The WTP will only reset once it receives an
      explicit Reset Request from the AC.

   Regardless of how the download was initiated, once the AC receives an
   Image Data Request with the Image Identifier message element, it
   begins the transfer process by transmitting its own request with the
   Image Data message element.  This continues until the firmware image
   has been transfered.

   The following message elements MAY be included in the Image Data
   Request message.

   o  Image Data, see Section 4.5.24

   o  Image Identifier, see Section 4.5.25

9.3.  Reset Request

   The Reset Request message is used to cause a WTP to reboot.

   A Reset Request message is sent by an AC to cause a WTP to
   reinitialize its operation.

   The following message elements MUST be included in the Reset Request
   message.

   o  Image Identifier, see Section 4.5.25

   When a WTP receives a Reset Request it will respond with a Reset
   Response indicating success and then reinitialize itself.  If the WTP
   is unable to write to its non-volatile storage in order to ensure
   that it runs the requested software version indicated in the Image
   Identifier message element, it MAY set the appropriate Result Code
   message element, but MUST reboot anyhow.  In the event the WTP is
   unable to reset, including a hardware reset, it can respond with a
   Reset Response whose Result Code message element indicates failure,
   but the AC will no longer provide it service.

Pat Calhoun
CTO, Wireless Networking Business Unit
Cisco Systems
_________________________________________________________________
To unsubscribe or modify your subscription options, please visit:
http://lists.frascone.com/mailman/listinfo/capwap

Archives: http://lists.frascone.com/pipermail/capwap

---

From: Margaret Wasserman <[email-masked]>
Date: Mon, 29 Jan 2007 09:48:00 -0500

Hi All,

We had consensus at the interim meeting last week that a specific set  
of changes should be made to address the firmware download issues  
described in issue #237 (Changes to firmware download process).  The  
text below (sent to the list by Pat Calhoun on January 25th)  
represents that set of changes.

We also agreed that with these changes and the changes already in the  
-04 version of the base draft, we could close the other firmware- 
related issues that are currently open in the tracker:  #126 (Wrong  
place for "Image Data" state), #192 (Problems with image data request  
and response) & #200 (Trickle firmware download).

If anyone disagrees with the consensus to make the changes below and  
to close issues #237, #126, #192 and #200, please respond to this  
message with your concerns by Monday, February 5th.  Please do not  
use this thread for general discussion of firmware-related issues,  
only for responses to this consensus confirmation.

Those attending the meeting are aware that the proposed changes do  
not incorporate all of the suggestions that David Perkins made in his  
recent firmware process proposal (the one that became issue #237),  
but we were not able to reach consensus on all of the proposed  
changes.  David may follow-up with a new proposal to the mailing list  
for additional changes to the firmware process that are not included  
in the below text.   If so, that proposal will be considered as a new  
issue.

Margaret

---

From: "Pat Calhoun (pacalhou)" <[email-masked]>
Date: Mon, 29 Jan 2007 15:49:09 -0800

Margaret,

Issue 238 also includes further clarifications to the firmware download
process, and also addresses some of the issues David had brought up that
the team felt was useful/necessary. Text has also been posted for this
issue.

Pat Calhoun

> -----Original Message-----
> From: Margaret Wasserman [mailto:[email-masked]] 
> Sent: Monday, January 29, 2007 6:48 AM
> To: Pat Calhoun (pacalhou)
> Cc: [email-masked]
> Subject: CONSENSUS CONFIRMATION: Firmware-related issues
> 
> 
> Hi All,
> 
> We had consensus at the interim meeting last week that a 
> specific set of changes should be made to address the 
> firmware download issues described in issue #237 (Changes to 
> firmware download process).  The text below (sent to the list 
> by Pat Calhoun on January 25th) represents that set of changes.
> 
> -04 version of the base draft, we could close the other 
> firmware- related issues that are currently open in the 
> tracker:  #126 (Wrong place for "Image Data" state), #192 
> (Problems with image data request and response) & #200 
> (Trickle firmware download).
> 
> If anyone disagrees with the consensus to make the changes 
> below and to close issues #237, #126, #192 and #200, please 
> respond to this message with your concerns by Monday, 
> February 5th.  Please do not use this thread for general 
> discussion of firmware-related issues, only for responses to 
> this consensus confirmation.
> 
> Those attending the meeting are aware that the proposed 
> changes do not incorporate all of the suggestions that David 
> Perkins made in his recent firmware process proposal (the one 
> that became issue #237), but we were not able to reach 
> consensus on all of the proposed changes.  David may 
> follow-up with a new proposal to the mailing list for 
> additional changes to the firmware process that are not included  
> > 2.3.1.  CAPWAP Protocol State Transitions [...]
> > 4.5.  CAPWAP Protocol Message Elements [...]
> >    Image Identifier                                     25
> >
> >
> > 4.5.25.  Image Identifier
> >
> >      |                       Vendor Identifier              
>          |
> >    One or more of the following message elements MAY be 
> included in  
> > the
> >    The Image Data Request message is used to update 
> firmware on the  
> > WTP.
> >    begins the transfer process by transmitting its own 
> request with  
> > the