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 /* 18 * Implementation Notes: 19 * Each platform must supply a platform-specific platform_link.h to provide the 20 * definitions and a platform-specific link.c to provide the implementation for 21 * the definitions in this file. 22 * The platform must also initialize the ChppPlatformLinkParameters for each 23 * link (context.linkParams). 24 */ 25 26 #ifndef CHPP_LINK_H_ 27 #define CHPP_LINK_H_ 28 29 #include <stddef.h> 30 #include <stdint.h> 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 /** 37 * Error codes used by the link layer. 38 */ 39 enum ChppLinkErrorCode { 40 //! No error - data queued to be sent asynchronously 41 CHPP_LINK_ERROR_NONE_QUEUED = 0, 42 43 //! No error - data successfully sent 44 CHPP_LINK_ERROR_NONE_SENT = 1, 45 46 //! Timeout 47 CHPP_LINK_ERROR_TIMEOUT = 2, 48 49 //! Busy 50 CHPP_LINK_ERROR_BUSY = 3, 51 52 //! Out of memory 53 CHPP_LINK_ERROR_OOM = 4, 54 55 //! Link not established 56 CHPP_LINK_ERROR_NO_LINK = 5, 57 58 //! Unspecified failure 59 CHPP_LINK_ERROR_UNSPECIFIED = 255 60 }; 61 62 /* 63 * Platform-specific struct with link details / parameters. 64 */ 65 struct ChppPlatformLinkParameters; 66 67 /** 68 * Platform-specific function to initialize the link layer. 69 * 70 * @param params Platform-specific struct with link details / parameters. 71 */ 72 void chppPlatformLinkInit(struct ChppPlatformLinkParameters *params); 73 74 /** 75 * Platform-specific function to deinitialize the link layer (e.g. clean exit). 76 * 77 * @param params Platform-specific struct with link details / parameters. 78 */ 79 void chppPlatformLinkDeinit(struct ChppPlatformLinkParameters *params); 80 81 /* 82 * Platform-specific function to send Tx data over to the link layer. 83 * 84 * @param params Platform-specific struct with link details / parameters. 85 * @param buf Data to be sent. 86 * @param len Length of the data to be sent in bytes. 87 * 88 * @return CHPP_LINK_ERROR_NONE_SENT if the platform implementation for this 89 * function is synchronous, i.e. it is done with buf and len once the function 90 * returns. A return value of CHPP_LINK_ERROR_NONE_QUEUED indicates that this 91 * function is implemented asynchronously. In this case, it is up to the 92 * platform implementation to call chppLinkSendDoneCb() after processing the 93 * contents of buf and len. Otherwise, an error code is returned per enum 94 * ChppLinkErrorCode. 95 */ 96 enum ChppLinkErrorCode chppPlatformLinkSend( 97 struct ChppPlatformLinkParameters *params, uint8_t *buf, size_t len); 98 99 /** 100 * Platform-specific function to perform a task from the main CHPP transport 101 * work thread. The task can be specified by the signal argument, which is 102 * triggered by previous call[s] to chppWorkThreadSignalFromLink(). An example 103 * of the type of work that can be performed is processing RX data from the 104 * physical layer. 105 * 106 * @param params Platform-specific struct with link details / parameters. 107 * @param signal The signal that describes the work to be performed. Only bits 108 * specified by CHPP_TRANSPORT_SIGNAL_PLATFORM_MASK can be set. 109 */ 110 void chppPlatformLinkDoWork(struct ChppPlatformLinkParameters *params, 111 uint32_t signal); 112 113 /* 114 * Platform-specific function to reset a non-synchronous link, where the link 115 * implementation is responsible for calling chppLinkSendDoneCb() after 116 * processing the contents of buf and len. For such links, a reset called before 117 * chppLinkSendDoneCb() indicates to the link to abort sending out buf, and that 118 * the contents of buf and len will become invalid. 119 * 120 * @param params Platform-specific struct with link details / parameters. 121 */ 122 void chppPlatformLinkReset(struct ChppPlatformLinkParameters *params); 123 124 #ifdef __cplusplus 125 } 126 #endif 127 128 #include "chpp/platform/platform_link.h" 129 130 #endif // CHPP_LINK_H_ 131