cmd/img_mgmt/include/img_mgmt/img_mgmt_impl.h

/*
 * 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 <stdbool.h>
#include <inttypes.h>
#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