1 //***************************************************************************** 2 // 3 //! @file am_hal_dsi.h 4 //! 5 //! @brief Hardware abstraction for the Display Serial Interface 6 //! 7 //! @addtogroup dsi_4p DSI - Display Serial Interface 8 //! @ingroup apollo4p_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2023, Ambiq Micro, Inc. 16 // All rights reserved. 17 // 18 // Redistribution and use in source and binary forms, with or without 19 // modification, are permitted provided that the following conditions are met: 20 // 21 // 1. Redistributions of source code must retain the above copyright notice, 22 // this list of conditions and the following disclaimer. 23 // 24 // 2. Redistributions in binary form must reproduce the above copyright 25 // notice, this list of conditions and the following disclaimer in the 26 // documentation and/or other materials provided with the distribution. 27 // 28 // 3. Neither the name of the copyright holder nor the names of its 29 // contributors may be used to endorse or promote products derived from this 30 // software without specific prior written permission. 31 // 32 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 33 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 34 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 35 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 36 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 37 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 38 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 39 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 40 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 41 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 42 // POSSIBILITY OF SUCH DAMAGE. 43 // 44 // This is part of revision stable-7da8bae71f of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 48 #ifndef AM_HAL_DSI_H 49 #define AM_HAL_DSI_H 50 51 #ifdef __cplusplus 52 extern "C" 53 { 54 #endif 55 56 //***************************************************************************** 57 // 58 // DSI error codes. 59 // 60 //***************************************************************************** 61 /*typedef enum 62 { 63 AM_HAL_DSI_INT_STATUS_RX_START_TRANS_ERROR = AM_HAL_STATUS_MODULE_SPECIFIC_START, 64 AM_HAL_DSI_INT_STATUS_RX_START_TRANS_SYNC_ERROR, 65 AM_HAL_DSI_INT_STATUS_RX_END_TRANS_SYNC_ERROR, 66 AM_HAL_DSI_INT_STATUS_RX_ESCAPE_ENTRY_ERROR, 67 AM_HAL_DSI_INT_STATUS_RX_LP_TX_SYNC_ERROR, 68 AM_HAL_DSI_INT_STATUS_RX_PERIPH_TIMEOUT_ERROR, 69 AM_HAL_DSI_INT_STATUS_RX_FALSE_CONTROL_ERROR, 70 AM_HAL_DSI_INT_STATUS_RX_ECC_SINGLE_BIT_ERROR, 71 AM_HAL_DSI_INT_STATUS_RX_ECC_MULTI_BIT_ERROR, 72 AM_HAL_DSI_INT_STATUS_START_TRANS_SYNC_ERROR, 73 74 } 75 am_hal_dsi_interrupt_status_t;*/ 76 77 //***************************************************************************** 78 // 79 //! DSI clock lane frequency. 80 // 81 //***************************************************************************** 82 typedef enum 83 { 84 AM_HAL_DSI_FREQ_TRIM_X1 = 0x40, 85 AM_HAL_DSI_FREQ_TRIM_X2 = 0x01, 86 AM_HAL_DSI_FREQ_TRIM_X3 = 0x41, 87 AM_HAL_DSI_FREQ_TRIM_X4 = 0x02, 88 AM_HAL_DSI_FREQ_TRIM_X5 = 0x42, 89 AM_HAL_DSI_FREQ_TRIM_X6 = 0x03, 90 AM_HAL_DSI_FREQ_TRIM_X7 = 0x43, 91 AM_HAL_DSI_FREQ_TRIM_X8 = 0x04, 92 AM_HAL_DSI_FREQ_TRIM_X9 = 0x44, 93 AM_HAL_DSI_FREQ_TRIM_X10 = 0x05, 94 AM_HAL_DSI_FREQ_TRIM_X11 = 0x45, 95 AM_HAL_DSI_FREQ_TRIM_X12 = 0x06, 96 AM_HAL_DSI_FREQ_TRIM_X13 = 0x46, 97 AM_HAL_DSI_FREQ_TRIM_X14 = 0x07, 98 AM_HAL_DSI_FREQ_TRIM_X15 = 0x47, 99 AM_HAL_DSI_FREQ_TRIM_X16 = 0x08, 100 AM_HAL_DSI_FREQ_TRIM_X17 = 0x48, 101 AM_HAL_DSI_FREQ_TRIM_X18 = 0x09, 102 AM_HAL_DSI_FREQ_TRIM_X19 = 0x49, 103 AM_HAL_DSI_FREQ_TRIM_X20 = 0x0A, 104 AM_HAL_DSI_FREQ_TRIM_X21 = 0x4A, 105 AM_HAL_DSI_FREQ_TRIM_X22 = 0x0B, 106 AM_HAL_DSI_FREQ_TRIM_X23 = 0x4B, 107 AM_HAL_DSI_FREQ_TRIM_X24 = 0x0C, 108 AM_HAL_DSI_FREQ_TRIM_X25 = 0x4C, 109 AM_HAL_DSI_FREQ_TRIM_X26 = 0x0D, 110 AM_HAL_DSI_FREQ_TRIM_X27 = 0x4D, 111 AM_HAL_DSI_FREQ_TRIM_X28 = 0x0E, 112 AM_HAL_DSI_FREQ_TRIM_X29 = 0x4E, 113 AM_HAL_DSI_FREQ_TRIM_X30 = 0x0F, 114 AM_HAL_DSI_FREQ_TRIM_X31 = 0x4F, 115 AM_HAL_DSI_FREQ_TRIM_X32 = 0x10, 116 AM_HAL_DSI_FREQ_TRIM_X33 = 0x50, 117 AM_HAL_DSI_FREQ_TRIM_X34 = 0x11, 118 AM_HAL_DSI_FREQ_TRIM_X35 = 0x51, 119 AM_HAL_DSI_FREQ_TRIM_X36 = 0x12, 120 AM_HAL_DSI_FREQ_TRIM_X37 = 0x52, 121 AM_HAL_DSI_FREQ_TRIM_X38 = 0x13, 122 AM_HAL_DSI_FREQ_TRIM_X39 = 0x53, 123 AM_HAL_DSI_FREQ_TRIM_X40 = 0x14, 124 AM_HAL_DSI_FREQ_TRIM_X41 = 0x54, 125 AM_HAL_DSI_FREQ_TRIM_X42 = 0x15, 126 AM_HAL_DSI_FREQ_TRIM_X43 = 0x55, 127 AM_HAL_DSI_FREQ_TRIM_X44 = 0x16, 128 AM_HAL_DSI_FREQ_TRIM_X45 = 0x56, 129 AM_HAL_DSI_FREQ_TRIM_X46 = 0x17, 130 AM_HAL_DSI_FREQ_TRIM_X47 = 0x57, 131 AM_HAL_DSI_FREQ_TRIM_X48 = 0x18, 132 AM_HAL_DSI_FREQ_TRIM_X49 = 0x58, 133 AM_HAL_DSI_FREQ_TRIM_X50 = 0x19, 134 AM_HAL_DSI_FREQ_TRIM_X51 = 0x59, 135 AM_HAL_DSI_FREQ_TRIM_X52 = 0x1A, 136 AM_HAL_DSI_FREQ_TRIM_X53 = 0x5A, 137 AM_HAL_DSI_FREQ_TRIM_X54 = 0x1B, 138 AM_HAL_DSI_FREQ_TRIM_X55 = 0x5B, 139 AM_HAL_DSI_FREQ_TRIM_X56 = 0x1C, 140 AM_HAL_DSI_FREQ_TRIM_X57 = 0x5C, 141 AM_HAL_DSI_FREQ_TRIM_X58 = 0x1D, 142 AM_HAL_DSI_FREQ_TRIM_X59 = 0x5D, 143 AM_HAL_DSI_FREQ_TRIM_X60 = 0x1E, 144 AM_HAL_DSI_FREQ_TRIM_X61 = 0x5E, 145 AM_HAL_DSI_FREQ_TRIM_X62 = 0x1F, 146 AM_HAL_DSI_FREQ_TRIM_X63 = 0x5F, 147 } am_hal_dsi_freq_trim_e; 148 149 //***************************************************************************** 150 // 151 //! DBI to DSI: DBI data width. 152 // 153 //***************************************************************************** 154 typedef enum 155 { 156 AM_HAL_DSI_DBI_WIDTH_8 = 8, 157 AM_HAL_DSI_DBI_WIDTH_16 = 16, 158 } am_hal_dsi_dbi_width_e; 159 160 //***************************************************************************** 161 // 162 //! DSI command type. 163 // 164 //***************************************************************************** 165 typedef enum 166 { 167 DCS_CMD = 0, 168 GE_CMD 169 } am_hal_dsi_cmd_type_e; 170 171 //***************************************************************************** 172 // 173 //! DSI high speed mode and low power mode. 174 // 175 //***************************************************************************** 176 typedef enum 177 { 178 LP_MODE = 0, 179 HS_MODE 180 } am_hal_dsi_speed_e; 181 182 //***************************************************************************** 183 // 184 //! @brief DSI external VDD18 power rail control callback function pointer type 185 //! 186 //! The BSP shall provide callback functions to control DSI external VDD18 power 187 //! rail. 188 // 189 //***************************************************************************** 190 typedef void (*am_hal_dsi_external_vdd18_callback)(bool bEnable); 191 192 //***************************************************************************** 193 // 194 // External functions. 195 // 196 //***************************************************************************** 197 //***************************************************************************** 198 // 199 //! @brief Register external VDD18 callback function 200 //! 201 //! @param cb is pointer of VDD18 control function. 202 //! 203 //! This function should be called before DSI init and deinit. 204 //! 205 //! @return AM_HAL_STATUS_SUCCESS 206 // 207 //***************************************************************************** 208 extern uint32_t am_hal_dsi_register_external_vdd18_callback(const am_hal_dsi_external_vdd18_callback cb); 209 210 //***************************************************************************** 211 // 212 //! @brief DSI configuration 213 //! 214 //! @param ui8LanesNum - Number of lanes. 215 //! @param ui8DBIBusWidth - Width of DBI bus. 216 //! @param ui32FreqTrim - DPHY output frequency trim. 217 //! @param bSendUlpsPattern - Unused parameter 218 //! 219 //! This function should be called after DSI power is enabled. 220 //! 221 //! @return AM_HAL_STATUS_SUCCESS 222 // 223 //***************************************************************************** 224 extern uint32_t am_hal_dsi_para_config(uint8_t ui8LanesNum, 225 uint8_t ui8DBIBusWidth, 226 uint32_t ui32FreqTrim, 227 bool bSendUlpsPattern); 228 229 //***************************************************************************** 230 // 231 //! @brief DSI initialization 232 //! 233 //! Configure power and clock of DSI. 234 //! 235 //! @return AM_HAL_STATUS_SUCCESS 236 // 237 //***************************************************************************** 238 extern uint32_t am_hal_dsi_init(void); 239 240 //***************************************************************************** 241 // 242 //! @brief DSI deinit 243 //! 244 //! Turn off power and clock of DSI. 245 //! 246 //! @return AM_HAL_STATUS_SUCCESS 247 // 248 //***************************************************************************** 249 extern uint32_t am_hal_dsi_deinit(void); 250 251 //***************************************************************************** 252 // 253 //! @brief DSI configuration 254 //! 255 //! @param ui32FreqTrim - DPHY output frequency trim. 256 //! 257 //! Configure DSI frequency and timing 258 //! 259 //! @return AM_HAL_STATUS_SUCCESS 260 // 261 //***************************************************************************** 262 extern uint32_t am_hal_dsi_timing(uint32_t ui32FreqTrim); 263 264 //***************************************************************************** 265 // 266 //! @brief DSI state 267 //! 268 //! ULPS mode entry 269 //! 270 //! @return AM_HAL_STATUS_SUCCESS 271 // 272 //***************************************************************************** 273 extern uint32_t am_hal_dsi_ulps_entry(void); 274 275 //***************************************************************************** 276 // 277 //! @brief DSI state 278 //! 279 //! ULPS mode exit 280 //! 281 //! @return AM_HAL_STATUS_SUCCESS 282 // 283 //***************************************************************************** 284 extern uint32_t am_hal_dsi_ulps_exit(void); 285 286 //***************************************************************************** 287 // 288 //! @brief DSI state 289 //! 290 //! @param bSendUlpsPattern - Unused paramter 291 //! 292 //! DSI napping 293 //! 294 //! @return AM_HAL_STATUS_SUCCESS 295 // 296 //***************************************************************************** 297 extern uint32_t am_hal_dsi_napping(bool bSendUlpsPattern); 298 299 //***************************************************************************** 300 // 301 //! @brief DSI state 302 //! 303 //! @param ui8LanesNum - Number of lanes. 304 //! @param ui8DBIBusWidth - Width of DBI bus. 305 //! @param ui32FreqTrim - DPHY output frequency trim. 306 //! @param bSendUlpsPattern - Unused parameter 307 //! 308 //! DSI wakeup 309 //! 310 //! @return AM_HAL_STATUS_SUCCESS 311 // 312 //***************************************************************************** 313 extern uint32_t am_hal_dsi_wakeup(uint8_t ui8LanesNum, uint8_t ui8DBIBusWidth, uint32_t ui32FreqTrim, bool bSendUlpsPattern); 314 315 //***************************************************************************** 316 // 317 //! @brief Set DSI return packet size (bytes) 318 //! 319 //! @param ui8DataLen - Return size(bytes). 320 //! @param bHS - Transmit Command in HS or LP mode 321 //! 322 //! DSI Transmits command to set maximum return size. 323 //! 324 //! @return AM_HAL_STATUS_SUCCESS 325 // 326 //***************************************************************************** 327 extern uint32_t am_hal_dsi_set_return_size(uint8_t ui8DataLen, bool bHS); 328 329 #ifdef __cplusplus 330 } 331 #endif 332 333 #endif // AM_HAL_DSI_H 334 335 //***************************************************************************** 336 // 337 // End Doxygen group. 338 //! @} 339 // 340 //***************************************************************************** 341 342
