250 lines
9.2 KiB
C
250 lines
9.2 KiB
C
/***************************************************************************//**
|
|
* @file
|
|
* @brief NVM3 driver HAL
|
|
*******************************************************************************
|
|
* # License
|
|
* <b>Copyright 2018 Silicon Laboratories Inc. www.silabs.com</b>
|
|
*******************************************************************************
|
|
*
|
|
* SPDX-License-Identifier: Zlib
|
|
*
|
|
* The licensor of this software is Silicon Laboratories Inc.
|
|
*
|
|
* This software is provided 'as-is', without any express or implied
|
|
* warranty. In no event will the authors be held liable for any damages
|
|
* arising from the use of this software.
|
|
*
|
|
* Permission is granted to anyone to use this software for any purpose,
|
|
* including commercial applications, and to alter it and redistribute it
|
|
* freely, subject to the following restrictions:
|
|
*
|
|
* 1. The origin of this software must not be misrepresented; you must not
|
|
* claim that you wrote the original software. If you use this software
|
|
* in a product, an acknowledgment in the product documentation would be
|
|
* appreciated but is not required.
|
|
* 2. Altered source versions must be plainly marked as such, and must not be
|
|
* misrepresented as being the original software.
|
|
* 3. This notice may not be removed or altered from any source distribution.
|
|
*
|
|
******************************************************************************/
|
|
|
|
#ifndef NVM3_HAL_H
|
|
#define NVM3_HAL_H
|
|
|
|
#include "sl_status.h"
|
|
#include <stdint.h>
|
|
#include <stdbool.h>
|
|
#include <stdlib.h>
|
|
|
|
#ifdef NVM3_HOST_BUILD
|
|
#include "nvm3_hal_host.h"
|
|
#else
|
|
#include "sl_assert.h"
|
|
#include "sl_common.h"
|
|
#endif
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/***************************************************************************//**
|
|
* @addtogroup nvm3
|
|
* @{
|
|
******************************************************************************/
|
|
|
|
/***************************************************************************//**
|
|
* @addtogroup nvm3hal NVM3 HAL
|
|
* @brief NVM3 Hardware Abstraction Layer
|
|
* @{
|
|
* @details
|
|
* This module provides the interface to the NVM. By having all NVM access
|
|
* functions in a separate file, it is possible to support different hardware
|
|
* by substituting the functions in this module.
|
|
*
|
|
* @note These functions are used by the NVM3 and should not be used by
|
|
* any applications.
|
|
******************************************************************************/
|
|
|
|
/******************************************************************************
|
|
****************************** MACROS **********************************
|
|
*****************************************************************************/
|
|
|
|
#define NVM3_HAL_WRITE_SIZE_32 0 ///< Only single writes are allowed
|
|
#define NVM3_HAL_WRITE_SIZE_16 1 ///< Two writes are allowed
|
|
|
|
#define NVM3_HAL_NVM_ACCESS_NONE 0 ///< No access
|
|
#define NVM3_HAL_NVM_ACCESS_RD 1 ///< Read access
|
|
#define NVM3_HAL_NVM_ACCESS_RDWR 2 ///< Read and write access
|
|
#define NVM3_HAL_NVM_ACCESS_NOP 3 ///< Ignore
|
|
|
|
/// @cond DO_NOT_INCLUDE_WITH_DOXYGEN
|
|
|
|
#define nvm3_halOpen(hal, a, b) ((hal)->open((a), (b)))
|
|
#define nvm3_halClose(hal) ((hal)->close())
|
|
#define nvm3_halGetInfo(hal, a) ((hal)->getInfo(a))
|
|
#define nvm3_halNvmAccess(hal, a) ((hal)->access(a))
|
|
#define nvm3_halReadWords(hal, a, b, c) ((hal)->readWords((a), (b), (c)))
|
|
#define nvm3_halWriteWords(hal, a, b, c) ((hal)->writeWords((a), (b), (c)))
|
|
#define nvm3_halPageErase(hal, a) ((hal)->pageErase(a))
|
|
|
|
/// @endcond
|
|
|
|
/******************************************************************************
|
|
****************************** TYPEDEFS **********************************
|
|
*****************************************************************************/
|
|
|
|
/// @brief Pointer to NVM
|
|
typedef void *nvm3_HalPtr_t;
|
|
|
|
/// @brief Device NVM capabilities
|
|
|
|
typedef struct nvm3_HalInfo {
|
|
uint16_t deviceFamilyPartNumber; ///< Device family or part number.
|
|
uint8_t writeSize; ///< Write-size: 0=32-bit, 1=16-bit.
|
|
uint8_t memoryMapped; ///< Memory-mapped: 0=not memory mapped, 1=memory mapped.
|
|
size_t pageSize; ///< The data storage page size.
|
|
uint64_t systemUnique; ///< Obsolete. Was used to support external flash.
|
|
} nvm3_HalInfo_t;
|
|
|
|
typedef uint8_t nvm3_HalNvmAccessCode_t; ///< Definition of the access data type.
|
|
|
|
/*******************************************************************************
|
|
***************************** PROTOTYPES **********************************
|
|
******************************************************************************/
|
|
|
|
/***************************************************************************//**
|
|
* @brief
|
|
* Open the NVM3 HAL for usage.
|
|
*
|
|
* @details
|
|
* This function must be run at initialization, before any other functions
|
|
* are called. It is used to call necessary startup routines before the
|
|
* hardware can be accessed.
|
|
*
|
|
* @param[in] nvmAdr
|
|
* A pointer to the destination in NVM.
|
|
*
|
|
* @param[in] nvmSize
|
|
* The total size of the NVM.
|
|
*
|
|
* @return
|
|
* The result of the open call.
|
|
* @ref SL_STATUS_OK on success or a NVM3 @ref sl_status_t on failure.
|
|
******************************************************************************/
|
|
typedef sl_status_t (*nvm3_HalOpen_t)(nvm3_HalPtr_t nvmAdr, size_t nvmSize);
|
|
|
|
/***************************************************************************//**
|
|
* @brief
|
|
* Close the NVM3 HAL for usage.
|
|
*
|
|
* @details
|
|
* This function should be called at program termination.
|
|
* Should be done before any graceful halts.
|
|
******************************************************************************/
|
|
typedef void(*nvm3_HalClose_t)(void);
|
|
|
|
/***************************************************************************//**
|
|
* @brief
|
|
* Retrieve device information.
|
|
*
|
|
* @details
|
|
* This function is used to retrieve information about the device properties,
|
|
* such as the device family, write size, whether the NVM is memory mapped or
|
|
* not, and finally the NVM page size.
|
|
*
|
|
* @param[in] info
|
|
* A pointer to a structure that will receive the device information.
|
|
******************************************************************************/
|
|
typedef sl_status_t (*nvm3_HalGetInfo_t)(nvm3_HalInfo_t *info);
|
|
|
|
/***************************************************************************//**
|
|
* @brief
|
|
* Control read and write access to the NVM.
|
|
*
|
|
* @details
|
|
* This function is used to control the access to the NVM. It can be either
|
|
* read, write, or none.
|
|
*
|
|
* @param[in] access
|
|
* The requested access.
|
|
******************************************************************************/
|
|
typedef void (*nvm3_HalNvmAccess_t)(nvm3_HalNvmAccessCode_t access);
|
|
|
|
/***************************************************************************//**
|
|
* @brief
|
|
* Erase a page in the NVM.
|
|
*
|
|
* @details
|
|
* This function is used to erase an NVM page.
|
|
*
|
|
* @param[in] nvmAdr
|
|
* A memory address pointing to the start of the page to erase.
|
|
*
|
|
* @return
|
|
* The result of the erase operation.
|
|
******************************************************************************/
|
|
typedef sl_status_t (*nvm3_HalPageErase_t)(nvm3_HalPtr_t nvmAdr);
|
|
|
|
/***************************************************************************//**
|
|
* @brief
|
|
* Read data from NVM.
|
|
*
|
|
* @details
|
|
* This function is used to read data from the NVM. It will be a
|
|
* blocking call, since the thread asking for data to be read cannot continue
|
|
* without the data.
|
|
*
|
|
* @param[in] nvmAdr
|
|
* A memory address in NVM where data will be read.
|
|
*
|
|
* @param[in] *dst
|
|
* A pointer to the destination buffer.
|
|
*
|
|
* @param[in] wordCnt
|
|
* The number of words to read.
|
|
******************************************************************************/
|
|
typedef sl_status_t (*nvm3_HalReadWords_t)(nvm3_HalPtr_t nvmAdr, void *dst, size_t wordCnt);
|
|
|
|
/***************************************************************************//**
|
|
* @brief
|
|
* Write data to the NVM.
|
|
*
|
|
* @details
|
|
* This function is used to write data to the NVM. This is a blocking
|
|
* function.
|
|
*
|
|
* @param[in] nvmAdr
|
|
* A memory address in NVM where data will be written.
|
|
*
|
|
* @param[in] *pSrc
|
|
* A pointer to the source data.
|
|
*
|
|
* @param[in] cnt
|
|
* The number of words to write.
|
|
*
|
|
* @return
|
|
* The result of the write operation.
|
|
* @ref SL_STATUS_OK on success or a NVM3 @ref sl_status_t on failure.
|
|
******************************************************************************/
|
|
typedef sl_status_t (*nvm3_HalWriteWords_t)(nvm3_HalPtr_t nvmAdr, void const *pSrc, size_t cnt);
|
|
|
|
/// @brief The HAL handle definition.
|
|
typedef struct {
|
|
nvm3_HalOpen_t open; ///< Pointer to the open function
|
|
nvm3_HalClose_t close; ///< Pointer to the close function
|
|
nvm3_HalGetInfo_t getInfo; ///< Pointer to the get-info function
|
|
nvm3_HalNvmAccess_t access; ///< Pointer to the access function
|
|
nvm3_HalPageErase_t pageErase; ///< Pointer to the page-erase function
|
|
nvm3_HalReadWords_t readWords; ///< Pointer to the read-words function
|
|
nvm3_HalWriteWords_t writeWords; ///< Pointer to the write-words function
|
|
} nvm3_HalHandle_t;
|
|
|
|
/** @} (end addtogroup nvm3hal) */
|
|
/** @} (end addtogroup nvm3) */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* NVM3_HAL_H */
|