Merge pull request #10558 from iNavFlight/MrD_Correct-comments-on-OSD-symbols
[inav.git] / lib / main / STM32F7 / Drivers / STM32F7xx_HAL_Driver / Src / stm32f7xx_hal_mdios.c
blob33a2991817e5abb1ac4834b96dd7c06b81c392e6
1 /**
2 ******************************************************************************
3 * @file stm32f7xx_hal_mdios.c
4 * @author MCD Application Team
5 * @version V1.2.2
6 * @date 14-April-2017
7 * @brief MDIOS HAL module driver.
8 * This file provides firmware functions to manage the following
9 * functionalities of the MDIOS Peripheral.
10 * + Initialization and de-initialization functions
11 * + IO operation functions
12 * + Peripheral Control functions
14 @verbatim
15 ===============================================================================
16 ##### How to use this driver #####
17 ===============================================================================
18 [..]
19 The MDIOS HAL driver can be used as follows:
21 (#) Declare a MDIOS_HandleTypeDef handle structure.
23 (#) Initialize the MDIOS low level resources by implementing the HAL_MDIOS_MspInit() API:
24 (##) Enable the MDIOS interface clock.
25 (##) MDIOS pins configuration:
26 (+++) Enable clocks for the MDIOS GPIOs.
27 (+++) Configure the MDIOS pins as alternate function.
28 (##) NVIC configuration if you need to use interrupt process:
29 (+++) Configure the MDIOS interrupt priority.
30 (+++) Enable the NVIC MDIOS IRQ handle.
32 (#) Program the Port Address and the Preamble Check in the Init structure.
34 (#) Initialize the MDIOS registers by calling the HAL_MDIOS_Init() API.
36 (#) Perform direct slave read/write operations using the following APIs:
37 (##) Read the value of a DINn register: HAL_MDIOS_ReadReg()
38 (##) Write a value to a DOUTn register: HAL_MDIOS_WriteReg()
40 (#) Get the Master read/write operations flags using the following APIs:
41 (##) Bit map of DOUTn registers read by Master: HAL_MDIOS_GetReadRegAddress()
42 (##) Bit map of DINn registers written by Master : HAL_MDIOS_GetWrittenRegAddress()
44 (#) Clear the read/write flags using the following APIs:
45 (##) Clear read flags of a set of registers: HAL_MDIOS_ClearReadRegAddress()
46 (##) Clear write flags of a set of registers: HAL_MDIOS_ClearWriteRegAddress()
48 (#) Enable interrupts on events using HAL_MDIOS_EnableEvents(), when called
49 the MDIOS will generate an interrupt in the following cases:
50 (##) a DINn register written by the Master
51 (##) a DOUTn register read by the Master
52 (##) an error occur
54 -@@- A callback is executed for each genereted interrupt, so the driver provides the following
55 HAL_MDIOS_WriteCpltCallback(), HAL_MDIOS_ReadCpltCallback() and HAL_MDIOS_ErrorCallback()
56 -@@- HAL_MDIOS_IRQHandler() must be called from the MDIOS IRQ Handler, to handle the interrupt
57 and execute the previous callbacks
59 (#) Reset the MDIOS peripheral and all related ressources by calling the HAL_MDIOS_DeInit() API.
60 (##) HAL_MDIOS_MspDeInit() must be implemented to reset low level ressources
61 (GPIO, Clocks, NVIC configuration ...)
64 @endverbatim
65 ******************************************************************************
66 * @attention
68 * <h2><center>&copy; COPYRIGHT(c) 2017 STMicroelectronics</center></h2>
70 * Redistribution and use in source and binary forms, with or without modification,
71 * are permitted provided that the following conditions are met:
72 * 1. Redistributions of source code must retain the above copyright notice,
73 * this list of conditions and the following disclaimer.
74 * 2. Redistributions in binary form must reproduce the above copyright notice,
75 * this list of conditions and the following disclaimer in the documentation
76 * and/or other materials provided with the distribution.
77 * 3. Neither the name of STMicroelectronics nor the names of its contributors
78 * may be used to endorse or promote products derived from this software
79 * without specific prior written permission.
81 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
82 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
83 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
84 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
85 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
86 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
87 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
88 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
89 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
90 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
92 ******************************************************************************
95 /* Includes ------------------------------------------------------------------*/
96 #include "stm32f7xx_hal.h"
98 /** @addtogroup STM32F7xx_HAL_Driver
99 * @{
102 /** @defgroup MDIOS MDIOS
103 * @brief HAL MDIOS module driver
104 * @{
106 #ifdef HAL_MDIOS_MODULE_ENABLED
108 #if defined (MDIOS)
110 /* Private typedef -----------------------------------------------------------*/
111 /* Private define ------------------------------------------------------------*/
112 #define MDIOS_PORT_ADDRESS_SHIFT ((uint32_t)8)
113 #define MDIOS_ALL_REG_FLAG ((uint32_t)0xFFFFFFFFU)
114 #define MDIOS_ALL_ERRORS_FLAG ((uint32_t)(MDIOS_SR_PERF | MDIOS_SR_SERF | MDIOS_SR_TERF))
116 #define MDIOS_DIN_BASE_ADDR (MDIOS_BASE + 0x100)
117 #define MDIOS_DOUT_BASE_ADDR (MDIOS_BASE + 0x180)
119 /* Private macro -------------------------------------------------------------*/
120 /* Private variables ---------------------------------------------------------*/
121 /* Private function prototypes -----------------------------------------------*/
122 /* Private functions ---------------------------------------------------------*/
123 /* Exported functions --------------------------------------------------------*/
124 /** @defgroup MDIOS_Exported_Functions MDIOS Exported Functions
125 * @{
128 /** @defgroup MDIOS_Exported_Functions_Group1 Initialization/de-initialization functions
129 * @brief Initialization and Configuration functions
131 @verbatim
132 ===============================================================================
133 ##### Initialization and Configuration functions #####
134 ===============================================================================
135 [..]
136 This subsection provides a set of functions allowing to initialize the MDIOS
137 (+) The following parameters can be configured:
138 (++) Port Address
139 (++) Preamble Check
141 @endverbatim
142 * @{
146 * @brief Initializes the MDIOS according to the specified parameters in
147 * the MDIOS_InitTypeDef and creates the associated handle .
148 * @param hmdios: pointer to a MDIOS_HandleTypeDef structure that contains
149 * the configuration information for MDIOS module
150 * @retval HAL status
152 HAL_StatusTypeDef HAL_MDIOS_Init(MDIOS_HandleTypeDef *hmdios)
154 uint32_t tmpcr = 0;
156 /* Check the MDIOS handle allocation */
157 if(hmdios == NULL)
159 return HAL_ERROR;
162 /* Check the parameters */
163 assert_param(IS_MDIOS_ALL_INSTANCE(hmdios->Instance));
164 assert_param(IS_MDIOS_PORTADDRESS(hmdios->Init.PortAddress));
165 assert_param(IS_MDIOS_PREAMBLECHECK(hmdios->Init.PreambleCheck));
167 /* Process Locked */
168 __HAL_LOCK(hmdios);
170 if(hmdios->State == HAL_MDIOS_STATE_RESET)
172 /* Init the low level hardware */
173 HAL_MDIOS_MspInit(hmdios);
176 /* Change the MDIOS state */
177 hmdios->State = HAL_MDIOS_STATE_BUSY;
179 /* Get the MDIOS CR value */
180 tmpcr = hmdios->Instance->CR;
182 /* Clear PORT_ADDRESS, DPC and EN bits */
183 tmpcr &= ((uint32_t)~(MDIOS_CR_EN | MDIOS_CR_DPC | MDIOS_CR_PORT_ADDRESS));
185 /* Set MDIOS control parametrs and enable the peripheral */
186 tmpcr |= (uint32_t)(((hmdios->Init.PortAddress) << MDIOS_PORT_ADDRESS_SHIFT) |\
187 (hmdios->Init.PreambleCheck) | \
188 (MDIOS_CR_EN));
190 /* Write the MDIOS CR */
191 hmdios->Instance->CR = tmpcr;
193 /* Change the MDIOS state */
194 hmdios->State = HAL_MDIOS_STATE_READY;
196 /* Release Lock */
197 __HAL_UNLOCK(hmdios);
199 /* Return function status */
200 return HAL_OK;
205 * @brief DeInitializes the MDIOS peripheral.
206 * @param hmdios: MDIOS handle
207 * @retval HAL status
209 HAL_StatusTypeDef HAL_MDIOS_DeInit(MDIOS_HandleTypeDef *hmdios)
211 /* Check the MDIOS handle allocation */
212 if(hmdios == NULL)
214 return HAL_ERROR;
217 /* Check the parameters */
218 assert_param(IS_MDIOS_ALL_INSTANCE(hmdios->Instance));
220 /* Change the MDIOS state */
221 hmdios->State = HAL_MDIOS_STATE_BUSY;
223 /* Disable the Peripheral */
224 __HAL_MDIOS_DISABLE(hmdios);
226 /* DeInit the low level hardware */
227 HAL_MDIOS_MspDeInit(hmdios);
229 /* Change the MDIOS state */
230 hmdios->State = HAL_MDIOS_STATE_RESET;
232 /* Release Lock */
233 __HAL_UNLOCK(hmdios);
235 /* Return function status */
236 return HAL_OK;
240 * @brief MDIOS MSP Init
241 * @param hmdios: mdios handle
242 * @retval None
244 __weak void HAL_MDIOS_MspInit(MDIOS_HandleTypeDef *hmdios)
246 /* Prevent unused argument(s) compilation warning */
247 UNUSED(hmdios);
249 /* NOTE : This function should not be modified, when the callback is needed,
250 the HAL_MDIOS_MspInit can be implemented in the user file
255 * @brief MDIOS MSP DeInit
256 * @param hmdios: mdios handle
257 * @retval None
259 __weak void HAL_MDIOS_MspDeInit(MDIOS_HandleTypeDef *hmdios)
261 /* Prevent unused argument(s) compilation warning */
262 UNUSED(hmdios);
264 /* NOTE : This function should not be modified, when the callback is needed,
265 the HAL_MDIOS_MspDeInit can be implemented in the user file
269 * @}
272 /** @defgroup MDIOS_Exported_Functions_Group2 IO operation functions
273 * @brief MDIOS Read/Write functions
275 @verbatim
276 ===============================================================================
277 ##### IO operation functions #####
278 ===============================================================================
279 This subsection provides a set of functions allowing to manage the MDIOS
280 read and write operations.
282 (#) APIs that allow to the MDIOS to read/write from/to the
283 values of one of the DINn/DOUTn registers:
284 (+) Read the value of a DINn register: HAL_MDIOS_ReadReg()
285 (+) Write a value to a DOUTn register: HAL_MDIOS_WriteReg()
287 (#) APIs that provide if there are some Slave registres have been
288 read or written by the Master:
289 (+) DOUTn registers read by Master: HAL_MDIOS_GetReadRegAddress()
290 (+) DINn registers written by Master : HAL_MDIOS_GetWrittenRegAddress()
292 (#) APIs that Clear the read/write flags:
293 (+) Clear read registers flags: HAL_MDIOS_ClearReadRegAddress()
294 (+) Clear write registers flags: HAL_MDIOS_ClearWriteRegAddress()
296 (#) A set of Callbacks are provided:
297 (+) HAL_MDIOS_WriteCpltCallback()
298 (+) HAL_MDIOS_ReadCpltCallback()
299 (+) HAL_MDIOS_ErrorCallback()
301 @endverbatim
302 * @{
306 * @brief Writes to an MDIOS output register
307 * @param hmdios: mdios handle
308 * @param RegNum: MDIOS input register number
309 * @param Data: Data to write
310 * @retval HAL status
312 HAL_StatusTypeDef HAL_MDIOS_WriteReg(MDIOS_HandleTypeDef *hmdios, uint32_t RegNum, uint16_t Data)
314 uint32_t tmpreg;
316 /* Check the parameters */
317 assert_param(IS_MDIOS_REGISTER(RegNum));
319 /* Process Locked */
320 __HAL_LOCK(hmdios);
322 /* Get the addr of output register to be written by the MDIOS */
323 tmpreg = MDIOS_DOUT_BASE_ADDR + (4 * RegNum);
325 /* Write to DOUTn register */
326 *((uint32_t *)tmpreg) = Data;
328 /* Process Unlocked */
329 __HAL_UNLOCK(hmdios);
331 return HAL_OK;
335 * @brief Reads an MDIOS input register
336 * @param hmdios: mdios handle
337 * @param RegNum: MDIOS input register number
338 * @param pData: pointer to Data
339 * @retval HAL status
341 HAL_StatusTypeDef HAL_MDIOS_ReadReg(MDIOS_HandleTypeDef *hmdios, uint32_t RegNum, uint16_t *pData)
343 uint32_t tmpreg;
345 /* Check the parameters */
346 assert_param(IS_MDIOS_REGISTER(RegNum));
348 /* Process Locked */
349 __HAL_LOCK(hmdios);
351 /* Get the addr of input register to be read by the MDIOS */
352 tmpreg = MDIOS_DIN_BASE_ADDR + (4 * RegNum);
354 /* Read DINn register */
355 *pData = (uint16_t)(*((uint32_t *)tmpreg));
357 /* Process Unlocked */
358 __HAL_UNLOCK(hmdios);
360 return HAL_OK;
364 * @brief Gets Written registers by MDIO master
365 * @param hmdios: mdios handle
366 * @retval bit map of written registers addresses
368 uint32_t HAL_MDIOS_GetWrittenRegAddress(MDIOS_HandleTypeDef *hmdios)
370 return hmdios->Instance->WRFR;
374 * @brief Gets Read registers by MDIO master
375 * @param hmdios: mdios handle
376 * @retval bit map of read registers addresses
378 uint32_t HAL_MDIOS_GetReadRegAddress(MDIOS_HandleTypeDef *hmdios)
380 return hmdios->Instance->RDFR;
384 * @brief Clears Write registers flag
385 * @param hmdios: mdios handle
386 * @param RegNum: registers addresses to be cleared
387 * @retval HAL status
389 HAL_StatusTypeDef HAL_MDIOS_ClearWriteRegAddress(MDIOS_HandleTypeDef *hmdios, uint32_t RegNum)
391 /* Check the parameters */
392 assert_param(IS_MDIOS_REGISTER(RegNum));
394 /* Process Locked */
395 __HAL_LOCK(hmdios);
397 /* Clear write registers flags */
398 hmdios->Instance->CWRFR |= (RegNum);
400 /* Release Lock */
401 __HAL_UNLOCK(hmdios);
403 return HAL_OK;
407 * @brief Clears Read register flag
408 * @param hmdios: mdios handle
409 * @param RegNum: registers addresses to be cleared
410 * @retval HAL status
412 HAL_StatusTypeDef HAL_MDIOS_ClearReadRegAddress(MDIOS_HandleTypeDef *hmdios, uint32_t RegNum)
414 /* Check the parameters */
415 assert_param(IS_MDIOS_REGISTER(RegNum));
417 /* Process Locked */
418 __HAL_LOCK(hmdios);
420 /* Clear read registers flags */
421 hmdios->Instance->CRDFR |= (RegNum);
423 /* Release Lock */
424 __HAL_UNLOCK(hmdios);
426 return HAL_OK;
430 * @brief Enables Events for MDIOS peripheral
431 * @param hmdios: mdios handle
432 * @retval HAL status
434 HAL_StatusTypeDef HAL_MDIOS_EnableEvents(MDIOS_HandleTypeDef *hmdios)
436 /* Process Locked */
437 __HAL_LOCK(hmdios);
439 /* Enable MDIOS interrupts: Register Write, Register Read and Error ITs */
440 __HAL_MDIOS_ENABLE_IT(hmdios, (MDIOS_IT_WRITE | MDIOS_IT_READ | MDIOS_IT_ERROR));
442 /* Process Unlocked */
443 __HAL_UNLOCK(hmdios);
445 return HAL_OK;
449 * @brief This function handles MDIOS interrupt request.
450 * @param hmdios: MDIOS handle
451 * @retval None
453 void HAL_MDIOS_IRQHandler(MDIOS_HandleTypeDef *hmdios)
455 /* Write Register Interrupt enabled ? */
456 if(__HAL_MDIOS_GET_IT_SOURCE(hmdios, MDIOS_IT_WRITE) != RESET)
458 /* Write register flag */
459 if(HAL_MDIOS_GetWrittenRegAddress(hmdios) != RESET)
461 /* Write callback function */
462 HAL_MDIOS_WriteCpltCallback(hmdios);
464 /* Clear write register flag */
465 HAL_MDIOS_ClearWriteRegAddress(hmdios, MDIOS_ALL_REG_FLAG);
469 /* Read Register Interrupt enabled ? */
470 if(__HAL_MDIOS_GET_IT_SOURCE(hmdios, MDIOS_IT_READ) != RESET)
472 /* Read register flag */
473 if(HAL_MDIOS_GetReadRegAddress(hmdios) != RESET)
475 /* Read callback function */
476 HAL_MDIOS_ReadCpltCallback(hmdios);
478 /* Clear read register flag */
479 HAL_MDIOS_ClearReadRegAddress(hmdios, MDIOS_ALL_REG_FLAG);
483 /* Error Interrupt enabled ? */
484 if(__HAL_MDIOS_GET_IT_SOURCE(hmdios, MDIOS_IT_ERROR) != RESET)
486 /* All Errors Flag */
487 if(__HAL_MDIOS_GET_ERROR_FLAG(hmdios, MDIOS_ALL_ERRORS_FLAG) !=RESET)
489 /* Error Callback */
490 HAL_MDIOS_ErrorCallback(hmdios);
492 /* Clear errors flag */
493 __HAL_MDIOS_CLEAR_ERROR_FLAG(hmdios, MDIOS_ALL_ERRORS_FLAG);
497 /* check MDIOS WAKEUP exti flag */
498 if(__HAL_MDIOS_WAKEUP_EXTI_GET_FLAG() != RESET)
500 /* MDIOS WAKEUP interrupt user callback */
501 HAL_MDIOS_WakeUpCallback(hmdios);
503 /* Clear MDIOS WAKEUP Exti pending bit */
504 __HAL_MDIOS_WAKEUP_EXTI_CLEAR_FLAG();
509 * @brief Write Complete Callback
510 * @param hmdios: mdios handle
511 * @retval None
513 __weak void HAL_MDIOS_WriteCpltCallback(MDIOS_HandleTypeDef *hmdios)
515 /* Prevent unused argument(s) compilation warning */
516 UNUSED(hmdios);
518 /* NOTE : This function should not be modified, when the callback is needed,
519 the HAL_MDIOS_WriteCpltCallback can be implemented in the user file
524 * @brief Read Complete Callback
525 * @param hmdios: mdios handle
526 * @retval None
528 __weak void HAL_MDIOS_ReadCpltCallback(MDIOS_HandleTypeDef *hmdios)
530 /* Prevent unused argument(s) compilation warning */
531 UNUSED(hmdios);
533 /* NOTE : This function should not be modified, when the callback is needed,
534 the HAL_MDIOS_ReadCpltCallback can be implemented in the user file
539 * @brief Error Callback
540 * @param hmdios: mdios handle
541 * @retval None
543 __weak void HAL_MDIOS_ErrorCallback(MDIOS_HandleTypeDef *hmdios)
545 /* Prevent unused argument(s) compilation warning */
546 UNUSED(hmdios);
548 /* NOTE : This function should not be modified, when the callback is needed,
549 the HAL_MDIOS_ErrorCallback can be implemented in the user file
554 * @brief MDIOS WAKEUP interrupt callback
555 * @param hmdios: mdios handle
556 * @retval None
558 __weak void HAL_MDIOS_WakeUpCallback(MDIOS_HandleTypeDef *hmdios)
560 /* Prevent unused argument(s) compilation warning */
561 UNUSED(hmdios);
563 /* NOTE : This function Should not be modified, when the callback is needed,
564 the HAL_MDIOS_WakeUpCallback could be implemented in the user file
569 * @}
572 /** @defgroup MDIOS_Exported_Functions_Group3 Peripheral Control functions
573 * @brief MDIOS control functions
575 @verbatim
576 ===============================================================================
577 ##### Peripheral Control functions #####
578 ===============================================================================
579 [..]
580 This subsection provides a set of functions allowing to control the MDIOS.
581 (+) HAL_MDIOS_GetState() API, helpful to check in run-time the state.
582 (+) HAL_MDIOS_GetError() API, returns the errors occured during data transfer.
584 @endverbatim
585 * @{
589 * @brief Gets MDIOS error flags
590 * @param hmdios: mdios handle
591 * @retval bit map of occured errors
593 uint32_t HAL_MDIOS_GetError(MDIOS_HandleTypeDef *hmdios)
595 /* return errors flags on status register */
596 return hmdios->Instance->SR;
600 * @brief Return the MDIOS HAL state
601 * @param hmdios: mdios handle
602 * @retval MDIOS state
604 HAL_MDIOS_StateTypeDef HAL_MDIOS_GetState(MDIOS_HandleTypeDef *hmdios)
606 /* Return MDIOS state */
607 return hmdios->State;
611 * @}
615 * @}
617 #endif /* MDIOS */
618 #endif /* HAL_MDIOS_MODULE_ENABLED */
620 * @}
624 * @}
627 /************************ (C) COPYRIGHT STMicroelectronics *****END OF FILE****/