Code drop from //branches/cupcake/...@124589

1 files changed, 84 insertions, 41 deletions

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 @@ typedef uint16_t GpsAidingData;
 #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 @@ typedef struct {
 } 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 @@ typedef struct {
     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();