LinuxQMISDK: qaGobiApiFms.h File Reference

LinuxQMISDK SLQS03.03.07

- Main Page
- Modules
- References
- Data Structures

- File List
- Globals

Data Structures | Macros | Enumerations | Functions
qaGobiApiFms.h File Reference
Firmware Management Service (FMS)

Firmware Management Service API function prototypes. More...

Go to the source code of this file.

## Data Structures
struct | fwinfo_s
struct | slqsfwinfo_s
struct | qmifwinfo_s
struct | ImageElement
struct | PrefImageList
struct | ImageIdElement
struct | ImageIDEntries
struct | ImageList

## Macros
#define | SLQSFWINFO_MODELID_SZ 20
#define | SLQSFWINFO_BOOTVERSION_SZ 85
#define | SLQSFWINFO_APPVERSION_SZ 85
#define | SLQSFWINFO_SKU_SZ 15
#define | SLQSFWINFO_PACKAGEID_SZ 85
#define | SLQSFWINFO_CARRIER_SZ 20
#define | SLQSFWINFO_PRIVERSION_SZ 10
#define | GOBI_MBN_IMG_ID_STR_LEN 16
#define | GOBI_MBN_BUILD_ID_STR_LEN 100
#define | GOBI_LISTENTRIES_MAX 2
#define | GOBI_SET_IMG_PREF_RSPLEN 40
#define | DEVICE_SHUTDOWN 5
#define | DEVICE_RESET 4
#define | FIRMWARE_UPDATE_SUCCESS 0x01
#define | FIRMWARE_UPDATE_FAIL 0x01
#define | PRI_UPDATE_FAIL 0x02
#define | FIRMWARE_UPGRADE_SUCCESS 0x00

## Enumerations
enum | eGobiImageTech { eGOBI_IMG_TECH_CDMA = 0, eGOBI_IMG_TECH_UMTS }
enum | eGobiImageCarrier { eGOBI_IMG_CAR_GENERIC = 1, eGOBI_IMG_CAR_FACTORY, eGOBI_IMG_CAR_NORF, eGOBI_IMG_CAR_VERIZON = 101, eGOBI_IMG_CAR_SPRINT, eGOBI_IMG_CAR_ALLTEL, eGOBI_IMG_CAR_BELL, eGOBI_IMG_CAR_TELUS, eGOBI_IMG_CAR_US, eGOBI_IMG_CAR_TELSTRA1, eGOBI_IMG_CAR_CHINA_UNICOM, eGOBI_IMG_CAR_TELCOM_NZ, eGOBI_IMG_CAR_SK_TELCOM1, eGOBI_IMG_CAR_RELIANCE1, eGOBI_IMG_CAR_TATA, eGOBI_IMG_CAR_METROPCS, eGOBI_IMG_CAR_LEAP, eGOBI_IMG_CAR_KDDI, eGOBI_IMG_CAR_IUSACELL, eGOBI_IMG_CAR_CHINA_TELECOM, eGOBI_IMG_CAR_OMH, eGOBI_IMG_CAR_GENERIC_CDMA, eGOBI_IMG_CAR_ATT = 201, eGOBI_IMG_CAR_VODAFONE, eGOBI_IMG_CAR_TMOBILE, eGOBI_IMG_CAR_ORANGE, eGOBI_IMG_CAR_TELEFONICA, eGOBI_IMG_CAR_TELCOM_ITALIA, eGOBI_IMG_CAR_3, eGOBI_IMG_CAR_O2, eGOBI_IMG_CAR_SFR, eGOBI_IMG_CAR_SWISSCOM, eGOBI_IMG_CAR_CHINA_MOBILE, eGOBI_IMG_CAR_TELSTRA2, eGOBI_IMG_CAR_SINGTEL_OPTUS, eGOBI_IMG_CAR_RELIANCE2, eGOBI_IMG_CAR_BHARTI, eGOBI_IMG_CAR_NTT_DOCOMO, eGOBI_IMG_CAR_EMOBILE, eGOBI_IMG_CAR_SOFTBANK, eGOBI_IMG_CAR_KT_FREETEL, eGOBI_IMG_CAR_SK_TELCOM2, eGOBI_IMG_CAR_TELENOR, eGOBI_IMG_CAR_NETCOM, eGOBI_IMG_CAR_TELIASONERA, eGOBI_IMG_CAR_AMX_TELCEL, eGOBI_IMG_CAR_BRASIL_VIVO, eGOBI_IMG_CAR_AERIS, eGOBI_IMG_CAR_ROGERS }
enum | eGobiImageRegion { eGOBI_IMG_REG_NA = 0, eGOBI_IMG_REG_LA, eGOBI_IMG_REG_EU, eGOBI_IMG_REG_ASIA, eGOBI_IMG_REG_AUS, eGOBI_IMG_REG_GLOBAL }
enum | eGobiImageGPS { eGOBI_IMG_GPS_NONE = 0, eGOBI_IMG_GPS_STAND_ALONE, eGOBI_IMG_GPS_ASSISTED, eGOBI_IMG_GPS_NO_XTRA }

## Functions
ULONG | GetImageStore (WORD imageStorePathSize, CHAR *pImageStorePath)
ULONG | SLQSGetFirmwareInfo (struct qmifwinfo_s *pinfo)
ULONG | SLQSGetImageInfoMC77xx (LPCSTR path, struct qmifwinfo_s *pinfo)
ULONG | SLQSGetImageInfoMC83xx (LPCSTR path, struct qmifwinfo_s *pinfo)
ULONG | SLQSGetImageInfo (LPCSTR path, struct qmifwinfo_s *pinfo)
ULONG | UpgradeFirmware2k (CHAR *pDestinationPath)
ULONG | GetImagesPreference (ULONG *pImageListSize, struct PrefImageList *pImageList)
ULONG | SetImagesPreference (ULONG imageListSize, BYTE *pImageList, ULONG bForceDownload, BYTE modemIndex, ULONG *pImageTypesSize, BYTE *pImageTypes)
ULONG | GetStoredImages (ULONG *pImageListSize, BYTE *pImageList)
ULONG | DeleteStoredImage (ULONG imageInfoSize, BYTE *pImageInfo)
BOOL | IsGobiDevice (void)
BOOL | IsSierraGobiDevice (void)
ULONG | SLQSGetImageInfo_9x15 (LPCSTR path, BYTE imgType, struct slqsfwinfo_s *pinfo)
ULONG | SLQSUpgradeFirmware9x15 (CHAR *pDestinationPath)
ULONG | SLQSGetBootVersionNumber (ULONG *bootversion)
BOOL | SLQSIsSpkgFormatRequired (void)
ULONG | upgrade_mc77xx_fw (LPCSTR path)

## Detailed Description

Firmware Management Service API function prototypes.

Copyright: © 2011 Sierra Wireless, Inc. all rights reserved

## Macro Definition Documentation

#define DEVICE_RESET 4

#define DEVICE_SHUTDOWN 5

#define FIRMWARE_UPDATE_FAIL 0x01

#define FIRMWARE_UPDATE_SUCCESS 0x01

#define FIRMWARE_UPGRADE_SUCCESS 0x00

#define GOBI_LISTENTRIES_MAX 2

#define GOBI_MBN_BUILD_ID_STR_LEN 100

#define GOBI_MBN_IMG_ID_STR_LEN 16

#define GOBI_SET_IMG_PREF_RSPLEN 40

#define PRI_UPDATE_FAIL 0x02

#define SLQSFWINFO_APPVERSION_SZ 85

#define SLQSFWINFO_BOOTVERSION_SZ 85

#define SLQSFWINFO_CARRIER_SZ 20

#define SLQSFWINFO_MODELID_SZ 20

#define SLQSFWINFO_PACKAGEID_SZ 85

#define SLQSFWINFO_PRIVERSION_SZ 10

#define SLQSFWINFO_SKU_SZ 15

## Enumeration Type Documentation

enum eGobiImageCarrier

enumeration which lists the carrier supported by the image

Enumerator
eGOBI_IMG_CAR_GENERIC |
eGOBI_IMG_CAR_FACTORY |
eGOBI_IMG_CAR_NORF |
eGOBI_IMG_CAR_VERIZON |
eGOBI_IMG_CAR_SPRINT |
eGOBI_IMG_CAR_ALLTEL |
eGOBI_IMG_CAR_BELL |
eGOBI_IMG_CAR_TELUS |
eGOBI_IMG_CAR_US |
eGOBI_IMG_CAR_TELSTRA1 |
eGOBI_IMG_CAR_CHINA_UNICOM |
eGOBI_IMG_CAR_TELCOM_NZ |
eGOBI_IMG_CAR_SK_TELCOM1 |
eGOBI_IMG_CAR_RELIANCE1 |
eGOBI_IMG_CAR_TATA |
eGOBI_IMG_CAR_METROPCS |
eGOBI_IMG_CAR_LEAP |
eGOBI_IMG_CAR_KDDI |
eGOBI_IMG_CAR_IUSACELL |
eGOBI_IMG_CAR_CHINA_TELECOM |
eGOBI_IMG_CAR_OMH |
eGOBI_IMG_CAR_GENERIC_CDMA |
eGOBI_IMG_CAR_ATT |
eGOBI_IMG_CAR_VODAFONE |
eGOBI_IMG_CAR_TMOBILE |
eGOBI_IMG_CAR_ORANGE |
eGOBI_IMG_CAR_TELEFONICA |
eGOBI_IMG_CAR_TELCOM_ITALIA |
eGOBI_IMG_CAR_3 |
eGOBI_IMG_CAR_O2 |
eGOBI_IMG_CAR_SFR |
eGOBI_IMG_CAR_SWISSCOM |
eGOBI_IMG_CAR_CHINA_MOBILE |
eGOBI_IMG_CAR_TELSTRA2 |
eGOBI_IMG_CAR_SINGTEL_OPTUS |
eGOBI_IMG_CAR_RELIANCE2 |
eGOBI_IMG_CAR_BHARTI |
eGOBI_IMG_CAR_NTT_DOCOMO |
eGOBI_IMG_CAR_EMOBILE |
eGOBI_IMG_CAR_SOFTBANK |
eGOBI_IMG_CAR_KT_FREETEL |
eGOBI_IMG_CAR_SK_TELCOM2 |
eGOBI_IMG_CAR_TELENOR |
eGOBI_IMG_CAR_NETCOM |
eGOBI_IMG_CAR_TELIASONERA |
eGOBI_IMG_CAR_AMX_TELCEL |
eGOBI_IMG_CAR_BRASIL_VIVO |
eGOBI_IMG_CAR_AERIS |
eGOBI_IMG_CAR_ROGERS |

enum eGobiImageGPS

enumeration which lists the GPS type supported by the image

Enumerator
eGOBI_IMG_GPS_NONE |
eGOBI_IMG_GPS_STAND_ALONE |
eGOBI_IMG_GPS_ASSISTED |
eGOBI_IMG_GPS_NO_XTRA |

enum eGobiImageRegion

enumeration which lists the region supported by the image

Enumerator
eGOBI_IMG_REG_NA |
eGOBI_IMG_REG_LA |
eGOBI_IMG_REG_EU |
eGOBI_IMG_REG_ASIA |
eGOBI_IMG_REG_AUS |
eGOBI_IMG_REG_GLOBAL |

enum eGobiImageTech

enumeration which lists the technology supported by the image

Enumerator
eGOBI_IMG_TECH_CDMA |
eGOBI_IMG_TECH_UMTS |

## Function Documentation

ULONG DeleteStoredImage | ( | ULONG | imageInfoSize,
|  | BYTE * | pImageInfo
| ) |  |

Used to delete the specified image from the device. This API function is only relevant to devices with the ability to store multiple firmware images(see Device Supported section below).

Parameters

  imageInfoSize[IN] | The size in BYTEs of the image info array
  pImageInfo[IN] | The image info list array containing information about the image to be deleted. See ImageElement

Returns
  eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise

See Also
  See qmerrno.h for eQCWWAN_xxx error values

Note
  Device Supported: MC83x5/SL9090
  Timeout: 2 Secs

ULONG GetImagesPreference | ( | ULONG * | pImageListSize,
|  | struct PrefImageList * | pImageList
| ) |  |

restore original alignment from stack Gets the current images preference from the device.

Parameters

  pImageListSize[IN/OUT] | Upon input, the size of struct ImageList ImageList Upon successful output, the number of BYTEs copied to the image list array
  pImageList[OUT] | The caller must supply a pointer to a ImageList structure typecast as a BYTE pointer

Returns
  eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise

See Also
  See qmerrno.h for eQCWWAN_xxx error values

Note
  Timeout: 2 seconds

ULONG GetImageStore | ( | WORD | imageStorePathSize,
|  | CHAR * | pImageStorePath
| ) |  |

Returns the image store folder, i.e., the folder containing one or more carrier-specific image subfolders compatible with the currently connected QC WWAN device.

Parameters

  imageStorePathSize | Maximum number of characters (including NULL terminator) that can be copied to the image store path array.
  pImageStorePath[OUT] | The path to the image store

Returns
  eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise

See Also
  See qmerrno.h for eQCWWAN_xxx error values

ULONG GetStoredImages | ( | ULONG * | pImageListSize,
|  | BYTE * | pImageList
| ) |  |

restore original alignment from stack Gets the list of images stored on the device.

Parameters

  pImageListSize[IN/OUT] | Upon input, the size of struct ImageList ImageList Upon successful output, the number of BYTEs copied to the image list array
  pImageList[OUT] | The caller must supply a pointer to a ImageList structure typecast as a BYTE pointer

Returns
  eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise

See Also
  See qmerrno.h for eQCWWAN_xxx error values

Note
  Device Supported: MC83x5/SL9090
  Timeout: 2 seconds

BOOL IsGobiDevice | ( | void |  | ) |

BOOL IsSierraGobiDevice | ( | void |  | ) |

Name : IsSierraGobiDevice Purpose : To Check device description

ULONG SetImagesPreference | ( | ULONG | imageListSize,
|  | BYTE * | pImageList,
|  | ULONG | bForceDownload,
|  | BYTE | modemIndex,
|  | ULONG * | pImageTypesSize,
|  | BYTE * | pImageTypes
| ) |  |

Sets the current images preference on the device. After this function successfully completes, the device must be reset for the selected image preference to be realized. Additionally, when the returned list of image types that require downloading is not empty, the device opens in QDL mode after the reset. At that point, the QDL portion of this API must be used to download the selected image preference to the device.

Parameters

  imageListSize | The size in BYTEs of the image list array
  pImageList[IN] | The image info list array containing Image Elements See PrefImageList
  bForceDownload[IN] | Force device to download images from host? 0 - No Nonzero - Yes
  modemIndex | Desired storage index for downloaded modem image (optional, a value of 0xFF indicates unspecified)
  pImageTypesSize[IN/OUT] | Upon input, maximum number of elements that download image types array can contain Upon successful output, number of elements in download image types array
  pImageTypes[OUT] | -The download image types array.

Returns
  eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise

See Also
  See qmerrno.h for eQCWWAN_xxx error values

Note
  Timeout: 2 seconds

ULONG SLQSGetBootVersionNumber | ( | ULONG * | bootversion | ) |

Gets the boot loader version number

Parameters

  bootversion[OUT] | boot loader version presentedd by a 4 byte integer

Returns
  eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise

See Also
  See qmerrno.h for eQCWWAN_xxx error values

Note
  Device Supported: MC9090/SL9090
  Timeout: 2 seconds

ULONG SLQSGetFirmwareInfo | ( | struct qmifwinfo_s * | pinfo | ) |

Returns firmware image information from the connected device

Parameters

  pinfo[OUT] | firmware image information record

Returns
  eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise

See Also
  See qmerrno.h for eQCWWAN_xxx error values
  struct qmifwinfo_s

Note
  Timeout: 2 Seconds.

ULONG SLQSGetImageInfo | ( | LPCSTR | path,
|  | struct qmifwinfo_s * | pinfo
| ) |  |

Returns firmware image information from a CWE file or mbn files stored on the host. For CWE, information is returned for the first CWE image found at the specified path.For MBN, the provided path must be located under the image store for the currently connected QC WWAN device. Note that as this API supports multiple firmware image types, it relies on the presence of a supported device. Otherwise, refer to SLQSGetImageInfoMC83xx and SLQSGetImageInfoMC77xx for APIs which do not rely on the presence of a supported device.

Parameters

  path[IN] | fully qualified path to folder containing CWE image or MBN images should use a "/" at the end of the path.
  pinfo[OUT] | firmware image information record

Returns
  eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise

See Also
  See qmerrno.h for eQCWWAN_xxx error values
  struct qmifwinfo_s

Note
  Timeout: N/A

ULONG SLQSGetImageInfo_9x15 | ( | LPCSTR | path,
|  | BYTE | imgType,
|  | struct slqsfwinfo_s * | pinfo
| ) |  |

Returns firmware image information from a CWE file(s) stored on the host. It does not rely on the presence of a supported device.

Parameters

  path[IN] | fully qualified path to folder containing the image(s) should use a "/" at the end of the path.
  imgType[IN] | 2 - Firmware Image( .cwe extension ) 3 - PRI Image ( .nvu extension )
  pinfo[OUT] | firmware image information record

Returns
  eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise

See Also
  See qmerrno.h for eQCWWAN_xxx error values
  struct qmifwinfo_s

Note
  Device Supported: MC73xx
  Timeout: N/A

ULONG SLQSGetImageInfoMC77xx | ( | LPCSTR | path,
|  | struct qmifwinfo_s * | pinfo
| ) |  |

Returns firmware image information from a SPKGS CWE file stored on the host. The information is returned for the first SPKGS CWE image found at the specified path. This API executes independent of a MC77xx being connected to the target.

Parameters

  path[IN] | fully qualified path to folder containing SPKG CWE image should use a "/" at the end of the path.
  pinfo[OUT] | firmware image information record

Returns
  eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise

See Also
  See qmerrno.h for eQCWWAN_xxx error values
  struct qmifwinfo_s

Note
  Device Supported: MC77xx
  Timeout: N/A

ULONG SLQSGetImageInfoMC83xx | ( | LPCSTR | path,
|  | struct qmifwinfo_s * | pinfo
| ) |  |

Returns firmware image information from an MBN file located on the host. This API executes independent of a MC83xx being connected to the target.

Parameters

  path[IN] | fully qualified path to folder containing MBN file should use a "/" at the end of the path.
  pinfo[OUT] | firmware image information record

Returns
  eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise

See Also
  See qmerrno.h for eQCWWAN_xxx error values
  struct qmifwinfo_s

Note
  Device Supported: MC83xx/SL9090
  Timeout: N/A

BOOL SLQSIsSpkgFormatRequired | ( | void |  | ) |

Check if SPKG format download is required for SL9090/MC9090

Parameters

  none |

Returns
  return TRUE if required, otherwise, return FALSE

Note
  Device Supported: MC9090/SL9090
  Timeout: 2 seconds

ULONG SLQSUpgradeFirmware9x15 | ( | CHAR * | pDestinationPath | ) |

This API is used to upgrade firmware on a MC73xx device. This API encapsulates all steps involved in the firmware download process. It is an alternative to any firmware download application. Hence it is a blocking API call. This API will not return until the entire process has been completed.

This API Performs the following steps:

1. Verifies arguments.
2. Retrieve and store the details of the firmware and the PRI file
3. Enable device state change callback.
4. Enable firmware download callback.
5. Set Image preference on the device and reset the device.
6. Wait for the firmware to download and device to become ready.
7. Check the firmware update status. If fail, return an error.
8. If update status is OK, check if current image preference and preferred image preference( from step 2 ) match
9. If match, firmware download is successful.
10. If do not match, repeat from step 5 once more.
11. Disable callbacks and exit.
    The call to this API blocks until step 7 or 11. This could be a significant amount of time ( in order of minutes ). Also note that the device state change callback and firmware download callback are used internally
    within this API. Hence the user application's instance of these callbacks (if any) are cleared. The user must re-enable these callbacks after a call to this API in order to use them.
    Parameters

      pDestinationPath[IN] | fully qualified path to firmware image to download. The path must end with a forward slash.

    Returns
      - eQCWWAN_ERR_INVALID_ARG - The path input does not contain any image
      - eQCWWAN_ERR_SWIIM_FW_UPDATE_FAIL - Upgrade( i.e. download to device ) failed
      - eQCWWAN_ERR_SWIIM_FW_UPDATE_SUCCESS - Upgrade succeeded and device online.
      - eQCWWAN_ERR_SWIIM_FW_PREFERENCE_MISMATCH - Upgrade succeeded but device offline due to image preference mismatch ( ref. syslogs for cause )
    See Also
      See qmerrno.h for eQCWWAN_xxx error values
    Note
      Timeout: NA

ULONG upgrade_mc77xx_fw | ( | LPCSTR | path | ) |

ULONG UpgradeFirmware2k | ( | CHAR * | pDestinationPath | ) |

This API is used to download firmware to a MC77xx or Gobi 3000 device.

This API Performs the following steps:

1. Verifies arguments.
2. Informs the SDK of the firmware upgrade path
3. Updates the images preference on the currently connected device.
4. Requests the device reset (device will reset after all open handles are released).
   Upon successful completion, the above steps will have been completed, however, the actual upgrade of the firmware will necessarily then follow.

Parameters

  pDestinationPath[IN] | fully qualified path to firmware image to download. The path must end with a forward slash. For a Gobi 3000 device the path should specify the carrier image folder index i.e. "<path\to\carrier\image>/<carrier index>/" where <carrier index>=""> is a valid sub-directory entry

Returns
  eQCWWAN_ERR_NONE on success, eQCWWAN_xxx error value otherwise

See Also
  See qmerrno.h for eQCWWAN_xxx error values

Note
  Timeout: 12 seconds