/*
 * printk.h - Kernel Log & debug messages API definition.
 *
 * authors  Alain Greiner (2016,2017,2018)
 *
 * Copyright (c) UPMC Sorbonne Universites
 *
 * This file is part of ALMOS-MKH.
 *
 * ALMOS-MKH is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by
 * the Free Software Foundation; version 2.0 of the License.
 *
 * ALMOS-MKH is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 */

///////////////////////////////////////////////////////////////////////////////////
// The printk.c and printk.h files define the functions used by the kernel
// to display messages on a text terminal.
// Two access modes are supported:
// - The printk() function displays kernel messages on the kernel terminal TXT0,
//   using a busy waiting policy: It calls directly the relevant TXT driver,
//   after taking the TXT0 chdev lock for exclusive access to the TXT0 terminal.
// - The user_printk() function displays messages on the calling thread private
//   terminal, using a descheduling policy: it register the request in the selected
//   TXT chdev waiting queue and deschedule. The calling thread is reactivated by
//   the IRQ signalling completion.
// Both functions use the generic TXT device to call the proper implementation
// dependant TXT driver.
// Finally these files define a set of conditional trace <***_dmsg> for debug.
///////////////////////////////////////////////////////////////////////////////////

#ifndef _PRINTK_H
#define _PRINTK_H

#include <hal_kernel_types.h>
#include <stdarg.h>

#include <hal_special.h> // hal_get_cycles()

/**********************************************************************************
 * This function build a formatted string.
 * The supported formats are defined below :
 *   %c : single character
 *   %d : signed decimal 32 bits integer
 *   %u : unsigned decimal 32 bits integer
 *   %x : hexadecimal 32 bits integer
 *   %l : hexadecimal 64 bits integer
 *   %s : NUL terminated character string
 **********************************************************************************
 * @ string     : pointer on target buffer (allocated by caller).
 * @ length     : target buffer length (number of bytes).
 * @ format     : format respecting the printf syntax.
 * @ returns the string length (including NUL) if success / return -1 if error.
 *********************************************************************************/
uint32_t snprintf( char     * string,
                   uint32_t   length,
                   char     * format, ... );

/**********************************************************************************
 * This function displays a formatted string on the kernel terminal TXT0,
 * using a busy waiting policy: It calls directly the relevant TXT driver,
 * after taking the TXT0 lock.
 **********************************************************************************
 * @ format     : formatted string.
 *********************************************************************************/
void printk( char* format, ... );

/**********************************************************************************
 * This function displays a formatted string on the kernel terminal TXT0,
 * using a busy waiting policy: It calls directly the relevant TXT driver,
 * without taking the TXT0 lock.
 **********************************************************************************
 * @ format     : formatted string.
 *********************************************************************************/
void nolock_printk( char* format, ... );


/**********************************************************************************
 * Private function designed to be called by the assert macro (below)
 **********************************************************************************
 * @ file_name     : File where the assert macro was invoked
 * @ function_name : Name of the calling function.
 * @ line          : Line number where the assert macro was invoked
 * @ cycle         : Cycle where the macro was invoked
 * @ format        : Formatted string
 * ...             : arguments of the format string
 *
 * See assert macro documentation for information about printed information.
 *********************************************************************************/
void __panic( const char * file_name,
              const char * function_name,
              uint32_t     line,
              cycle_t      cycle,
              const char * format, ... )
__attribute__((__noreturn__));

/**********************************************************************************
 * This macro displays a formated message on kernel TXT0 terminal,
 * and forces the calling core in sleeping mode if a Boolean condition is false.
 * Actually used to debug the kernel.
 *
 * Information printed by assert:
 * Current running thread:
 *   - thread descriptior adress
 *   - thread id (trdid)
 *
 * Current Process:
 *   - Process descriptor adress
 *   - Process id (pid)
 *
 * Current Core:
 *   - local cluster position (local_cxy)
 *   - local core id (lid)
 *
 * File name (__FILE__) and were the assert is invoked.
 * And the assert message.
 *
 * Cycle: before the assert branchment.
 * Note: cycle may change due to compiler optimisation.
 *
 * Exemple:
 * assert( my_ptr != NULL, "my_ptr should not be NULL")
 **********************************************************************************
 * @ condition     : condition that must be true.
 * @ format        : formatted string
 *********************************************************************************/
#define assert( expr, format, ... ) { uint32_t __line_at_expansion = __LINE__;    \
  const volatile cycle_t __assert_cycle = hal_get_cycles();                       \
  if ( ( expr ) == false ) {                                                      \
    __panic( __FILE__, __FUNCTION__,                                              \
             __line_at_expansion, __assert_cycle,                                 \
             ( format ), ##__VA_ARGS__ );                                         \
  }                                                                               \
}

/**********************************************************************************
 * This function displays a non-formated message on kernel TXT0 terminal.
 * This function is actually used to debug the assembly level kernel functions.
 **********************************************************************************
 * @ string   : non-formatted string.
 *********************************************************************************/
void puts( char * string );

/**********************************************************************************
 * This function displays a 32 bits value in hexadecimal on kernel TXT0 terminal.
 * This function is actually used to debug the assembly level kernel functions.
 **********************************************************************************
 * @ val   : 32 bits unsigned value.
 *********************************************************************************/
void putx( uint32_t val );

/**********************************************************************************
 * This function displays a 64 bits value in hexadecimal on kernel TXT0 terminal.
 * This function is actually used to debug the assembly level kernel functions.
 **********************************************************************************
 * @ val   : 64 bits unsigned value.
 *********************************************************************************/
void putl( uint64_t val );



/*  deprecated march 2018 [AG]

#if CONFIG_CHDEV_DEBUG
#define chdev_dmsg(...)   if(hal_time_stamp() > CONFIG_CHDEV_DEBUG) printk(__VA_ARGS__)
#else
#define chdev_dmsg(...)
#endif

#if CONFIG_CLUSTER_DEBUG
#define cluster_dmsg(...)   if(hal_time_stamp() > CONFIG_CLUSTER_DEBUG) printk(__VA_ARGS__)
#else
#define cluster_dmsg(...)
#endif

#if CONFIG_CONTEXT_DEBUG
#define context_dmsg(...)   if(hal_time_stamp() > CONFIG_CONTEXT_DEBUG) printk(__VA_ARGS__)
#else
#define context_dmsg(...)
#endif

#if CONFIG_CORE_DEBUG
#define core_dmsg(...)   if(hal_time_stamp() > CONFIG_CORE_DEBUG) printk(__VA_ARGS__)
#else
#define core_dmsg(...)
#endif

#if CONFIG_DEVFS_DEBUG
#define devfs_dmsg(...)   if(hal_time_stamp() > CONFIG_DEVFS_DEBUG) printk(__VA_ARGS__)
#else
#define devfs_dmsg(...)
#endif

#if CONFIG_DMA_DEBUG
#define dma_dmsg(...)   if(hal_time_stamp() > CONFIG_DMA_DEBUG) printk(__VA_ARGS__)
#else
#define dma_dmsg(...)
#endif

#if CONFIG_DQDT_DEBUG
#define dqdt_dmsg(...)   if(hal_time_stamp() > CONFIG_DQDT_DEBUG) printk(__VA_ARGS__)
#else
#define dqdt_dmsg(...)
#endif

#if CONFIG_ELF_DEBUG
#define elf_dmsg(...)   if(hal_time_stamp() > CONFIG_ELF_DEBUG) printk(__VA_ARGS__)
#else
#define elf_dmsg(...)
#endif

#if CONFIG_EXEC_DEBUG
#define exec_dmsg(...)   if(hal_time_stamp() > CONFIG_EXEC_DEBUG) printk(__VA_ARGS__)
#else
#define exec_dmsg(...)
#endif

#if CONFIG_EXCP_DEBUG
#define excp_dmsg(...)   if(hal_time_stamp() > CONFIG_EXCP_DEBUG) printk(__VA_ARGS__)
#else
#define excp_dmsg(...)
#endif

#if CONFIG_FATFS_DEBUG
#define fatfs_dmsg(...)   if(hal_time_stamp() > CONFIG_FATFS_DEBUG) printk(__VA_ARGS__)
#else
#define fatfs_dmsg(...)
#endif

#if CONFIG_FBF_DEBUG
#define fbf_dmsg(...)   if(hal_time_stamp() > CONFIG_FBF_DEBUG) printk(__VA_ARGS__)
#else
#define fbf_dmsg(...)
#endif

#if CONFIG_FORK_DEBUG
#define fork_dmsg(...)   if(hal_time_stamp() > CONFIG_FORK_DEBUG) printk(__VA_ARGS__)
#else
#define fork_dmsg(...)
#endif

#if CONFIG_GPT_DEBUG
#define gpt_dmsg(...)   if(hal_time_stamp() > CONFIG_GPT_DEBUG) printk(__VA_ARGS__)
#else
#define gpt_dmsg(...)
#endif

#if CONFIG_GRPC_DEBUG
#define grpc_dmsg(...)   if(hal_time_stamp() > CONFIG_GRPC_DEBUG) printk(__VA_ARGS__)
#else
#define grpc_dmsg(...)
#endif

#if CONFIG_IDLE_DEBUG
#define idle_dmsg(...)   if(hal_time_stamp() > CONFIG_IDLE_DEBUG) printk(__VA_ARGS__)
#else
#define idle_dmsg(...)
#endif

#if CONFIG_IOC_DEBUG
#define ioc_dmsg(...)   if(hal_time_stamp() > CONFIG_IOC_DEBUG) printk(__VA_ARGS__)
#else
#define ioc_dmsg(...)
#endif

#if CONFIG_IRQ_DEBUG
#define irq_dmsg(...)   if(hal_time_stamp() > CONFIG_IRQ_DEBUG) printk(__VA_ARGS__)
#else
#define irq_dmsg(...)
#endif

#if CONFIG_KCM_DEBUG
#define kcm_dmsg(...)   if(hal_time_stamp() > CONFIG_KCM_DEBUG) printk(__VA_ARGS__)
#else
#define kcm_dmsg(...)
#endif

#if CONFIG_KHM_DEBUG
#define khm_dmsg(...)   if(hal_time_stamp() > CONFIG_KHM_DEBUG) printk(__VA_ARGS__)
#else
#define khm_dmsg(...)
#endif

#if CONFIG_KILL_DEBUG
#define kill_dmsg(...)   if(hal_time_stamp() > CONFIG_KILL_DEBUG) printk(__VA_ARGS__)
#else
#define kill_dmsg(...)
#endif

#if CONFIG_KINIT_DEBUG
#define kinit_dmsg(...)   if(hal_time_stamp() > CONFIG_KINIT_DEBUG) printk(__VA_ARGS__)
#else
#define kinit_dmsg(...)
#endif

#if CONFIG_KMEM_DEBUG
#define kmem_dmsg(...)   if(hal_time_stamp() > CONFIG_KMEM_DEBUG) printk(__VA_ARGS__)
#else
#define kmem_dmsg(...)
#endif

#if CONFIG_MAPPER_DEBUG
#define mapper_dmsg(...)   if(hal_time_stamp() > CONFIG_MAPPER_DEBUG) printk(__VA_ARGS__)
#else
#define mapper_dmsg(...)
#endif

#if CONFIG_MMAP_DEBUG
#define mmap_dmsg(...)   if(hal_time_stamp() > CONFIG_MMAP_DEBUG) printk(__VA_ARGS__)
#else
#define mmap_dmsg(...)
#endif

#if CONFIG_MMC_DEBUG
#define mmc_dmsg(...)   if(hal_time_stamp() > CONFIG_MMC_DEBUG) printk(__VA_ARGS__)
#else
#define mmc_dmsg(...)
#endif

#if CONFIG_NIC_DEBUG
#define nic_dmsg(...)   if(hal_time_stamp() > CONFIG_NIC_DEBUG) printk(__VA_ARGS__)
#else
#define nic_dmsg(...)
#endif

#if CONFIG_PIC_DEBUG
#define pic_dmsg(...)   if(hal_time_stamp() > CONFIG_PIC_DEBUG) printk(__VA_ARGS__)
#else
#define pic_dmsg(...)
#endif

#if CONFIG_PPM_DEBUG
#define ppm_dmsg(...)   if(hal_time_stamp() > CONFIG_PPM_DEBUG) printk(__VA_ARGS__)
#else
#define ppm_dmsg(...)
#endif

#if CONFIG_PROCESS_DEBUG
#define process_dmsg(...)   if(hal_time_stamp() > CONFIG_PROCESS_DEBUG) printk(__VA_ARGS__)
#else
#define process_dmsg(...)
#endif

#if CONFIG_READ_DEBUG
#define read_dmsg(...)   if(hal_time_stamp() > CONFIG_READ_DEBUG) printk(__VA_ARGS__)
#else
#define read_dmsg(...)
#endif

#if CONFIG_RPC_DEBUG
#define rpc_dmsg(...)   if(hal_time_stamp() > CONFIG_RPC_DEBUG) printk(__VA_ARGS__)
#else
#define rpc_dmsg(...)
#endif

#if CONFIG_SCHED_DEBUG
#define sched_dmsg(...)   if(hal_time_stamp() > CONFIG_SCHED_DEBUG) printk(__VA_ARGS__)
#else
#define sched_dmsg(...)
#endif

#if CONFIG_SIGACTION_DEBUG
#define sigaction_dmsg(...)   if(hal_time_stamp() > CONFIG_SIGACTION_DEBUG) printk(__VA_ARGS__)
#else
#define sigaction_dmsg(...)
#endif

#if CONFIG_SYSCALL_DEBUG
#define syscall_dmsg(...)   if(hal_time_stamp() > CONFIG_SYSCALL_DEBUG) printk(__VA_ARGS__)
#else
#define syscall_dmsg(...)
#endif

#if CONFIG_THREAD_DEBUG
#define thread_dmsg(...)   if(hal_time_stamp() > CONFIG_THREAD_DEBUG) printk(__VA_ARGS__)
#else
#define thread_dmsg(...)
#endif

#if CONFIG_TXT_DEBUG
#define txt_dmsg(...)   if(hal_time_stamp() > CONFIG_TXT_DEBUG) printk(__VA_ARGS__)
#else
#define txt_dmsg(...)
#endif

#if CONFIG_VFS_DEBUG
#define vfs_dmsg(...)   if(hal_time_stamp() > CONFIG_VFS_DEBUG) printk(__VA_ARGS__)
#else
#define vfs_dmsg(...)
#endif

#if CONFIG_VMM_DEBUG
#define vmm_dmsg(...)   if(hal_time_stamp() > CONFIG_VMM_DEBUG) printk(__VA_ARGS__)
#else
#define vmm_dmsg(...)
#endif

#if CONFIG_WRITE_DEBUG
#define write_dmsg(...)   if(hal_time_stamp() > CONFIG_WRITE_DEBUG) printk(__VA_ARGS__)
#else
#define write_dmsg(...)
#endif

*/

#endif  // _PRINTK_H

// Local Variables:
// tab-width: 4
// c-basic-offset: 4
// c-file-offsets:((innamespace . 0)(inline-open . 0))
// indent-tabs-mode: nil
// End:
// vim: filetype=c:expandtab:shiftwidth=4:tabstop=4:softtabstop=4

