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_GOLDEN = 1,   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) (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)
	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.

FWUP module APIs provide the feature of updating firmware. There are two locations of firmware preset. One is Current location and the other is TRIAL location. When firmware upgrade happens the new firmware will be written in TRIAL location. Upon validation, that firmware moves to Current location. While a firmware is being present in TRIAL location, new firmware upgradation can not take place until the firmware present in TRIAL location is either accepted or rejected.

m2mb_fwup_init API should be used to initialize the FWUP module, this will create an internal thread and waits for m2mb_fwup_start API to get called. This API cannot be called when active firmware is running in TRIAL location.

m2mb_fwup_start API should be called when the actual data for FWUP is about to be received.

m2mb_fwup_process_recv_data API is used to send the received data to FWUP. Considering the usual size of firmware, FWUP can only process 2048 bytes at a given time. So, the firmware should be processed as fragments. The type of fragment should be given as the input, M2MB_FWUP_DATA_FRAGMENT should be set as the flag for initial or subsequent fragment. M2MB_FWUP_DATA_FRAGMENT_LAST should be set as the flag for last fragment of firmware. M2MB_FWUP_DATA_FRAGMENT_ERROR should be set as the flag in case of receive failure.

m2mb_fwup_get_active_fwd API can be used to find out the boot type of active firmware.

m2mb_fwup_done API can be used to validate the firmware in TRIAL image location.

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) (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 201 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 91 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_GOLDEN	FirmWare being in Golden image location
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 78 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 104 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

)

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;
}