Home | History | Annotate | Download | only in pal 
      1 /*
      2  * Copyright (C) 2017 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 #ifndef CHRE_PAL_SYSTEM_H_
     18 #define CHRE_PAL_SYSTEM_H_
     19 
     20 /**
     21  * @file
     22  * Defines a set of system functions implemented by the entity opening a PAL
     23  * interface that PAL implementations are strongly recommended to use in place
     24  * of calling directly into the underlying system. One of the motivations for
     25  * having PAL implementations use these functions rather than equivalent ones
     26  * exposed by the underlying platform is to provide improved debuggability of
     27  * the CHRE implementation as a whole.
     28  */
     29 
     30 #include <stdint.h>
     31 
     32 #include "chre_api/chre/re.h"
     33 #include "chre/pal/version.h"
     34 
     35 #ifdef __cplusplus
     36 extern "C" {
     37 #endif
     38 
     39 /**
     40  * Initial version of the CHRE PAL System API.
     41  */
     42 #define CHRE_PAL_SYSTEM_API_V1_0  CHRE_PAL_CREATE_API_VERSION(1, 0)
     43 
     44 /**
     45  * The version of the CHRE GNSS PAL defined in this header file.
     46  */
     47 #define CHRE_PAL_SYSTEM_API_CURRENT_VERSION  CHRE_PAL_SYSTEM_API_V1_0
     48 
     49 struct chrePalSystemApi {
     50     /**
     51      * The version of this API structure, which can be used at runtime to
     52      * determine if functions added in newer versions are available, etc.
     53      */
     54     uint32_t version;
     55 
     56     /**
     57      * Retrieves the current time using the same time base as supplied to the
     58      * nanoapp in chreGetTime(). This function should be used when populating
     59      * reference time fields in event structures passed by a PAL implementation
     60      * to CHRE.
     61      *
     62      * @return Current time since some fixed arbitrary reference point in the
     63      *         past, in nanoseconds
     64      *
     65      * @see chreGetTime
     66      */
     67     uint64_t (*getCurrentTime)(void);
     68 
     69     /**
     70      * Logs a message to the same messaging subsystem as used by the CHRE
     71      * system. Semantics are the same as chreLog, but the implementation may
     72      * differ.
     73      *
     74      * @param level Log level, same as defined in the CHRE API
     75      * @param formatStr printf-style format string, details provided in the CHRE
     76      *        API
     77      *
     78      * @see chreLog
     79      */
     80     void (*log)(enum chreLogLevel level, const char *formatStr, ...);
     81 
     82     /**
     83      * Dynamically allocate a block of memory. Semantics are the same as
     84      * chreHeapAlloc, but the implementation may differ.
     85      *
     86      * @param size Size of the allocation, in bytes
     87      *
     88      * @return Pointer to buffer that is aligned to store any kind of variable,
     89      *         or NULL if the allocation failed
     90      *
     91      * @see chreHeapAlloc
     92      */
     93     void *(*memoryAlloc)(size_t size);
     94 
     95     /**
     96      * Return memory allocated via memoryAlloc to the system. Semantics are the
     97      * same as chreHeapFree, but the implementation may differ.
     98      *
     99      * @param pointer A pointer previously returned by memoryAlloc
    100      *
    101      * @see chreHeapFree
    102      */
    103     void (*memoryFree)(void *pointer);
    104 };
    105 
    106 #ifdef __cplusplus
    107 }
    108 #endif
    109 
    110 #endif  // CHRE_PAL_SYSTEM_H_
    111