/**************************************************************************** * include/nuttx/progmem.h * * SPDX-License-Identifier: Apache-2.0 * * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. The * ASF licenses this file to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance with the * License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the * License for the specific language governing permissions and limitations * under the License. * ****************************************************************************/ #ifndef __INCLUDE_NUTTX_PROGMEM_H #define __INCLUDE_NUTTX_PROGMEM_H /**************************************************************************** * Included Files ****************************************************************************/ #include #include #include #ifdef CONFIG_ARCH_HAVE_PROGMEM /**************************************************************************** * Pre-processor Definitions ****************************************************************************/ #undef EXTERN #if defined(__cplusplus) #define EXTERN extern "C" extern "C" { #else #define EXTERN extern #endif /**************************************************************************** * Public Functions Definitions ****************************************************************************/ /**************************************************************************** * Name: up_progmem_neraseblocks * * Description: * Return number of erase blocks * ****************************************************************************/ size_t up_progmem_neraseblocks(void); /**************************************************************************** * Name: up_progmem_isuniform * * Description: * Is program memory uniform or erase page and read/write page size differs? * ****************************************************************************/ bool up_progmem_isuniform(void); /**************************************************************************** * Name: up_progmem_pagesize * * Description: * Return read/write page size * ****************************************************************************/ size_t up_progmem_pagesize(size_t page); /**************************************************************************** * Name: up_progmem_erasesize * * Description: * Return erase block size. Must be a multiple of the read/write page size. * ****************************************************************************/ size_t up_progmem_erasesize(size_t block); /**************************************************************************** * Name: up_progmem_getpage * * Description: * Address to read/write page conversion * * Input Parameters: * addr - Address with or without flash offset * (absolute or aligned to page0) * * Returned Value: * Page or negative value on error. * The following errors are reported (errno is not set!): * * -EFAULT: On invalid address * ****************************************************************************/ ssize_t up_progmem_getpage(size_t addr); /**************************************************************************** * Name: up_progmem_getaddress * * Description: * Read/write page to address conversion * * Input Parameters: * page - page index * * Returned Value: * Base address of given page, SIZE_MAX if page index is not valid. * ****************************************************************************/ size_t up_progmem_getaddress(size_t page); /**************************************************************************** * Name: up_progmem_eraseblock * * Description: * Erase selected erase block. * * Input Parameters: * block - The erase block index to be erased. * * Returned Value: * block size or negative value on error. * The following errors are reported (errno is not set!): * * -EFAULT: On invalid page * -EIO: On unsuccessful erase * -EROFS: On access to write protected area * -EACCES: Insufficient permissions (read/write protected) * -EPERM: If operation is not permitted due to some other constraints * (i.e. some internal block is not running etc.) * ****************************************************************************/ ssize_t up_progmem_eraseblock(size_t block); /**************************************************************************** * Name: up_progmem_ispageerased * * Description: * Checks whether erase page is erased * * Input Parameters: * page - The page index to be checked. * * Returned Value: * Returns number of bytes NOT erased or negative value on error. If it * returns zero then complete page is erased. * * The following errors are reported: * -EFAULT: On invalid page * ****************************************************************************/ ssize_t up_progmem_ispageerased(size_t page); /**************************************************************************** * Name: up_progmem_write * * Description: * Program data at given address * * Note: this function is not limited to single page and nor it requires * the address be aligned inside the page boundaries. * * Input Parameters: * addr - Address with or without flash offset * (absolute or aligned to page0) * buf - Pointer to buffer * count - Number of bytes to write * * Returned Value: * Bytes written or negative value on error. The following errors are * reported (errno is not set!) * * EINVAL: If count is not aligned with the flash boundaries (i.e. * some MCU's require per half-word or even word access) * EFAULT: On invalid address * EIO: On unsuccessful write * EROFS: On access to write protected area * EACCES: Insufficient permissions (read/write protected) * EPERM: If operation is not permitted due to some other constraints * (i.e. some internal block is not running etc.) * ****************************************************************************/ ssize_t up_progmem_write(size_t addr, FAR const void *buf, size_t count); /**************************************************************************** * Name: up_progmem_read * * Description: * Read data at given address * * Note: this function is not limited to single page and nor it requires * the address be aligned inside the page boundaries. * * Input Parameters: * addr - Address with or without flash offset * (absolute or aligned to page0) * buf - Pointer to buffer * count - Number of bytes to read * * Returned Value: * Bytes read or negative value on error. The following errors are * reported (errno is not set!) * * EINVAL: If count is not aligned with the flash boundaries (i.e. * some MCU's require per half-word or even word access) * EFAULT: On invalid address * EIO: On unsuccessful read * EACCES: Insufficient permissions (read/write protected) * EPERM: If operation is not permitted due to some other constraints * (i.e. some internal block is not running etc.) * ****************************************************************************/ #ifdef CONFIG_ARCH_HAVE_PROGMEM_READ ssize_t up_progmem_read(size_t addr, FAR void *buf, size_t count); #endif /**************************************************************************** * Name: up_progmem_erasestate * * Description: * Return value of erase state. * ****************************************************************************/ uint8_t up_progmem_erasestate(void); #undef EXTERN #if defined(__cplusplus) } #endif #endif /* CONFIG_ARCH_HAVE_PROGMEM */ #endif /* __INCLUDE_NUTTX_PROGMEM_H */