/* * 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. */ /** * @file * @brief Declares implementation-specific functions required by image * management. The default stubs can be overridden with functions that * are compatible with the host OS. */ #ifndef H_IMG_MGMT_IMPL_ #define H_IMG_MGMT_IMPL_ #include #include #include "img_mgmt/img_mgmt.h" #ifdef __cplusplus extern "C" { #endif /** * @brief Ensures the spare slot (slot 1) is fully erased. * * @return 0 on success, MGMT_ERR_[...] code on failure. */ int img_mgmt_impl_erase_slot(void); /** * @brief Marks the image in the specified slot as pending. On the next reboot, * the system will perform a boot of the specified image. * * @param slot The slot to mark as pending. In the typical * use case, this is 1. * @param permanent Whether the image should be used permanently or * only tested once: * 0=run image once, then confirm or * revert. * 1=run image forever. * * @return 0 on success, MGMT_ERR_[...] code on failure. */ int img_mgmt_impl_write_pending(int slot, bool permanent); /** * @brief Marks the image in slot 0 as confirmed. The system will continue * booting into the image in slot 0 until told to boot from a different slot. * * @return 0 on success, MGMT_ERR_[...] code on failure. */ int img_mgmt_impl_write_confirmed(void); /** * @brief Reads the specified chunk of data from an image slot. * * @param slot The index of the slot to read from. * @param offset The offset within the slot to read from. * @param dst On success, the read data gets written here. * @param num_bytes The number of byets to read. * * @return 0 on success, MGMT_ERR_[...] code on failure. */ int img_mgmt_impl_read(int slot, unsigned int offset, void *dst, unsigned int num_bytes); /** * @brief Writes the specified chunk of image data to slot 1. * * @param offset The offset within slot 1 to write to. * @param data The image data to write. * @param num_bytes The number of bytes to read. * @param last Whether this chunk is the end of the image: * false=additional image chunks are * forthcoming. * true=last image chunk; flush unwritten data * to disk. * * @return 0 on success, MGMT_ERR_[...] code on failure. */ int img_mgmt_impl_write_image_data(unsigned int offset, const void *data, unsigned int num_bytes, bool last); /** * @brief Indicates the type of swap operation that will occur on the next * reboot, if any, between provided slot and it's pair. * Quering any slots of the same pair will give the same result. * * @param image An slot number; * @return An IMG_MGMT_SWAP_TYPE_[...] code. */ int img_mgmt_impl_swap_type(int slot); /** * Collects information about the specified image slot. * * @return Flags of the specified image slot */ uint8_t img_mgmt_state_flags(int query_slot); /** * Erases image data at given offset * * @param offset The offset within slot 1 to erase at. * @param num_bytes The number of bytes to erase. * @return 0 on success, MGMT_ERR_[...] code on failure. */ int img_mgmt_impl_erase_image_data(unsigned int off, unsigned int num_bytes); /** * Erases a flash sector as image upload crosses a sector boundary. * Erasing the entire flash size at one time can take significant time, * causing a bluetooth disconnect or significant battery sag. * Instead we will erase immediately prior to crossing a sector. * We could check for empty to increase efficiency, but instead we always erase * for consistency and simplicity. * * @param off Offset that is about to be written * @param len Number of bytes to be written * * @return 0 if success * ERROR_CODE if could not erase sector */ int img_mgmt_impl_erase_if_needed(uint32_t off, uint32_t len); /** * Verifies an upload request and indicates the actions that should be taken * during processing of the request. This is a "read only" function in the * sense that it doesn't write anything to flash and doesn't modify any global * variables. * * @param req The upload request to inspect. * @param action On success, gets populated with information * about how to process the request. * * @return 0 if processing should occur; * A MGMT_ERR code if an error response should be * sent instead. */ int img_mgmt_impl_upload_inspect(const struct img_mgmt_upload_req *req, struct img_mgmt_upload_action *action, const char **errstr); #define ERASED_VAL_32(x) (((x) << 24) | ((x) << 16) | ((x) << 8) | (x)) int img_mgmt_impl_erased_val(int slot, uint8_t *erased_val); int img_mgmt_impl_log_upload_start(int status); int img_mgmt_impl_log_upload_done(int status, const uint8_t *hashp); int img_mgmt_impl_log_pending(int status, const uint8_t *hash); int img_mgmt_impl_log_confirm(int status, const uint8_t *hash); #ifdef __cplusplus } #endif #endif