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