1 #ifndef HAP_PLS_H 2 #define HAP_PLS_H 3 4 /** 5 * Copyright (c) 2019, The Linux Foundation. All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions are 9 * met: 10 * * Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * * Redistributions in binary form must reproduce the above 13 * copyright notice, this list of conditions and the following 14 * disclaimer in the documentation and/or other materials provided 15 * with the distribution. 16 * * Neither the name of The Linux Foundation nor the names of its 17 * contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED 21 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 22 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT 23 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS 24 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 25 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 26 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 27 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 29 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 30 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 #include <stdint.h> 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif 38 39 /** 40 * Process local storage is local storage for the hlos process context. 41 * 42 * Warning, this API should only be called from within a thread started by FastRPC, and not from 43 * any user created threads via the qurt apis. 44 * 45 * When used from within a FastRPC started thread this will attach 46 * desturctors to the lifetime of the HLOS process that is making the 47 * rpc calls. Users can use this to store context for the lifetime of 48 * the calling process on the hlos. 49 * 50 * Recovering instances 51 * -------------------- 52 * 53 * To maintain the same instance structure for a caller from the HLOS users 54 * can use the HAP_pls_add_lookup api, which will lookup the key, and add it 55 * if its not already present. 56 * For example: 57 * 58 * static int my_instance(struct my_struct* me) { 59 * return HAP_pls_add_lookup((uintptr_t)my_ctor, //type, some unique static address 60 * 0, //key, for different type instances 61 * sizeof(*me), //size of our struture 62 * my_ctor, //structure ctor 63 * 0, //aditional user context for ctor 64 * my_dtor, //desturctor 65 * &me); //result 66 * } 67 * 68 * First call to my_instance will initialize the structure by allocating it and calling my_ctor. 69 * Second call to my_instance will return the created instance. 70 * This API is thread safe, but when two threads try to intialize the structure the first 71 * time they may both create an instance, but only 1 will be returned. 72 * The destructor will be called when the HLOS process exits. 73 * 74 * See HAP_pls_add and HAP_pls_add_lookup. 75 * 76 * Exit Hooks 77 * ---------- 78 * 79 * Users can use either HAP_pls_add_lookup or HAP_pls_add to add a destructor that will be 80 * called when the HLOS process exits. The main difference between the two functions is that 81 * HAP_pls_add will always add, and the last instance added will be the one returned by 82 * HAP_pls_lookup. 83 * 84 * 85 */ 86 87 /** 88 * adds a new type/key to the local storage, overriding 89 * any previous value at the key. Overriding the key 90 * does not cause the destructor to run. Destructors are 91 * run when the HLOS process exits. 92 * 93 * @param type, type part of the key to be used for lookup, 94 * these should be static addresses, like the address of a function. 95 * @param key, the key to be used for lookup 96 * @param size, the size of the data 97 * @param ctor, constructor that takes a context and memory of size 98 * @param ctx, constructor context passed as the first argument to ctor 99 * @param dtor, destructor to run at pls shutdown 100 * @param ppo, output data 101 * @retval, 0 for success 102 */ 103 int HAP_pls_add(uintptr_t type, uintptr_t key, int size, int (*ctor)(void* ctx, void* data), void* ctx, void (*dtor)(void*), void** ppo); 104 105 /** 106 * Like add, but will only add 1 item, and return the same item on the 107 * next add. If two threads try to call this function at teh same time 108 * they will both receive the same value as a result, but the constructors 109 * may be called twice. 110 * item if its already there, otherwise tries to add. 111 * ctor may be called twice 112 * callers should avoid calling pls_add for the same type/key which will override the singleton 113 */ 114 int HAP_pls_add_lookup(uintptr_t type, uintptr_t key, int size, int (*ctor)(void* ctx, void* data), void* ctx, void (*dtor)(void*), void** ppo); 115 116 /** 117 * finds the last data pointer added for key to the local storage 118 * 119 * @param key, the key to be used for lookup 120 * @param ppo, output data 121 * @retval, 0 for success 122 */ 123 int HAP_pls_lookup(uintptr_t type, uintptr_t key, void** ppo); 124 125 126 #ifdef __cplusplus 127 } 128 #endif 129 #endif //HAP_PLS_H 130