XCore console

Files CCore/inc/sys/SysCon.h CCore/src/sys/SysCon_general.cpp

XCore provides a number of tools to work with console input-output. A Target must implement the primary console class to support console.

/* GetPlanInitNode_...() */

PlanInitNode * GetPlanInitNode_SysCon();

/* consts */

enum ConInputResult
 {
  Con_Drop = 0,
  Con_Echo,
  Con_NoEcho,
  Con_EOL
 };

/* types */

using ConInputFunction = Function<ConInputResult (char)> ;

using ConOutputFunction = Function<void (NanoPacket<char> packet)> ;

/* functions */

NanoPacket<char> AllocConPacket(MSec timeout);

void ConWrite(NanoPacket<char> packet);

void EnablePacketCon();

void DisablePacketCon();

void ShowConStat();

GetPlanInitNode_SysCon is a PlanInit node of the primary console object. It is implemented by the Target.

ConInputResult is en enum. It is used to designate a desired action with the input character.

ConInputFunction is a Function. It is used to process an input character.

ConOutputFunction is a Function. It is used to process an output character NanoPacket.

AllocConPacket() allocates a NanoPacket to use it for console output. The argument is the timeout for the operation. If a packet cannot be allocated withing the given timeout the null is returned.

ConWrite() writes the NanoPacket to the console. The null value is allowed.

EnablePacketCon() turns on the packet console mode. You must not use this function directly, it is only for XCore.

DisablePacketCon() turns off the packet console mode. You must not use this function directly, it is only for XCore.

ShowConStat() prints console statistics. This function behavior is defined by the Target, it may do nothing.

/* class OwnConInput */

class OwnConInput : NoCopy
 {
   AntiSem asem;

  public:

   OwnConInput(TextLabel name,ConInputFunction input_any);

   ~OwnConInput();
 };

This class is used to install the input processing function. Constructor installs the function and destructor uninstalls it. The argument input_any is some input processing function. It may be called in any context. This function receives an input character and must return a value to indicate a desired response: Con_Drop to inform that character was discarded, Con_Echo to echo the character back, Con_NoEcho to suppress the echo and Con_EOL to echo end-of-line.

/* class HookConInput */

class HookConInput : NoCopy
 {
   ConInputFunction input_any;
   AntiSem *asem;

  public:

   HookConInput();

   ~HookConInput();

   ConInputResult operator () (char ch) { return input_any(ch); }
 };

This class is used to temporary hook the active console input function. It can be used to send an input character.

/* class RedirectCon */

class RedirectCon : NoCopy
 {
   AntiSem asem;

  public:

   RedirectCon(TextLabel name,ConOutputFunction output);

   ~RedirectCon();
 };

This class is used to install the console output processing function. Constructor installs the function and destructor uninstalls it. Being installed this function receives the output packets, instead a default console processing.

/* class HookConOutput */

class HookConOutput : NoCopy
 {
   ConOutputFunction output;
   AntiSem *asem;

  public:

   HookConOutput();

   ~HookConOutput();

   void operator () (NanoPacket<char> packet) { output(packet); }
 };

This class is used to temporary hook the console output and send the given packet(s) to the console.

/* class ConBase */

class ConBase : public Funchor_nocopy
 {
   ....

  private:

   // default input/output

   virtual void attachDefaultInput(ConInputFunction input_any)=0;

   virtual void detachDefaultInput()=0;

   virtual void defaultOutput(NanoPacket<char> packet)=0;

  public:

   // constructors

   static constexpr ulen MemLen(ulen max_data_len,ulen count) { return NanoPacket<char>::AllocLen(max_data_len)*count; }

   ConBase(TextLabel name,void *mem,ulen max_data_len,ulen count);

   ~ConBase();

   // methods

   unsigned getNoPacketCount();

   NanoPacket<char> alloc(MSec timeout);

   virtual void enablePacket()=0;

   virtual void disablePacket()=0;

   virtual void showStat()=0;

   // global object, defined in target

   static ConBase * GetObject();
 };

This is a base class for the Target-implemented primary console class. Target must define a drived class from ConBase and provide access to the global object of such class via the ConBase::GetObject() method. Here is a pattern how to do this. A derived class must implement the following pure virtual methods:

attachDefaultInput() attaches the given function to the default console input. Each time the user hit a key the attached function is called with the appropriate character as the argument. The return value is used to do some response.

detachDefaultInput() detaches the default console input from the input processing function.

defaultOutput() is the default console output. The argument may be null. This function send the packet payload to the console. It may do it immediately or put the packet into some packet queue for a further processing.

enablePacket() enables the packet mode of operation. This method is called by XCore after the core is up. After this point the console implementation may use the full power of XCore. Before this point only polling methods can be used to operate the console.

disablePacket() disables the packet mode of operation. This method is called by XCore before the shutdown the core. After this point the console implementation may not use tasks, interrupts and other core stuff to do the job.

showStat() prints the statistic counters. The meaning of the printed information is implementation-defined. This method may do nothing.

Other methods of the ConBase are:

Constructor takes the following arguments: name is the internal sync object name. mem is the address of a block of memory, must be aligned. This block is used to construct the internal packet pool. The block length can be calculated using the method MemLen(). max_data_len is the maximum data length of a nano-packet. count is the number of nano-packets in the packet pool.

MemLen() calculates the required length of the memory block.

getNoPacketCount() returns the number of no-packet events. No-packet event happens when the alloc() method fails.

alloc() allocates the nano-packet from the internal packet pool.