Code drop from //branches/cupcake/...@124589
diff --git a/include/hardware/gps.h b/include/hardware/gps.h
index 54b50a5..5f8740f 100644
--- a/include/hardware/gps.h
+++ b/include/hardware/gps.h
@@ -23,36 +23,58 @@
extern "C" {
#endif
-/** milliseconds since January 1, 1970 */
+/** Milliseconds since January 1, 1970 */
typedef int64_t GpsUtcTime;
-/** maximum number of Space Vehicles for gps_sv_status_callback */
+/** Maximum number of SVs for gps_sv_status_callback(). */
#define GPS_MAX_SVS 32
-
+/** Requested mode for GPS operation. */
typedef uint16_t GpsPositionMode;
+// IMPORTANT: Note that the following values must match
+// constants in GpsLocationProvider.java.
+/** Mode for running GPS standalone (no assistance). */
#define GPS_POSITION_MODE_STANDALONE 0
+/** SUPL MS-Based mode. */
#define GPS_POSITION_MODE_MS_BASED 1
+/** SUPL MS-Assisted mode. */
#define GPS_POSITION_MODE_MS_ASSISTED 2
+/** GPS status event values. */
typedef uint16_t GpsStatusValue;
-// IMPORTANT - these symbols here must match constants in GpsLocationProvider.java
+// IMPORTANT: Note that the following values must match
+// constants in GpsLocationProvider.java.
+/** GPS status unknown. */
#define GPS_STATUS_NONE 0
+/** GPS has begun navigating. */
#define GPS_STATUS_SESSION_BEGIN 1
+/** GPS has stopped navigating. */
#define GPS_STATUS_SESSION_END 2
+/** GPS has powered on but is not navigating. */
#define GPS_STATUS_ENGINE_ON 3
+/** GPS is powered off. */
#define GPS_STATUS_ENGINE_OFF 4
+/** Flags to indicate which values are valid in a GpsLocation. */
typedef uint16_t GpsLocationFlags;
-// IMPORTANT - these symbols here must match constants in GpsLocationProvider.java
+// IMPORTANT: Note that the following values must match
+// constants in GpsLocationProvider.java.
+/** GpsLocation has valid latitude and longitude. */
#define GPS_LOCATION_HAS_LAT_LONG 0x0001
+/** GpsLocation has valid altitude. */
#define GPS_LOCATION_HAS_ALTITUDE 0x0002
+/** GpsLocation has valid speed. */
#define GPS_LOCATION_HAS_SPEED 0x0004
+/** GpsLocation has valid bearing. */
#define GPS_LOCATION_HAS_BEARING 0x0008
+/** GpsLocation has valid accuracy. */
#define GPS_LOCATION_HAS_ACCURACY 0x0010
+/** Flags used to specify which aiding data to delete
+ when calling delete_aiding_data(). */
typedef uint16_t GpsAidingData;
-// IMPORTANT - these symbols here must match constants in GpsLocationProvider.java
+// IMPORTANT: Note that the following values must match
+// constants in GpsLocationProvider.java.
#define GPS_DELETE_EPHEMERIS 0x0001
#define GPS_DELETE_ALMANAC 0x0002
#define GPS_DELETE_POSITION 0x0004
@@ -68,73 +90,88 @@
#define GPS_DELETE_ALL 0xFFFF
/**
- * names for GPS XTRA interface
+ * Name for the GPS XTRA interface.
*/
#define GPS_XTRA_INTERFACE "gps-xtra"
/**
- * names for GPS supplemental interface
- * TODO: Remove not used.
+ * Name for the GPS SUPL interface.
*/
#define GPS_SUPL_INTERFACE "gps-supl"
-/** The location */
+/** Represents a location. */
typedef struct {
- /** contains GpsLocationFlags bits */
+ /** Contains GpsLocationFlags bits. */
uint16_t flags;
+ /** Represents latitude in degrees. */
double latitude;
+ /** Represents longitude in degrees. */
double longitude;
+ /** Represents altitude in meters above the WGS 84 reference
+ * ellipsoid. */
double altitude;
+ /** Represents speed in meters per second. */
float speed;
+ /** Represents heading in degrees. */
float bearing;
+ /** Represents expected accuracy in meters. */
float accuracy;
+ /** Timestamp for the location fix. */
GpsUtcTime timestamp;
} GpsLocation;
-/** The status */
+/** Represents the status. */
typedef struct {
GpsStatusValue status;
} GpsStatus;
-/** Space Vehicle info */
+/** Represents SV information. */
typedef struct {
+ /** Pseudo-random number for the SV. */
int prn;
+ /** Signal to noise ratio. */
float snr;
+ /** Elevation of SV in degrees. */
float elevation;
+ /** Azimuth of SV in degrees. */
float azimuth;
} GpsSvInfo;
-/** Space Vehicle status */
+/** Represents SV status. */
typedef struct {
- /** number of SVs currently visible */
+ /** Number of SVs currently visible. */
int num_svs;
- /** Array of space vehicle info */
+ /** Contains an array of SV information. */
GpsSvInfo sv_list[GPS_MAX_SVS];
- /** bit mask indicating which SVs have ephemeris data */
+ /** Represents a bit mask indicating which SVs
+ * have ephemeris data.
+ */
uint32_t ephemeris_mask;
- /** bit mask indicating which SVs have almanac data */
+ /** Represents a bit mask indicating which SVs
+ * have almanac data.
+ */
uint32_t almanac_mask;
/**
- * bit mask indicating which SVs were used for
- * computing the most recent position fix
+ * Represents a bit mask indicating which SVs
+ * were used for computing the most recent position fix.
*/
uint32_t used_in_fix_mask;
} GpsSvStatus;
-/** Callback with location information */
+/** Callback with location information. */
typedef void (* gps_location_callback)(GpsLocation* location);
-/** Callback with the status information */
+/** Callback with status information. */
typedef void (* gps_status_callback)(GpsStatus* status);
-/** Callback with the space vehicle status information */
+/** Callback with SV status information. */
typedef void (* gps_sv_status_callback)(GpsSvStatus* sv_info);
-/** GPS call back structure */
+/** GPS callback structure. */
typedef struct {
gps_location_callback location_cb;
gps_status_callback status_cb;
@@ -142,40 +179,40 @@
} GpsCallbacks;
-/** Standard GPS interface */
+/** Represents the standard GPS interface. */
typedef struct {
/**
- * Open the interface and provide the callback routines
+ * Opens the interface and provides the callback routines
* to the implemenation of this interface.
*/
int (*init)( GpsCallbacks* callbacks );
- /** Start navigating */
+ /** Starts navigating. */
int (*start)( void );
- /** Stop navigating */
+ /** Stops navigating. */
int (*stop)( void );
- /** Set requested frequency of fixes in seconds */
+ /** Sets requested frequency of fixes in seconds. */
void (*set_fix_frequency)( int frequency );
- /** Close the interface */
+ /** Closes the interface. */
void (*cleanup)( void );
- /** Inject the current time */
+ /** Injects the current time. */
int (*inject_time)(GpsUtcTime time, int64_t timeReference,
int uncertainty);
/**
- * The next call to start will not use the information
- * defined in the flags. GPS_DELETE_ALL is passed for
+ * Specifies that the next call to start will not use the
+ * information defined in the flags. GPS_DELETE_ALL is passed for
* a cold start.
*/
void (*delete_aiding_data)(GpsAidingData flags);
/**
- * fix_frequency is time between fixes in seconds.
- * set fix_frequency to zero for a single shot fix.
+ * fix_frequency represents the time between fixes in seconds.
+ * Set fix_frequency to zero for a single-shot fix.
*/
int (*set_position_mode)(GpsPositionMode mode, int fix_frequency);
@@ -183,31 +220,37 @@
const void* (*get_extension)(const char* name);
} GpsInterface;
-/** The download request callback routine. */
+/** Callback to request the client to download XTRA data.
+ The client should download XTRA data and inject it by calling
+ inject_xtra_data(). */
typedef void (* gps_xtra_download_request)();
-/** The download request callback structure. */
+/** Callback structure for the XTRA interface. */
typedef struct {
gps_xtra_download_request download_request_cb;
} GpsXtraCallbacks;
/** Extended interface for XTRA support. */
typedef struct {
+ /**
+ * Opens the XTRA interface and provides the callback routines
+ * to the implemenation of this interface.
+ */
int (*init)( GpsXtraCallbacks* callbacks );
+ /** Injects XTRA data into the GPS. */
int (*inject_xtra_data)( char* data, int length );
} GpsXtraInterface;
-/** returns the hardware GPS interface. */
+/** Returns the hardware GPS interface. */
const GpsInterface* gps_get_hardware_interface();
/**
- * returns the qemu hardware interface GPS interface.
+ * Returns the qemu emulated GPS interface.
*/
const GpsInterface* gps_get_qemu_interface();
/**
- * returns the default GPS interface,
- * implemented in lib/hardware/gps.cpp.
+ * Returns the default GPS interface.
*/
const GpsInterface* gps_get_interface();