glhal/glgps_hal.h File Reference
glhal/glgps_hal.h File Reference

Global Locate Hardware Abstraction layer interface. More...

Include dependency graph for glgps_hal.h:
This graph shows which files directly or indirectly include this file:

Classes

struct  GPSCTRL_EVENT
 Structure to send an event from the HAL to the GLCT. More...
struct  GlcReqMgrHandler
 Structure used to register custom request manager. More...

Defines

#define BATCH_MANAGER_REQUEST   "req_brm"
 Can be any type of request (periodic, single shot,...) originated from batch request manager (QA Jobs)
#define CNTIN_TEST_REQUEST   "req_cntin"
 Count-in (TCXO calibration)

Functions

int GpsHalNrControl (int iFlags, unsigned long ulTimeOffsetMS)
 Control options:
HAL layer management
GpsHalGpsHalCreateHal (void)
 Creates HAL layer In this function the application can perform any needed initialization of the HAL.
void GpsHalInit (GpsHal *pHal)
 Prepares HAL to be opened.
void GpsHalDestroy (GpsHal *pHal)
 Destroys HAL; in this function the application can clean up the HAL as needed.
void GpsHalSetCfgValue (GpsHal *pHal, const plain_char *pcAttrName, const plain_char *pcValue)
 Sets the value of the parameter not recognized by the GLCT config parser.
short GpsHalOpen (GpsHal *pHal)
 Opens GPS HAL.
void GpsHalClose (GpsHal *pHal)
 Closes GPS HAL This is where serial port is closed, TCXO power turned off, ASIC turned off.
void GpsHalCloseLog (GpsHal *pHal)
 The session has ended the log file can be closed.
Event reception
int GpsHalWaitForEvent (GpsHal *pHal, GPSCTRL_EVENT *pEvent, int iTimeoutMs)
 Sleep in this function until event is received.
void GpsHalRegisterCustomEvent (GpsHal *pHal, GlcReqMgrHandler *pHdlr, short sCount)
 This callback is called by GLCT to allow application register custom Request Managers.
void GpsHalOkToDeepSleep (short sPadNum)
 This callback is called by GLCT to let HAL know that its OK to put host CPU to deep sleep mode.
Outgoing communications to the chip
void GpsHalChipsetWrite (GpsHal *pHal, unsigned char *asicBytes, short sBytesToWrite)
 Write data to the communication port.
Outgoing communications to the DAC debug unit
void GpsHalUdpDacWrite (GpsHal *pHal, unsigned char *asicBytes, short sBytesToWrite)
 Write data to the DAC communication port.
HAL timer function
void GpsHalUpdateTimer (GpsHal *pHal, unsigned long ulTimerTimeoutMs)
 This callback is optional. See description below.
Debug read
int GpsHalDebugRead (GpsHal *pHal, void *pBuf, int iBytes, int *piEof, int *piError)
 Reads data for debugging.
Assert handling
void GpsHalAssert (GpsHal *pHal, const plain_char *pAssertMessage)
 Hal method to handle a core gll library assert.
Nonvolatile storage APIs
short GpsHalNvStgOpenRead (GpsHal *pHal)
 Open nonvolatile storage for reading.
short GpsHalNvStgRead (GpsHal *pHal, plain_char *pcBuff, short sBuffSize)
 Read data from nonvolatile storage.
short GpsHalNvStgOpenWrite (GpsHal *pHal)
 Open non volatile storage for writing.
short GpsHalNvStgWrite (GpsHal *pHal, const plain_char *pcBuff, short sBuffSize)
 Write data to nonvolatile storage.
void GpsHalNvStgClose (GpsHal *pHal)
 Close previously opened nonvolatile storage.
EE APIs
short GpsHalEEOpenRead (GpsHal *pHal)
 Open EE file for read only (O_RDONLY).
short GpsHalEERead (GpsHal *pHal, plain_char *pcBuff, short sBuffSize)
 Read data from EE file.
short GpsHalEEOpenWrite (GpsHal *pHal)
 Open EE file for write only (O_CREAT|O_WRONLY)
short GpsHalEEWrite (GpsHal *pHal, const plain_char *pcBuff, short sBuffSize)
 Write data to EE file.
void GpsHalEECloseRead (GpsHal *pHal)
 Close previously opened EE file (for read)
void GpsHalEECloseWrite (GpsHal *pHal)
 Close previously opened EE file (for write)
int GpsHalEESeekRead (GpsHal *pHal, unsigned long ulPosition)
 move the EE file pointer to sepecific position (file opened for read)
int GpsHalEESeekWrite (GpsHal *pHal, unsigned long ulPosition)
 move the EE file pointer to sepecific position (file opened for write)
void GpsHalEEStopGenerator (GpsHal *pHal)
 Stop the EE generator.
void GpsHalEEInformGeneratorNewBE (GpsHal *pHal)
 Inform the EE generator of new ephemeris.
int GpsHalEEStartGenerator (GpsHal *pHal, const plain_char *acCbeeGenAppFileSpec, const plain_char *acArgLine)
 Start the EE generator.
LTO APIs
short GpsHalLtoOpen (GpsHal *pHal)
 Open LTO file.
short GpsHalLtoRead (GpsHal *pHal, plain_char *pcBuff, short sBuffSize)
 Read LTO file.
void GpsHalLtoClose (GpsHal *pHal)
 Close LTO file.
Self Test
plain_char * GpsHalSelfTestReadLine (GpsHal *pHal)
 Read and return one line from self test input file.
int GpsHalSelfTestWriteLine (GpsHal *pHal, const plain_char *pBuffer)
 Write one line to the self test file output file Returns a negative value to indicate an error condition.
Dynamic Memory APIs
void * GpsHalMemAlloc (unsigned long ulSize)
 Allocate memory block.
void GpsHalMemFree (void *ptr)
 Free memory block.
NMEA interface
int GpsHalNmeaOpen (GpsHal *pHal, const plain_char *pcName)
 Creates/Opens the NMEA output/request listener.
void GpsHalNmeaWrite (GpsHal *pHal, int writer, const plain_char *pcNmea, short sBuffSize)
 Write NMEA to the output.
void GpsHalNmeaCustom (GpsHal *pHal, int writer, const GL_FIX_STATUS *pFixStatus)
 Gives opportunity to HAL to generate some custom NMEA message once per position fix.
void GpsHalNmeaFactTest (GpsHal *pHal, int writer, const GL_FACT_TEST_STATUS *ptStatus)
 TODO: document factory test API.
void GpsHalNmeaClose (GpsHal *pHal, int listener)
 Closes the NMEA output/request listener.
Reference frequency control APIs
short GpsHalRefFreqOn (GpsHal *pHal)
 Indicate that the reference frequency is required.
short GpsHalRefFreqQuery (GpsHal *pHal)
 Query the status of the reference frequency.
short GpsHalRefFreqOff (GpsHal *pHal)
 Obtain the frequency offset of the reference frequency.
SYNCIN APIs
short GpsHalGetSyncInTime (GpsHal *pHal, GL_TIME *pstGlTime, UTC_TIME *pstUtcTime)
 Query the status of the sync in time.
RRC messages APIs
int GpsHalNrmRrcSend (GpsHal *pHal, const unsigned char *data, int size)
 Send a RRC message.
int GpsHalNrmRrlpSend (GpsHal *pHal, const unsigned char *data, int size)
 Send a RRLP message.
#define _NUMOF(name)   _NUMOF##name
 Number of elements in enum.
enum  GLCT_PAL_EV_CODE {
  GLCTEV_NONE = 1L<<0, GLCTEV_HAL_FATAL_ERROR = 1L<<1, GLCTEV_PAL_ENG_ASIC_DATA = 1L<<2, GLCTEV_PAL_ENG_FREQ_DATA = 1L<<3,
  GLCTEV_PAL_ENG_TIMER_TICK = 1L<<4, GLCTEV_PAL_MGR_CMD_XXX = 1L<<5, GLCTEV_PAL_PWR_CHG = 1L<<6, GLCTEV_PAL_EXT_SENS = 1L<<8,
  GLCTEV_PAL_UDP_DAC_DATA = 1L<<9 , GLCTEV_PAL_NRM_SUPL_DATA = 1L<<16, GLCTEV_PAL_NRM_RRLP_DATA = 1L<<17, GLCTEV_PAL_NRM_RRC_DATA = 1L<<18,
  GLCTEV_PAL_NRM_ASST_DATA = 1L<<19, GLCTEV_PAL_APP1_DATA = 1L<<20, GLCTEV_PAL_APP2_DATA = 1L<<21, GLCTEV_PAL_APP3_DATA = 1L<<22,
  GLCTEV_PAL_APP4_DATA = 1L<<23
}
 Events sent from HAL to the GPS control task. More...
enum  GLCT_PWR_MODE { GLCT_PWR_MODE_DEFAULT, GLCT_PWR_MAX_PERFORMANCE, GLCT_PWR_MIN_POWER }
 This is the payload of the GLCTEV_PAL_PWR_CHG event One example would be the monitoring of the power source: More...
typedef GpsHalConfig GpsHal
 Alternate type for GpsHalConfig.
typedef enum GLCT_PAL_EV_CODE GLCT_PAL_EV_CODE
 Events sent from HAL to the GPS control task.
typedef struct GPSCTRL_EVENT GPSCTRL_EVENT
 Structure to send an event from the HAL to the GLCT.
typedef void * GlAppReqHdlr
 Opaque pointer to the AppRequestProcessor.
typedef GlAppReqHdlr(* GlcbReqMgrCreate )(void)
 Event handler initialization routine.
typedef void(* GlcbSetCfgValue )(GlAppReqHdlr hdlr, const plain_char *pcAttrName, const plain_char *pcValue)
 Passes attributes read from <app> element of the XML file.
typedef void(* GlcbReqMgrStart )(GlAppReqHdlr hdlr, void *pGlCtrl)
 Called once the GLCT is initialized and ready to process the events.
typedef void(* GlcbReqMgrProcEvent )(GlAppReqHdlr hdlr, void *pGlCtrl, GPSCTRL_EVENT *pEvent)
 Called whenever HAL will post event registered with GpsHalRegisterCustomEvent()
typedef void(* GlcbReqMgrDestroy )(GlAppReqHdlr hdlr, void *pGlCtrl)
 Called before GLCT is destroyed.
typedef struct GlcReqMgrHandler GlcReqMgrHandler
 Structure used to register custom request manager.

HAL time function

#define RANDOM_SLEEP_NOT_SUPPORTED   (~0ul)
unsigned long GpsHalGetTimer (GpsHal *pHal)
 Returns value of 32bit counter scaled to milliseconds.
unsigned long GpsHalGetPrecTimer (GpsHal *pHal)
 Returns value of 64bit counter scaled to microseconds.
unsigned long GpsHalRandomSleep (unsigned long maxSec)
 Sleep for random number of seconds.

Diagnostic output

#define GpsHalDiagLineFmt   GpsHalDiag
void GpsHalDiagLine (GpsHal *pHal, const plain_char *pcLine)
 Writes the string to the logging facility.
void GpsHalDiagLineFmt (GpsHal *pHal, const plain_char *pcLine,...)
 Writes the string to the logging facility.

PGLOR_NET APIs to report TTFF and network status to NMEA output stream

#define PG_BIT(bit)   (1L << (bit))
 Indicate network protocol ACK/NAK or MSA position pass/fail.
#define PGLOR_NET_RES_FIX_PASS   PG_BIT(7)
#define PGLOR_NET_RES_FIX_FAIL   PG_BIT(18)
#define PGLOR_NET_RES_PROTO_PASS   PG_BIT(0)
#define PGLOR_NET_RES_PROTO_FAIL   PG_BIT(17)
#define PGLOR_NET_FIX_SINGLE   PG_BIT(1)
#define PGLOR_NET_FIX_PERIODIC   PG_BIT(2)
#define PGLOR_NET_MSA_POSITION   PG_BIT(28)
#define PGLOR_NET_PROTO_RRLP   PG_BIT(4)
#define PGLOR_NET_PROTO_RRC   PG_BIT(5)
#define PGLOR_NET_PROTO_SUPL   PG_BIT(6)
#define PGLOR_NET_PROTO_LBS   PG_BIT(27)
#define PGLOR_NET_PROTO_LTE   PG_BIT(26)
#define PGLOR_NET_DONE   PG_BIT(19)
 Indicate end of session (EOS) for non-assisted cases.
#define PGLOR_NET_METH_G   PG_BIT(25)
#define PGLOR_NET_METH_A   PG_BIT(9)
#define PGLOR_NET_METH_B   PG_BIT(10)
#define PGLOR_NET_METH_F   PG_BIT(29)
#define PGLOR_NET_METH_L   PG_BIT(20)
#define PGLOR_NET_METH_X   PG_BIT(21)
#define PGLOR_NET_METH_W   PG_BIT(22)
#define PGLOR_NET_METH_N   PG_BIT(23)
#define PGLOR_NET_METH_M   PG_BIT(24)
#define PGLOR_NET_ASST_FINE_TIME   PG_BIT(8)
#define PGLOR_NET_ASST_FREQ   PG_BIT(11)
#define PGLOR_NET_ASST_LOCATION   PG_BIT(12)
#define PGLOR_NET_ASST_TIME   PG_BIT(13)
#define PGLOR_NET_ASST_EPH   PG_BIT(14)
#define PGLOR_NET_ASST_ACQ   PG_BIT(15)
#define PGLOR_NET_ASST_OTHER   PG_BIT(16)
#define PGLOR_NET_PROTO
#define PGLOR_NET_ASST
#define PGLOR_NET_RES_PROTO
#define PGLOR_NET_RES_FIX
#define PGLOR_NET_FIX
#define PGLOR_NET_PROTO_ANY_CP
enum  PGLOR_NET_SESSION_TYPE { , PGLOR_NET_SESSION_TYPE_SI = 1, PGLOR_NET_SESSION_TYPE_NI = 2, PGLOR_NET_SESSION_TYPE_WARM = 3, PGLOR_NET_SESSION_TYPE_ASST = 4 }
 Types of assistance sessions that are reported in the PGLOR,SM1 field <ST>. More...
enum  PGLOR_NET_ERROR_TYPE {
  PGLOR_NET_ERR_NO_ERROR = 0, PGLOR_NET_ERR_FAKE, PGLOR_NET_ERR_LCS_SOCKET_NOT_READY, PGLOR_NET_ERR_LCS_SOCKET_WRITE,
  PGLOR_NET_ERR_NOT_STARTED, PGLOR_NET_ERR_NOT_CONNECTED, PGLOR_NET_ERR_TIMEOUT, PGLOR_NET_ERR_RESPONSE_MISMATCH,
  PGLOR_NET_ERR_WRONG_SESSION, PGLOR_NET_ERR_OUT_OF_FORMAT, PGLOR_NET_ERR_NET_TYPE_UNSUPPORTED, PGLOR_NET_ERR_MISSING_CALLBACK,
  PGLOR_NET_ERR_MARSHALL_OUT_OF_FORMAT, PGLOR_NET_ERR_MARSHALL_FEW_ARG, PGLOR_NET_ERR_MARSHALL_PAYLOAD, PGLOR_NET_ERR_CALL_FAIL_BUSY,
  PGLOR_NET_ERR_CALL_FAIL_NO_USER_RESPONDING, PGLOR_NET_ERR_CALL_FAIL_USER_ALERTING_NO_ANSWER, PGLOR_NET_ERR_CALL_FAIL_CAUSE_REJECTED, PGLOR_NET_ERR_CALL_FAIL_ERROR_UNSPECIFIED,
  PGLOR_NET_ERR_CALL_FAIL_CALL_BARRED, PGLOR_NET_ERR_CALL_FAIL_ACM_LIMIT_EXCEEDED, PGLOR_NET_ERR_CALL_FAIL_SERVER_NO_RESPONSE, PGLOR_NET_ERR_CALL_FAIL_PREMATURE_STOP
}
 Types of errors that are reported in the PGLOR,NET field <SS>. More...
typedef enum PGLOR_NET_SESSION_TYPE PGLOR_NET_SESSION_TYPE
 Types of assistance sessions that are reported in the PGLOR,SM1 field <ST>.
typedef enum PGLOR_NET_ERROR_TYPE PGLOR_NET_ERROR_TYPE
 Types of errors that are reported in the PGLOR,NET field <SS>.
typedef void(* pFunc_PrintPglorNet_t )(void *pHal, const unsigned char *sNmeaPglorNet, int nBytes)
 Each customer HAL must provide a means to report PGLOR,NET.
void GpsHalNrInit (void *pHal, pFunc_PrintPglorNet_t cbPrint, int bFull)
 Initialize the PGLOR,NET data: provide the HAL and a callback function to handle the printing.
void GpsHalNrFixStart (unsigned long ulFlags)
 Call this function when starting a request that will result in a $PGLOR,NET,pass/fail message.
void GpsHalNrFixEnd (unsigned long ulFlags)
 Indicate we got a fix (could be an unsuccessful fix).
void GpsHalNrProtocol (unsigned long ulFlag, unsigned long ulData)
 Report AGPS protocol progress. Use the PGLOR_NET_*** bits to describe the protocol.
void GpsHalNrSessionStart (int bClear)
 Report AGPS session is starting.
unsigned long GpsHalNrSessionStartTime (void)
 Returns the session start time.
unsigned long GpsHalNrFixStartTime (void)
 Returns the fix start time.
void GpsHalNrSessionEnd (unsigned long ulFlag, unsigned long ulData)
 Report AGPS session is ending: start removing attributes of the session.
void GpsHalNrSetSessionType (PGLOR_NET_SESSION_TYPE t)
 Sets the session type.
PGLOR_NET_SESSION_TYPE GpsHalNrGetSessionType (void)
 Gets the session type.
void GpsHalNrSetPosSource (GL_POS_SOURCE source)
 Sets the position source.
GL_POS_SOURCE GpsHalNrGetPosSource (void)
 Gets the position source.

Detailed Description

Global Locate Hardware Abstraction layer interface.

See Hardware Abstraction Layer (HAL) for more information


Define Documentation

#define PG_BIT (   bit)    (1L << (bit))

Indicate network protocol ACK/NAK or MSA position pass/fail.

Causes PGLOR,SM2 summary #2 output.


Typedef Documentation

Alternate type for GpsHalConfig.

A pointer to this type is used throughout the API as a handle to particular HAL instance.

typedef void(* pFunc_PrintPglorNet_t)(void *pHal, const unsigned char *sNmeaPglorNet, int nBytes)

Each customer HAL must provide a means to report PGLOR,NET.

Pass a pointer to a PGLOR,NET print function to GpsHalNrInit().

Types of assistance sessions that are reported in the PGLOR,SM1 field <ST>.


Enumeration Type Documentation

Events sent from HAL to the GPS control task.

Enumerator:
GLCTEV_NONE 

No event.

GLCTEV_HAL_FATAL_ERROR 

The HAL needs to be destroyed.

Just doing close/reopen is not good enough. GpsHalClose() (and GpsHalDestroy()) will be called.

GLCTEV_PAL_ENG_ASIC_DATA 

Generated by HAL when new data from ASIC arrived, the size of data should not exceed MAX_GL_COMM_PACKET_IN, otherwise the ASSERT will be generated.

GLCTEV_PAL_ENG_FREQ_DATA 

Generated by HAL when information on ref freq is updated.

GLCTEV_PAL_ENG_TIMER_TICK 

Generated periodically by the HAL to maintain internal GLL timers.

GLCTEV_PAL_MGR_CMD_XXX 

A control ASCII command received.

GLCTEV_PAL_PWR_CHG 

Power mode change.

GLCTEV_PAL_EXT_SENS 

Data from the external sensor is available.

GLCTEV_PAL_UDP_DAC_DATA 

Generated by HAL when new (Direct Access Call)DAC UDP data arrives from debug and/or control unit.

GLCTEV_PAL_NRM_SUPL_DATA 

Generated by HAL when new data from SUPL arrived.

GLCTEV_PAL_NRM_RRLP_DATA 

Generated by HAL when new data from RRLP arrived.

GLCTEV_PAL_NRM_RRC_DATA 

Generated by HAL when new data from RRC arrived.

GLCTEV_PAL_NRM_ASST_DATA 

Generated by HAL when new data from custom assistance source.

GLCTEV_PAL_APP1_DATA 

Generated by HAL when data from APP1 is arrived.

GLCTEV_PAL_APP2_DATA 

Generated by HAL when data from APP2 is arrived.

GLCTEV_PAL_APP3_DATA 

Generated by HAL when data from APP3 is arrived.

GLCTEV_PAL_APP4_DATA 

Generated by HAL when data from APP4 is arrived.

This is the payload of the GLCTEV_PAL_PWR_CHG event One example would be the monitoring of the power source:

  • If running on external power source we want to have the best GPS performance that might come at expense of power consumption
  • While running on internal battery the GPS performance can be sacrificed to extend the battery life
Enumerator:
GLCT_PWR_MODE_DEFAULT 

Default.

GLCT_PWR_MAX_PERFORMANCE 

Maximize GPS performance.

GLCT_PWR_MIN_POWER 

Maximize battery life.

Types of errors that are reported in the PGLOR,NET field <SS>.

Enumerator:
PGLOR_NET_ERR_NO_ERROR 

There is no error.

PGLOR_NET_ERR_FAKE 

The fake (debug) error.

PGLOR_NET_ERR_LCS_SOCKET_NOT_READY 

The LCS socket used for internal IPC is not initialized.

PGLOR_NET_ERR_LCS_SOCKET_WRITE 

During the session, we get an error while writing to LCS socket.

PGLOR_NET_ERR_NOT_STARTED 

During the session fix attempt didn't even start.

PGLOR_NET_ERR_NOT_CONNECTED 

During the session, the connection is lost or the session is closed.

PGLOR_NET_ERR_TIMEOUT 

During the session, the other side took too much time.

PGLOR_NET_ERR_RESPONSE_MISMATCH 

The received response does not match the requested.

PGLOR_NET_ERR_WRONG_SESSION 

We cannot recover the session or session is not there.

PGLOR_NET_ERR_OUT_OF_FORMAT 

During the session, the other side's reported data is out of format.

PGLOR_NET_ERR_NET_TYPE_UNSUPPORTED 

The given network type is not supported.

PGLOR_NET_ERR_MISSING_CALLBACK 

One of the callback function is missing.

PGLOR_NET_ERR_MARSHALL_OUT_OF_FORMAT 

During the session, marshalled request/response is not internally correct.

PGLOR_NET_ERR_MARSHALL_FEW_ARG 

During the session, marshalled parameters are missing.

PGLOR_NET_ERR_MARSHALL_PAYLOAD 

During the session, marshalled payload is wrong.

PGLOR_NET_ERR_CALL_FAIL_BUSY 

Control Plane Error from RIL: The other side is busy calling.

PGLOR_NET_ERR_CALL_FAIL_NO_USER_RESPONDING 

Control Plane Error from RIL: The other side didn't answer.

PGLOR_NET_ERR_CALL_FAIL_USER_ALERTING_NO_ANSWER 

Control Plane Error from RIL:

PGLOR_NET_ERR_CALL_FAIL_CAUSE_REJECTED 

Control Plane Error from RIL: Call rejected.

PGLOR_NET_ERR_CALL_FAIL_ERROR_UNSPECIFIED 

Control Plane Error from RIL: All other call errors.

PGLOR_NET_ERR_CALL_FAIL_CALL_BARRED 

Control Plane Error from RIL: Call barred from above layer.

PGLOR_NET_ERR_CALL_FAIL_ACM_LIMIT_EXCEEDED 

Control Plane Error from RIL: Certain limit exceeded.

PGLOR_NET_ERR_CALL_FAIL_SERVER_NO_RESPONSE 

Control Plane Error from RIL: Server's response not received.

PGLOR_NET_ERR_CALL_FAIL_PREMATURE_STOP 

Control Plane Error: This or other side stopped call before the fix.

Types of assistance sessions that are reported in the PGLOR,SM1 field <ST>.

Enumerator:
PGLOR_NET_SESSION_TYPE_SI 

'U' - unspecified

PGLOR_NET_SESSION_TYPE_NI 

'S' - set initiated

PGLOR_NET_SESSION_TYPE_WARM 

'N' - network initiated

PGLOR_NET_SESSION_TYPE_ASST 

'W' - stay warm


Function Documentation

void GpsHalAssert ( GpsHal pHal,
const plain_char *  pAssertMessage 
)

Hal method to handle a core gll library assert.

On some platforms you may want to do a hard-reset at this point. On others, you may prefer to rely on the default behavior of the glct, which will at this point close the HAL and exit.

Parameters:
pHal- Handle to HAL instance retrieved through prior call to GpsHalCreateHal().
pAssertMessage- content of assert message Null-terminated string.
Precondition:
pHal != NULL
void GpsHalChipsetWrite ( GpsHal pHal,
unsigned char *  asicBytes,
short  sBytesToWrite 
)

Write data to the communication port.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
asicBytesStorage location of data to be written to ASIC.
sBytesToWriteNumber of bytes to write.
Remarks:
You may signal failure to write by setting GLCTEV_HAL_FATAL_ERROR event code in pEvent structure before returning from GpsHalWaitForEvent().
Precondition:
pHal != NULL
void GpsHalClose ( GpsHal pHal)

Closes GPS HAL This is where serial port is closed, TCXO power turned off, ASIC turned off.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Precondition:
pHal != NULL
GpsHal* GpsHalCreateHal ( void  )

Creates HAL layer In this function the application can perform any needed initialization of the HAL.

Returns:
valid pointer to GpsHalConfig structure, NULL in case of failure.
Remarks:
It is important to realize that the the Glct expects to be able to write hal configuration information to the address pointed to by the return value before GpsHalInit() is being called. After that, it does not attempt to interpret or change the content of memory being pointed at anymore, but blindly passes it back to the HAL implementation.
int GpsHalDebugRead ( GpsHal pHal,
void *  pBuf,
int  iBytes,
int *  piEof,
int *  piError 
)

Reads data for debugging.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
pBufbuffer to hold data read
iBytesnumber of bytes requested to be read into pBuf
piEofoutput field for end of file indicator nonzero indicates end of file has been reached
piErroroutput field for error indicator nonzero indicates an error has occured
Return values:
Returnnumber of bytes successfully read
void GpsHalDestroy ( GpsHal pHal)

Destroys HAL; in this function the application can clean up the HAL as needed.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Precondition:
pHal != NULL
void GpsHalDiagLine ( GpsHal pHal,
const plain_char *  pcLine 
)

Writes the string to the logging facility.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
pcLineNull-terminated string.
Precondition:
pHal != NULL
void GpsHalDiagLineFmt ( GpsHal pHal,
const plain_char *  pcLine,
  ... 
)

Writes the string to the logging facility.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
pcLineNull-terminated format string with the same syntax as printf()
Precondition:
pHal != NULL
void GpsHalEECloseRead ( GpsHal pHal)

Close previously opened EE file (for read)

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Precondition:
pHal != NULL
void GpsHalEECloseWrite ( GpsHal pHal)

Close previously opened EE file (for write)

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Precondition:
pHal != NULL

Inform the EE generator of new ephemeris.

Parameters:
pHalHandle to HAL instance
Returns:
Nothing.
Precondition:
pHal != NULL
short GpsHalEEOpenRead ( GpsHal pHal)

Open EE file for read only (O_RDONLY).

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Returns:
Non-zero when successful
Precondition:
pHal != NULL
short GpsHalEEOpenWrite ( GpsHal pHal)

Open EE file for write only (O_CREAT|O_WRONLY)

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Returns:
Non-zero when successful
Precondition:
pHal != NULL NOTE: DONOT use O_TRUNC
short GpsHalEERead ( GpsHal pHal,
plain_char *  pcBuff,
short  sBuffSize 
)

Read data from EE file.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
pcBuffStorage location for data read from non-volatile storage
sBuffSizeMaximum number of bytes to read.
Returns:
Actual number of bytes read, 0 if no more data could be read because end of file is reached, -1 if reading failed for another reason.
Precondition:
pHal != NULL, pcBuff != NULL
int GpsHalEESeekRead ( GpsHal pHal,
unsigned long  ulPosition 
)

move the EE file pointer to sepecific position (file opened for read)

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
ulPositionabsolute position in the file, relative to the beginning of the file
Returns:
the offset, in bytes, of the new position from the beginning of the file; –1L to indicate an error
Precondition:
pHal != NULL
int GpsHalEESeekWrite ( GpsHal pHal,
unsigned long  ulPosition 
)

move the EE file pointer to sepecific position (file opened for write)

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
ulPositionabsolute position in the file, relative to the beginning of the file
Returns:
the offset, in bytes, of the new position from the beginning of the file; –1L to indicate an error
Precondition:
pHal != NULL
int GpsHalEEStartGenerator ( GpsHal pHal,
const plain_char *  acCbeeGenAppFileSpec,
const plain_char *  acArgLine 
)

Start the EE generator.

Parameters:
pHalHandle to HAL instance
acCbeeGenAppFileSpec- pointer to the CBEE application executable.
acArgLine- additional command-line parameters.
Returns:
non-zero if the start was successful
Precondition:
pHal != NULL
void GpsHalEEStopGenerator ( GpsHal pHal)

Stop the EE generator.

Parameters:
pHalHandle to HAL instance
Returns:
Nothing.
Precondition:
pHal != NULL
short GpsHalEEWrite ( GpsHal pHal,
const plain_char *  pcBuff,
short  sBuffSize 
)

Write data to EE file.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
pcBuffStorage location of data to be written to non-volatile storage
sBuffSizeNumber of bytes to write.
Returns:
Actual number of bytes written, -1 if writing failed.
Precondition:
pHal != NULL
unsigned long GpsHalGetPrecTimer ( GpsHal pHal)

Returns value of 64bit counter scaled to microseconds.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Returns:
monotonically increasing value scaled to microseconds that may roll over (2^64 -> 0).
Precondition:
pHal != NULL
short GpsHalGetSyncInTime ( GpsHal pHal,
GL_TIME pstGlTime,
UTC_TIME pstUtcTime 
)

Query the status of the sync in time.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
pstGlTimeTODO: comment pstGlTime
pstUtcTimeTODO: comment pstUtcTime
Returns:
TODO: comment return values
Precondition:
pHal != NULL
unsigned long GpsHalGetTimer ( GpsHal pHal)

Returns value of 32bit counter scaled to milliseconds.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Returns:
monotonically increasing value scaled to milliseconds that may roll over (2^32 -> 0).
Precondition:
pHal != NULL
void GpsHalInit ( GpsHal pHal)

Prepares HAL to be opened.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Precondition:
pHal != NULL
void GpsHalLtoClose ( GpsHal pHal)

Close LTO file.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Precondition:
pHal != NULL
short GpsHalLtoOpen ( GpsHal pHal)

Open LTO file.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Returns:
Non-zero when successful
Precondition:
pHal != NULL
short GpsHalLtoRead ( GpsHal pHal,
plain_char *  pcBuff,
short  sBuffSize 
)

Read LTO file.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
pcBuffStorage location for data read from non-volatile storage
sBuffSizeMaximum number of bytes to read.
Returns:
Actual number of bytes read, 0 if no more data could be read because end of file is reached, -1 if reading failed for another reason.
Precondition:
pHal != NULL
void* GpsHalMemAlloc ( unsigned long  ulSize)

Allocate memory block.

Parameters:
ulSizeSize of the requested memory block, in bytes
Returns:
Valid Pointer on the allocated memory block if successful NULL Pointer if failure
Precondition:
pHal != NULL
void GpsHalMemFree ( void *  ptr)

Free memory block.

Parameters:
ptrPointer on the memory block to be freed
Precondition:
pHal != NULL
void GpsHalNmeaClose ( GpsHal pHal,
int  listener 
)

Closes the NMEA output/request listener.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
listenerHandle to request listener implementation obtained from call to GpsHalNmeaOpen().
Precondition:
pHal != NULL
void GpsHalNmeaCustom ( GpsHal pHal,
int  writer,
const GL_FIX_STATUS pFixStatus 
)

Gives opportunity to HAL to generate some custom NMEA message once per position fix.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
writerId of NMEA writer implementation obtained from call to GpsHalNmeaOpen().
pFixStatuspointer to structure with detailed position fix information, see GL_FIX_STATUS.
Precondition:
pHal != NULL, pFixStatus != NULL
Remarks:
REVIEW: Only gets called for ... request types
int GpsHalNmeaOpen ( GpsHal pHal,
const plain_char *  pcName 
)

Creates/Opens the NMEA output/request listener.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
pcNameOne of the request types defined here.
Returns:
-1 if failed, all other values are considered successful.
Precondition:
pHal != NULL, pcNmea != NULL
void GpsHalNmeaWrite ( GpsHal pHal,
int  writer,
const plain_char *  pcNmea,
short  sBuffSize 
)

Write NMEA to the output.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
writerId of writer implementation obtained from call to GpsHalNmeaOpen().
pcNmeaStorage location of properly formatted, valid NMEA sentence
sBuffSizelength of NMEA sentence
Precondition:
pHal != NULL, pcNmea != NULL
int GpsHalNrControl ( int  iFlags,
unsigned long  ulTimeOffsetMS 
)

Control options:

  • FAKE - a successful GPS first fix becomes session done. Otherwise end of GPS run becomes session done.
  • DEBUG - Report internal details of the glgps_hal_net operations. Otherwise end of GPS run becomes session done.
void GpsHalNrFixStart ( unsigned long  ulFlags)

Call this function when starting a request that will result in a $PGLOR,NET,pass/fail message.

unsigned long GpsHalNrFixStartTime ( void  )

Returns the fix start time.

Returns zero if fix process has not been started.

void GpsHalNrInit ( void *  pHal,
pFunc_PrintPglorNet_t  cbPrint,
int  bFull 
)

Initialize the PGLOR,NET data: provide the HAL and a callback function to handle the printing.

  • pHal - Pointer to the HAL.
  • cbPrint - Set the callback invoked when there is a PGLOR,NET string.
  • bFull - 1 clears the GpsHalNrControl() flags also.
int GpsHalNrmRrcSend ( GpsHal pHal,
const unsigned char *  data,
int  size 
)

Send a RRC message.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
dataTODO: comment data
sizeTODO: comment size
Returns:
TODO: comment return values
Precondition:
pHal != NULL
int GpsHalNrmRrlpSend ( GpsHal pHal,
const unsigned char *  data,
int  size 
)

Send a RRLP message.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
dataTODO: comment data
sizeTODO: comment size
Returns:
TODO: comment return values
Precondition:
pHal != NULL
void GpsHalNrSessionEnd ( unsigned long  ulFlag,
unsigned long  ulData 
)

Report AGPS session is ending: start removing attributes of the session.

Handling of ulFlag is reversed in this function: the flags are removed.

void GpsHalNrSessionStart ( int  bClear)

Report AGPS session is starting.

You may use GpsHalNrProtocol() function to notify this event instead.

Parameters:
bClear[input] Clears the previous session completely. Otherwise, only the session start time will be updated.
unsigned long GpsHalNrSessionStartTime ( void  )

Returns the session start time.

Returns zero if session has not been started.

void GpsHalNvStgClose ( GpsHal pHal)

Close previously opened nonvolatile storage.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Precondition:
pHal != NULL
short GpsHalNvStgOpenRead ( GpsHal pHal)

Open nonvolatile storage for reading.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Returns:
Non-zero when successful
Precondition:
pHal != NULL
short GpsHalNvStgOpenWrite ( GpsHal pHal)

Open non volatile storage for writing.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Returns:
Non-zero when successful
Precondition:
pHal != NULL
short GpsHalNvStgRead ( GpsHal pHal,
plain_char *  pcBuff,
short  sBuffSize 
)

Read data from nonvolatile storage.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
pcBuffStorage location for data read from non-volatile storage
sBuffSizeMaximum number of bytes to read.
Returns:
Actual number of bytes read, 0 if no more data could be read because end of file is reached, -1 if reading failed for another reason.
Precondition:
pHal != NULL, pcBuff != NULL
short GpsHalNvStgWrite ( GpsHal pHal,
const plain_char *  pcBuff,
short  sBuffSize 
)

Write data to nonvolatile storage.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
pcBuffStorage location of data to be written to non-volatile storage
sBuffSizeNumber of bytes to write.
Returns:
Actual number of bytes written, -1 if writing failed.
Precondition:
pHal != NULL
void GpsHalOkToDeepSleep ( short  sPadNum)

This callback is called by GLCT to let HAL know that its OK to put host CPU to deep sleep mode.

this parameter specifies how many meaningless bytes will be prepended to the first incoming data packet that can be safely discarded to allow host CPU and UART to wakeup.

short GpsHalOpen ( GpsHal pHal)

Opens GPS HAL.

This is where serial port is opened, TCXO power turned on, ASIC turned on.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Return values:
0if success, non-zero otherwise
Precondition:
pHal != NULL
unsigned long GpsHalRandomSleep ( unsigned long  maxSec)

Sleep for random number of seconds.

Parameters:
maxSecMaximum number of seconds to sleep.
Return values:
Returnnumber of seconds spent in sleep or RANDOM_SLEEP_NOT_SUPPORTED if this feature is not available.
short GpsHalRefFreqOff ( GpsHal pHal)

Obtain the frequency offset of the reference frequency.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Returns:
Should return 1.
Precondition:
pHal != NULL
short GpsHalRefFreqOn ( GpsHal pHal)

Indicate that the reference frequency is required.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Returns:
TODO: comment return values
Precondition:
pHal != NULL
short GpsHalRefFreqQuery ( GpsHal pHal)

Query the status of the reference frequency.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
Returns:
Should return 1.
Precondition:
pHal != NULL
void GpsHalRegisterCustomEvent ( GpsHal pHal,
GlcReqMgrHandler pHdlr,
short  sCount 
)

This callback is called by GLCT to allow application register custom Request Managers.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
pHdlr- Fill the fields of this structure with appropriate values for your request handler. The GLCT initializes the eCode to GLCTEV_NONE if this field left unchanged no more subsequent calls are done to this callback. Otherwise it will be called once again for opportunity to set another request manager handler
sCount- Increments from 0 every time the GLCT calls this callback. This parameter provides you with the ability to distinguish between calls without remembering what what you set before
Precondition:
pHal != NULL, pHdlr != NULL
void GpsHalSetCfgValue ( GpsHal pHal,
const char *  pcAttrName,
const char *  pcValue 
)

Sets the value of the parameter not recognized by the GLCT config parser.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
pcAttrNameTODO: comment pcAttrName
pcValueTODO: comment pcValue
Precondition:
pHal != NULL

Or if you are defining a config parameter spans out of the ARP module, define it here instead of ARP's config parser callback function.

void GpsHalUdpDacWrite ( GpsHal pHal,
unsigned char *  asicBytes,
short  sBytesToWrite 
)

Write data to the DAC communication port.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
asicBytesStorage location of data to be written to DAC debug unit.
sBytesToWriteNumber of bytes to write.
Remarks:
You may signal failure to write by setting GLCTEV_HAL_FATAL_ERROR event code in pEvent structure before returning from GpsHalWaitForEvent().
Precondition:
pHal != NULL
void GpsHalUpdateTimer ( GpsHal pHal,
unsigned long  ulTimerTimeoutMs 
)

This callback is optional. See description below.

This Hal callback is used only in application that uses asynchronous event, i.e. not using GpsRun and GpsHalWaitForEvent, but instead calling directly GlctProcessEvent each time an event occurs. In that case, as there is no blocking calls on event, the application needs to create a timer that will call GlctProcessEvent with GLCTEV_PAL_ENG_TIMER_TICK, each time the timer expires. The timer should be restarted each time this callback is called, using the new value provided. This callback is optional and under compilation flag so that only asynchronous design will request this function to be declared (use _USE_TIMER_CB_ to compile Glct).

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
ulTimerTimeoutMsTime in Ms that the application can sleep before calling GlctProcessEvent with GLCTEV_PAL_ENG_TIMER_TICK. Note that in most cases, GpsHalUpdateTimer will be call again to restart the timer before the timer expires.
Precondition:
pHal != NULL
int GpsHalWaitForEvent ( GpsHal pHal,
GPSCTRL_EVENT pEvent,
int  iTimeoutMs 
)

Sleep in this function until event is received.

Efficiently wait for an event from either the serial port, the network connection, command strings for the GPS control software, whatever else you might need to wait on.

Parameters:
pHalHandle to HAL instance retrieved through prior call to GpsHalCreateHal().
pEventTODO: comment pEvent
iTimeoutMsTODO: comment iTimeoutMs
Returns:
0 in all cases.
Remarks:
Return value is currently unused. Consider different values reserved for future and consider 0 to be reserved for meaning success.
Precondition:
pHal != NULL, pEvent != NULL
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines