// vim: set noet ts=4 sw=4:

/*! \file
 *  \brief Debug macros enabling debug output on a separate window for each
 * core.
 */

#pragma once
#include "../types.h"

/*! \def DBG_VERBOSE
 * \brief An output stream, which is only displayed in the debug window in
 * verbose mode
 *
 * \note If a serial console has been implemented, the output can be redirected
 *       to the serial stream instead (by changing the macro) -- this makes the
 *       (usually) very large output more readable (since it allows scrolling
 * back)
 */
#ifdef VERBOSE
// If VERBOSE is defined, forward everything to \ref DBG
#define DBG_VERBOSE DBG
#else
// Otherwise sent everything to the NullStream (which will simply discard
// everything)
#define DBG_VERBOSE nullstream
// in this case we have to include the null stream
#include "./nullstream.h"
#endif

/*! \def DBG
 *  \brief An output stream, which is displayed in the debug window of the core
 * it was executed on
 *
 * In single core (\OOStuBS) this is just an alias to the debug window object
 * `dout`.
 */
/*! However, on a multi core system a debug window for each core is
 * required, therefore `dout` has to be an \ref TextStream object array with the
 * core ID as array index  -- the selection is done via Core::getID()
 *
 * \warning In case of a very unfavorable scheduling, it is theoretically
 *          possible that the debug output in a multi core system is displayed
 *          on the wrong (previous) core.
 */

#include "../arch/core.h"
#include "../device/textstream.h"
#define DBG *copyout[Core::getID()]

/*! \brief Debug window for the CGA screen
 *
 * Debug output using \ref DBG like
 *      `DBG << "var = " << var << endl`
 * should be displayed in window dedicated to the core it is executed on.
 *
 * While this is quite easy on single core systems like \OOStuBS -- they only
 * require a single \ref TextStream object called `dout` -- multi core systems
 * like \MPStuBS need an object array with one window per core.
 * In the latter case direct list initialization can be used:
 *
 * \code{.cpp}
 *  TextStream dout[Core::MAX]{
 *     {0, 40, 17, 21},   // Debug window for core 0, like TextStream(0, 40, 17,
 * 21) {40, 80, 17, 21},  // Debug window for core 1, like TextStream(40, 80,
 * 17, 21)
 *     //...
 *   };
 * \endcode
 *
 * The debug windows in should be located right below the normal output window
 * without any overlap and should be able to display at least 3 lines.
 * In \MPStuBS, two windows can be placed side-by-side, having 40 columns each.
 *
 */
extern TextStream dout[Core::MAX];

/*! \brief Debug window with copy function to serial
 *
 * Provide an additional layer to also ouput debug prints to serial.
 * While this is a simple CopyStream pointer in the single core case, it is
 * an array in the multi core case, which consists of three TextStreams and
 * one CopyStream.
 * For that, construction is done like:
 * \todo(11) Define `copyout`
 *
 * \code{.cpp}
 *  OutputStream* copyout[Core::MAX]{&dout[0], &dout[1], ...}
 * \endcode
 *
 */
extern OutputStream* copyout[Core::MAX];