1 /* 2 * Copyright (C) 2020 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 CHPP_LINK_H_ 18 #define CHPP_LINK_H_ 19 20 #include <stddef.h> 21 #include <stdint.h> 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 /** 28 * Error codes used by the link layer. 29 */ 30 enum ChppLinkErrorCode { 31 //! No error - data queued to be sent asynchronously 32 CHPP_LINK_ERROR_NONE_QUEUED = 0, 33 34 //! No error - data successfully sent 35 CHPP_LINK_ERROR_NONE_SENT = 1, 36 37 //! Timeout 38 CHPP_LINK_ERROR_TIMEOUT = 2, 39 40 //! Busy 41 CHPP_LINK_ERROR_BUSY = 3, 42 43 //! Out of memory 44 CHPP_LINK_ERROR_OOM = 4, 45 46 //! Link not established 47 CHPP_LINK_ERROR_NO_LINK = 5, 48 49 //! Unspecified failure 50 CHPP_LINK_ERROR_UNSPECIFIED = 255 51 }; 52 53 struct ChppTransportState; 54 55 /** 56 * Link layer configuration. 57 */ 58 struct ChppLinkConfiguration { 59 /** 60 * Size of the TX buffer in bytes. 61 * The TX buffer is provided by the link layer (@see getTxBuffer). 62 * 63 * The TX buffer stores the effective payload and the transport encoding 64 * overhead. The size of the effective payload is txBufferLen - 65 * CHPP_TRANSPORT_ENCODING_OVERHEAD_BYTES. 66 */ 67 size_t txBufferLen; 68 /** 69 * Size of the RX buffer in bytes. 70 * 71 * The RX buffer stores the effective payload and the transport encoding 72 * overhead. The size of the effective payload is rxBufferLen - 73 * CHPP_TRANSPORT_ENCODING_OVERHEAD_BYTES. 74 */ 75 size_t rxBufferLen; 76 }; 77 78 struct ChppLinkApi { 79 /** 80 * Platform-specific function to initialize the link layer. 81 * 82 * @param linkContext Platform-specific struct with link state. 83 * @param transportContext State of the associated transport layer. 84 * 85 * The init function typically: 86 * - stores the transportContext in the link state. It is needed when calling 87 * the transport layer callbacks, 88 * - initializes anything required for the link layer operations. 89 * 90 * It can also store the configuration in the link state when the 91 * configuration differs across link instances. 92 */ 93 void (*init)(void *linkContext, struct ChppTransportState *transportContext); 94 95 /** 96 * Platform-specific function to deinitialize the link layer (e.g. clean 97 * exit). 98 * 99 * @param linkContext Platform-specific struct with link details / parameters. 100 */ 101 void (*deinit)(void *linkContext); 102 103 /** 104 * Platform-specific function to send Tx data over to the link layer. 105 * 106 * The TX data is located in the Tx buffer, @see getTxBuffer. 107 * 108 * @param linkContext Platform-specific struct with link details / parameters. 109 * @param len Length of the data to be sent in bytes. 110 * 111 * @return CHPP_LINK_ERROR_NONE_SENT if the platform implementation for this 112 * function is synchronous, i.e. it is done with buf and len once the function 113 * returns. A return value of CHPP_LINK_ERROR_NONE_QUEUED indicates that this 114 * function is implemented asynchronously. In this case, it is up to the 115 * platform implementation to call chppLinkSendDoneCb() after processing the 116 * contents TX buffer. Otherwise, an error code is returned per enum 117 * ChppLinkErrorCode. 118 */ 119 enum ChppLinkErrorCode (*send)(void *linkContext, size_t len); 120 121 /** 122 * Platform-specific function to perform a task from the main CHPP transport 123 * work thread. The task can be specified by the signal argument, which is 124 * triggered by previous call[s] to chppWorkThreadSignalFromLink(). An example 125 * of the type of work that can be performed is processing RX data from the 126 * physical layer. 127 * 128 * @param linkContext Platform-specific struct with link details / parameters. 129 * @param signal The signal that describes the work to be performed. Only bits 130 * specified by CHPP_TRANSPORT_SIGNAL_PLATFORM_MASK can be set. 131 */ 132 void (*doWork)(void *linkContext, uint32_t signal); 133 134 /** 135 * Platform-specific function to reset a non-synchronous link, where the link 136 * implementation is responsible for calling chppLinkSendDoneCb() after 137 * processing the contents of buf and len. For such links, a reset called 138 * before chppLinkSendDoneCb() indicates to the link to abort sending out buf, 139 * and that the contents of buf and len will become invalid. 140 * 141 * @param linkContext Platform-specific struct with link details / parameters. 142 */ 143 void (*reset)(void *linkContext); 144 145 /** 146 * Returns the link layer configuration. 147 * 148 * @param linkContext Platform-specific struct with link details / parameters. 149 */ 150 struct ChppLinkConfiguration (*getConfig)(void *linkContext); 151 152 /** 153 * Returns a pointer to the TX buffer. 154 * 155 * The associated transport layer will write control bytes and payload to this 156 * buffer. 157 * 158 * The size of the buffer must be returned in the configuration. 159 * @see getConfig. 160 * 161 * @param linkContext Platform-specific struct with link details / parameters. 162 */ 163 uint8_t *(*getTxBuffer)(void *linkContext); 164 }; 165 166 #ifdef __cplusplus 167 } 168 #endif 169 170 #endif // CHPP_LINK_H_ 171