To fully take advantage of advanced peripherals (for example, NAND flash controllers), you might decide to provide your own implementation of the controller layer. The controller layer is one level above the BSP layer. Its interface is more flexible, but is also more complex to implement. If you choose that route, it is strongly recommended to use the provided implementations as an example. Listing 15-12 describes the API that must be implemented for the controller layer.
Listing 15-12 Controller API type definition
Before implementing the following functions, it is important to understand the difference between out-of-sector (OOS) data and the spare area. In a NAND device, each page has a spare area, typically used to store metadata and error correction codes (ECC). The spare area also contains a factory defect mark and, optionally, reserved sections. In the implementation of the µC/FS NAND driver, the OOS data is metadata sent to the controller layer by the translation layer. It must be stored in the spare area, wit.hout overwriting the bad block mark and without writing to the reserved section. It must also be protected by ECC. The OOS data is only a part of what is inside the spare area. It doesn’t include the factory defect marks, the reserved sections and the ECC data. Also, if the sector size is not equal to the page size, the OOS data will be associated to a single sector, while the spare area will be associated to a single page. In that case, multiple OOS sections would be fit in a single spare area.
Open/Close functions
The Open() and Close() function will be called respectively by FSDev_Open() and FSDev_Close(). Typically, FSDev_Open() is called during initialization and FSDev_Close() is never called. When implementing the Open() function of the controller layer, you should typically add all necessary code for the bus/controller initialization (or call the Open() function of the BSP layer). You should also allocate the necessary memory and perform all the operations that need to be done a single time only, when opening the device. The Close() function is typically left empty.
Part data get function
The PartDataGet() function should return an instance of the type FS_NAND_PART_DATA associated to a particular device.
Setup function
The Setup() function is called a single time, after the Open() function. It must perform the proper calculation to make sure that the out-of-sector data (OOS) and the error correction codes (ECC) can fit in the spare area.
Sector read function
The SectorRd() function must copy the data found at the physical sector sec_ix_phy into the p_dest buffer. It must also copy the out-of-sector data (OOS - the section of the spare area, excluding ECC, bad block marks and unused sections) into the p_dest_oos buffer. Before returning successfully, the function should check for errors and correct them, if needed (with ECC).
Out-Of-sector (OOS) raw read function
The OOSRdRaw() function must copy len octets from the offset octet in the OOS of the sector sec_ix_phy into the p_dest_oos buffer. This function should not perform error correction.
Spare area raw read function
The SpareRdRaw() function must copy len octets from the offset octet in the spare area of the page pg_ix_phy into the p_dest_spare buffer. This function should not perform error correction.
Sector write function
The SectorWr() function must write the data found in the p_src buffer into the physical sector sec_ix_phy of the NAND device. It must also write the out-of-sector data (OOS - the section of the spare area, excluding ECC, bad block marks and unused sections) found in the p_src_oos buffer into the spare area. It should also store error correction codes (ECC) in the spare area.
Block erase function
The BlkErase() function should erase the block blk_ix_phy of the device.
IO control function
The IO_Ctrl() function body can be left empty. It was created to perform device or controller specific commands without the need of a custom API. It can simply return the FS_ERR_DEV_INVALID_IO_CTRL error code.
Note that the ONFI part layer implementation makes use of the FS_DEV_IO_CTRL_NAND_PARAM_PG_RD I/O control operation. In order to retain compatibility with the ONFI part layer implementation, your controller implementation must support that operation.