LPCOpen SPIFI FLASH Library (LPCSPIFILIB)
Documentation for the LPCSPIFILIB library
spifilib_api.h
1 /*
2  * @brief LPCSPIFILIB driver definitions and functions
3  *
4  * @note
5  * Copyright(C) NXP Semiconductors, 2014
6  * All rights reserved.
7  *
8  * @par
9  * Software that is described herein is for illustrative purposes only
10  * which provides customers with programming information regarding the
11  * LPC products. This software is supplied "AS IS" without any warranties of
12  * any kind, and NXP Semiconductors and its licenser disclaim any and
13  * all warranties, express or implied, including all implied warranties of
14  * merchantability, fitness for a particular purpose and non-infringement of
15  * intellectual property rights. NXP Semiconductors assumes no responsibility
16  * or liability for the use of the software, conveys no license or rights under any
17  * patent, copyright, mask work right, or any other intellectual property rights in
18  * or to any products. NXP Semiconductors reserves the right to make changes
19  * in the software without notification. NXP Semiconductors also makes no
20  * representation or warranty that such application will be suitable for the
21  * specified use without further testing or modification.
22  *
23  * @par
24  * Permission to use, copy, modify, and distribute this software and its
25  * documentation is hereby granted, under NXP Semiconductors' and its
26  * licensor's relevant copyrights in the software, without fee, provided that it
27  * is used in conjunction with NXP Semiconductors microcontrollers. This
28  * copyright, permission, and disclaimer notice must appear in all copies of
29  * this code.
30  */
31 
32 #ifndef __SPIFILIB_API_H_
33 #define __SPIFILIB_API_H_
34 
35 #include "spifilib_dev.h"
36 
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40 
59 uint16_t spifiGetLibVersion(void);
60 
73 SPIFI_ERR_T spifiInit(uint32_t spifiCtrlAddr, uint8_t reset);
74 
83 
89 const char *spifiReturnErrString(SPIFI_ERR_T errCode);
90 
95 uint32_t spifiGetSuppFamilyCount(void);
96 
105 const char *spifiGetSuppFamilyName(uint32_t index);
106 
114 uint32_t spifiGetHandleMemSize(uint32_t spifiCtrlAddr);
115 
124 SPIFI_HANDLE_T *spifiInitDevice(void *pMem, uint32_t sizePMem, uint32_t spifiCtrlAddr, uint32_t baseAddr);
125 
136 SPIFI_ERR_T spifiDevSetOpts(SPIFI_HANDLE_T *pHandle, uint32_t options, uint8_t set);
137 
155 
161 static INLINE uint32_t spifiDevGetCount(const SPIFI_FAM_NODE_T *pFamily)
162 {
163  return *(pFamily->pDesc->pDevCount);
164 }
165 
172 const char *spifiDevEnumerateName(SPIFI_DEV_ENUMERATOR_T *pContext, uint8_t reset);
173 
179 SPIFI_ERR_T spifiDevInit(const SPIFI_HANDLE_T *pHandle);
180 
187 
197 SPIFI_ERR_T spifiDevSetMemMode(const SPIFI_HANDLE_T *pHandle, uint8_t enMMode);
198 
204 uint8_t spifiDevGetMemoryMode(const SPIFI_HANDLE_T *pSpifi);
205 
211 static INLINE SPIFI_ERR_T spifiDevUnlockDevice(const SPIFI_HANDLE_T *pHandle)
212 {
213  return pHandle->pFamFx->lockCmd(pHandle, SPIFI_PCMD_UNLOCK_DEVICE, 0);
214 }
215 
221 static INLINE SPIFI_ERR_T spifiDevLockDevice(const SPIFI_HANDLE_T *pHandle)
222 {
223  return pHandle->pFamFx->lockCmd(pHandle, SPIFI_PCMD_LOCK_DEVICE, 0);
224 }
225 
232 static INLINE SPIFI_ERR_T spifiDevUnlockBlock(const SPIFI_HANDLE_T *pHandle, uint32_t block)
233 {
234  return pHandle->pFamFx->lockCmd(pHandle, SPIFI_PCMD_UNLOCK_BLOCK, block);
235 }
236 
243 static INLINE SPIFI_ERR_T spifiDevLockBlock(const SPIFI_HANDLE_T *pHandle, uint32_t block)
244 {
245  return pHandle->pFamFx->lockCmd(pHandle, SPIFI_PCMD_LOCK_BLOCK, block);
246 }
247 
253 static INLINE SPIFI_ERR_T spifiDevEraseAll(const SPIFI_HANDLE_T *pHandle)
254 {
255  return pHandle->pFamFx->eraseAll(pHandle);
256 }
257 
264 static INLINE SPIFI_ERR_T spifiDevEraseSubBlock(const SPIFI_HANDLE_T *pHandle, uint32_t blknum)
265 {
266  return pHandle->pFamFx->eraseSubBlock(pHandle, blknum);
267 }
268 
278 static INLINE SPIFI_ERR_T spifiDevPageProgram(const SPIFI_HANDLE_T *pHandle,
279  uint32_t addr,
280  uint32_t *writeBuff,
281  uint32_t bytes)
282 {
283  return pHandle->pFamFx->pageProgram(pHandle, addr, writeBuff, bytes);
284 }
285 
295 static INLINE SPIFI_ERR_T spifiDevRead(const SPIFI_HANDLE_T *pHandle, uint32_t addr, uint32_t *readBuff, uint32_t bytes)
296 {
297  return pHandle->pFamFx->read(pHandle, addr, readBuff, bytes);
298 }
299 
306 static INLINE void spifiDevReset(const SPIFI_HANDLE_T *pHandle)
307 {
308  pHandle->pFamFx->reset(pHandle);
309 }
310 
316 static INLINE const char *spifiDevGetDeviceName(const SPIFI_HANDLE_T *pHandle)
317 {
318  return pHandle->pInfoData->pDevName;
319 }
320 
321 #define spifiDevGetFamilyName spifiDevGetDeviceName
329 uint32_t spifiDevGetInfo(const SPIFI_HANDLE_T *pHandle, SPIFI_INFO_ID_T infoId);
330 
345 uint32_t spifiGetAddrFromBlock(const SPIFI_HANDLE_T *pHandle, uint32_t blockNum);
346 
353 uint32_t spifiGetAddrFromSubBlock(const SPIFI_HANDLE_T *pHandle, uint32_t subBlockNum);
354 
361 uint32_t spifiGetBlockFromAddr(const SPIFI_HANDLE_T *pHandle, uint32_t addr);
362 
369 uint32_t spifiGetSubBlockFromAddr(const SPIFI_HANDLE_T *pHandle, uint32_t addr);
370 
377 uint32_t spifiGetSubBlockFromBlock(const SPIFI_HANDLE_T *pHandle, uint32_t blockNum);
378 
388 SPIFI_ERR_T spifiProgram(const SPIFI_HANDLE_T *pHandle, uint32_t addr, const uint32_t *writeBuff, uint32_t bytes);
389 
401 SPIFI_ERR_T spifiRead(const SPIFI_HANDLE_T *pHandle, uint32_t addr, uint32_t *readBuff, uint32_t bytes);
402 
412 SPIFI_ERR_T spifiErase(const SPIFI_HANDLE_T *pHandle, uint32_t firstBlock, uint32_t numBlocks);
413 
424 SPIFI_ERR_T spifiEraseByAddr(const SPIFI_HANDLE_T *pHandle, uint32_t firstAddr, uint32_t lastAddr);
425 
434 #ifdef __cplusplus
435 }
436 #endif
437 
438 #endif /* __SPIFILIB_API_H_ */
SPIFI_HANDLE_T * spifiInitDevice(void *pMem, uint32_t sizePMem, uint32_t spifiCtrlAddr, uint32_t baseAddr)
Initialize driver and hardware for a specific device.
Definition: spifilib_dev_common.c:567
uint32_t spifiGetAddrFromSubBlock(const SPIFI_HANDLE_T *pHandle, uint32_t subBlockNum)
Returns the starting address of a sub-block number.
Definition: spifilib_dev_common.c:706
SPIFI_ERR_T(* reset)(const struct SPIFI_HANDLE *)
Definition: spifilib_dev.h:265
const char * spifiDevEnumerateName(SPIFI_DEV_ENUMERATOR_T *pContext, uint8_t reset)
Enumerates the friendly names of supported devices.
Definition: spifilib_dev_common.c:290
SPIFI_ERR_T(* eraseSubBlock)(const struct SPIFI_HANDLE *, uint32_t)
Definition: spifilib_dev.h:259
static INLINE SPIFI_ERR_T spifiDevEraseSubBlock(const SPIFI_HANDLE_T *pHandle, uint32_t blknum)
Erase a sub-block.
Definition: spifilib_api.h:264
static INLINE SPIFI_ERR_T spifiDevLockBlock(const SPIFI_HANDLE_T *pHandle, uint32_t block)
Lock a single device block.
Definition: spifilib_api.h:243
SPIFI_ERR_T spifiDevSetOpts(SPIFI_HANDLE_T *pHandle, uint32_t options, uint8_t set)
Set or unset driver options.
Definition: spifilib_dev_common.c:635
static INLINE SPIFI_ERR_T spifiDevEraseAll(const SPIFI_HANDLE_T *pHandle)
Full LPCSPIFILIB device erase.
Definition: spifilib_api.h:253
static INLINE SPIFI_ERR_T spifiDevUnlockDevice(const SPIFI_HANDLE_T *pHandle)
Full LPCSPIFILIB device unlock.
Definition: spifilib_api.h:211
Definition: spifilib_dev.h:144
SPIFI_ERR_T spifiEraseByAddr(const SPIFI_HANDLE_T *pHandle, uint32_t firstAddr, uint32_t lastAddr)
Erase multiple blocks by address range.
Definition: spifilib_dev_common.c:849
uint32_t * pDevCount
Definition: spifilib_dev.h:216
SPIFI_ERR_T(* eraseAll)(const struct SPIFI_HANDLE *)
Definition: spifilib_dev.h:255
static INLINE void spifiDevReset(const SPIFI_HANDLE_T *pHandle)
Reset the device.
Definition: spifilib_api.h:306
SPIFI_ERR_T spifiDevInit(const SPIFI_HANDLE_T *pHandle)
Initialize a detected LPCSPIFILIB device.
Definition: spifilib_dev_common.c:352
SPIFI_ERR_T(* lockCmd)(const struct SPIFI_HANDLE *, SPIFI_PCMD_LOCK_UNLOCK_T, uint32_t)
Definition: spifilib_dev.h:253
uint32_t spifiGetSubBlockFromAddr(const SPIFI_HANDLE_T *pHandle, uint32_t addr)
Returns the sub-block number the passed address is located in.
Definition: spifilib_dev_common.c:738
Context for enumerating devices.
Definition: spifilib_dev.h:352
Definition: spifilib_dev.h:146
uint32_t spifiGetAddrFromBlock(const SPIFI_HANDLE_T *pHandle, uint32_t blockNum)
Returns the starting address of a block number.
Definition: spifilib_dev_common.c:694
uint16_t spifiGetLibVersion(void)
Report the SPIFILIB version.
Definition: spifilib_dev_common.c:319
LPCSPIFILIB device handle, used with all device and info functions.
Definition: spifilib_dev.h:321
SPIFI_ERR_T(* pageProgram)(const struct SPIFI_HANDLE *, uint32_t, const uint32_t *, uint32_t)
Definition: spifilib_dev.h:261
static INLINE SPIFI_ERR_T spifiDevRead(const SPIFI_HANDLE_T *pHandle, uint32_t addr, uint32_t *readBuff, uint32_t bytes)
Read data from a LPCSPIFILIB device.
Definition: spifilib_api.h:295
uint32_t spifiGetSuppFamilyCount(void)
Return the number of registered device families in this driver.
Definition: spifilib_dev_common.c:522
static INLINE const char * spifiDevGetDeviceName(const SPIFI_HANDLE_T *pHandle)
Returns a string pointer to the generic device family name.
Definition: spifilib_api.h:316
SPIFI_ERR_T
Possible error codes that can be returned from functions.
Definition: spifilib_dev.h:57
const struct SPIFI_FAM_DESC * pDesc
Definition: spifilib_dev.h:202
const struct SPIFI_FAM_FX * pFamFx
Definition: spifilib_dev.h:322
SPIFI_ERR_T spifiDevDeInit(const SPIFI_HANDLE_T *pHandle)
De-initialize a detected LPCSPIFILIB device.
Definition: spifilib_dev_common.c:366
SPIFI_ERR_T spifiDevRegister(const SPIFI_FAM_NODE_T *pFamily, SPIFI_DEV_NODE_T *pDevData)
Add device to family driver.
Definition: spifilib_dev_common.c:276
Register device data node.
Definition: spifilib_dev.h:226
SPIFI_FAM_NODE_T * spifiRegisterFamily(SPIFI_FAM_NODE_T *(*regFx)(void))
Register a SPIFILIB family driver.
Definition: spifilib_dev_common.c:252
uint32_t spifiGetBlockFromAddr(const SPIFI_HANDLE_T *pHandle, uint32_t addr)
Returns the block number the passed address is located in.
Definition: spifilib_dev_common.c:725
SPIFI_ERR_T(* read)(const struct SPIFI_HANDLE *, uint32_t, uint32_t *, uint32_t)
Definition: spifilib_dev.h:263
uint32_t spifiGetSubBlockFromBlock(const SPIFI_HANDLE_T *pHandle, uint32_t blockNum)
Returns the first sub-block for a block.
Definition: spifilib_dev_common.c:762
struct SPIFI_INFODATA * pInfoData
Definition: spifilib_dev.h:324
uint8_t spifiDevGetMemoryMode(const SPIFI_HANDLE_T *pSpifi)
Return status of memory mode.
Definition: spifilib_dev_common.c:466
SPIFI_ERR_T spifiInit(uint32_t spifiCtrlAddr, uint8_t reset)
Initialize the SPIFILIB driver.
Definition: spifilib_dev_common.c:325
SPIFI_ERR_T spifiDevSetMemMode(const SPIFI_HANDLE_T *pHandle, uint8_t enMMode)
Sets or clears memory mode.
Definition: spifilib_dev_common.c:473
const char * spifiReturnErrString(SPIFI_ERR_T errCode)
Converts a SPIFILIB error code into a meaningful string.
Definition: spifilib_dev_common.c:380
uint32_t spifiGetHandleMemSize(uint32_t spifiCtrlAddr)
Detect and return memory needed for device handle at passed address.
Definition: spifilib_dev_common.c:550
Definition: spifilib_dev.h:143
Definition: spifilib_dev.h:145
static INLINE SPIFI_ERR_T spifiDevLockDevice(const SPIFI_HANDLE_T *pHandle)
Full LPCSPIFILIB device lock.
Definition: spifilib_api.h:221
const char * spifiGetSuppFamilyName(uint32_t index)
Return the driver device family name for a specific index.
Definition: spifilib_dev_common.c:529
const char * pDevName
Definition: spifilib_dev.h:344
static INLINE uint32_t spifiDevGetCount(const SPIFI_FAM_NODE_T *pFamily)
Returns the number of supported devices within a family.
Definition: spifilib_api.h:161
SPIFI_ERR_T spifiRead(const SPIFI_HANDLE_T *pHandle, uint32_t addr, uint32_t *readBuff, uint32_t bytes)
Read the device into the passed buffer.
Definition: spifilib_dev_common.c:807
SPIFI_ERR_T spifiErase(const SPIFI_HANDLE_T *pHandle, uint32_t firstBlock, uint32_t numBlocks)
Erase multiple blocks.
Definition: spifilib_dev_common.c:829
LPCSPIFILIB family data.
Definition: spifilib_dev.h:201
static INLINE SPIFI_ERR_T spifiDevPageProgram(const SPIFI_HANDLE_T *pHandle, uint32_t addr, uint32_t *writeBuff, uint32_t bytes)
Program up to a page of data at an address.
Definition: spifilib_api.h:278
static INLINE SPIFI_ERR_T spifiDevUnlockBlock(const SPIFI_HANDLE_T *pHandle, uint32_t block)
Unlock a single device block.
Definition: spifilib_api.h:232
SPIFI_ERR_T spifiProgram(const SPIFI_HANDLE_T *pHandle, uint32_t addr, const uint32_t *writeBuff, uint32_t bytes)
Program the device with the passed buffer.
Definition: spifilib_dev_common.c:785