| /*=========================================================================== |
| FILE: |
| GobiImageMgmtAPI.h |
| |
| DESCRIPTION: |
| QUALCOMM Image Management API for Gobi 3000 |
| |
| Copyright (c) 2011, Code Aurora Forum. All rights reserved. |
| |
| Redistribution and use in source and binary forms, with or without |
| modification, are permitted provided that the following conditions are met: |
| * Redistributions of source code must retain the above copyright |
| notice, this list of conditions and the following disclaimer. |
| * Redistributions in binary form must reproduce the above copyright |
| notice, this list of conditions and the following disclaimer in the |
| documentation and/or other materials provided with the distribution. |
| * Neither the name of Code Aurora Forum nor |
| the names of its contributors may be used to endorse or promote |
| products derived from this software without specific prior written |
| permission. |
| |
| |
| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" |
| AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE |
| LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR |
| CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF |
| SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
| INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
| CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) |
| ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE |
| POSSIBILITY OF SUCH DAMAGE. |
| ==========================================================================*/ |
| |
| #include "types.h" |
| |
| /*=========================================================================*/ |
| // Pragmas |
| /*=========================================================================*/ |
| #pragma once |
| |
| /*=========================================================================*/ |
| // Definitions |
| /*=========================================================================*/ |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /*=========================================================================*/ |
| // Prototypes |
| /*=========================================================================*/ |
| |
| /*=========================================================================== |
| METHOD: |
| GobiEnumerateDevices |
| |
| DESCRIPTION: |
| This function enumerates the Gobi devices currently attached to the |
| system |
| |
| PARAMETERS: |
| pDevicesSize [I/O] - Upon input the maximum number of elements that the |
| device array can contain. Upon successful output |
| the actual number of elements in the device array |
| pDevices [ O ] - The device array |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG GobiEnumerateDevices( |
| BYTE * pDevicesSize, |
| BYTE * pDevices ); |
| |
| /*=========================================================================== |
| METHOD: |
| SetDeviceID |
| |
| DESCRIPTION: |
| This function sets the ID of the device to target |
| |
| PARAMETERS: |
| pDeviceID [ I ] - The device ID as reported by Windows |
| pDeviceKey [ I ] - The device key (unique, stored on-device) |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG SetDeviceID( |
| CHAR * pDeviceID, |
| CHAR * pDeviceKey ); |
| |
| /*=========================================================================== |
| METHOD: |
| GetImagesPreference |
| |
| DESCRIPTION: |
| This function gets the current images preference |
| |
| PARAMETERS: |
| pImageListSize [I/O] - Upon input the size in BYTEs of the image list |
| array. Upon success the actual number of BYTEs |
| copied to the image list array |
| pImageList [ O ] - The image info list array |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG GetImagesPreference( |
| ULONG * pImageListSize, |
| BYTE * pImageList ); |
| |
| /*=========================================================================== |
| METHOD: |
| SetImagesPreference |
| |
| DESCRIPTION: |
| This function sets the current images preference |
| |
| PARAMETERS: |
| imageListSize [ I ] - The size in BYTEs of the image list array |
| pImageList [ I ] - The image list array |
| bForceDownload [ I ] - Force device to download images from host? |
| modemIndex [ I ] - Desired storage index for downloaded modem image |
| pImageTypesSize [I/O] - Upon input the maximum number of elements that |
| the download image types array can contain. |
| Upon successful output the actual number of |
| elements in the download image types array |
| pImageTypes [ O ] - The download image types array |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG SetImagesPreference( |
| ULONG imageListSize, |
| BYTE * pImageList, |
| ULONG bForceDownload, |
| BYTE modemIndex, |
| ULONG * pImageTypesSize, |
| BYTE * pImageTypes ); |
| |
| /*=========================================================================== |
| METHOD: |
| GetBARMode |
| |
| DESCRIPTION: |
| This function returns the boot and recovery image download mode |
| |
| PARAMETERS: |
| pBARMode [ O ] - Boot and recovery image download mode |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG GetBARMode( ULONG * pBARMode ); |
| |
| /*=========================================================================== |
| METHOD: |
| SetBARMode |
| |
| DESCRIPTION: |
| This function requests the device enter boot and recovery image download |
| mode after the next reset |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG SetBARMode(); |
| |
| /*=========================================================================== |
| METHOD: |
| GetStoredImages |
| |
| DESCRIPTION: |
| This function gets the list of images stored on the device |
| |
| PARAMETERS: |
| pImageListSize [I/O] - Upon input the size in BYTEs of the image list |
| array. Upon success the actual number of BYTEs |
| copied to the image list array |
| pImageList [ O ] - The image info list array |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG GetStoredImages( |
| ULONG * pImageListSize, |
| BYTE * pImageList ); |
| |
| /*=========================================================================== |
| METHOD: |
| GetStoredImageInfo |
| |
| DESCRIPTION: |
| This function returns info about the specified image from the device |
| |
| PARAMETERS: |
| imageInfoSize [ I ] - The size in BYTEs of the image info array |
| pImageInfo [ I ] - The image info array |
| pMajorVersion [ O ] - Major version of compatible boot downloader |
| pMinorVersion [ O ] - Minor version of compatible boot downloader |
| pVersionID [ O ] - Image version ID |
| pInfo [ O ] - Image info string |
| pLockID [ O ] - Image OEM lock ID |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG GetStoredImageInfo( |
| ULONG imageInfoSize, |
| BYTE * pImageInfo, |
| ULONG * pMajorVersion, |
| ULONG * pMinorVersion, |
| ULONG * pVersionID, |
| CHAR * pInfo, |
| ULONG * pLockID ); |
| |
| /*=========================================================================== |
| METHOD: |
| DeleteStoredImage |
| |
| DESCRIPTION: |
| This function deletes the specified image from the device |
| |
| PARAMETERS: |
| imageInfoSize [ I ] - The size in BYTEs of the image info array |
| pImageInfo [ I ] - The image info array |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG DeleteStoredImage( |
| ULONG imageInfoSize, |
| BYTE * pImageInfo ); |
| |
| /*=========================================================================== |
| METHOD: |
| ResetDevice |
| |
| DESCRIPTION: |
| This function resets the device |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG ResetDevice(); |
| |
| /*=========================================================================== |
| METHOD: |
| GobiEnumerateQDLPorts |
| |
| DESCRIPTION: |
| This function enumerates the Gobi QDL port IDs currently attached to the |
| system |
| |
| PARAMETERS: |
| pPortSize [I/O] - Upon input the maximum number of elements that the |
| port ID array can contain. Upon successful output |
| the actual number of elements in the port ID array |
| pPorts [ O ] - Port ID array |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG GobiEnumerateQDLPorts( |
| BYTE * pPortSize, |
| BYTE * pPorts ); |
| |
| /*=========================================================================== |
| METHOD: |
| SetQDLTimeout |
| |
| DESCRIPTION: |
| This function sets the timeout for all subsequent QDL transactions |
| |
| PARAMETERS: |
| to [ O ] - Timeout (in milliseconds) for subsequent transactions |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG SetQDLTimeout( ULONG to ); |
| |
| /*=========================================================================== |
| METHOD: |
| OpenQDLPort |
| |
| DESCRIPTION: |
| This function opens the specified QDL port of the device |
| |
| PARAMETERS: |
| pPortID [ I ] - ID of QDL port to connect to |
| bBARMode [ I ] - Request boot and recovery mode feature |
| pMajorVersion [ O ] - Major version of the device boot downloader |
| pMinorVersion [ O ] - Minor version of the device boot downloader |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG OpenQDLPort( |
| CHAR * pPortID, |
| ULONG bBARMode, |
| ULONG * pMajorVersion, |
| ULONG * pMinorVersion ); |
| |
| /*=========================================================================== |
| METHOD: |
| CloseQDLPort |
| |
| DESCRIPTION: |
| This function closes the currently open QDL port of the device |
| |
| PARAMETERS: |
| bInformDevice [ I ] - Inform device that QDL port is being closed? |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG CloseQDLPort( ULONG bInformDevice ); |
| |
| /*=========================================================================== |
| METHOD: |
| GetQDLImagesPreference |
| |
| DESCRIPTION: |
| This function gets the current images preference as reported by the |
| device boot downloader |
| |
| PARAMETERS: |
| pImageListSize [I/O] - Upon input the maximum number of elements that the |
| image info list can contain. Upon successful output |
| the actual number of elements in the image info list |
| pImageList [ O ] - The image info list |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG GetQDLImagesPreference( |
| ULONG * pImageListSize, |
| BYTE * pImageList ); |
| |
| /*=========================================================================== |
| METHOD: |
| PrepareQDLImageWrite |
| |
| DESCRIPTION: |
| This function prepares the device boot downloader for an image write |
| |
| PARAMETERS: |
| imageType [ I ] - Type of image being written |
| imageSize [ I ] - Size of image being written |
| pBlockSize [I/O] - Upon input the maximum size of image block supported |
| by host, upon successful output the maximum size of |
| image block supported by device |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG PrepareQDLImageWrite( |
| BYTE imageType, |
| ULONG imageSize, |
| ULONG * pBlockSize ); |
| |
| /*=========================================================================== |
| METHOD: |
| WriteQDLImageBlock |
| |
| DESCRIPTION: |
| This function writes the specified image block to the device |
| |
| PARAMETERS: |
| sequenceNumber [ I ] - Sequence number for image write |
| blockSize [ I ] - Size of image block |
| pImageBlock [ I ] - Image block |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG WriteQDLImageBlock( |
| USHORT sequenceNumber, |
| ULONG blockSize, |
| BYTE * pImageBlock ); |
| |
| /*=========================================================================== |
| METHOD: |
| ValidateQDLImages |
| |
| DESCRIPTION: |
| This function requests the device validate the written images |
| |
| PARAMETERS: |
| pImageType [ O ] - Upon failure this may contain the type of the image |
| that failed validation |
| |
| RETURN VALUE: |
| ULONG - Return code |
| ===========================================================================*/ |
| ULONG ValidateQDLImages( BYTE * pImageType ); |
| |
| #ifdef __cplusplus |
| }; |
| #endif |