1 /* 2 * Copyright (c) Meta Platforms, Inc. and affiliates. 3 * All rights reserved. 4 * 5 * This source code is licensed under the BSD-style license found in the 6 * LICENSE file in the root directory of this source tree. 7 */ 8 9 /** 10 * @file 11 * Platform abstraction layer to allow individual platform libraries to override 12 * symbols in ExecuTorch. PAL functions are defined as C functions so a platform 13 * library implementer can use C in lieu of C++. 14 */ 15 16 #pragma once 17 18 // Use C-style includes so that C code can include this header. 19 #include <stddef.h> 20 #include <stdint.h> 21 22 #include <executorch/runtime/platform/compiler.h> 23 #include <executorch/runtime/platform/types.h> 24 25 /** 26 * Clients should neither define nor use this macro. Used to optionally declare 27 * the et_pal_*() functions as weak symbols. 28 * 29 * This provides a way to both: 30 * - Include the header and define weak symbols (used by the internal default 31 * implementations) 32 * - Include the header and define strong symbols (used by client overrides) 33 */ 34 #ifndef ET_INTERNAL_PLATFORM_WEAKNESS 35 #define ET_INTERNAL_PLATFORM_WEAKNESS 36 #endif 37 38 extern "C" { 39 40 /** 41 * Represents the conversion ratio from system ticks to nanoseconds. 42 * To convert, use nanoseconds = ticks * numerator / denominator. 43 */ 44 typedef struct { 45 uint64_t numerator; 46 uint64_t denominator; 47 } et_tick_ratio_t; 48 49 /** 50 * Initialize the platform abstraction layer. 51 * 52 * This function should be called before any other function provided by the PAL 53 * to initialize any global state. Typically overridden by PAL implementer. 54 */ 55 void et_pal_init(void) ET_INTERNAL_PLATFORM_WEAKNESS; 56 57 /** 58 * Immediately abort execution, setting the device into an error state, if 59 * available. 60 */ 61 ET_NORETURN void et_pal_abort(void) ET_INTERNAL_PLATFORM_WEAKNESS; 62 63 /** 64 * Return a monotonically non-decreasing timestamp in system ticks. 65 * 66 * @retval Timestamp value in system ticks. 67 */ 68 et_timestamp_t et_pal_current_ticks(void) ET_INTERNAL_PLATFORM_WEAKNESS; 69 70 /** 71 * Return the conversion rate from system ticks to nanoseconds as a fraction. 72 * To convert a system ticks to nanoseconds, multiply the tick count by the 73 * numerator and then divide by the denominator: 74 * nanoseconds = ticks * numerator / denominator 75 * 76 * The utility method executorch::runtime::ticks_to_ns(et_timestamp_t) can also 77 * be used to perform the conversion for a given tick count. It is defined in 78 * torch/executor/runtime/platform/clock.h. 79 * 80 * @retval The ratio of nanoseconds to system ticks. 81 */ 82 et_tick_ratio_t et_pal_ticks_to_ns_multiplier(void) 83 ET_INTERNAL_PLATFORM_WEAKNESS; 84 85 /** 86 * Severity level of a log message. Values must map to printable 7-bit ASCII 87 * uppercase letters. 88 */ 89 typedef enum { 90 kDebug = 'D', 91 kInfo = 'I', 92 kError = 'E', 93 kFatal = 'F', 94 kUnknown = '?', // Exception to the "uppercase letter" rule. 95 } et_pal_log_level_t; 96 97 /** 98 * Emit a log message via platform output (serial port, console, etc). 99 * 100 * @param[in] timestamp Timestamp of the log event in system ticks since boot. 101 * @param[in] level Severity level of the message. Must be a printable 7-bit 102 * ASCII uppercase letter. 103 * @param[in] filename Name of the file that created the log event. 104 * @param[in] function Name of the function that created the log event. 105 * @param[in] line Line in the source file where the log event was created. 106 * @param[in] message Message string to log. 107 * @param[in] length Message string length. 108 */ 109 void et_pal_emit_log_message( 110 et_timestamp_t timestamp, 111 et_pal_log_level_t level, 112 const char* filename, 113 const char* function, 114 size_t line, 115 const char* message, 116 size_t length) ET_INTERNAL_PLATFORM_WEAKNESS; 117 118 /** 119 * NOTE: Core runtime code must not call this directly. It may only be called by 120 * a MemoryAllocator wrapper. 121 * 122 * Allocates size bytes of memory. 123 * 124 * @param[in] size Number of bytes to allocate. 125 * @returns the allocated memory, or nullptr on failure. Must be freed using 126 * et_pal_free(). 127 */ 128 void* et_pal_allocate(size_t size) ET_INTERNAL_PLATFORM_WEAKNESS; 129 130 /** 131 * Frees memory allocated by et_pal_allocate(). 132 * 133 * @param[in] ptr Pointer to memory to free. May be nullptr. 134 */ 135 void et_pal_free(void* ptr) ET_INTERNAL_PLATFORM_WEAKNESS; 136 137 } // extern "C" 138