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 ESE_H_ 18 #define ESE_H_ 1 19 20 #include "ese_hw_api.h" 21 #include "../../../libese-sysdeps/include/ese/sysdeps.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /* 28 * Public client interface for Embedded Secure Elements. 29 * 30 * Prior to use in a file, import all necessary variables with: 31 * ESE_INCLUDE_HW(SOME_HAL_IMPL); 32 * 33 * Instantiate in a function with: 34 * ESE_DECLARE(my_ese, SOME_HAL_IMPL); 35 * or 36 * struct EseInterface my_ese = ESE_INITIALIZER(SOME_HAL_IMPL); 37 * or 38 * struct EseInterface *my_ese = malloc(sizeof(struct EseInterface)); 39 * ... 40 * ese_init(my_ese, SOME_HAL_IMPL); 41 * 42 * To initialize the hardware abstraction, call: 43 * ese_open(my_ese); 44 * 45 * To release any claimed resources, call 46 * ese_close(my_ese) 47 * when interface use is complete. 48 * 49 * To perform a transmit-receive cycle, call 50 * ese_transceive(my_ese, ...); 51 * with a filled transmit buffer with total data length and 52 * an empty receive buffer and a maximum fill length. 53 * 54 * A negative return value indicates an error and a hardware 55 * specific code and string may be collected with calls to 56 * ese_error_code(my_ese); 57 * ese_error_message(my_ese); 58 * 59 * The EseInterface is not safe for concurrent access. 60 * (Patches welcome ;). 61 */ 62 struct EseInterface; 63 #define ese_init(ese_ptr, HW_TYPE) __ese_init(ese_ptr, HW_TYPE) 64 #define ESE_DECLARE(name, HW_TYPE, ...) \ 65 struct EseInterface name = __ESE_INTIALIZER(HW_TYPE) 66 #define ESE_INITIALIZER __ESE_INITIALIZER 67 #define ESE_INCLUDE_HW __ESE_INCLUDE_HW 68 69 const char *ese_name(const struct EseInterface *ese); 70 int ese_open(struct EseInterface *ese, void *hw_opts); 71 void ese_close(struct EseInterface *ese); 72 int ese_transceive(struct EseInterface *ese, const uint8_t *tx_buf, uint32_t tx_len, uint8_t *rx_buf, uint32_t rx_max); 73 74 bool ese_error(const struct EseInterface *ese); 75 const char *ese_error_message(const struct EseInterface *ese); 76 int ese_error_code(const struct EseInterface *ese); 77 78 #ifdef __cplusplus 79 } /* extern "C" */ 80 #endif 81 82 #endif /* ESE_H_ */ 83