1 /** 2 * @file hi_sdio_device.h 3 * 4 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 * Description: sdio slave mode APIs. \n 18 * Create: 2019-01-17 19 */ 20 21 /** 22 * @defgroup iot_sdio SDIO Slave 23 * @ingroup drivers 24 */ 25 26 #ifndef __HI_SDIO_DEVICE_H__ 27 #define __HI_SDIO_DEVICE_H__ 28 29 #include <hi_types_base.h> 30 31 /** 32 * @ingroup iot_sdio 33 * 34 * SDIO definition.CNcomment:SDIO定义CNend 35 */ 36 #define CHAN_TX_BUSY 1 37 #define CHAN_TX_IDLE 0 38 #define CHAN_RX_BUSY 1 39 #define CHAN_RX_IDLE 0 40 41 #define HISDIO_EXTENDREG_COUNT 64 42 #define HISDIO_BLOCK_SIZE 512 43 44 /** 45 * @ingroup iot_sdio 46 * 47 * Device to Host sdio message type, The name can be modified according to product. 48 CNcomment:设备到主机的SDIO消息类型，类型名称可以根据产品实际应用场景更改。CNend 49 */ 50 typedef enum { 51 D2H_MSG_WLAN_READY = 0, 52 D2H_MSG_WOW_COMPLETE = 1, /**< wow complete. */ 53 D2H_MSG_FLOWCTRL_OFF = 2, /**< can't send data */ 54 D2H_MSG_FLOWCTRL_ON = 3, /**< can send data */ 55 D2H_MSG_WAKEUP_SUCC = 4, /**< wakeup done */ 56 D2H_MSG_ALLOW_SLEEP = 5, /**< allow sleep */ 57 D2H_MSG_DISALLOW_SLEEP = 6, /**< disalow sleep */ 58 D2H_MSG_DEVICE_PANIC = 7, /**< device panic */ 59 D2H_MSG_POWEROFF_ACK = 8, /**< poweroff cmd ack */ 60 D2H_MSG_CREDIT_UPDATE = 11, /**< update high priority buffer credit value */ 61 D2H_MSG_HIGH_PKT_LOSS = 12, /**< high pri pkts loss count */ 62 D2H_MSG_HEARTBEAT = 14, /**< send heartbeat */ 63 D2H_MSG_WOW_WIFI_REDAY = 15, /**< device ready for host sleep */ 64 D2H_MSG_COUNT = 32, /**< max support msg count */ 65 } hi_sdio_d2h_msg_type_e; 66 67 /** 68 * @ingroup iot_sdio 69 * 70 * Host to Device sdio message type, The name can be modified according to product. 71 CNcomment:主机到设备的SDIO消息类型，类型名称可以根据产品实际应用场景更改。CNend 72 */ 73 typedef enum { 74 H2D_MSG_FLOWCTRL_ON = 0, 75 H2D_MSG_DEVICE_INFO_DUMP = 1, 76 H2D_MSG_DEVICE_MEM_DUMP = 2, 77 H2D_MSG_TEST = 3, 78 H2D_MSG_PM_WLAN_OFF = 4, 79 H2D_MSG_SLEEP_REQ = 5, 80 H2D_MSG_PM_DEBUG = 6, 81 H2D_MSG_QUERY_RF_TEMP = 8, 82 H2D_MSG_HCC_SLAVE_THRUPUT_BYPASS = 9, 83 H2D_MSG_DEVICE_MEM_INFO = 10, 84 H2D_MSG_STOP_SDIO_TEST = 11, 85 H2D_MSG_FORCESLP_REQ = 13, 86 H2D_MSG_WOW_WIFI_SUSPEND = 14, 87 H2D_MSG_WOW_WIFI_RESUME = 15, 88 H2D_MSG_COUNT = 32, /**< max support msg value count */ 89 } hi_sdio_h2d_msg_type_e; 90 91 /** 92 * @ingroup iot_sdio 93 * 94 * max message value between Host and Device. 95 */ 96 typedef enum { 97 SDIO_DEVICE_MSG_WLAN_READY = 0, 98 SDIO_DEVICE_MSG_COUNT = 32, /**< max support msg count */ 99 SDIO_DEVICE_MSG_BUTT 100 } hi_sdio_msg_e; 101 102 /** 103 * @ingroup iot_sdio 104 * 105 * SDIO ADMA table. 106 */ 107 typedef struct { 108 hi_u16 param; 109 hi_u16 len; 110 uintptr_t address; 111 } hi_sdio_admatable; 112 113 /** 114 * @ingroup iot_sdio 115 * 116 * SDIO extend function structure. 117 */ 118 typedef struct { 119 hi_u32 int_stat; 120 hi_u32 msg_stat; 121 hi_u32 xfer_count; 122 hi_u32 credit_info; 123 hi_s8 credit_isvalid; 124 hi_u8 comm_reg[HISDIO_EXTENDREG_COUNT]; 125 hi_s8 commreg_isvalid; 126 hi_s32 valid_commreg_cnt; 127 } hi_sdio_extendfunc; 128 129 /** 130 * @ingroup iot_sdio 131 * 132 * use this callback to notify host msg event occurs. 133 */ 134 typedef hi_void (*notify_host_message_event)(hi_void); 135 136 /** 137 * @ingroup iot_sdio 138 * 139 * SDIO interrupt callback structure. 140 */ 141 typedef struct { 142 hi_s32 (*rdstart_callback)(hi_u32 len, hi_u8 *admatable); /**< Callback function for HOST reading. 143 CNcomment:DEV感知到HOST发起了读操作 CNend */ 144 hi_s32 (*rdover_callback)(hi_void); /**< Callback function for HOST reading over. 145 CNcomment:DEV感知到HOST读操作结束 CNend */ 146 hi_void (*rderr_callback)(hi_void); /**< Callback function for HOST read error. 147 CNcomment:DEV感知到HOST读数据错误 CNend */ 148 hi_s32 (*wrstart_callback)(hi_u32 len, hi_u8 *admatable); /**< Callback function for HOST writting. 149 CNcomment:DEV感知到HOST发起了写操作 CNend */ 150 hi_s32 (*wrover_callback)(hi_void); /**< Callback function for HOST write over. 151 CNcomment:DEV感知到HOST写操作结束 CNend */ 152 hi_void (*processmsg_callback)(hi_u32 msg); /**< Callback function for HOST getting message. 153 CNcomment:DEV接收到HOST发来的消息 CNend */ 154 hi_void (*soft_rst_callback)(hi_void); /**< Callback function for HOST getting reset 155 interruption.CNcomment:DEV接收到HOST发来的 156 软复位中断 CNend */ 157 } hi_sdio_intcallback; 158 159 /** 160 * @ingroup iot_sdio 161 * @brief sdio init function 162 * 163 * @par 描述: 164 * sdio initialization function.CNcomment:sdio 初始化函数。CNend 165 * 166 * @attention None 167 * @param None 168 * 169 * @retval #0 Success. 170 * @retval #Other Failure. For details, see hi_errno.h. 171 172 * @par 依赖: 173 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 174 * @see None。 175 */ 176 hi_u32 hi_sdio_init(hi_void); 177 178 /** 179 * @ingroup iot_sdio 180 * @brief sdio reinit function 181 * 182 * @par 描述: 183 * sdio Reinitialize the function.CNcomment:sdio 重新初始化函数。CNend 184 * 185 * @attention None 186 * @param None 187 * 188 * @retval #0 Success. 189 * @retval #Other Failure. For details, see hi_errno.h. 190 191 * @par 依赖: 192 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 193 * @see None。 194 */ 195 hi_u32 hi_sdio_reinit(hi_void); 196 197 /** 198 * @ingroup iot_sdio 199 * @brief sdio soft reset function 200 * 201 * @par 描述: 202 * sdio software reset function.CNcomment:sdio 软件复位函数。CNend 203 * 204 * @attention None 205 * @param None 206 * 207 * @retval None 208 * 209 * @par 依赖: 210 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 211 * @see None 212 */ 213 hi_void hi_sdio_soft_reset(hi_void); 214 215 /** 216 * @ingroup iot_sdio 217 * @brief sdio register interrupt callback function 218 * 219 * @par 描述: 220 * sdio register interrupt callback function.CNcomment:sdio 注册中断回调 函数。CNend 221 * 222 * @attention。 223 * @param callback_func [IN] type #const hi_sdio_intcallback，sdio callback function. 224 * 225 * @retval #0 Success. 226 * @retval #Other Failure. For details, see hi_errno.h. 227 228 * @par 依赖: 229 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 230 * @see None。 231 */ 232 hi_u32 hi_sdio_register_callback(const hi_sdio_intcallback *callback_func); 233 234 /** 235 * @ingroup iot_sdio 236 * @brief sdio complete send function 237 * 238 * @par 描述: 239 * sdio complete send function.CNcomment:sdio 结束发送接口函数。CNend 240 * 241 * @attention。 242 * @param admatable [IN] type #hi_u8 *, adma table first address. One channel occupies eight bytes. Ensure that the 243 * buffer space is sufficient to prevent memory overwriting. CNcomment:adma table首地址，一个通道占用8字节，使 244 * 用时请确保足够 245 的缓存空间，防止内存越界访问。CNend 246 * @param adma_index [IN] type hi_u32, adma_index adma Transmission channel number, range: [0-130].CNcomment:adma 247 * 传输通道号,范围[0-130]。CNend 248 * 249 * @retval #0 Success. 250 * @retval #Other Failure. For details, see hi_errno.h. 251 252 * @par 依赖: 253 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 254 * @see None。 255 */ 256 hi_u32 hi_sdio_complete_send(hi_u8 *admatable, hi_u32 adma_index); 257 258 /** 259 * @ingroup iot_sdio 260 * @brief set sdio pad adma table function 261 * 262 * @par 描述: 263 * set sdio pad adma table function.CNcomment:sdio 配置数据对齐后的ADMA表CNend 264 * 265 * @attention。 266 * @param padlen [IN] type #hi_u32, Length of data to be sent after data alignment. 267 CNcomment:数据对齐后要发送的数据长度。CNend 268 * @param admatable [IN] type #hi_u8 *, adma table first address. One channel occupies eight bytes. Ensure that the 269 * buffer space is sufficient to prevent memory overwriting. 270 CNcomment:adma table首地址，一个通道占用8字节，使用时请确保足够的缓存空间，防止内存越界访问。CNend 271 * @param adma_index [IN] type #hi_u32, adma Transmission channel number, range: [0-130]. 272 CNcomment:adma传输通道号,范围[0-130]。CNend 273 * 274 * @retval #0 Success. 275 * @retval #Other Failure. For details, see hi_errno.h. 276 277 * @par 依赖: 278 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 279 * @see None。 280 */ 281 hi_u32 hi_sdio_set_pad_admatab(hi_u32 padlen, hi_u8 *admatable, hi_u32 adma_index); 282 283 /** 284 * @ingroup iot_sdio 285 * @brief write extend information function 286 * 287 * @par 描述: 288 * write extend information function.CNcomment:写扩展信息接口CNend 289 * 290 * @attention。 291 * @param extfunc [IN] type #hi_sdio_extendfunc, Extended information pointer.CNcomment:扩展信息指针.CNend 292 * 293 * @retval #0 Success. 294 * @retval #Other Failure. For details, see hi_errno.h. 295 296 * @par 依赖: 297 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 298 * @see None。 299 */ 300 hi_u32 hi_sdio_write_extendinfo(hi_sdio_extendfunc *extfunc); 301 302 /** 303 * @ingroup iot_sdio 304 * @brief start to send data 305 * 306 * @par 描述: 307 * start to send data.CNcomment:启动数据发送接口CNend 308 * 309 * @attention。 310 * @param xfer_bytes [IN] type #hi_u32, Length of sent data.CNcomment:发送数据长度.CNend 311 * 312 * @retval #0 Success. 313 * @retval #Other Failure. For details, see hi_errno.h. 314 315 * @par 依赖: 316 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 317 * @see None。 318 */ 319 hi_void hi_sdio_send_data(hi_u32 xfer_bytes); 320 321 /** 322 * @ingroup iot_sdio 323 * @brief set adma table 324 * 325 * @par 描述: 326 * set adma table.CNcomment:设置adma传输通道CNend 327 * 328 * @attention。 329 * @param admatable [IN] type #hi_u8*, adma table first address. One channel occupies eight bytes. Ensure that the 330 * buffer space is sufficient to prevent memory overwriting. CNcomment:adma table首地址，一个通道占用8字节，使 331 用时请确保足够的缓存空间，防止内存越界访问。CNend 332 * @param adma_index [IN] type #hi_u32, adma Transmission channel number, range: [0-130].CNcomment:adma传输通道号, 333 范围[0-130]。CNend 334 * @param data_addr [IN] type #const hi_u32 *, dama transmission destination address.CNcomment:dama 传输目的地址CNend 335 * @param data_len [IN] type #hi_u32, adma Transmission data length.CNcomment:adma 传输数据长度CNend 336 * 337 * @retval #0 Success. 338 * @retval #Other Failure. For details, see hi_errno.h. 339 340 * @par 依赖: 341 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 342 * @see None。 343 */ 344 hi_u32 hi_sdio_set_admatable(hi_u8 *admatable, hi_u32 adma_index, const hi_u32 *data_addr, hi_u32 data_len); 345 346 /** 347 * @ingroup iot_sdio 348 * @brief schedule sdio pending message. 349 * 350 * @par 描述: 351 * schedule sdio message.CNcomment:将挂起的sdio消息发送出去CNend 352 * 353 * @attention。 354 * @param None 355 * 356 * @retval #true if there is no pending msg or send pending msg success, retun true. 357 CNcomment:如果没有挂起的消息，或者将挂起的消息发送成功，返回true.CNend 358 * @retval #false if sdio not in work status or there is msg sending, return false. 359 CNcomment:如果sdio不在工作状态，或者sdio正在发送消息，返回false.CNend 360 * 361 * @par 依赖: 362 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 363 * @see None。 364 */ 365 hi_bool hi_sdio_sched_msg(hi_void); 366 367 /** 368 * @ingroup iot_sdio 369 * @brief sync send message. 370 * 371 * @par 描述: 372 * put msg in pending msg and send.CNcomment:将消息加入消息队列并发送CNend 373 * 374 * @attention。 375 * @param msg [IN] type #hi_u32, The message, range [0-31].CNcomment:给定消息，范围[0-31].CNend 376 * 377 * @retval #true Success. 378 * @retval #false Failure. 379 * 380 * @par 依赖: 381 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 382 * @see None。 383 */ 384 hi_bool hi_sdio_send_sync_msg(hi_u32 msg); 385 386 /** 387 * @ingroup iot_sdio 388 * @brief send given message ack 389 * 390 * @par 描述: 391 * Sending a Specified Signal Message.CNcomment:发送指定消息CNend 392 * 393 * @attention: 394 the current sending msg will be overwrite by this msg. 395 CNcomment: 当前正在发送的消息将该消息覆盖?CNend 396 * @param msg [IN] type #hi_u32, The message, range [0-31].CNcomment:给定消息，范围[0-31].CNend 397 * 398 * @retval #true Success. 399 * @retval #false Failure. 400 * 401 * @par 依赖: 402 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 403 * @see None。 404 */ 405 hi_bool hi_sdio_send_msg_ack(hi_u32 msg); 406 407 /** 408 * @ingroup iot_sdio 409 * @brief Clear given msg and add new msg to pending msg and send. 410 * 411 * @par 描述: 412 * Clear given msg and add new msg in pending msg and send. 413 CNcomment:清除消息队列中挂起的指定消息，将新消息加入消息队列并发送CNend 414 * @attention。 415 * @param send_msg [IN] type #hi_u32, Message in range [0~31] which will be sent. 416 CNcomment:指定发送的消息号，范围[0-31]CNend 417 * @param clear_msg [IN] type #hi_u32, Message in range [0~31] which will be cleard. 418 CNcomment:指定清除的消息号，范围[0-31]CNend 419 * 420 * @retval #true Success. 421 * @retval #false Failure. 422 * 423 * @par 依赖: 424 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 425 * @see None。 426 */ 427 hi_bool hi_sdio_process_message(hi_u32 send_msg, hi_u32 clear_msg); 428 429 /** 430 * @ingroup iot_sdio 431 * @brief sdio is pending given message 432 * 433 * @par 描述: 434 * sdio is pending given message.CNcomment:判断sdio是否挂起指定的消息CNend 435 * 436 * @attention。 437 * @param msg [IN] type #hi_u32, The message, range [0-31].CNcomment:给定消息，范围[0-31].CNend 438 * 439 * @retval #true message at pending status.CNcomment:指定消息处于挂起状态CNend 440 * @retval #false message at other status. CNcomment:指定消息不处于挂起状态CNend 441 * 442 * @par 依赖: 443 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 444 * @see None。 445 */ 446 hi_u32 hi_sdio_is_pending_message(hi_u32 msg); 447 448 /** 449 * @ingroup iot_sdio 450 * @brief Check whether the sdio is sending a specified message. 451 * 452 * @par 描述: 453 * Check whether the sdio is sending a specified message.CNcomment:判断sdio是否正在发送指定的消息CNend 454 * 455 * @attention。 456 * @param msg [IN] type #hi_u32, The message, range [0-31].CNcomment:给定消息，范围[0-31].CNend 457 * 458 * @retval #true The message at sending status.CNcomment:指定消息处于发送状态CNend 459 * @retval #false The message at other status.CNcomment:指定消息不处于发送状态CNend 460 * 461 * @par 依赖: 462 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 463 * @see None。 464 */ 465 hi_u32 hi_sdio_is_sending_message(hi_u32 msg); 466 467 /** 468 * @ingroup iot_sdio 469 * @brief get sdio extend configuration. 470 * 471 * @par 描述: 472 * get sdio extend configuration.CNcomment:获取扩展区配置信息CNend 473 * 474 * @attention None 475 * @param None 476 * 477 * @retval hi_sdio_extendfunc* pointer to extend info buffer. 478 * 479 * @par 依赖: 480 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 481 * @see None。 482 */ 483 hi_sdio_extendfunc *hi_sdio_get_extend_info(hi_void); 484 485 /** 486 * @ingroup iot_sdio 487 * @brief register callback to notify host msg or data event occurs. 488 * 489 * @par 描述: 490 * register callback to notify host msg or data event occurs. 491 CNcomment:注册通知Host发送了消息或数据的回调函数。CNend 492 * 493 * @attention None 494 * @param msg_event_callback [IN] type #notify_host_message_event, notify_host_message_event callback function when 495 * sending msg or data. 496 CNcomment:消息或数据发送时调用的回调函数CNend 497 * 498 * @retval None 499 * 500 * @par 依赖: 501 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 502 * @see None。 503 */ 504 hi_void hi_sdio_register_notify_message_callback(notify_host_message_event msg_event_callback); 505 506 /** 507 * @ingroup iot_sdio 508 * @brief set sdio powerdown or not when system enter deep_sleep. 509 * 510 * @par 描述: 511 * set sdio powerdown or not when system enter deep_sleep. 512 CNcomment:设置系统深睡模式下，SDIO模块是否掉电。CNend 513 * 514 * @attention default powerdown.CNcomment:默认掉电.CNend 515 * @param power_down [IN] type #hi_bool, powerdown or not.CNcomment:是否掉电.CNend 516 * 517 * @retval None 518 * 519 * @par 依赖: 520 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 521 * @see None。 522 */ 523 hi_void hi_sdio_set_powerdown_when_deep_sleep(hi_bool power_down); 524 525 /** 526 * @ingroup iot_sdio 527 * @brief Init sdio but not wait host clock ready and not wait func1 enable interrupt. 528 * 529 * @par 描述: 530 * Init sdio but not wait host clock ready and not wait func1 enable interrupt. 531 CNcomment:初始化SDIO，初始化过程中不判断host时钟是否就绪， 532 不判断是否接收到了使能function1的中断。CNend 533 * 534 * @attention None 535 * @param None 536 * 537 * @retval None 538 * 539 * @par 依赖: 540 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 541 * @see None。 542 */ 543 hi_void hi_sdio_init_no_wait(hi_void); 544 545 /** 546 * @ingroup iot_sdio 547 * @brief Get whether host clock ready. 548 * 549 * @par 描述: 550 * Get whether host clock ready. 551 CNcomment:判断HOST时钟是否就绪。CNend 552 * 553 * @attention None 554 * @param None 555 * 556 * @retval None 557 * 558 * @par 依赖: 559 * @li hi_sdio_device.h：Describe sdio slave APIs.CNcomment:该接口声明所在的头文件。CNend 560 * @see None。 561 */ 562 hi_bool hi_sdio_host_clk_ready(hi_void); 563 564 #endif /* end of hi_sdio_device.h */ 565