/*  *********************************************************************
 *  ASTRIS - Remote JTAG probe
 *
 *  Astris Booster System API Helpers
 *
 *  File: astris_booster_api_helpers.h
 *
 ***********************************************************************
 *
 *  Copyright (C) 2021 Apple Inc. All rights reserved.
 *
 *  This document is the property of Apple Inc.
 *  It is considered confidential and proprietary.
 *
 *  This document may not be reproduced or transmitted in any form,
 *  in whole or in part, without the express written permission of
 *  Apple Inc.
 ********************************************************************* */

#ifndef astris_booster_default_api_h
#define astris_booster_default_api_h

#include "astris_booster_api.h"

__BEGIN_DECLS

/*!
 * @function AXbooster_interface_init_astris_api_default
 * @abstract Default initialization to be used with AXbooster_interface_init_astris_api.
 * @discussion Many times you dont need to have a special init, so this helper function
 * does what is considered the default for any booster: sets up logging context, the
 * booster context, and sets the Astris API source version in the handoff struct.
 *
 * Most users would just need to call this function in their implementation of
 * AXbooster_interface_init_astris_api_default.
 * @return ASTRIS_ERR_OK if everything went well, other something failed.
 */
int AXbooster_interface_init_astris_api_default(const char *axl, AXbooster_handoff_info_t *info);

/*!
 * @function AXbooster_interface_cleanup_astris_api_default
 * @brief Calls into the default clean up functions to clean up the Astris library
 * that is being used in the booster.
 * @return ASTRIS_ERR_OK if everything went well, other something failed.
 */
int AXbooster_interface_cleanup_astris_api_default();

/*!
 * @function AXbooster_interface_init_downstream
 * @abstract Hands the current Astris context to the booster that is downstream.
 * @discussion This function should be used for boosters that link with another booster,
 * here we are calling that other booster the "downstream" booster. This function should be called
 * on the current booster AFTER calling set up function of the current booster (usually AXbooster_interface_init_astris_api_default).
 * All these calls should be happening in AXbooster_interface_init_astris_api function that
 * the current booster has implemented.
 *
 * There is a helper function AXbooster_interface_init_with_downstream, which does the
 * method calls in the right order.
 *
 * A call into this function calls AXbooster_interface_init_astris_api function
 * in the downstream booster which initializes the context's and API in the downstream booster.
 *
 * @param[in] info AXbooster_handoff_info_t same as you would pass to AXbooster_interface_init_astris_api
 * @param[in] downstream_soc_bundle This is the bundle name, aka usually the name of the folder that contains the
 * boosters without the type (no .framework or .booster). On SoCs we ship this is a value that is
 * easy to get and you should be able to just do: AppleDownstream_t::bundle_name.
 * @return ASTRIS_ERR_OK if everything went well, other something failed.
 */
int AXbooster_interface_init_downstream(AXbooster_handoff_info_t *info, const char *downstream_soc_bundle);

/*!
 * @function AXbooster_interface_cleanup_downstream
 * @brief Functions same as AXbooster_interface_init_downstream but for AXbooster_interface_cleanup_astris_api
 * where this function calls AXbooster_interface_cleanup_astris_api on the "downstream" booster,
 * aka the booster that your booster is linking with.
 *
 * Right now this function is not used in any, and is here for future needs.
 * @return ASTRIS_ERR_OK if everything went well, other something failed.
 */
int AXbooster_interface_cleanup_downstream(const char *downstream_soc_bundle);

/*!
 * @function AXbooster_interface_init_with_downstream
 * @brief This is a helper function that first calls into AXbooster_interface_init_astris_api_default
 * and then calls into AXbooster_interface_init_downstream, in the right order. This
 * should be used if instead AXbooster_interface_init_astris_api_default if your booster links with
 * another booster
 * @param[in] info AXbooster_handoff_info_t same as you would pass to AXbooster_interface_init_astris_api
 * @param[in] downstream_soc_bundle This is the bundle name, aka usually the name of the folder that contains the
 * boosters without the type (no .framework or .booster). On SoCs we ship this is a value that is
 * easy to get and you should be able to just do: AppleDownstream_t::bundle_name.
 * @return ASTRIS_ERR_OK if everything went well, other something failed.
 */
int AXbooster_interface_init_with_downstream(AXbooster_handoff_info_t *info, const char *downstream_soc_bundle);

/*!
  @function AXbooster_interface_cleanup_with_downstream
  @brief This is a helper function for boosters that link with other boosters. This
  function should be called in AXbooster_interface_cleanup_astris_api, and will do the default
  clean up of the current booster and the downstream booster. The clean up of downstream
  booster will happen by a call to: AXbooster_interface_cleanup_downstream.

  @param[in] downstream_soc_bundle This is the bundle name, aka usually the name of the folder that contains the
  boosters without the type (no .framework or .booster). On SoCs we ship this is a value that is
  easy to get and you should be able to just do: AppleDownstream_t::bundle_name.
  @return ASTRIS_ERR_OK if everything went well, other something failed.
 */
int AXbooster_interface_cleanup_with_downstream(const char *downstream_soc_bundle);

__END_DECLS

#endif /* astris_booster_default_api_h */
