/*
 * 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 modlog - Module-mapped logging.
 *
 * The modlog facility allows log entries to be written to numeric modules
 * identifiers.  In typical usage, startup code maps 8-bit module IDs to one or
 * more log objects, while other parts of the application log events by write
 * entries to modules IDs.  This usage differs from the underlying `sys/log`
 * facility, which requires clients to provide a log object to write to
 * rather than just a module identifier.
 *
 * Benefits provided by the modlog package are:
 *     o Improved modularity - configuration and usage are distinct.
 *     o Ability to write to several logs with a single function call.  If one
 *       module ID is mapped to several logs, a write to that ID causes all
 *       mapped logs to be written.
 *     o Default mappings.  Writes to unmapped module IDs get written to an
 *       optional set of default logs.
 *     o Minimum log level per mapping.  Writes specifying a log level less
 *       than the module's minimum level are discarded.
 *
 * Costs of using modlog rather than the bare `sys/log` facility are:
 *     o Increased RAM usage (`MODLOG_MAX_MAPPINGS` * 12).
 *     o Increased CPU usage - each log write requires a lookup in the set
 *       of configured modlog mappings.
 */

#ifndef H_MODLOG_
#define H_MODLOG_

#include "os/mynewt.h"
#include "log/log.h"

#define MODLOG_MODULE_DFLT      255

/**
 * @brief Modlog mapping descriptor.
 *
 * Describes an individual mapping of module ID to log.
 */
struct modlog_desc {
    /** The log being mapped. */
    struct log *log;

    /** Unique identifier for this mapping. */
    uint8_t handle;

    /** The numeric module ID being mapped. */
    uint8_t module;

    /** Log writes with a level less than this are discarded. */
    uint8_t min_level;
};

/** @typedef modlog_foreach_fn
 * @brief Function applied to each modlog mapping during a `modlog_foreach`
 *        traversal.
 *
 * @param desc                  The modlog mapping to operate on.
 * @param arg                   Optional user argument.
 *
 * @return                      0 if the traversal should continue;
 *                              nonzero to abort the traversal with the
 *                                  specified return code.
 */
typedef int modlog_foreach_fn(const struct modlog_desc *desc, void *arg);

/* Only enable modlog if logging is also enabled. */
#if MYNEWT_VAL(LOG_FULL) || defined(__DOXYGEN__)

/**
 * @brief Retrieves the modlog mapping with the specified handle.
 *
 * @param handle                The handle of the modlog mapping to retrieve.
 * @param out_desc              On success, the retrieved mapping is written
 *                                  here.  Pass NULL if you do not reqire this
 *                                  information.
 *
 * @return                      0 on success;
 *                              SYS_ENOENT if no mapping with the specified
 *                                  handle exists;
 *                              Other SYS_[...] error code on failure.
 */
int modlog_get(uint8_t handle, struct modlog_desc *out_desc);

/**
 * @brief Registers a new modlog mapping.
 *
 * @param module                The module to map to a log.
 * @param log                   The log to map.
 * @param min_level             Subsequent writes to this mapping with a level
 *                                  less than this value are discarded.
 * @param out_handle            On success, the new mapping's handle gets
 *                                  written here.  Pass NULL if you do not
 *                                  require this information.
 * 
 * @return                      0 on success;
 *                              SYS_ENOMEM on memory exhaustion.
 *                              Other SYS_[...] error on failure.
 */
int modlog_register(uint8_t module, struct log *log, uint8_t min_level,
                    uint8_t *out_handle);

/**
 * @brief Deletes the configured modlog mapping with the specified handle.
 *
 * @param handle                The handle of the mapping to delete.
 *
 * @return                      0 on success;
 *                              SYS_ENOENT if the specified handle is unmapped.
 *                              Other SYS_[...] error on failure.
 */
int modlog_delete(uint8_t handle);

/**
 * @brief Deletes all configured modlog mappings.
 */
void modlog_clear(void);

/**
 * @brief Writes the contents of a flat buffer to the specified log module.
 *
 * @param module                The log module to write to.
 * @param level                 The severity of the log entry to write.
 * @param etype                 The type of data being written; one of the
 *                                  `LOG_ETYPE_[...]` constants.
 * @param data                  The flat buffer to write.
 * @param len                   The number of bytes to write.
 *
 * @return                      0 on success; nonzero on failure.
 */
int modlog_append(uint8_t module, uint8_t level, uint8_t etype,
                  void *data, uint16_t len);

/**
 * @brief Writes the contents of an mbuf to the specified log module.
 *
 * @param module                The log module to write to.
 * @param level                 The severity of the log entry to write.
 * @param etype                 The type of data being written; one of the
 *                                  `LOG_ETYPE_[...]` constants.
 * @param om                    The mbuf to write.
 *
 * @return                      0 on success; nonzero on failure.
 */
int modlog_append_mbuf(uint8_t module, uint8_t level, uint8_t etype,
                       struct os_mbuf *om);

/**
 * @brief Applies a function to each configured modlog mapping.
 *
 * The callback is permitted to delete the mapping under operation.  No other
 * manipulations of the mapping list are allowed during the traversal.
 *
 * @param fn                    The function to apply to each modlog mapping.
 * @param arg                   Optional argument to pass to the callback.
 *
 * @return                      0 if the full iteration completed;
 *                              nonzero if the callback aborted the iteration.
 */
int modlog_foreach(modlog_foreach_fn *fn, void *arg);

/**
 * @brief Writes a formatted text entry to the specified log module.
 *
 * @param module                The log module to write to.
 * @param level                 The severity of the log entry to write.
 * @param msg                   The "printf" formatted string to write.
 */
void modlog_printf(uint8_t module, uint8_t level, const char *msg, ...);

#else /* LOG_FULL */

static inline int
modlog_get(uint8_t handle, struct modlog_desc *out_desc)
{
    return SYS_ENOTSUP;
}

static inline int
modlog_register(uint8_t module, struct log *log, uint8_t min_level,
                uint8_t *out_handle)
{
    return 0;
}

static inline int
modlog_delete(uint8_t handle)
{
    return SYS_ENOTSUP;
}

static inline void
modlog_clear(void)
{ }

static inline int
modlog_append(uint8_t module, uint8_t level, uint8_t etype, void *data,
              uint16_t len)
{
    return 0;
}

static inline int
modlog_append_mbuf(uint8_t module, uint8_t level, uint8_t etype,
                   struct os_mbuf *om)
{
    os_mbuf_free_chain(om);
    return 0;
}

static inline int
modlog_foreach(modlog_foreach_fn *fn, void *arg)
{
    return SYS_ENOTSUP;
}

static inline void
modlog_printf(uint8_t module, uint8_t level, const char *msg, ...)
{ }

#endif

#if MYNEWT_VAL(LOG_LEVEL) <= LOG_LEVEL_DEBUG || defined __DOXYGEN__
/**
 * @brief Writes a formatted debug text entry to the specified log module.
 *
 * This expands to nothing if the global log level is greater than
 * `LOG_LEVEL_DEBUG`.
 *
 * @param ml_mod_               The log module to write to.
 * @param ml_msg_               The "printf" formatted string to write.
 */
#define MODLOG_DEBUG(ml_mod_, ml_msg_, ...) \
    modlog_printf((ml_mod_), LOG_LEVEL_DEBUG, (ml_msg_), ##__VA_ARGS__)
#else
#define MODLOG_DEBUG(ml_mod_, ...) IGNORE(__VA_ARGS__)
#endif

#if MYNEWT_VAL(LOG_LEVEL) <= LOG_LEVEL_INFO || defined __DOXYGEN__
/**
 * @brief Writes a formatted info text entry to the specified log module.
 *
 * This expands to nothing if the global log level is greater than
 * `LOG_LEVEL_INFO`.
 *
 * @param ml_mod_               The log module to write to.
 * @param ml_msg_               The "printf" formatted string to write.
 */
#define MODLOG_INFO(ml_mod_, ml_msg_, ...) \
    modlog_printf((ml_mod_), LOG_LEVEL_INFO, (ml_msg_), ##__VA_ARGS__)
#else
#define MODLOG_INFO(ml_mod_, ...) IGNORE(__VA_ARGS__)
#endif

#if MYNEWT_VAL(LOG_LEVEL) <= LOG_LEVEL_WARN || defined __DOXYGEN__
/**
 * @brief Writes a formatted warn text entry to the specified log module.
 *
 * This expands to nothing if the global log level is greater than
 * `LOG_LEVEL_WARN`.
 *
 * @param ml_mod_               The log module to write to.
 * @param ml_msg_               The "printf" formatted string to write.
 */
#define MODLOG_WARN(ml_mod_, ml_msg_, ...) \
    modlog_printf((ml_mod_), LOG_LEVEL_WARN, (ml_msg_), ##__VA_ARGS__)
#else
#define MODLOG_WARN(ml_mod_, ...) IGNORE(__VA_ARGS__)
#endif

#if MYNEWT_VAL(LOG_LEVEL) <= LOG_LEVEL_ERROR || defined __DOXYGEN__
/**
 * @brief Writes a formatted error text entry to the specified log module.
 *
 * This expands to nothing if the global log level is greater than
 * `LOG_LEVEL_ERROR`.
 *
 * @param ml_mod_               The log module to write to.
 * @param ml_msg_               The "printf" formatted string to write.
 */
#define MODLOG_ERROR(ml_mod_, ml_msg_, ...) \
    modlog_printf((ml_mod_), LOG_LEVEL_ERROR, (ml_msg_), ##__VA_ARGS__)
#else
#define MODLOG_ERROR(ml_mod_, ...) IGNORE(__VA_ARGS__)
#endif

#if MYNEWT_VAL(LOG_LEVEL) <= LOG_LEVEL_CRITICAL || defined __DOXYGEN__
/**
 * @brief Writes a formatted critical text entry to the specified log module.
 *
 * This expands to nothing if the global log level is greater than
 * `LOG_LEVEL_CRITICAL`.
 *
 * @param ml_mod_               The log module to write to.
 * @param ml_msg_               The "printf" formatted string to write.
 */
#define MODLOG_CRITICAL(ml_mod_, ml_msg_, ...) \
    modlog_printf((ml_mod_), LOG_LEVEL_CRITICAL, (ml_msg_), ##__VA_ARGS__)
#else
#define MODLOG_CRITICAL(ml_mod_, ...) IGNORE(__VA_ARGS__)
#endif

/**
 * @brief Writes a formatted text entry with the specified level to the
 * specified log module.
 *
 * The provided log level must be one of the following tokens:
 *     o CRITICAL
 *     o ERROR
 *     o WARN
 *     o INFO
 *     o DEBUG
 *
 * This expands to nothing if the global log level is greater than
 * the specified level.
 *
 * @param ml_lvl_               The log level of the entry to write.
 * @param ml_mod_               The log module to write to.
 */
#define MODLOG(ml_lvl_, ml_mod_, ...) \
    MODLOG_ ## ml_lvl_((ml_mod_), __VA_ARGS__)

/**
 * @brief Writes a formatted text entry with the specified level to the
 * default log module.
 *
 * The provided log level must be one of the following tokens:
 *     o CRITICAL
 *     o ERROR
 *     o WARN
 *     o INFO
 *     o DEBUG
 *
 * This expands to nothing if the global log level is greater than
 * the specified level.
 *
 * @param ml_lvl_               The log level of the entry to write.
 */
#define MODLOG_DFLT(ml_lvl_, ...) \
    MODLOG(ml_lvl_, LOG_MODULE_DEFAULT, __VA_ARGS__)

/* If `MODLOG_LOG_MACROS` in enabled, retire the old `LOG_[...]` macros and
 * redefine them to use modlog.
 */
#if MYNEWT_VAL(MODLOG_LOG_MACROS)

#undef LOG_DEBUG
#define LOG_DEBUG       MODLOG_DEBUG

#undef LOG_INFO
#define LOG_INFO        MODLOG_INFO

#undef LOG_WARN
#define LOG_WARN        MODLOG_WARN

#undef LOG_ERROR
#define LOG_ERROR       MODLOG_ERROR

#undef LOG_CRITICAL
#define LOG_CRITICAL    MODLOG_CRITICAL

#undef LOG_DFLT
#define LOG_DFLT        MODLOG_DFLT

#endif

#endif