### Complete SPIF Usage Example

Source: https://context7.com/nimaltd/spif/llms.txt

Demonstrates SPI FLASH initialization, erase, write, and read operations with error handling. Includes necessary includes and HAL initialization.

```c
#include "main.h"
#include "spi.h"
#include "spif.h"
#include <string.h>
#include <stdio.h>

SPIF_HandleTypeDef hspif;

void SPIF_Test(void)
{
    uint8_t writeBuffer[256];
    uint8_t readBuffer[256];

    /* Initialize SPI FLASH */
    if (SPIF_Init(&hspif, &hspi1, GPIOB, GPIO_PIN_6) == false)
    {
        printf("SPIF Init failed!\r\n");
        return;
    }

    printf("Flash detected: %ld blocks (%ld KB)\r\n",
           hspif.BlockCnt, (hspif.BlockCnt * 64));

    /* Prepare test data */
    for (int i = 0; i < 256; i++)
    {
        writeBuffer[i] = i;
    }

    /* Erase sector 0 */
    printf("Erasing sector 0...\r\n");
    if (SPIF_EraseSector(&hspif, 0) == false)
    {
        printf("Erase failed!\r\n");
        return;
    }

    /* Write data */
    printf("Writing 256 bytes to address 0x0000...\r\n");
    if (SPIF_WriteAddress(&hspif, 0x0000, writeBuffer, 256) == false)
    {
        printf("Write failed!\r\n");
        return;
    }

    /* Read back data */
    printf("Reading 256 bytes from address 0x0000...\r\n");
    memset(readBuffer, 0, sizeof(readBuffer));
    if (SPIF_ReadAddress(&hspif, 0x0000, readBuffer, 256) == false)
    {
        printf("Read failed!\r\n");
        return;
    }

    /* Verify data */
    if (memcmp(writeBuffer, readBuffer, 256) == 0)
    {
        printf("Data verification PASSED!\r\n");
    }
    else
    {
        printf("Data verification FAILED!\r\n");
    }
}

int main(void)
{
    HAL_Init();
    SystemClock_Config();
    MX_GPIO_Init();
    MX_SPI1_Init();
    MX_USART2_UART_Init();

    SPIF_Test();

    while (1) { }
}

```

--------------------------------

### SPIF_ReadAddress

Source: https://context7.com/nimaltd/spif/llms.txt

Reads a specified number of bytes starting from a memory address into a buffer.

```APIDOC
## SPIF_ReadAddress

### Description
Reads a specified number of bytes starting from a memory address into a buffer. This function can read across page, sector, and block boundaries seamlessly.

### Parameters
- **hspif** (SPIF_HandleTypeDef*) - Required - Pointer to the SPIF handle.
- **address** (uint32_t) - Required - The memory address to read from.
- **buffer** (uint8_t*) - Required - Pointer to the buffer to store read data.
- **size** (uint32_t) - Required - Number of bytes to read.

### Response
- **bool** - Returns true if the read operation was successful.
```

--------------------------------

### SPIF_Init - Initialize SPI FLASH

Source: https://context7.com/nimaltd/spif/llms.txt

Initializes the SPI FLASH handle, detects the connected chip via JEDEC ID, configures memory parameters, and prepares the interface for read/write operations. Requires a configured SPI peripheral and a GPIO pin for chip select.

```APIDOC
## SPIF_Init - Initialize SPI FLASH

### Description
Initializes the SPI FLASH handle by detecting the connected chip using JEDEC ID, configuring memory parameters (page count, sector count, block count), and preparing the interface for read/write operations. The function requires a configured SPI peripheral and a GPIO pin for chip select (active low).

### Method
`SPIF_Init`

### Parameters
- **hspif** (*SPIF_HandleTypeDef*)
- **SPI handle** (*SPI_HandleTypeDef*)
- **CS GPIO port** (*GPIO_TypeDef*)
- **CS pin** (uint16_t)

### Request Example
```c
#include "spif.h"

/* Define SPIF handle */
SPIF_HandleTypeDef hspif;

/* Initialize in main() after SPI and GPIO are configured via CubeMX */
int main(void)
{
    HAL_Init();
    SystemClock_Config();
    MX_GPIO_Init();
    MX_SPI1_Init();

    /* Initialize SPI FLASH: &hspif, SPI handle, CS GPIO port, CS pin */
    if (SPIF_Init(&hspif, &hspi1, GPIOB, GPIO_PIN_6) == true)
    {
        /* Success - chip detected and configured */
        /* Access chip info: hspif.Manufactor, hspif.Size, hspif.BlockCnt, etc. */
        printf("Flash initialized: %ld blocks, %ld sectors, %ld pages\r\n",
               hspif.BlockCnt, hspif.SectorCnt, hspif.PageCnt);
    }
    else
    {
        /* Failed - check wiring, SPI config, or chip compatibility */
        Error_Handler();
    }

    while (1) { }
}
```

### Response
- **bool**: `true` if initialization is successful, `false` otherwise.

### Response Example
```
Flash initialized: 1024 blocks, 16384 sectors, 65536 pages
```
```

--------------------------------

### Initialize SPI FLASH

Source: https://context7.com/nimaltd/spif/llms.txt

Initializes the SPI FLASH handle and detects the chip using JEDEC ID. Requires a configured SPI peripheral and a GPIO pin for chip select.

```c
#include "spif.h"

/* Define SPIF handle */
SPIF_HandleTypeDef hspif;

/* Initialize in main() after SPI and GPIO are configured via CubeMX */
int main(void)
{
    HAL_Init();
    SystemClock_Config();
    MX_GPIO_Init();
    MX_SPI1_Init();

    /* Initialize SPI FLASH: &hspif, SPI handle, CS GPIO port, CS pin */
    if (SPIF_Init(&hspif, &hspi1, GPIOB, GPIO_PIN_6) == true)
    {
        /* Success - chip detected and configured */
        /* Access chip info: hspif.Manufactor, hspif.Size, hspif.BlockCnt, etc. */
        printf("Flash initialized: %ld blocks, %ld sectors, %ld pages\r\n",
               hspif.BlockCnt, hspif.SectorCnt, hspif.PageCnt);
    }
    else
    {
        /* Failed - check wiring, SPI config, or chip compatibility */
        Error_Handler();
    }

    while (1) { }
}
```

--------------------------------

### SPIF Address Conversion Macros

Source: https://context7.com/nimaltd/spif/llms.txt

Utility macros for converting between addresses, pages, sectors, and blocks. Essential for calculating memory locations.

```c
/* Memory organization constants */
/* SPIF_PAGE_SIZE   = 0x100   (256 bytes) */
/* SPIF_SECTOR_SIZE = 0x1000  (4096 bytes, 16 pages) */
/* SPIF_BLOCK_SIZE  = 0x10000 (65536 bytes, 16 sectors, 256 pages) */

/* Convert between units */
uint32_t address = 0x12345;

uint32_t page = SPIF_AddressToPage(address);       /* Address -> Page number */
uint32_t sector = SPIF_AddressToSector(address);   /* Address -> Sector number */
uint32_t block = SPIF_AddressToBlock(address);     /* Address -> Block number */

/* Convert to address */
uint32_t pageAddr = SPIF_PageToAddress(100);       /* Page 100 -> Address 0x6400 */
uint32_t sectorAddr = SPIF_SectorToAddress(10);    /* Sector 10 -> Address 0xA000 */
uint32_t blockAddr = SPIF_BlockToAddress(2);       /* Block 2 -> Address 0x20000 */

/* Cross-unit conversions */
uint32_t sectorFromPage = SPIF_PageToSector(32);   /* Page 32 -> Sector 2 */
uint32_t blockFromSector = SPIF_SectorToBlock(48); /* Sector 48 -> Block 3 */
uint32_t pageFromBlock = SPIF_BlockToPage(1);      /* Block 1 -> Page 256 */

printf("Address 0x%lX is in page %ld, sector %ld, block %ld\r\n",
       address, page, sector, block);

```

--------------------------------

### Read Data from Block

Source: https://context7.com/nimaltd/spif/llms.txt

Reads data from a specific block with an optional offset. Useful for large contiguous data. Verify block number and buffer size.

```c
/* Read 8KB from block 0 */
uint8_t blockBuffer[8192];
uint32_t blockNumber = 0;

if (SPIF_ReadBlock(&hspif, blockNumber, blockBuffer, sizeof(blockBuffer), 0) == true)
{
    printf("Read 8KB from block %ld\r\n", blockNumber);
}

/* Read from middle of block */
uint8_t dataBuffer[4096];
uint32_t blockOffset = 32768;  /* 32KB into the block */

if (SPIF_ReadBlock(&hspif, blockNumber, dataBuffer, sizeof(dataBuffer), blockOffset) == true)
{
    printf("Read 4KB from block %ld at offset %ld\r\n", blockNumber, blockOffset);
}
```

--------------------------------

### Read Data from Sector

Source: https://context7.com/nimaltd/spif/llms.txt

Reads data from a specific sector with an optional offset. Ensure the sector number and buffer size are valid.

```c
/* Read 1KB from sector 5 */
uint8_t sectorBuffer[1024];
uint32_t sectorNumber = 5;

if (SPIF_ReadSector(&hspif, sectorNumber, sectorBuffer, sizeof(sectorBuffer), 0) == true)
{
    printf("Read 1KB from sector %ld\r\n", sectorNumber);
}

/* Read with offset */
uint8_t configBuffer[128];
uint32_t sectorOffset = 512;

if (SPIF_ReadSector(&hspif, sectorNumber, configBuffer, sizeof(configBuffer), sectorOffset) == true)
{
    printf("Config data read from sector %ld at offset %ld\r\n", sectorNumber, sectorOffset);
}
```

--------------------------------

### Write Data to SPI Flash Page

Source: https://context7.com/nimaltd/spif/llms.txt

Writes data to a specific page (256 bytes) with an optional offset. Data exceeding page boundaries is truncated. The page must be erased before writing.

```c
/* Write data to page 0 starting at offset 0 */
uint8_t pageData[128] = {0x01, 0x02, 0x03, 0x04};  /* First 4 bytes set, rest 0 */
uint32_t pageNumber = 0;

SPIF_EraseSector(&hspif, SPIF_PageToSector(pageNumber));

if (SPIF_WritePage(&hspif, pageNumber, pageData, 128, 0) == true)
{
    printf("128 bytes written to page %ld\r\n", pageNumber);
}
```

```c
/* Write data to page with offset */
uint8_t moreData[] = {0xAA, 0xBB, 0xCC, 0xDD};
uint32_t offset = 128;  /* Start at byte 128 of the page */

if (SPIF_WritePage(&hspif, pageNumber, moreData, sizeof(moreData), offset) == true)
{
    printf("4 bytes written to page %ld at offset %ld\r\n", pageNumber, offset);
}
```

--------------------------------

### Read Data from SPI Flash Page

Source: https://context7.com/nimaltd/spif/llms.txt

Reads data from a specific page with an optional offset. The maximum read size is limited to the remaining bytes in the page from the offset.

```c
/* Read entire page */
uint8_t pageBuffer[SPIF_PAGE_SIZE];  /* 256 bytes */
uint32_t pageNumber = 10;

if (SPIF_ReadPage(&hspif, pageNumber, pageBuffer, SPIF_PAGE_SIZE, 0) == true)
{
    printf("Page %ld contents read\r\n", pageNumber);
}
```

```c
/* Read partial page with offset */
uint8_t partialBuffer[64];
uint32_t offset = 100;

if (SPIF_ReadPage(&hspif, pageNumber, partialBuffer, sizeof(partialBuffer), offset) == true)
{
    printf("Read 64 bytes from page %ld starting at offset %ld\r\n", pageNumber, offset);
}
```

--------------------------------

### Write Data to SPI Flash Sector

Source: https://context7.com/nimaltd/spif/llms.txt

Writes data to a specific sector (4KB), handling internal page writes automatically. The sector must be erased before writing.

```c
/* Write 1KB of data to sector 2 */
uint8_t sectorData[1024];
memset(sectorData, 0x55, sizeof(sectorData));

uint32_t sectorNumber = 2;

SPIF_EraseSector(&hspif, sectorNumber);

if (SPIF_WriteSector(&hspif, sectorNumber, sectorData, sizeof(sectorData), 0) == true)
{
    printf("1KB written to sector %ld\r\n", sectorNumber);
}
```

```c
/* Write with offset within sector */
uint8_t configData[64] = {/* configuration bytes */};
uint32_t sectorOffset = 2048;  /* Start at 2KB into the sector */

if (SPIF_WriteSector(&hspif, sectorNumber, configData, sizeof(configData), sectorOffset) == true)
{
    printf("Config written at sector %ld offset %ld\r\n", sectorNumber, sectorOffset);
}
```

--------------------------------

### SPIF_WriteAddress

Source: https://context7.com/nimaltd/spif/llms.txt

Writes a byte array to a specified memory address, handling page boundary crossings automatically.

```APIDOC
## SPIF_WriteAddress

### Description
Writes a byte array to a specified memory address. This function automatically handles page boundary crossing when writing data larger than a single page (256 bytes). The target memory region must be erased (0xFF) before writing.

### Parameters
- **hspif** (SPIF_HandleTypeDef*) - Required - Pointer to the SPIF handle.
- **address** (uint32_t) - Required - The target memory address.
- **data** (uint8_t*) - Required - Pointer to the data buffer to write.
- **size** (uint32_t) - Required - Number of bytes to write.

### Response
- **bool** - Returns true if the write operation was successful.
```

--------------------------------

### SPIF_WritePage

Source: https://context7.com/nimaltd/spif/llms.txt

Writes data to a specific page (256 bytes) with an optional offset.

```APIDOC
## SPIF_WritePage

### Description
Writes data to a specific page (256 bytes). The page must be erased before writing. Optionally specify an offset within the page. Data exceeding page boundaries is truncated.

### Parameters
- **hspif** (SPIF_HandleTypeDef*) - Required - Pointer to the SPIF handle.
- **pageNumber** (uint32_t) - Required - The target page number.
- **data** (uint8_t*) - Required - Pointer to the data buffer.
- **size** (uint32_t) - Required - Number of bytes to write.
- **offset** (uint32_t) - Required - Offset within the page to start writing.

### Response
- **bool** - Returns true if the write operation was successful.
```

--------------------------------

### Write Data to SPI Flash Block

Source: https://context7.com/nimaltd/spif/llms.txt

Writes data to a specific block (64KB), handling internal page writes automatically. The block must be erased before writing.

```c
/* Write data to block 1 */
uint8_t blockData[4096];  /* 4KB of data */
memset(blockData, 0x77, sizeof(blockData));

uint32_t blockNumber = 1;

SPIF_EraseBlock(&hspif, blockNumber);

if (SPIF_WriteBlock(&hspif, blockNumber, blockData, sizeof(blockData), 0) == true)
{
    printf("4KB written to block %ld\r\n", blockNumber);
}
```

--------------------------------

### Erase Single Block

Source: https://context7.com/nimaltd/spif/llms.txt

Erases a single 64KB block, which is faster than erasing individual sectors for large memory regions.

```c
/* Erase block 0 (addresses 0x00000 - 0x0FFFF) */
uint32_t blockNumber = 0;

if (SPIF_EraseBlock(&hspif, blockNumber) == true)
{
    printf("Block %ld erased (64KB cleared)\r\n", blockNumber);
}

/* Erase block containing a specific address */
uint32_t targetAddress = 0x25000;
uint32_t targetBlock = SPIF_AddressToBlock(targetAddress);  /* = 2 */

if (SPIF_EraseBlock(&hspif, targetBlock) == true)
{
    printf("Block %ld erased\r\n", targetBlock);
}
```

--------------------------------

### SPIF_EraseBlock - Erase Single Block

Source: https://context7.com/nimaltd/spif/llms.txt

Erases a single 64KB block, which contains 16 sectors. Block erase is faster than erasing individual sectors for large memory regions.

```APIDOC
## SPIF_EraseBlock - Erase Single Block

### Description
Erases a single 64KB block (0x10000 bytes). Blocks contain 16 sectors each. Block erase is faster than erasing individual sectors when clearing large memory regions.

### Method
`SPIF_EraseBlock`

### Parameters
- **hspif** (*SPIF_HandleTypeDef*)
- **blockNumber** (uint32_t) - The number of the block to erase.

### Request Example
```c
/* Erase block 0 (addresses 0x00000 - 0x0FFFF) */
uint32_t blockNumber = 0;

if (SPIF_EraseBlock(&hspif, blockNumber) == true)
{
    printf("Block %ld erased (64KB cleared)\r\n", blockNumber);
}

/* Erase block containing a specific address */
uint32_t targetAddress = 0x25000;
uint32_t targetBlock = SPIF_AddressToBlock(targetAddress);  /* = 2 */

if (SPIF_EraseBlock(&hspif, targetBlock) == true)
{
    printf("Block %ld erased\r\n", targetBlock);
}
```

### Response
- **bool**: `true` if the block erase is successful, `false` otherwise.

### Response Example
```
Block 0 erased (64KB cleared)
Block 2 erased
```
```

--------------------------------

### Write Data to SPI Flash Address

Source: https://context7.com/nimaltd/spif/llms.txt

Writes a byte array to a specified memory address. Handles page boundary crossing. Ensure the target memory region is erased before writing.

```c
/* Write string data to address 0x1000 */
uint8_t writeData[] = "Hello SPI FLASH!";
uint32_t address = 0x1000;

/* Erase the sector first */
SPIF_EraseSector(&hspif, SPIF_AddressToSector(address));

/* Write data */
if (SPIF_WriteAddress(&hspif, address, writeData, sizeof(writeData)) == true)
{
    printf("Data written to address 0x%lX\r\n", address);
}
```

```c
/* Write large data spanning multiple pages */
uint8_t largeData[512];  /* Spans 2 pages */
memset(largeData, 0xAA, sizeof(largeData));

SPIF_EraseSector(&hspif, 0);  /* Erase sector 0 */

if (SPIF_WriteAddress(&hspif, 0x0000, largeData, sizeof(largeData)) == true)
{
    printf("512 bytes written across page boundaries\r\n");
}
```

--------------------------------

### Erase Single Sector

Source: https://context7.com/nimaltd/spif/llms.txt

Erases a single 4KB sector. Sectors must be erased before writing new data.

```c
/* Erase sector 0 (addresses 0x0000 - 0x0FFF) */
uint32_t sectorNumber = 0;

if (SPIF_EraseSector(&hspif, sectorNumber) == true)
{
    printf("Sector %ld erased successfully\r\n", sectorNumber);
}

/* Erase sector containing a specific address */
uint32_t targetAddress = 0x5000;
uint32_t targetSector = SPIF_AddressToSector(targetAddress);  /* = 5 */

if (SPIF_EraseSector(&hspif, targetSector) == true)
{
    printf("Sector %ld (containing address 0x%lX) erased\r\n",
           targetSector, targetAddress);
}
```

--------------------------------

### Read Data from SPI Flash Address

Source: https://context7.com/nimaltd/spif/llms.txt

Reads a specified number of bytes from a memory address into a buffer. This function can read across page, sector, and block boundaries seamlessly.

```c
/* Read 32 bytes from address 0x1000 */
uint8_t readBuffer[32];
uint32_t address = 0x1000;

if (SPIF_ReadAddress(&hspif, address, readBuffer, sizeof(readBuffer)) == true)
{
    printf("Read from 0x%lX: ", address);
    for (int i = 0; i < sizeof(readBuffer); i++)
    {
        printf("0x%02X ", readBuffer[i]);
    }
    printf("\r\n");
}
```

```c
/* Read large data block */
uint8_t largeBuffer[2048];

if (SPIF_ReadAddress(&hspif, 0x0000, largeBuffer, sizeof(largeBuffer)) == true)
{
    printf("Read 2KB from start of flash\r\n");
}
```

--------------------------------

### SPIF_EraseSector - Erase Single Sector

Source: https://context7.com/nimaltd/spif/llms.txt

Erases a single 4KB sector. Sectors must be erased before writing new data. This is the smallest erasable unit for most SPI FLASH chips.

```APIDOC
## SPIF_EraseSector - Erase Single Sector

### Description
Erases a single 4KB sector (0x1000 bytes). Sectors must be erased before writing new data. Erasing sets all bytes in the sector to 0xFF. This is the smallest erasable unit for most SPI FLASH chips.

### Method
`SPIF_EraseSector`

### Parameters
- **hspif** (*SPIF_HandleTypeDef*)
- **sectorNumber** (uint32_t) - The number of the sector to erase.

### Request Example
```c
/* Erase sector 0 (addresses 0x0000 - 0x0FFF) */
uint32_t sectorNumber = 0;

if (SPIF_EraseSector(&hspif, sectorNumber) == true)
{
    printf("Sector %ld erased successfully\r\n", sectorNumber);
}

/* Erase sector containing a specific address */
uint32_t targetAddress = 0x5000;
uint32_t targetSector = SPIF_AddressToSector(targetAddress);  /* = 5 */

if (SPIF_EraseSector(&hspif, targetSector) == true)
{
    printf("Sector %ld (containing address 0x%lX) erased\r\n",
           targetSector, targetAddress);
}
```

### Response
- **bool**: `true` if the sector erase is successful, `false` otherwise.

### Response Example
```
Sector 0 erased successfully
Sector 5 (containing address 0x5000) erased
```
```

--------------------------------

### SPIF_EraseChip - Full Chip Erase

Source: https://context7.com/nimaltd/spif/llms.txt

Erases the entire FLASH chip, setting all memory bits to 0xFF. This operation can take several seconds and blocks until completion.

```APIDOC
## SPIF_EraseChip - Full Chip Erase

### Description
Erases the entire FLASH chip. This operation sets all memory bits to 0xFF and can take several seconds depending on chip size (approximately 1 second per block). This function blocks until the erase operation completes.

### Method
`SPIF_EraseChip`

### Parameters
- **hspif** (*SPIF_HandleTypeDef*)

### Request Example
```c
/* Erase entire chip before bulk data storage */
if (SPIF_EraseChip(&hspif) == true)
{
    printf("Chip erase complete\r\n");
    /* All memory is now 0xFF and ready for writing */
}
else
{
    printf("Chip erase failed\r\n");
}
```

### Response
- **bool**: `true` if the chip erase is successful, `false` otherwise.

### Response Example
```
Chip erase complete
```
```

--------------------------------

### Full Chip Erase

Source: https://context7.com/nimaltd/spif/llms.txt

Erases the entire FLASH chip by setting all bits to 0xFF. This is a blocking operation that may take several seconds.

```c
/* Erase entire chip before bulk data storage */
if (SPIF_EraseChip(&hspif) == true)
{
    printf("Chip erase complete\r\n");
    /* All memory is now 0xFF and ready for writing */
}
else
{
    printf("Chip erase failed\r\n");
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.