// Copyright 2020 The Pigweed Authors
//
// Licensed 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
//
//     https://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.
#pragma once

#include <assert.h>
#include <stddef.h>
#include <stdint.h>

#include "pw_preprocessor/compiler.h"
#include "pw_preprocessor/concat.h"
#include "pw_preprocessor/macro_arg_count.h"
#include "pw_preprocessor/util.h"
#include "pw_tokenizer/internal/argument_types.h"
#include "pw_tokenizer/internal/tokenize_string.h"

// Tokenizes a string literal and converts it to a pw_TokenizerStringToken. This
// expression can be assigned to a local or global variable, but cannot be used
// in another expression. For example:
//
//   constexpr uint32_t global = PW_TOKENIZE_STRING("Wow!");  // This works.
//
//   void SomeFunction() {
//     constexpr uint32_t token = PW_TOKENIZE_STRING("Cool!");  // This works.
//
//     DoSomethingElse(PW_TOKENIZE_STRING("Lame!"));  // This does NOT work.
//   }
//
#define PW_TOKENIZE_STRING(string_literal) \
  _PW_TOKENIZE_LITERAL_UNIQUE(__COUNTER__, string_literal)

// Encodes a tokenized string and arguments to the provided buffer. The size of
// the buffer is passed via a pointer to a size_t. After encoding is complete,
// the size_t is set to the number of bytes written to the buffer.
//
// The macro's arguments are equivalent to the following function signature:
//
//   TokenizeToBuffer(void* buffer,
//                    size_t* buffer_size_pointer,
//                    const char* format,
//                    ...);  /* printf-style arguments */
//
// For example, the following encodes a tokenized string with a temperature to a
// buffer. The buffer is passed to a function to send the message over a UART.
//
//   uint8_t buffer[32];
//   size_t size_bytes = sizeof(buffer);
//   PW_TOKENIZE_TO_BUFFER(
//       buffer, &size_bytes, "Temperature (C): %0.2f", temperature_c);
//   MyProject_EnqueueMessageForUart(buffer, size);
//
#define PW_TOKENIZE_TO_BUFFER(buffer, buffer_size_pointer, format, ...) \
  do {                                                                  \
    _PW_TOKENIZE_STRING(format, __VA_ARGS__);                           \
    pw_TokenizeToBuffer(buffer,                                         \
                        buffer_size_pointer,                            \
                        _pw_tokenizer_token,                            \
                        PW_TOKENIZER_ARG_TYPES(__VA_ARGS__)             \
                            PW_COMMA_ARGS(__VA_ARGS__));                \
  } while (0)

// Encodes a tokenized string and arguments to a buffer on the stack. The
// provided callback is called with the encoded data. The size of the
// stack-allocated argument encoding buffer is set with the
// PW_TOKENIZER_CFG_ENCODING_BUFFER_SIZE_BYTES option.
//
// The macro's arguments are equivalent to the following function signature:
//
//   TokenizeToCallback(void (*callback)(const uint8_t* data, size_t size),
//                      const char* format,
//                      ...);  /* printf-style arguments */
//
// For example, the following encodes a tokenized string with a sensor name and
// floating point data. The encoded message is passed directly to the
// MyProject_EnqueueMessageForUart function, which the caller provides as a
// callback.
//
//   void MyProject_EnqueueMessageForUart(const uint8_t* buffer,
//                                        size_t size_bytes) {
//     uart_queue_write(uart_instance, buffer, size_bytes);
//   }
//
//   void LogSensorValue(const char* sensor_name, float value) {
//     PW_TOKENIZE_TO_CALLBACK(MyProject_EnqueueMessageForUart,
//                             "%s: %f",
//                             sensor_name,
//                             value);
//   }
//
#define PW_TOKENIZE_TO_CALLBACK(callback, format, ...)        \
  do {                                                        \
    _PW_TOKENIZE_STRING(format, __VA_ARGS__);                 \
    pw_TokenizeToCallback(callback,                           \
                          _pw_tokenizer_token,                \
                          PW_TOKENIZER_ARG_TYPES(__VA_ARGS__) \
                              PW_COMMA_ARGS(__VA_ARGS__));    \
  } while (0)

// Encodes a tokenized string and arguments to a buffer on the stack. The buffer
// is passed to the user-defined pw_TokenizerHandleEncodedMessage function. The
// size of the stack-allocated argument encoding buffer is set with the
// PW_TOKENIZER_CFG_ENCODING_BUFFER_SIZE_BYTES option.
//
// The option PW_TOKENIZER_CFG_ENABLE_TOKENIZE_TO_GLOBAL_HANDLER must be enabled
// in order to use this macro. When that option is enabled, the
// pw_TokenizerHandleEncodedMessage function *MUST* be defined by the user of
// pw_tokenizer.
//
// The macro's arguments are equivalent to the following function signature:
//
//   TokenizeToGlobalHandler(const char* format,
//                           ...);  /* printf-style arguments */
//
// For example, the following encodes a tokenized string with a value returned
// from a function call. The encoded message is passed to the caller-defined
// pw_TokenizerHandleEncodedMessage function.
//
//   void OutputLastReadSize() {
//     PW_TOKENIZE_TO_GLOBAL_HANDLER("Read %u bytes", ReadSizeBytes());
//   }
//
//   void pw_TokenizerHandleEncodedMessage(const uint8_t encoded_message[],
//                                         size_t size_bytes) {
//     MyProject_EnqueueMessageForUart(buffer, size_bytes);
//   }
//
#if PW_TOKENIZER_CFG_ENABLE_TOKENIZE_TO_GLOBAL_HANDLER

#define PW_TOKENIZE_TO_GLOBAL_HANDLER(format, ...)                 \
  do {                                                             \
    _PW_TOKENIZE_STRING(format, __VA_ARGS__);                      \
    pw_TokenizeToGlobalHandler(_pw_tokenizer_token,                \
                               PW_TOKENIZER_ARG_TYPES(__VA_ARGS__) \
                                   PW_COMMA_ARGS(__VA_ARGS__));    \
  } while (0)

// If PW_TOKENIZER_CFG_ENABLE_TOKENIZE_TO_GLOBAL_HANDLER is set, this function
// must be defined by the user of pw_tokenizer. This function is called with the
// encoded message by pw_TokenizeToGlobalHandler.
PW_EXTERN_C void pw_TokenizerHandleEncodedMessage(
    const uint8_t encoded_message[], size_t size_bytes);

// This function encodes the tokenized strings. Do not call it directly;
// instead, use the PW_TOKENIZE_TO_GLOBAL_HANDLER macro.
PW_EXTERN_C void pw_TokenizeToGlobalHandler(pw_TokenizerStringToken token,
                                            pw_TokenizerArgTypes types,
                                            ...);

#else  // PW_TOKENIZE_TO_GLOBAL_HANDLER is not available

#define PW_TOKENIZE_TO_GLOBAL_HANDLER(...)                                    \
  static_assert(0,                                                            \
                "PW_TOKENIZER_CFG_ENABLE_TOKENIZE_TO_GLOBAL_HANDLER must be " \
                "set to 1 to use PW_TOKENIZE_TO_GLOBAL_HANDLER")

#endif  // PW_TOKENIZER_CFG_ENABLE_TOKENIZE_TO_GLOBAL_HANDLER

// Like PW_TOKENIZE_TO_GLOBAL_HANDLER, encodes a tokenized string and arguments
// to a buffer on the stack. The macro adds a payload argument, which is passed
// through to the global handler function
// pw_TokenizerHandleEncodedMessageWithPayload, which must be defined by the
// user of pw_tokenizer. The payload type is specified by the
// PW_TOKENIZER_CFG_PAYLOAD_TYPE option and defaults to void*.
//
// For example, the following tokenizes a log string and passes the log level as
// the payload.
/*
     #define LOG_ERROR(...) \
         PW_TOKENIZE_TO_GLOBAL_HANDLER_WITH_PAYLOAD(kLogLevelError, __VA_ARGS__)

     void pw_TokenizerHandleEncodedMessageWithPayload(
         pw_TokenizerPayload log_level,
         const uint8_t encoded_message[],
         size_t size_bytes) {
       if (log_level >= kLogLevelWarning) {
         MyProject_EnqueueMessageForUart(buffer, size_bytes);
       }
     }
 */
#if PW_TOKENIZER_CFG_ENABLE_TOKENIZE_TO_GLOBAL_HANDLER

#define PW_TOKENIZE_TO_GLOBAL_HANDLER_WITH_PAYLOAD(payload, format, ...)      \
  do {                                                                        \
    _PW_TOKENIZE_STRING(format, __VA_ARGS__);                                 \
    pw_TokenizeToGlobalHandlerWithPayload(payload,                            \
                                          _pw_tokenizer_token,                \
                                          PW_TOKENIZER_ARG_TYPES(__VA_ARGS__) \
                                              PW_COMMA_ARGS(__VA_ARGS__));    \
  } while (0)

typedef PW_TOKENIZER_CFG_PAYLOAD_TYPE pw_TokenizerPayload;

// If PW_TOKENIZER_CFG_ENABLE_TOKENIZE_TO_GLOBAL_HANDLER_WITH_PAYLOAD is set,
// this function must be defined by the user of pw_tokenizer. This function is
// called with the encoded message by pw_TokenizeToGlobalHandler and a
// caller-provided payload argument.
PW_EXTERN_C void pw_TokenizerHandleEncodedMessageWithPayload(
    pw_TokenizerPayload payload,
    const uint8_t encoded_message[],
    size_t size_bytes);

// This function encodes the tokenized strings. Do not call it directly;
// instead, use the PW_TOKENIZE_TO_GLOBAL_HANDLER_WITH_PAYLOAD macro.
PW_EXTERN_C void pw_TokenizeToGlobalHandlerWithPayload(
    pw_TokenizerPayload payload,
    pw_TokenizerStringToken token,
    pw_TokenizerArgTypes types,
    ...);

#else  // PW_TOKENIZE_TO_GLOBAL_HANDLER_WITH_PAYLOAD is not available

#define PW_TOKENIZE_TO_GLOBAL_HANDLER_WITH_PAYLOAD(...)                    \
  static_assert(0,                                                         \
                "PW_TOKENIZER_CFG_ENABLE_TOKENIZE_TO_GLOBAL_HANDLER_WITH_" \
                "PAYLOAD must be set to 1 to use "                         \
                "PW_TOKENIZE_TO_GLOBAL_HANDLER_WITH_PAYLOAD")

#endif  // PW_TOKENIZER_CFG_ENABLE_TOKENIZE_TO_GLOBAL_HANDLER_WITH_PAYLOAD

PW_EXTERN_C_START

// These functions encode the tokenized strings. These should not be called
// directly. Instead, use the corresponding PW_TOKENIZE_TO_* macros above.
void pw_TokenizeToBuffer(void* buffer,
                         size_t* buffer_size_bytes,  // input and output arg
                         pw_TokenizerStringToken token,
                         pw_TokenizerArgTypes types,
                         ...);

void pw_TokenizeToCallback(void (*callback)(const uint8_t* encoded_message,
                                            size_t size_bytes),
                           pw_TokenizerStringToken token,
                           pw_TokenizerArgTypes types,
                           ...);

// This empty function allows the compiler to check the format string.
inline void pw_TokenizerCheckFormatString(const char* format, ...)
    PW_PRINTF_FORMAT(1, 2);

inline void pw_TokenizerCheckFormatString(const char* format, ...) {
  PW_UNUSED(format);
}

PW_EXTERN_C_END

// These macros implement string tokenization. They should not be used directly;
// use one of the PW_TOKENIZE_* macros above instead.
#define _PW_TOKENIZE_LITERAL_UNIQUE(id, string_literal)                     \
  /* assign to a variable */ PW_TOKENIZER_STRING_TOKEN(string_literal);     \
                                                                            \
  /* Declare without nested scope so this works in or out of a function. */ \
  static _PW_TOKENIZER_CONST char PW_CONCAT(                                \
      _pw_tokenizer_string_literal_DO_NOT_USE_THIS_VARIABLE_,               \
      id)[] _PW_TOKENIZER_SECTION(id) = string_literal

// This macro uses __COUNTER__ to generate an identifier to use in the main
// tokenization macro below. The identifier is unique within a compilation unit.
#define _PW_TOKENIZE_STRING(format, ...) \
  _PW_TOKENIZE_STRING_UNIQUE(__COUNTER__, format, __VA_ARGS__)

// This macro takes a printf-style format string and corresponding arguments. It
// checks that the arguments are correct, stores the format string in a special
// section, and calculates the string's token at compile time.
// clang-format off
#define _PW_TOKENIZE_STRING_UNIQUE(id, format, ...)                            \
  if (0) { /* Do not execute to prevent double evaluation of the arguments. */ \
    pw_TokenizerCheckFormatString(format PW_COMMA_ARGS(__VA_ARGS__));          \
  }                                                                            \
                                                                               \
  /* Check that the macro is invoked with a supported number of arguments. */  \
  static_assert(                                                               \
      PW_ARG_COUNT(__VA_ARGS__) <= PW_TOKENIZER_MAX_SUPPORTED_ARGS,            \
      "Tokenized strings cannot have more than "                               \
      PW_STRINGIFY(PW_TOKENIZER_MAX_SUPPORTED_ARGS) " arguments; "             \
      PW_STRINGIFY(PW_ARG_COUNT(__VA_ARGS__)) " arguments were used for "      \
      #format " (" #__VA_ARGS__ ")");                                          \
                                                                               \
  /* Declare the format string as an array in the special tokenized string */  \
  /* section, which should be excluded from the final binary. Use unique   */  \
  /* names for the section and variable to avoid compiler warnings.        */  \
  static _PW_TOKENIZER_CONST char PW_CONCAT(                                   \
      _pw_tokenizer_format_string_, id)[] _PW_TOKENIZER_SECTION(id) = format;  \
                                                                               \
  /* Tokenize the string to a pw_TokenizerStringToken at compile time. */      \
  _PW_TOKENIZER_CONST pw_TokenizerStringToken _pw_tokenizer_token =            \
      PW_TOKENIZER_STRING_TOKEN(format)

// clang-format on

#ifdef __cplusplus  // use constexpr for C++
#define _PW_TOKENIZER_CONST constexpr
#else  // use const for C
#define _PW_TOKENIZER_CONST const
#endif  // __cplusplus

// _PW_TOKENIZER_SECTION places the format string in a special .tokenized.#
// linker section. Host-side decoding tools read the strings from this section
// to build a database of tokenized strings.
//
// This section should be declared as type INFO so that it is excluded from the
// final binary. To declare the section, as well as the .tokenizer_info section,
// used for tokenizer metadata, add the following to the linker
// script's SECTIONS command:
//
//   .tokenized 0x00000000 (INFO) :
//   {
//     KEEP(*(.tokenized))
//     KEEP(*(.tokenized.*))
//   }
//
//   .tokenizer_info 0x00000000 (INFO) :
//   {
//     KEEP(*(.tokenizer_info))
//   }
//
// Any address could be used for this section, but it should not map to a real
// device to avoid confusion. 0x00000000 is a reasonable default. An address
// such as 0xFF000000 that is outside of the ARMv7m memory map could also be
// used.
//
// A linker script snippet that provides these sections is provided in the file
// tokenizer_linker_sections.ld. This file may be directly included into
// existing linker scripts.
//
// The tokenized string sections can also be managed without linker script
// modifications, though this is not recommended. The section can be extracted
// and removed from the ELF with objcopy:
//
//   objcopy --only-section .tokenize* <ORIGINAL_ELF> <OUTPUT_ELF>
//   objcopy --remove-section .tokenize* <ORIGINAL_ELF>
//
// OUTPUT_ELF will be an ELF with only the tokenized strings, and the original
// ELF file will have the sections removed.
//
// Without the above linker script modifications, the section garbage collection
// option (--gc-sections) removes the tokenized string sections. To avoid
// editing the target linker script, a separate metadata ELF can be linked
// without --gc-sections to preserve the tokenized data.
#define _PW_TOKENIZER_SECTION(unique) \
  PW_KEEP_IN_SECTION(PW_STRINGIFY(PW_CONCAT(.tokenized., unique)))