M2MB FWUP

This section describes M2MB APIs to perform various firmware upgrade module operations. More...

enum	M2MB_FWUP_FWD_BOOT_TYPE {   M2MB_FWUP_FWD_BOOT_TYPE_CURRENT = 2,   M2MB_FWUP_FWD_BOOT_TYPE_TRIAL = 4 }
	FWUP Firmware Boot Type enumeration. More...
enum	M2MB_FWUP_DATA_FLAG {   M2MB_FWUP_DATA_FRAGMENT = 1,   M2MB_FWUP_DATA_FRAGMENT_LAST = 2,   M2MB_FWUP_DATA_FRAGMENT_ERROR = 0 }
	FWUP Data event enumeration. More...
enum	M2MB_FWUP_STATUS_CODE {   M2MB_FWUP_OK_E = 0,   M2MB_FWUP_ERROR_E = 1,   M2MB_FWUP_ERR_INCOMPLETE_E = 1000,   M2MB_FWUP_ERR_SESSION_IN_PROGRESS_E,   M2MB_FWUP_ERR_SESSION_NOT_START_E,   M2MB_FWUP_ERR_SESSION_NOT_READY_FOR_SUSPEND_E,   M2MB_FWUP_ERR_SESSION_NOT_SUSPEND_E,   M2MB_FWUP_ERR_SESSION_RESUME_NOT_SUPPORT_E,   M2MB_FWUP_ERR_SESSION_CANCELLED_E,   M2MB_FWUP_ERR_SESSION_SUSPEND_E,   M2MB_FWUP_ERR_INTERFACE_NAME_TOO_LONG_E,   M2MB_FWUP_ERR_URL_TOO_LONG_E,   M2MB_FWUP_ERR_FLASH_NOT_SUPPORT_FW_UPGRADE_E,   M2MB_FWUP_ERR_FLASH_INIT_TIMEOUT_E,   M2MB_FWUP_ERR_FLASH_READ_FAIL_E,   M2MB_FWUP_ERR_FLASH_WRITE_FAIL_E,   M2MB_FWUP_ERR_FLASH_ERASE_FAIL_E,   M2MB_FWUP_ERR_FLASH_NOT_ENOUGH_SPACE_E,   M2MB_FWUP_ERR_FLASH_CREATE_PARTITION_E,   M2MB_FWUP_ERR_FLASH_IMAGE_NOT_FOUND_E,   M2MB_FWUP_ERR_FLASH_ERASE_PARTITION_E,   M2MB_FWUP_ERR_FLASH_WRITE_PARTITION_E,   M2MB_FWUP_ERR_IMAGE_NOT_FOUND_E,   M2MB_FWUP_ERR_IMAGE_DOWNLOAD_FAIL_E,   M2MB_FWUP_ERR_INCORRECT_IMAGE_CHECKSUM_E,   M2MB_FWUP_ERR_SERVER_RSP_TIMEOUT_E,   M2MB_FWUP_ERR_INVALID_FILENAME_E,   M2MB_FWUP_ERR_INCORRECT_IMAGE_HDR_E,   M2MB_FWUP_ERR_INSUFFICIENT_MEMORY_E,   M2MB_FWUP_ERR_INCORRECT_SIGNATURE_E,   M2MB_FWUP_ERR_INCORRCT_VERSION_E,   M2MB_FWUP_ERR_INCORRECT_NUM_IMAGES_E,   M2MB_FWUP_ERR_INCORRECT_IMAGE_LENGTH_E,   M2MB_FWUP_ERR_INCORRECT_HASH_TYPE_E,   M2MB_FWUP_ERR_INCORRECT_IMAGE_ID_E,   M2MB_FWUP_ERR_BATTERY_LEVEL_TOO_LOW_E,   M2MB_FWUP_ERR_CRYPTO_FAIL_E,   M2MB_FWUP_ERR_PLUGIN_ENTRY_EMPTY_E,   M2MB_FWUP_ERR_TRIAL_IS_RUNNING_E,   M2MB_FWUP_ERR_FILE_NOT_FOUND_E,   M2MB_FWUP_ERR_FILE_OPEN_ERROR_E,   M2MB_FWUP_ERR_FILE_NAME_TOO_LONG_E,   M2MB_FWUP_ERR_FILE_WRITE_ERROR_E,   M2MB_FWUP_ERR_MOUNT_FILE_SYSTEM_ERROR_E,   M2MB_FWUP_ERR_PRESERVE_LAST_FAILED_E }
	FWUP operation status enumeration. More...
typedef enum M2MB_FWUP_FWD_BOOT_TYPE	M2MB_FWUP_FWD_BOOT_TYPE_T
	FWUP Firmware Boot Type enumeration. More...
typedef enum M2MB_FWUP_DATA_FLAG	M2MB_FWUP_DATA_FLAG_T
	FWUP Data event enumeration. More...
typedef enum M2MB_FWUP_STATUS_CODE	M2MB_FWUP_STATUS_CODE_T
	FWUP operation status enumeration. More...
typedef VOID(*	M2MB_FWUP_USER_CB_T) (void *user_ctx, M2MB_FWUP_STATUS_CODE_T resp_code)
	Firmware Upgrade user call back prototype. More...
M2MB_STATUS_T	m2mb_fwup_init (UINT32 flags)
	FWUP module initialization. More...
M2MB_STATUS_T	m2mb_fwup_start (M2MB_FWUP_USER_CB_T user_cb, void *user_cb_ctx)
	FWUP module start. More...
M2MB_STATUS_T	m2mb_fwup_process_recv_data (UINT32 data_len, UINT8 *data_ptr, M2MB_FWUP_DATA_FLAG_T flag)
	FWUP module process data. More...
UINT8	m2mb_fwup_get_active_fwd (UINT32 *fwd_boot_type, UINT32 *valid_fwd)
	FWUP module active firmware information. More...
M2MB_FWUP_STATUS_CODE_T	m2mb_fwup_done (UINT32 accept, UINT32 reboot)
	FWUP module validate TRIAL image. More...

Detailed Description

This section describes M2MB APIs to perform various firmware upgrade module operations.

Firmware Upgrade

Firmware Memory Map

Firmware Upgrade module APIs provide the feature of updating firmware. There are two locations of firmware, FWS1 and FWS2 (Firmware Set). The running firmware i.e, the current firmware will be present in one of this location. When firmware upgrade happens, the new firmware will be written to the other location. Upon validation, if the user accepts it, that firmware becomes active and from next boot the active firmware runs. If the user rejects the newly loaded firmware, the old firmware becomes active. For the next firmware upgrade user must validate (either accept or reject) the old upgraded firmware, else, firmware upgrade procedure fails. The firmware set contains multiple firmware bundled into one binary, that is given to firmware update module. Each FW has its own file system, and on firmware upgrade procedure the file system is copied from one location the other. For the Firmware upgrade, user must call the APIs in below sequence:

• User calls m2mb_fwup_init to initialize the FWUP module. This will allocate resource needed.
• When the Firmware upgrade request is triggered (by pressing button, or over serial port or over network), user calls the m2m_fwup_start API with its user callback. This will put the system in FWUP mode and starts a timer for 2mins to start receiving data from the user. In case it doesn’t receive data within 2mins, it comes out of firmware upgrade mode and indicates failure to the user by calling the registered user callback.
• User calls m2mb_fwup_process_data to process the received firmware. Since the firmware is huge user calls this API as and when it received data from external world. On the first call to this API after m2mb_fwup_start, the 2min timer is stopped and 1min timer is started to wait to receive the next block of data (call of m2mb_fwup_process_data).
• Upon receiving the complete data, FWUP module stops the 1min timer and copies the file system, by optimizing the discarded flash sector. User is indicated before this process starts, by calling the registered callback. User can complete all file operation, so that data is saved properly and copied to the next file system location.
• If user has indicated auto reboot, then the system is automatically reboot after the user callback is called with FWUP success message. Else, user must reboot the system by calling m2mb_system_reset. User is reuired to complete any procedure (indicating its peers of FWUP completion) if needed in the user callback and make sure the data is gone out by putting delay.
• On reboot, the new FW starts running.
• User needs to accept the new FW or need to reject it by calling m2mb_fwup_done. On reject, the system will use the old FW.
• Note that user needs to call API before initiating next FWUP procedure, else FWUP procedure will fail.

Typedef Documentation

M2MB_FWUP_DATA_FLAG_T

typedef enum M2MB_FWUP_DATA_FLAG M2MB_FWUP_DATA_FLAG_T

FWUP Data event enumeration.

This enum defines macros for DATA event of FWUP data processing. This event signify the type/portion of the data for processing.

M2MB_FWUP_FWD_BOOT_TYPE_T

typedef enum M2MB_FWUP_FWD_BOOT_TYPE M2MB_FWUP_FWD_BOOT_TYPE_T

FWUP Firmware Boot Type enumeration.

This enum defines macros for type of the firmware currently active.

M2MB_FWUP_STATUS_CODE_T

typedef enum M2MB_FWUP_STATUS_CODE M2MB_FWUP_STATUS_CODE_T

FWUP operation status enumeration.

This enum defines macros for FWUP operation status. This status signify the result of various operations on FWUP module.

M2MB_FWUP_USER_CB_T

typedef VOID(* M2MB_FWUP_USER_CB_T) (void *user_ctx, M2MB_FWUP_STATUS_CODE_T resp_code)

Firmware Upgrade user call back prototype.

Type definition of the user callback to receive asynchronous events from FWUP module. It is registered with m2mb_fwup_start API, and it will be called by FWUP module thread context internally incase of success or failure.

Parameters

[in]

resp_code

resp_code provides the response status code of the operation.

Example

VOID m2m_fwup_user_cb( UINT32 response_code )
{
    if(response_code == M2MB_FWUP_OK_E)
    {
        ...
    }
    else
    {
        ...
    }
}
int main()
{
    INT8 result;

    ...

    result = m2mb_fwup_init();
    if (result != M2MB_OK)
    {
        return M2MB_ERROR;
    }

    ...

    result = m2mb_fwup_start( m2m_fwup_user_cb  );
    if (result != M2MB_OK)
    {
        return M2MB_ERROR;
    }
    return M2MB_OK;
}

Definition at line 195 of file m2mb_fwup.h.

Enumeration Type Documentation

M2MB_FWUP_DATA_FLAG

enum M2MB_FWUP_DATA_FLAG

FWUP Data event enumeration.

This enum defines macros for DATA event of FWUP data processing. This event signify the type/portion of the data for processing.

Enumerator
M2MB_FWUP_DATA_FRAGMENT	Part of request body received
M2MB_FWUP_DATA_FRAGMENT_LAST	Entire request is received
M2MB_FWUP_DATA_FRAGMENT_ERROR	Error in receiving

Definition at line 85 of file m2mb_fwup.h.

M2MB_FWUP_FWD_BOOT_TYPE

enum M2MB_FWUP_FWD_BOOT_TYPE

FWUP Firmware Boot Type enumeration.

This enum defines macros for type of the firmware currently active.

Enumerator
M2MB_FWUP_FWD_BOOT_TYPE_CURRENT	FirmWare being in Current image location
M2MB_FWUP_FWD_BOOT_TYPE_TRIAL	FirmWare being in TRIAL image location

Definition at line 73 of file m2mb_fwup.h.

M2MB_FWUP_STATUS_CODE

enum M2MB_FWUP_STATUS_CODE

FWUP operation status enumeration.

This enum defines macros for FWUP operation status. This status signify the result of various operations on FWUP module.

Enumerator
M2MB_FWUP_OK_E	Operation performed successfully.
M2MB_FWUP_ERROR_E	Operation failed.
M2MB_FWUP_ERR_INCOMPLETE_E	Operation is incomplete.
M2MB_FWUP_ERR_SESSION_IN_PROGRESS_E	FWUP session is in progress
M2MB_FWUP_ERR_SESSION_NOT_START_E	FWUP session is not started.
M2MB_FWUP_ERR_SESSION_NOT_READY_FOR_SUSPEND_E	FWUP session is not ready to be Suspended
M2MB_FWUP_ERR_SESSION_NOT_SUSPEND_E	FWUP session is not in the Suspend state.
M2MB_FWUP_ERR_SESSION_RESUME_NOT_SUPPORT_E	FWUP session resume is not supported.
M2MB_FWUP_ERR_SESSION_CANCELLED_E	FWUP session was canceled.
M2MB_FWUP_ERR_SESSION_SUSPEND_E	FWUP session was suspended.
M2MB_FWUP_ERR_INTERFACE_NAME_TOO_LONG_E	Interface name is too long.
M2MB_FWUP_ERR_URL_TOO_LONG_E	URL is too long.
M2MB_FWUP_ERR_FLASH_NOT_SUPPORT_FW_UPGRADE_E	Not supported firmware upgrade.
M2MB_FWUP_ERR_FLASH_INIT_TIMEOUT_E	Flash initialization timeout.
M2MB_FWUP_ERR_FLASH_READ_FAIL_E	Flash read failure.
M2MB_FWUP_ERR_FLASH_WRITE_FAIL_E	Flash write failure.
M2MB_FWUP_ERR_FLASH_ERASE_FAIL_E	Flash erase failure.
M2MB_FWUP_ERR_FLASH_NOT_ENOUGH_SPACE_E	Not enough free space in flash.
M2MB_FWUP_ERR_FLASH_CREATE_PARTITION_E	Partition creation failure.
M2MB_FWUP_ERR_FLASH_IMAGE_NOT_FOUND_E	Partition image was not found.
M2MB_FWUP_ERR_FLASH_ERASE_PARTITION_E	Partition erase failure.
M2MB_FWUP_ERR_FLASH_WRITE_PARTITION_E	Partition write failure.
M2MB_FWUP_ERR_IMAGE_NOT_FOUND_E	Image not found failure.
M2MB_FWUP_ERR_IMAGE_DOWNLOAD_FAIL_E	Image download failure.
M2MB_FWUP_ERR_INCORRECT_IMAGE_CHECKSUM_E	Incorrect image checksum failure.
M2MB_FWUP_ERR_SERVER_RSP_TIMEOUT_E	Server communication timeout.
M2MB_FWUP_ERR_INVALID_FILENAME_E	Image file name is invalid.
M2MB_FWUP_ERR_INCORRECT_IMAGE_HDR_E	FWUP image header is invalid.
M2MB_FWUP_ERR_INSUFFICIENT_MEMORY_E	Not enough memory.
M2MB_FWUP_ERR_INCORRECT_SIGNATURE_E	FWUP image signature is invalid.
M2MB_FWUP_ERR_INCORRCT_VERSION_E	FWUP image version is invalid.
M2MB_FWUP_ERR_INCORRECT_NUM_IMAGES_E	FWUP image number of images is invalid.
M2MB_FWUP_ERR_INCORRECT_IMAGE_LENGTH_E	FWUP image length is invalid.
M2MB_FWUP_ERR_INCORRECT_HASH_TYPE_E	FWUP image hash type is invalid.
M2MB_FWUP_ERR_INCORRECT_IMAGE_ID_E	FWUP image ID is invalid.
M2MB_FWUP_ERR_BATTERY_LEVEL_TOO_LOW_E	Battery level is too low.
M2MB_FWUP_ERR_CRYPTO_FAIL_E	Crypto check failure.
M2MB_FWUP_ERR_PLUGIN_ENTRY_EMPTY_E	FWUP plugin callback is empty.
M2MB_FWUP_ERR_TRIAL_IS_RUNNING_E	TRIAL image is running
M2MB_FWUP_ERR_FILE_NOT_FOUND_E	File was not found.
M2MB_FWUP_ERR_FILE_OPEN_ERROR_E	Open file failure.
M2MB_FWUP_ERR_FILE_NAME_TOO_LONG_E	File name is too long.
M2MB_FWUP_ERR_FILE_WRITE_ERROR_E	Write file failure.
M2MB_FWUP_ERR_MOUNT_FILE_SYSTEM_ERROR_E	Mount file system failure.
M2MB_FWUP_ERR_PRESERVE_LAST_FAILED_E	Preserving failure.

Definition at line 98 of file m2mb_fwup.h.

Function Documentation

m2mb_fwup_done()

M2MB_FWUP_STATUS_CODE_T m2mb_fwup_done	(	UINT32	accept,
		UINT32	reboot
	)

FWUP module validate TRIAL image.

This API validates the firmware present in TRIAL image location. If the firmware is accepted, it will be moved to current image location upon reboot.

Parameters

[in]	accept	1 - To accept the TRIAL image. 0 - To discard the TRIAL image.
[in]	reboot	1 - To reboot after validation. 0 - Not to reboot after validation.

Returns

Returns M2MB_OK on success, M2MB_ERROR on failure

m2mb_fwup_done(UINT32 accept, UINT32 reboot);

  VOID m2m_fwup_user_cb( UINT32 response_code )
  {
      if(response_code == M2MB_FWUP_OK_E)
      {
          ...
      }
      else
      {
          ...
      }
  }
  int main()
  {
  INT8 result;

  ...

  result = m2mb_fwup_init();
  if (result != M2MB_OK)
          {
          return M2MB_ERROR;
          }
          
...

          result = m2mb_fwup_start( m2m_fwup_user_cb  );
  if (result != M2MB_OK)
          {
          return M2MB_ERROR;
          }

          ...

          while(total_length)
          {
              //if partial data is received 
              result = m2mb_fwup_m2mb_fwup_process_recv_data( length, data, 
                          M2MB_FWUP_DATA_BODY_RECV );
              if( result != M2MB_OK )
              {
                  return M2MB_ERROR;
              }

              //if complete data is received 
    result = m2mb_fwup_m2mb_fwup_process_recv_data( length, data, 
                M2MB_FWUP_DATA_ALL_RECV );
    if( result != M2MB_OK )
    {
        return M2MB_ERROR;
    }

    total_length -= length;
          }
          
...

          m2mb_fwup_done( 1, 0 ); //To accept and reboot
          
          return M2MB_OK;
}

m2mb_fwup_get_active_fwd()

UINT8 m2mb_fwup_get_active_fwd	(	UINT32 *	fwd_boot_type,
		UINT32 *	valid_fwd
	)

FWUP module active firmware information.

This API provides active firmware descriptor of FWUP module.

Parameters

[out]	fwd_boot_type	Boot type of active firmware descriptor.
[out]	valid_fwd	Validity of active firmware descriptor.

Returns

Returns Boot Block Number

m2mb_fwup_get_active_fwd(UINT32 *fwd_boot_type, UINT32 *valid_fwd);

  int main()
  {
  INT8 result;

  ...

UINT32 fwd_boot_type = 0;
UINT32 valid_fwd     = 0;

m2mb_fwup_get_active_fwd( &fwd_boot_type, &valid_fwd );

if( fwd_boot_type != M2MB_FWUP_FWD_BOOT_TYPE_TRIAL )
{
    m2mb_fwup_init( 1 );
}

...

          return M2MB_OK;
}

m2mb_fwup_init()

M2MB_STATUS_T m2mb_fwup_init

(

UINT32

flags

)

FWUP module initialization.

This API initializes FWUP module. FWUP module can't be initialized of active firmware's boot type is not M2MB_FWUP_FWD_BOOT_TYPE_TRIAL.

Parameters

[in]

flags

User should pass the flags, this defines the auto-reboot feature.

Returns

Returns M2MB_OK on success, M2MB_ERROR on failure

m2mb_fwup_init( UINT32 flags );

  int main()
  {
  INT8 result;

  ...

  result = m2mb_fwup_init();
  if (result != M2MB_OK)
          {
          return M2MB_ERROR;
          }
          return M2MB_OK;
}

m2mb_fwup_process_recv_data()

M2MB_STATUS_T m2mb_fwup_process_recv_data	(	UINT32	data_len,
		UINT8 *	data_ptr,
		M2MB_FWUP_DATA_FLAG_T	flag
	)

FWUP module process data.

This API sends the data to be processed to FWUP module.

Parameters

[in]	data_len	Length of the data to be processed by FWUP module.
[in]	data_ptr	Pointer containing location of the data to be processed by FWUP module.
[in]	flag	Flag of type M2MB_FWUP_DATA_FLAG_T defining the type/portion of the data to be processed.

Returns

Returns M2MB_OK on success, M2MB_ERROR on failure

m2mb_fwup_process_recv_data( UINT32 data_len, UINT8 *data_ptr, M2MB_FWUP_DATA_FLAG_T event );

  VOID m2m_fwup_user_cb( UINT32 response_code )
  {
      if(response_code == M2MB_FWUP_OK_E)
      {
          ...
      }
      else
      {
          ...
      }
  }
  int main()
  {
  INT8 result;

  ...

  result = m2mb_fwup_init();
  if (result != M2MB_OK)
          {
          return M2MB_ERROR;
          }

          ...

          result = m2mb_fwup_start( m2m_fwup_user_cb  );
  if (result != M2MB_OK)
          {
          return M2MB_ERROR;
          }

          ...

          while(total_length)
          {
              //if partial data is received 
              result = m2mb_fwup_m2mb_fwup_process_recv_data( length, data, 
                          M2MB_FWUP_DATA_BODY_RECV );
              if( result != M2MB_OK )
              {
                  return M2MB_ERROR;
              }

              //if complete data is received 
    result = m2mb_fwup_m2mb_fwup_process_recv_data( length, data, 
                M2MB_FWUP_DATA_ALL_RECV );
    if( result != M2MB_OK )
    {
        return M2MB_ERROR;
    }

    total_length -= length;
          }

          
          return M2MB_OK;
}

m2mb_fwup_start()

M2MB_STATUS_T m2mb_fwup_start	(	M2MB_FWUP_USER_CB_T	user_cb,
		void *	user_cb_ctx
	)

FWUP module start.

This API starts FWUP module.

Parameters

[in]

user_cb

User should pass a callback of type M2MB_FWUP_USER_CB_T to receive status of FWUP operations.

Returns

Returns M2MB_OK on success, M2MB_ERROR on failure

m2mb_fwup_start( M2MB_FWUP_USER_CB_T user_cb );

  VOID m2m_fwup_user_cb( UINT32 response_code )
  {
      if(response_code == M2MB_FWUP_OK_E)
      {
          ...
      }
      else
      {
          ...
      }
  }
  int main()
  {
  INT8 result;

  ...

  result = m2mb_fwup_init();
  if (result != M2MB_OK)
          {
          return M2MB_ERROR;
          }

          ...

          result = m2mb_fwup_start( m2m_fwup_user_cb  );
  if (result != M2MB_OK)
          {
          return M2MB_ERROR;
          }
          return M2MB_OK;
}