1. Introduction

This Broadcom GNSS Geolocation Sensor for Windows 8 running on x86 or ARM CPU 
is for evaluation purposes only. It is NOT a production release.

2. Overview

The high level block diagram can be found at Docs\Windows_Location_Sensor.pdf.
In this release, only autonomous GNSS positioning is supported, and all the 
optional features are not supported yet.

The source code may be included upon request for the users to get familiar with 
the operations and provide recommendations to Broadcom.

2.1 Supported Features
2.1.1 All Broadcom GNSS ASICs since BCM4750
2.1.1.1 BCM4750, BCM4751, BCM47511, BCM2076
2.1.2 Broadcom ASIC connected to ACPI/UART
    BcmGnss.dll <=> BcmGnssBus.sys <=> ACPI/UART <=> BCM475x
2.1.3 Radio Manager
2.1.4 LTO and automatic download
2.1.5 Crash recovery
2.1.6 Power Management
2.1.7 SUPL SI - only on platforms with cellular modem and proper implementation
    of AT commands:
    - AT+COPS
    - AT+CREG
    - AT+CIMI
    - AT+CNUM
    - For LTE SI, we will use the non-standard message "AT%IECELLID=1"
    
2.2 Unsupported Features
2.2.1 CBEE
2.2.2 Third-party sensors (HULA)
2.2.3 SUPL NI
2.2.4 Control Plane
2.2.5 I2C host interface

2.3 Primary Software Components

2.3.1 BcmGnssLocationSensor.dll - Location sensor driver, with source code
    allPartners\deliverables\middleware_connectors\Windows\BcmGnssLocationSensor

2.3.2 BcmGnss.dll - GNSS software engine, with source code
    allPartners\deliverables\glgpsapp\WinGPS

2.3.3 BcmGnssBus.sys - ACPI/UART&GPIO Driver wrapper exposes ACPI/UART driver 
    as COM22 for BcmGnss.dll

2.3.4 BcmGnssGpioAcpi.dll - GPIO plug-in, with source code
    allPartners\deliverables\glhal\win_xp\gpio\ACPI
    
3. Installation and Uninstallation

3.1 Disable Driver Signature Enforcement (this step may be optional on some
    Windows 8 versions)
3.1.1 Run cmd as administrator. 
3.1.1.1 Windows Key + r
3.1.1.2 cmd
3.1.1.3 Right-click cmd on taskbar, choose "Command Prompt\Run as administrator"
3.1.2 bcdedit /set testsigning 1
3.1.3 bcdedit /copy {current} /d "MyBoot"
3.1.4 Add registry value HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\CI
    UMCIAuditMode REG_DWORD 1
3.1.5 Reboot computer
3.1.6 Click "Change defaults or choose other options"
3.1.7 Click "Choose other options"
3.1.8 Click "Troubleshoot"
3.1.9 Click "Advanced options"
3.1.10 Click "Windows Startup Settings"
3.1.10.1 It may appear as "Change Windows Startup Settings" on some versions
3.1.11 Click "restart"
3.1.12 Choose "Disable Driver Signature Enforcement"

3.2 Boot machine with "Disable Driver Signature Enforcement" as needed. 
3.2.1 Copy the release package to the C:\ drive, say C:\Broadcom_Win8_Location 
so that your have C:\Broadcom_Win8_Location\Readme.txt. Locate the file 
%OS%\BcmGnss.dll
3.2.1.1 Ensure the previous version is cleanly uninstalled as described in 
section 3.3
3.2.2 Installing through Device Manager
3.2.2.1 Locate "Other devices\Unknown device" with Hardware ID=ACPI\BCMGNSS
    or Hardware ID=ACPI\BCM4751
3.2.2.2 Click "Update Driver"
3.2.2.3 Click "Browse my computer for driver software"
3.2.2.4 Click "Browse" and point the path to there %OS%\BcmGnss.dll resides
3.2.2.5 Click "Next" to complete the installation
3.2.2.6 Right-click "Other devices\Broadcom GNSS Location Provider_22" and 
choose "Update Driver Software"
3.2.2.7 Click "Browse my computer for driver software"
3.2.2.8 Click "Browse" and point the path to there %OS%\BcmGnss.dll resides
3.2.2.9 Click "Next" to complete the installation
3.2.2.10 Click "Restart Later" if a restart dialog box appears
3.2.2.11 WARNING: If the GNSS ASIC on the target platform is not BCM47511, 
    update the RfType as described in C:\Broadcom_Win8_Location\Docs\asci.txt

3.3 To uninstall, open Device Manager
3.3.1 Right-click on "Sensors\Broadcom GNSS Geolocation Sensor" and choose 
    "Disable", then click "Yes"
3.3.2 Right-click on "Sensors\Broadcom GNSS Geolocation Sensor" and choose 
    "Uninstall"
3.3.3 Check "Delete the driver software for this device" and click "OK"
3.3.4 Right-click on "System devices\Broadcom GNSS Bus Driver" and choose
    "Disable", then click "Yes"
3.3.5 Right-click on "System devices\Broadcom GNSS Bus Driver" and choose
    "Uninstall"
3.3.6 Check "Delete the driver software for this device" and click "OK"
3.3.7 Click "Restart Later" if a restart dialog box appears
3.3.8 Import uninstall.reg to remove all registry entries.
3.3.9 Delete C:\Windows\System32\Drivers\UMDF\BcmGnss*.*
3.3.10 Delete C:\Windows\System32\Drivers\BcmGnss*.*
3.3.11 Delete the entire directory C:\BcmGnssLog and 
    C:\ProgramData\Broadcom\Location

4. Theory of Operation

4.1 Normal Mode
When one or more location client is connected to the sensor, a start command is 
sent from BcmGnssLocationSensor.dll to the BcmGnss.dll. Once the position is 
computed, BcmGnss.dll sends the position data to BcmGnssLocationSensor.dll.
When client count drops to zero, BcmGnssLocationSensor.dll sends a stop command 
BcmGnss.dll to turn off the GNSS engine and puts the ASIC to standby.

4.1.1 Enable Location Sensor
4.1.1.1 Press the "Windows" key on the keyboard
4.1.1.2 Click "PC settings"
4.1.1.3 Click "Privacy"
4.1.1.4 Ensure "Allow apps to use my location" is "On"

To validate the Broadcom location sensor as the only positioning source, ensure 
that all other location sensors such as the one installed by Microsoft 
[Device Manager\Sensors\Windows Location Provider] are disabled. 
This mode can be validated by running Tools\SensorDiagnosticTool.exe (SDT).

4.2 Test Mode
To perform bring-up test, unit test or systematic test, one can disable 
BcmGnssLocationSensor.dll and run BcmGnss.dll in batch mode by rundll32. Results
can be analyzed by log files, currently configured to 
%APPDATA%\Broadcom\Location\ in BcmGnssConfig.xml. It is recommended to remove 
%APPDATA%\Broadcom\Location\SyslogArchive before starting any tests. 

Note that %APPDATA% may be a hidden directory that requires updating settings 
in folder options of Windows explorer.

4.2.1 Host Interface Validation
4.2.1.1 For initial hardware bring-up, run Bringup.bat and follow directions.
Repeat this test at least three times to ensure GPIO and UART drivers are 
functioning as expected. See description in Docs\bringup.txt.
4.2.1.2 Ensure DUT can receive satellite signals. Run the tests below and ensure
the serial summary in log files showing zero TxERR and RxERR as described in
Docs\bringup.txt. 
4.2.1.2.1 Run %OS%\Tests\Serial_Stress.bat. It takes 24 hours to complete.
4.2.1.2.2 On a separate machine, run SDT for 24 hours.
4.2.1.3 Validate the log files from section 4.2.1.2 contain no errors in the 
    end of each file:
    Tx 0 Seq errors, 0 CRC errors
    Rx 0 Seq errors, 0 CRC errors, 0 Malformed Pckts
4.2.1.3.1 Sample as follows:
2012/06/21 10:44:53.811 $881802E Gll Ran for 54767.1 Secs
2012/06/21 10:44:53.811 $881802E Serial Tx:  1890092 packets Tx'd, 0 Seq errors, 0 CRC errors, Avg Rate=489.2 bytes/sec
2012/06/21 10:44:53.811 $881802E Serial Rx:  2104226 packets Rx'd, 0 Seq errors, 0 CRC errors, 0 Malformed Pckts, Avg Rate=1470.7 bytes/sec

4.2.2 Satellite Cache Data
It is extremely important to delete the satellite cache file 
%APPDATA%\Broadcom\Location\gldata.sto whenever the RF exposure is switched 
from live satellites to simulator, and vice versa. 

4.2.3 RF Reception Analysis (Single Channel Simulator Required)

4.2.3.1 Simulator Calibration
4.2.3.1.1 Connect the RF output of simulator to the "INT LNA" port of Broadcom 
GNSS evaluation kit that matches the ASIC on your platform. If you don't have 
one, borrow it from Broadcom support engineer.
    BCM47511    => Beluga
    BCM4751     => Thames
    BCM4750     => BASS
    BCM2076     => Roadrunner
4.2.3.1.2 Connect the evaluation kit to a conventional Windows PC with a USB 
cable, and run install_cp210x.bat as administrator and follow the instructions.
4.2.3.1.3 On simulator, set PRN1 signal level to -130dBm.
4.2.3.1.4 On the Windows PC, run Tests\Factory_High_SNR.bat as administrator and 
wait for it to complete in about 65 seconds. 
4.2.3.1.5 Run rflog.py against the log file to observe the received "Average 
Signal Strength" (ASS). Adjust the simulator output and run again until the 
"ASS" is -130dBm.
4.2.3.1.6 Save this simulator settings for step 4.2.3.2.

4.2.3.2 Validating RF Reception of Device Under Test (DUT)
4.2.3.2.1 Connect the simulator output directly to the DUT.
4.2.3.2.2 Run the simulator per settings in step 4.2.3.1.6
4.2.3.2.3 On the DUT, run Tests\Factory_High_SNR.bat as administrator and wait 
for it to complete in about 65 seconds.
4.2.3.2.4 Run rflog.py against the log file to observe the received "ASS". If 
the "ASS" is -131dBm or less, work with the RF/Hardware engineers internally 
and/or Broadcom to make it as close to -130dBm as possible.

4.2.3.3 Typical Signal Gains and Losses
4.2.3.3.1 In general, an LNA accounts for about 1dB (gain).
4.2.3.3.2 In general, a front end saw filter accounts for about -1.2dB (loss).

4.2.3.4 Validating Antenna RF Reception
4.2.3.4.1 Ensure the DUT can run for at least 30 minutes outside the building.
4.2.3.4.2 Ensure the DUT is connected with GNSS antenna and delete the satellite
cache data per section 4.2.2.
4.2.3.4.3 Bring the DUT to a true open-sky area without above or surrounding
obstructions. True open-sky area can be the roof of a tall building, an open 
space parking lot, or a community park (without above or surrounding trees).
4.2.3.4.4 Run Tests\CollectAlmanac.bat as administrator and wait for it to 
complete in about 15 minutes.
4.2.3.4.5 Use ssplot.exe (part of Broadcom.NmeaAnalyzer) to observe the average 
of four strongest satellites received. Compare this with the results in 
section 4.2.3.2.4, and work with RF/Hardware engineers internally and/or 
Broadcom to reduce the losses. Most of the losses can be caused by interference
noise within the DUT. Placing the antenna as close to the GNSS ASIC as possible
is highly recommended. Shielding can also be added to the cable or RF path to 
minimize noise. 

4.2.3.5 Recommendations of Antenna Placement
4.2.3.5.1 As close to the GNSS ASIC as possible to minimize noise.
4.2.3.5.2 On the edge that is unlikely blocked by the user's hands.
4.2.3.5.3 On the edge that is likely to have most exposure to the sky.

4.2.4 For systematic tests, delete the satellite cache data per section 4.2.2.
Expose the DUT to satellite signals and run as administrator in the following 
order. This order is IMPORTANT!!! Do not interrupt the tests, and wait for them
to complete naturally. If interruption is absolutely necessary, kill the process
"rundll32" started by CollectAlmanac.bat.
4.2.4.1 Tests\CollectAlmanac.bat    - Real satellites or GNSS simulator required
4.2.4.1 Tests\Hot_Starts.bat        - Real satellites or GNSS simulator required
4.2.4.2 Tests\Warm_Starts.bat       - Real satellites or GNSS simulator required
4.2.4.3 Tests\Cold_Starts.bat       - Real satellites or GNSS simulator required

4.2.5 For factory test in production line, run the same tests as in 4.2.3.1 and
4.2.3.2. Monitor the signal strength from NMEA lines through UDP port 18723. 
Platform maker is responsible for setting the pass/fail criteria with trade-off
in quality against yield. As a rule of thumb, 1dB loss is typically acceptable. 
However, all signal losses should be analyzed and recovered as much as possible 
before production. See section 4.2.3.

4.2.6 Optional, use these scripts as template to create other test suites for
jobs in BcmGnssConfig.xml. See UserManual\index.html for more details.

================================= Known Issues =================================
1. After toggling radio, unable to uninstall driver. Reboot as a workaround.

=============================== Revision History ===============================
2012-01-21  Initial Release

2012-02-01  Resolved permission issue of failing to open ACPI UART from sensor
            Validated Radio Manager 

2012-02-06  Added support for 64-bit OS

2012-02-10  All drivers are digitally signed

2012-02-22  Updated new LTO evaluation licence key brcmdev which will expire in
            another 6 months from today
           
2012-03-14  Serial error free on x86 and ARM platforms
            Added x64 missing DLL during build process
            Added support for location report interval
            Added support for reporting appropriate device state transitions.
            Added more sensor data fields supported by GPS engine.
            Sensor device is no longer root enumerated. Its now installed on top 
                of the child (Sensors\BcmGnssLocationSensor) created by 
                BcmGnssBus.sys

2012-03-30  Added ACPI\BCM4751 in BcmGnssBus if ASL fails to build ACPI\BCMGNSS.
            Updated CollectEphemerisPeriodMinute="60" in BcmGnssConfig.xml
            Updated sensor state transitions per guideline on 2012-03-20.
            Updated power management support (not tested).
            Fixed a crash due to dereferencing wrong pointer.
            All .inf files are Unicode.
            Source code included.
            BcmGnss_StripPrivate.pdb included.
            Disable LBS as it would cause a crash - investigating.

2012-03-30  Updated signtool version 6.2.8302.0.
            Updated Windows_Location_Sensor.pdf.
            Fixed a regression on log disable.

2012-04-03  Fixed a leap year bug.
            Updated .inf file.
            Updated uninstall.reg to clean up registry entries.
            Fixed reboot pop-up at the end of install/uninstall.
                See section 3.3 above.

2012-04-13  Updated timeout to ensure glgps_main thread gracefully terminate.
            Disabled CollectEphemerisPeriodMinute as it might cause assert.
            BcmGnssLocationSensor.inf formatted in unicode UTF-16.
           
2012-04-16  Support power management per specification.
            Replaced SENSOR_STATE_NO_DATA with SENSOR_STATE_NOT_AVAILABLE.
            All .inf files are UTF-16 Unicode.
            Disabled Win32 and x64 builds as they are currently not applicable.
            Fixed a race condition in terminating GlGpsDllThread.
           
2012-04-18  Fixed an initialization path that incorrectly lead to I2C.
            Only set SENSOR_STATE_NOT_AVAILABLE when radio is off.
            Fixed a build script issue that was delete too many files.
           
2012-04-20  Fixed thread synchronization issues. 

2012-04-30  Support power management per new specification and removed client
                subscription count as position request criteria.
            Adjusted timeout in BcmGnssBus.sys to accommodate lower level UART
                Driver holding on to read requests for too long and causing 
                BcmGnss.dll to terminate.
            Replaced __debugbreak with RaiseException for cases where BcmGnss
                can no longer continue position computation. This will cause
                the thread terminate, and restarted without triggering the 
                kernel debugger.

2012-05-02  Signed binary files with SHA256 and cross certificate.
            Fixed a breakpoint while Application Verifier is enabled.
            
2012-05-07  Fixed BcmGnss.dll to properly handle UART driver returning 
                ERROR_OPERATION_ABORTED
            Adjusted the timeout of missed fix from 2 seconds to 3 second to
                accommodate OS time resolution in BcmGnssLocationSensor.
            Removed call to WdfDeviceStopIdle and WdfDeviceResumeIdle in 
                BcmGnssBus as they are not necessary.

2012-05-24  BcmGnssLocationSensor.dll - "Broadcom Location" renamed to "GNSS" 
                in radio manager friendly name. It can be customized by 
                HKLM\SYSTEM\CurrentControlSet\Control\RadioManagement\Misc\BcmGnssRadioManager 
                    FriendlyName REG_SZ
            BcmGnssLocationSensor.inf - resolved .inf check issues
            BcmGnssBus.sys - removed SERIAL_EV_RXCHAR and SERIAL_EV_TXEMPTY 
            BcmGnss.dll - upgraded to version 4 of engine
            BcmGnssConfig.xml 
                - program data such as log files default to 
                %APPDATA%\Broadcom\Location
                 added PsfRecoverJobsUponBadTime="true" if GPS time is corrupt.

2012-06-18  Added version resource to all binary files. 
                - The version values are temporary. Actual version values will
                need to be properly updated in future releases.
            BcmGnssConfig.xml
                - Added <hal LtoDownloadPeriodMinute="120" /> to automatically 
                download LTO file in the background every 120 minutes. This 
                value is configurable. See BcmGnssConfig.xml for details.
                - Added <hal arp-supl-enable="true" /> to support SUPL 1.0 SI.
                This only works if the platform supports AT commands listed in
                section 2.1.7.
            BcmGnssBus.sys 
                - Removed the eject pop-up during installation.
                - Fixed a HCK failure.
            BcmGnssLocationSensor.dll 
                - If the client report interval is one minute or longer, stop 
                the GNSS engine and ASIC to save power.
                - Fixed a heap allocation error.
                - Fixed an error due to unpaired idle states.
            BcmGnssLocationSensor.inf - resolved .inf check issue
            
2012-06-22  Fixed report interval reset to 1 second after radio off/on.
            Fixed COM Surrogate pop-up after radio toggle.
            
2012-06-29  All binary files are properly versioned
            BcmGnssLocationSensor.dll and BcmGnss.dll
                - Added workaround to handle ghost clients in sensor framework
                - Fixed The second event registration doesn't get event form 
                GPS when Desired Accuracy is high.
                - Fixed a bug when radio is off, run SDT, and state is showing 
                INITIALIZING, it should be NOT_AVAILABLE 
            BcmGnssConfig.xml
                - Disable LTO download as WinINet is used instead of WinHTTP
                since driver is a service, not a user mode application.
                
2012-07-03  BcmGnssAtRil.dll
                - Fixed leakage
                
2012-07-16  Created Win32_BCM4751 that is specifically for BCM4751
            BcmGnssLocationSensor.dll and BcmGnss.dll
                Improved assertion handling
            Removed add-on .dll files that are not applicable.
                BcmGnssAtRil.dll
                BcmGnssCbee.dll
                BcmGnssLbsWlan.dll
                BcmGnssNetDetect.dll            
            BcmGnss.dll
                - Added registry override in %OS%\Tests\*.reg
                - Use WinHttp instead of WinINET for LTO download
                - BcmGnssConfig.xml LTO download enabled
            BcmGnssGpioAcpi.dll
                - Renamed from BcmGnssGpio.dll
                - Fixed resource leak by removing printf

2012-07-23  BcmGnssLocationSensor.dll 
                - Added ExitShutdown() for PnP rebalancing
                - Resolved leaks by removing unnecessary CoCreateInstance
            BcmGnss.dll
                - Added byte stream dump to aide UART driver debugging
                - Fixed a yellow bang by the correct state upon shutdown
                - Fixed a bug for LogEnabled in registry is not recognized by
                GNSS engine.
            BcmGnssBus.sys
                - Allow device disable from device manager
                - Delete Location Sensor device when the bus driver receives
                ReleaseHardware callback. WHCK equivalent is PnP Test failure.
                - Marking bus driver exclusive. Only one client can have an 
                open handle to it any point in time.

2012-07-25  PnpLockdown = 1 on all drivers

2012-08-10  BcmGnss.dll
                - Added support for PsfNotConnected
            -bcmgnssbus.inf
                - Fixed the bug  should not use the SID 'UD' in its security descriptor)

2012-08-12  BcmGnssLocationSensor.dll
                - Fixed a fex of Code 3, YB, pnp WUDF errors.
                - Start/Stop positiion now can be sent from D0Entry/D0Exit only.
                - Added timed wait for start or stop to finisih.
                - Glgps thread will be killled if it doesn't quit for 40 seconds from sending an IRM stop.

2012-08-14  BcmGnssLocationSensor.dll
                - Fixed the bug Updating location sensor driver prompts reboot.
                
2012-08-17  Brought back PnpLockdown = 1 on all drivers.

2012-08-23  BcmGnssLocationSensor.dll
                - Fix WHCK RadioManager system test failures.
            BcmGnss.dll
                - Added support for SUPL alternate H-SLP 
                - Added <hal SslMethod="TLSv1_1> and <hal SslMethod="TLSv1_2>
                to support TLS v1.1 and v1.2 when using a secure connection
                to the SUPL server.                            
                
2012-08-28  BcmGnssLocationSensor.dll
                - Fixed a by "Setting report interval does not work as expected
                  if the interval is higher than 60 seconds. Say 65"
                - Fixed the Radio Manager to remove the GNSS radio from the 
                PC Settings Wireless UI when the location driver is disabled.
            BcmGnssBus.sys
                - Fix for a WHCK test crash due to insufficient stack size.
                - Changing the port name to BCMGNSS1 from COM22 to avoid 
                  potential collision.
            BcmGnssConfig.xml 
                - Changing the port name to BCMGNSS1 from COM22 to avoid 
                  potential collision.
            BcmGnss.dll 
                - Download LTO based on internet connection event notification 
                (WiFi or broadband) and Minimum Elapsed Second Before Refresh. 
                Based on UTC time when LTO was last downloaded
                - Download reference time when internet connect is available.
                Ensure to disable internet connection while testing against
                simulator.
                - gldata.sto is stored in registry. Use Tests/Delete_STO.bat to
                delete the content as described in section 4.2.2.
                - LogRawByteStreamPerLine is disabled by default. Import 
                Tests/LogRawByteStreamOn.reg to enable, if needed for UART 
                driver debugging.

2012-09-07  BcmGnssBus.sys
                - Fixed an yellow bang issue reported on x86 platforms.

2012-09-13
            BcmGnss.dll 
                - Disabled NMEA output and IRM input through UDP by default as
                it is only useful during testing. It can be enabled by importing
                NetworkIoOn.reg.
                - Added WSACleanup during shutdown.
                - For CP210x UART, send the power down sequence so as to not 
                reset the NVRAM on the ASIC
2012-09-21  BcmGnssLocationSensor.dll
                - Send IRM QUIT command repeateldy until glls quits. To help
                solve code 3 problems.
                
2012-10-04  BcmGnssLocationSensor.dll
                - Fixed crash recovery mechanism.
================================= End of File ==================================
