Структуризировано: добавлены комменты и переименованы переменные

2024-08-12 18:09:00 +03:00
parent acaa14abdb
commit b8cb176c61
10 changed files with 640 additions and 689 deletions
--- a/spi_flash/spi_flash.h
+++ b/spi_flash/spi_flash.h
@@ -1,36 +1,9 @@
-/********************************W25 FLASH***********************************
-Данный файл содержит базовые функции для общения с SPI Flash.
-//-------------------Функции-------------------//
-@func users
-	- W25_FLASH_Read								Считывание FLASH
-	- W25_FLASH_Write_Area					Запись данных в заданный участок FLASH (с потерей данных в выбраном сектора за пределами этого участка)
-	- W25_FLASH_Erase_Sector				Очистка сектора FLASH
-	- W25_FLASH_Program_Area				Программирование FLASH
-	
-@func initialization
-	- W25_Base_Init									Инициализация SPI и GPIO для FLASH
-
-@func process interaction with flash
-	- W25_FLASH_Program_Page				Программирование страницы. *есть более общая функция W25_FLASH_Program_Area, которая программирует участки больше страницы
-	- W25_WriteEnablingUntilTimeout	Разрешение записи, пока не будет ответа или не истек таймаут
-	- W25_WaitOnFlagUntilTimeout		Ожидание флага пока не истек таймаута
-
-@func cmd functions
-	- W25_CMD_Read_Status_Register	Отправка комманд 	Read Status Register 1 / Read Status Register 1 (0x05h / 0x35h)
-	- W25_CMD_Write_Status_Register	Отправка комманды Write Status Register (0x01h)
-	- W25_CMD_Write_Enable					Отправка комманды Write Enable 					(0x06h)
-	- W25_CMD_Write_Disable					Отправка комманды Write Disable 				(0x04h)
-	- W25_CMD_Read_Data							Отправка комманды Read Data 						(0x03h)
-	- W25_CMD_Fast_Read							Отправка комманды Fast Read							(0x0Bh)
-	- W25_CMD_Page_Program					Отправка комманды Page Program					(0x02h)
-	- W25_CMD_Erase_Sector					Отправка комманды Erase Sector					(0x20h)
-	- W25_CMD_Read_JEDEC_ID					Отправка комманды Read JEDEC ID					(0x4Bh)
-	- W25_CMD_Read_Device_ID				Отправка комманды Read Manufacture / Device Id (0x90)
-	
-@func SPI functions
-	- W25_SPI_Transmit 							Функция отправки по SPI (содержит только HAL_SPI_Transmit)
-	- W25_SPI_Receive								Функция приема по SPI (содержит только HAL_SPI_Receive)
+/********************************W25 FLASH**********************************
+Данный файл содержит инклюды и дефайны для общения с памятью FLASH по SPI.
 ***************************************************************************/
+#ifndef __SPI_FLASH_H_
+#define __SPI_FLASH_H_
+
 #include "stm32f4xx_hal.h"
 #include "gpio_general.h"

@@ -45,10 +18,12 @@
 /////////////////////////////////////////////////////////////////////
 ////////////////////////////---DEFINES---////////////////////////////
 /**  
-	* @brief 	Defines for CMD.
+	* @brief 	Defines for W25 chip.
 	*/
-#define 		W25_CS_Set(_hw25_) 		(_hw25_->GPIOs.CS_GPIOx->BSRR = _hw25_->GPIOs.CS_PIN << 16)
-#define 		W25_CS_Reset(_hw25_) 	(_hw25_->GPIOs.CS_GPIOx->BSRR = _hw25_->GPIOs.CS_PIN)
+#define 		W25_Select(_hw25_) 		(_hw25_->GPIOs.CS_GPIOx->BSRR = _hw25_->GPIOs.CS_PIN << 16)
+#define 		W25_Deselect(_hw25_) 	(_hw25_->GPIOs.CS_GPIOx->BSRR = _hw25_->GPIOs.CS_PIN)
+#define 		W25_SECTOR_SIZE					(0x1000)
+#define 		W25_PAGE_SIZE						(0x100)
 /**  
 	* @brief 	Defines for CMD.
 	*/
@@ -79,17 +54,13 @@
 #define 		W25_SR_BP0							(1<<2)
 #define 		W25_SR_WEL							(1<<1)
 #define 		W25_SR_BUSY							(1<<0)
-/**  
-	* @brief 	Defines for W25 chip.
-	*/
-#define 		W25_SECTOR_SIZE					(0x1000)
-#define 		W25_PAGE_SIZE						(0x100)
+
 /**
 	* @brief	Calc dividing including remainder (divide and ceil)
 	*	@param 	_val_		- делимое.
 	*	@param 	_div_		- делитель.
 	*	@note 	Если результат деления без остатка: он возвращается как есть
-						Если с остатком - округляется вверх
+	*					Если с остатком - округляется вверх
 	*/
 //#define Divide_Up(_val_, _div_)												(((_val_)%(_div_))? (_val_)/(_div_)+1 : (_val_)/_div_)	/* через тернарный оператор */
 #define Divide_Up(_val_, _div_)												((_val_ - 1) / _div_) + 1																	/* через мат выражение */	
@@ -107,7 +78,7 @@ typedef struct
 	
 	uint32_t 	Sector_Address;
 	uint32_t 	Sector_Size;
-}W25_reProgramInitTypeDef;
+}W25_WriteInitTypeDef;

 typedef struct
 {
@@ -134,7 +105,11 @@ extern W25_HandleTypeDef hw25;
 ///////////////////////---STRUCTURES & ENUMS---//////////////////////

 /////////////////////////////////////////////////////////////////////
-///////////////////////////---FUNCTIONS---///////////////////////////
+///////////////////////---FUNCTIONS FOR USER---//////////////////////
+/**  
+	* @brief 	Initialize SPI and GPIO for W25 FLASH.
+	* @param 	hw25 - указатель на структуру с настройками SPI и GPIO портов.
+	*/
 void W25_Base_Init(W25_HandleTypeDef *hw25);

 /** 
@@ -152,18 +127,20 @@ HAL_StatusTypeDef W25_FLASH_Read(W25_HandleTypeDef *hw25, uint32_t FLASH_Address
 /** 
 	* @brief 	Write data to area in FLASH.
 	* @param 	hw25 					- указатель на хендл flash.
-	* @param 	reProgramInit - указатель на структуру, определяющую участок памяти для записи.
+	* @param 	WriteInit 		- указатель на структуру, определяющую участок памяти для записи.
 	* @param 	Timeout	 			- время, за которое должно быть осуществлено чтение.
 	* @return HAL status.
 	* @note		Позволяет перепрограммировать участок памяти. Можно записывать несколько страниц.
 	*					Данные в сектора участка, но за пределами участка не сохраняются.
 	*/
-HAL_StatusTypeDef W25_FLASH_Write_Area(W25_HandleTypeDef *hw25, W25_reProgramInitTypeDef *reProgramInit, uint32_t Timeout);
+HAL_StatusTypeDef W25_FLASH_Write_Area(W25_HandleTypeDef *hw25, W25_WriteInitTypeDef *WriteInit, uint32_t Timeout);

 /** 
 	* @brief 	Program area in FLASH.
 	* @param 	hw25 					- указатель на хендл flash.
-	* @param 	reProgramInit - указатель на структуру, определяющую участок памяти для записи.
+	* @param 	FLASH_Address - адресс куда начинать записывать.
+	* @param 	pData	 				- откуда брать данные для записи в FLASH.
+	* @param 	Size	 				- сколько байтов записать.
 	* @param 	Timeout	 			- время, за которое должно быть осуществлено чтение.
 	* @return HAL status.
 	* @note		Позволяет перепрограммировать участок памяти. Можно записывать несколько страниц.
@@ -174,19 +151,52 @@ HAL_StatusTypeDef W25_FLASH_Program_Area(W25_HandleTypeDef *hw25, uint32_t FLASH
 /** 
 	* @brief 	Erase FLASH Sector.
 	* @param 	hw25 					- указатель на хендл flash.
-	* @param 	reProgramInit - указатель на структуру, определяющую участок памяти для записи.
-	* @param 	Timeout	 			- время, за которое должно быть осуществлено чтение.
+	* @param 	FLASH_Address - адресс где надо данные стереть.
+	* @param 	Timeout	 			- время, за которое должно быть осуществлена очистка.
 	* @return HAL status.
-	* @note		Позволяет перепрограммировать участок памяти. Можно записывать несколько страниц.
-	*					Данные в сектора участка, но за пределами участка не сохраняются.
+	* @note		При Timeout = 0, функция не будет ожидать окончания очистки (выставления в 0 флагов BUSY и WEL)
+	* @note		Микросхема вроде сама высчитывает какой сектор ерейзнуть, в соответствии с заданным адресом.
 	*/
 HAL_StatusTypeDef W25_FLASH_Erase_Sector(W25_HandleTypeDef *hw25, uint32_t FLASH_Address, uint32_t Timeout);

-
+/** 
+	* @brief 	Program page in FLASH.
+	* @param 	hw25 					- указатель на хендл flash.
+	* @param 	FLASH_Address - адресс куда начинать записывать.
+	* @param 	pData	 				- откуда брать данные для записи в FLASH.
+	* @param 	Size	 				- сколько байтов записать.
+	* @param 	Timeout	 			- время, за которое должно быть осуществлено чтение.
+	* @param 	tickstart	 		- время, относительно которого надо отсчитывать таймаут.
+	* @return HAL status.
+	* @note		Позволяет перепрограммировать только байты в прелелах одной страницы.
+						Для более гибкого программирования есть функция W25_FLASH_Program_Area, которая программирует участки любой длины (в теории).
+	*/
 HAL_StatusTypeDef W25_FLASH_Program_Page(W25_HandleTypeDef *hw25, uint32_t FLASH_Address, uint8_t *pData, uint16_t Size, uint32_t Timeout, uint32_t tickstart);
+/** 
+	* @brief 	Setting WEL bit until it setted or until timeout.
+	* @param 	hw25 					- указатель на хендл flash.
+	* @param 	Timeout	 			- время, за которое должно быть осуществлено чтение.
+	* @param 	tickstart	 		- время, относительно которого надо отсчитывать таймаут.
+	* @return HAL status.
+	* @note		Подает команду на разрешение записи до тех пор, пока она запись не разрешиться или до тех пор, пока таймаут не истечет.
+	*/
 HAL_StatusTypeDef W25_WriteEnablingUntilTimeout(W25_HandleTypeDef *hw25, uint32_t Timeout, uint32_t tickstart);
-HAL_StatusTypeDef W25_WaitOnFlagUntilTimeout(W25_HandleTypeDef *hw25, uint16_t FlagMask, uint16_t FlagStatus, uint32_t Timeout, uint32_t tickstart);

+/** 
+	* @brief 	Wait for flag until timeout.
+	* @param 	hw25 					- указатель на хендл flash.
+	* @param 	FlagMask	 		- маска для флагов, какие флаги считывать.
+	* @param 	FlagStatus	 	- какое состояние должно быть у выбранных флагов.
+	* @param 	Timeout	 			- время, за которое должно быть осуществлено чтение.
+	* @param 	tickstart	 		- время, относительно которого надо отсчитывать таймаут.
+	* @return HAL status.
+	* @note		Считывает флаги до тех пор, пока они не будут в состоянии FlagStatus или до тех пор, пока таймаут не истечет.
+	*/
+HAL_StatusTypeDef W25_WaitOnFlagUntilTimeout(W25_HandleTypeDef *hw25, uint16_t FlagMask, uint16_t FlagStatus, uint32_t Timeout, uint32_t tickstart);
+///////////////////////---FUNCTIONS FOR USER---//////////////////////
+
+/////////////////////////////////////////////////////////////////////
+//////////////////////---FUNCTION FOR COMMAND---/////////////////////
 /** 
 	* @brief 	Send command to read Status Register.
 	* @param 	hw25 					- указатель на хендл flash.
@@ -236,9 +246,9 @@ void W25_CMD_Fast_Read(W25_HandleTypeDef *hw25, uint32_t FLASH_Address, uint8_t
 /** 
 	* @brief 	Send command to fast page program.
 	* @param 	hw25 					- указатель на хендл flash.
-	* @param 	FLASH_Address - адресс откуда начинать считывание.
+	* @param 	FLASH_Address - адресс куда начинать записывать.
 	* @param 	pData	 				- откуда брать данные для записи в FLASH.
-	* @param 	Size	 				- сколько байтов считывать.
+	* @param 	Size	 				- сколько байтов записать.
 	* @note		Программирование FLASH только в пределах одной страницы. 
 	*					Т.е. если запись с 0x0, то не больше 256 байт. Если с 0ч40, то не больше 192 байт.
 	*/
@@ -265,7 +275,10 @@ uint32_t W25_CMD_Read_JEDEC_ID(W25_HandleTypeDef *hw25);
 	* @return	Device ID микросхемы.
 	*/
 uint64_t W25_CMD_Read_Device_ID(W25_HandleTypeDef *hw25);
+//////////////////////---FUNCTION FOR COMMAND---/////////////////////

+/////////////////////////////////////////////////////////////////////
+//////////////////////---FUNCTION FOR PERIPTH---/////////////////////
 /** 
 	* @brief 	SPI Transmit.
 	* @param 	hw25 - указатель на хендл flash.
@@ -286,5 +299,6 @@ void W25_SPI_Transmit (W25_HandleTypeDef *hw25, uint8_t *data, uint16_t size);
 	*/
 void W25_SPI_Receive (W25_HandleTypeDef *hw25, uint8_t *data, uint16_t size);

-///////////////////////////---FUNCTIONS---///////////////////////////
+//////////////////////---FUNCTION FOR PERIPTH---/////////////////////

+#endif // __SPI_FLASH_H_