NEARLY_MANUAL.txt

================
Built-in Console
----------------
Built-in Console uses USART3 on STM32F103XXX board. To access it you need a USB to Serial TTL converter 
and connect to the board as below:

  .----------------------.                                              .------------------------.
  | STM32F103XX board    |             .-------------------.            |     PC or Computer     |
  | -------------------- |             | USB to Serial TTL |            | ---------------------- |
  |                      |             |     converter     |            |                        |
  |                      |             | ----------------- |            |                        |
  |                      |             |                   |            |                        |
  |   PB 10 (Serial 3 TX)+-------------+ RX pin        USB +------------+ USB (COMx)             |
  |                      |             |                   |            |                        |
  |   PB 11 (Serial 3 RX)+-------------+ TX pin            |            |                        |
  |                      |             |                   |            |                        |
  |                      |             `-------------------'            |                        |
  |                      |                                              |                        |
  `----------------------'                                              `------------------------'
  
Note the crossover connection between STM32F103XXX board and USB to Serial TTL.
PC recognizes USB to Serial TTL converter as serial port or COM port. Make sure USB to Serial 
TTL driver is installed to Windows if not already install. 
After physical connection established, you need a terminal program to to access console, e.g 
hyperterminal and Putty. Open that program and from the program open appropriate serial (COM) port. 
On Windows system the serial port name is COM1, COM2 and so on. Open it with parameters below:

1. Bits per seconds (baud rate)    : 921600 (This baud rate may not available for some USB-Serial 
                                     TTL converter)
2. Data bits                       : 8
3. Parity                          : None
4. Stop bits                       : 1
5. Flow control                    : None

If the port has successfully opened then press <Enter> and 
the terminal program should display:
--------------------------------------------

NanoOS Version 1.2 on Stm32f10XXX chipset.
System running at 72000000 Hz (72 MHz).
#>

--------------------------------------------
Note that NanoOS console is very simple console, don't provide AAA (Authorization, Authentication and
Accounting) and do not have 'command auto complete' on command line.

Here's the available commands on the console:
 ver                      to display version of NanoOS and console.
 help                     to display this help.
 exit                     to exit from console.
 led                      to run test LED.
 run [flash|sram]         to run application in flash or sram, the default is run in flash. Note that 
                          NanoOS application should be installed first, use ST-Link debugger and its 
                          utility software or use NTerminal to install it.
 thread [0|1|2|...]       to display thread(s) status.
 term [0|1|2|...]         to terminate thread id of 0, 1 and so on.
 suspend [0|1|2|...]      to suspend thread id of 0, 1 and so on.
 resume [0|1|2|...]       to resume thread id of 0, 1 and so on.
 stress                   to run simple stress test.
 lock_stress              to run simple stress test with lock.
 dump                     to display application binary data in flash.
 reset                    to reset this system.
 config [save|show|load]  to show, load and save NanoOS configuration. This is very limited configuration.
 auto_run [ena|dis]       to enable or disable application auto run. This mean application is loaded or 
                          executed or started right after system start up. Don't forget to save this config 
                          via 'config save' command. This configuration also tell NanoOS to automatically
                          run the application right after NanoOS application installation complete and success.
 app_priv [priv|unpriv]   to set application control: privileged or unprivileged. Setup application as 
                          privileged or unprivileged mode or control when it is running.
 debug                    to enter debug console (no switch back to current console).
 
Note that the built-in console can be used by NanoOS application to output a debug message which can be 
usefull for debugging the application, specially when building a graphical user interface.
NanoOS also has built-in debug console but with very minimum facility and it is just a viewer only. This
may usefull for debugging the NanoOS itself or the application. 
Here's the available debug commands:
 last_stack               to view 16 stacks of the last debug stack pointer if any. Exception handlers like 
                          system tick exception record this stack pointer.
 last_frame               to view last frame address, just like last debug stack pointer, this is recorded
                          byte exception handler.
 thread [0|1|2|...]       to view thread slot and its parameters such as thread id and status.
 stack [0|1|2|...]        to view stack slot (memory to be used as stack) of a thread from start to last stack
                          pointer of thread stack.
 mem_cfg                  to view memory usage, but for now only view system SRAM usage and system stack size 
                          (available SRAM to be used as system stack).
 reset                    to reset the chip.
 param                    to view trap code when NanoOS encounter unhandled exception or unexpected processor's
                          execution in debug mode.
 exc_prio                 to view exception and interrupt priority of current system.


============================
USB Serial I/O (NanoOS Port)
----------------------------
NanoOS has USB Serial I/O interface to communicate to the outside world. To a PC this is virtual serial port.
This interface is designed for NanoOS application to communicate with a program on PC. On Windows system it 
uses usbser.sys so no need to write a special driver for it. When plugged to Windows on PC for the first time 
you will be asked to provide a driver for it. You can use NanoOSPort.inf (included in this distribution) and 
direct the installation process to this file and everything should be OK.

!!!! WARNING !!!!
   This USB Serial I/O use 'anonymous' or 'unregistered' PID and VID, thus could conflict with other USB device 
   that uses the same PID and VID in the system.
   
If the installation success Window will give the name of the device with COM1 or COM2 or COM3 and so on. Check 
with device manager on Windows it should show Deka's NanoOS Port (COM5). Note that COM number may be different
from one computer to another computer. When a program want to use this port, it open this with with given name
above and with parameters below:

1. Bits per seconds (baud rate)    : 921600
2. Data bits                       : 8
3. Parity                          : None
4. Stop bits                       : 1
5. Flow control                    : None

NanoOS itself doesn't realy care about the parameters above but since this serial port use usbser.sys of 
Window it require you to provide the parameters above when you want to access it. This port can be accessed 
with terminal progam such as hyperterminal or putty and from those programs you can get input-ouput of 
NanoOS application which run on NanoOS. You can also use your own program on PC to communicate with NanoOS 
application via this port too.


===========================
NanoOS Terminal (NTerminal)
---------------------------
NTerminal is a program specifically to access some NanoOS resources. It has:
- Simple terminal to access Built-in console of NanoOS.
- Simple terminal to communicate with NanoOS application.
- Simple virtual display that simulate LCD touch screen or similar device.
- Facility to install NanoOS application.
- Facility to install NanoOS Port service to share NanoOS Port amongs processes.
- Facility to generate Visual Studio C++ 2008 Express Edition solution and/or project for NanoOS Application.
Currently only run on Windows XP.

To use NTerminal establish a physical connection like this:

  .----------------------.                                              .------------------------.
  | STM32F103XX board    |             .-------------------.            |     PC or Computer     |
  | -------------------- |             | USB to Serial TTL |            | ---------------------- |
  |                      |             |     converter     |            |                        |
  |                      |             | ----------------- |            |                        |
  |                      |             |                   |            |                        |
  |   PB 10 (Serial 3 TX)+-------------+ RX pin        USB +------------+ USB (COMx)             |
  |                      |             |                   |            |                        |
  |   PB 11 (Serial 3 RX)+-------------+ TX pin            |            |                        |
  |                      |             |                   |            |                        |
  |                      |             `-------------------'            |                        |
  |     USB (Micro-B)    |                                              |           USB          |
  `----------+-----------'                                              `------------+-----------'
             |                                                                       |
             |                                                                       |
             `--------------------------- USB Cable ---------------------------------'

This is the same as connecting to console above but use additional USB connection from board to PC
as additional connection.

To connect to built-in console, on the menu, click Application - Console - COMx. Note that COMx is
the name of USB-Serial TTL on PC. If success then press <Enter> as the Built-in console section 
mentioned above. If error, console window will tell what the error is. Check the connection and try 
to unplug and plug USB-Serial TTL and then try to open it again. If still error, well you probably
need to change USB-Serial TTL product to another USB-Serial TTL product.

For the NanoOSs USB Serial I/O, NTerminal will 'auto detect' it. Window text of USB Serial IO window
will tell you whether the NanoOSs USB Serial IO device is connected. Try to unplug and plug the board
from PC and let see if USB Serial IO's window text change from connected to disconnected and then 
connected again when you plug USB Serial IO.

If you want to use virtual display, on the menu click 'Options' - 'NanoOS Port' - 'Virtual Display'. 
Checkbox should be displayed in the Enable VDisplay menu item. And also VDisplay window will turn to 
black. If NanoOSs USB Serial IO connected the window of VDisplay will tell you that the device is 
connected. Please see VDispTest project that use this virtual display as an output if you want to use
it.

NTerminal can be used to install NanoOS application, on the menu click 'Application' - 'Install App...' 
and then a dialog box should shows up and let you choose what application file to be installed. Click OK 
when you have choosen the file and if everything work well, the console window will show the progress of 
installation process. If you want to cancel the installation process, on the menu just click 
'Application' - 'Cancel install'. Note that application can't be 'uninstalled' but if need to 'uninstalled'
it just write a dummy application and then install it to NanoOS.

In the NTerminal NanoOS Port or USB Serial IO can be disabled and let the PC application who use the NanoOS 
Port library can use it. Note that USB Serial IO can only be accessed only one PC application (or process) at 
a time because it is basically a serial (COM) port device. To disable the NanoOS Port in the NTerminal, on
the menu click 'Options' - 'NanoOS Port' - 'Disable'.

To install NPortSvc service, on the menu, click 'Options' - 'NanoOS Port Service' - 'Install' and when open file
dialog box appears locate NPortSvc.exe, choose it and click OK. The result, success or failure, will be displayed
in the console terminal. This installation don't start service automatically, to start NPortSvc service, on the menu, 
click 'Options' - 'NanoOS Port Service' - 'Start' and as the installation process, the result will be displayed in 
console terminal. Notice that starting NPortSvc service will disable access to NanoOS Port from NTerminal in the 
other word NTerminal can not access NanosOS Port anymore. If you want to enable access to NanoOS Port from NTerminal
just stop the NPortSvc from menu 'Options' - 'NanoOS Port Service' - 'Stop'. Note that most of service operations 
such as install and start service require administrator privilege.

To generate NanoOS Application Solution/Project in Visual Studio C++ 2008 Express Edition, on the menu, click; 
'Application' - 'Generate NApplication Project...'. And then complete dialogbox input when it appears.


==========================
Writing NanoOS application
--------------------------
In NanoOS you can safely think that you are in a single process with one or more thread. A thread can run on 
privileged or unprivileged mode, on privileged mode you can can access Cortex-M processor peripheral like SCB, 
SYSTICK and so on. Note that when you change those peripherals you may change NanoOS characteristic thus NanoOS 
may not run correctly. On unprivileged mode you don't have that access. Note that NanoOS currently doesn't 
support float variable type and variable type that has size larger than 32 bits such as long long and double.

This manual using Visual Studio 2008 Express Edition to write a simple application and here's step by step
how to start a simple Hello world program in NanoOS;

1. From Visual C++ create new `Makefile Project` on a directory and name the project and its solution as
   you want, for example, the project directory is D:\Dev and the project/solution name is Hello. Click OK
   and then accept the default option when dialog box wizzard appears and then click finish. Visual C++ will 
   create a directory named D:\Dev and in that directory will contain Hello.sln (solution file) and
   Hello directory. Hello directory will contain Hello.vcproj (project file).
   
2. Add new source file, in this example add a new file named Hello.c and write code like this:
   (or you can copy this codes to Hello.c in NanoOS source tree).
   ----------------------------------
   #include "NanoOSApi.h"
   
   int main(int argc, char * argv[])
   {
       Printf("Hello world.\r\n", 0);
       return 0;
   }
   ----------------------------------
   In this example we will create a hello world program and using NanoOS API, when using NanoOS API you need
   to include NanoOSApi.h. Note that arguments in main() is 0 or null, for now they are just 'accessories'.
   
3. Copy Makefile file from <directory where NanoOS packect is extracted>\Src\Application\Hello to current project
   directory, in this example <directory where NanoOS packect extracted> is D:\Dev\NanoOS and current project
   directory is D:\Dev\Hello\Hello, so in this example, copy Makefile file from D:\Dev\NanoOS\Src\Application\Hello 
   to D:\Dev\Hello\Hello.
   
4. Copy NanoApp.ld file from <directory where NanoOS packect extracted>\Src\Application to current project 
   directory, in this example <directory where NanoOS packect extracted> is D:\Dev\NanoOS and current project 
   directory is D:\Dev\Hello\Hello, so in this example, copy NanoApp.ld file from D:\Dev\NanoOS\Src\Application to 
   D:\Dev\Hello\Hello.
   
5. Add those 2 files (Makefile and NanoApp.ld) to current project.

6. Open or edit Makefile and then adjust some macros, (note that in this example the NanoOS packect is 
   extracted to directory D:\Dev\NanoOS and the project directory is D:\Dev\Hello\Hello).
   Set macro OUT_DIR to D:\Dev\Hello\Hello\Bin :
      OUT_DIR = D:\Dev\Hello\Hello\Bin
   Set macro SRCS_DIR to D:\Dev\Hello\Hello :
      SRCS_DIR = D:\Dev\Hello\Hello
   Set macro INCLUDE to D:\Dev\NanoOS\Src\Application :
      INCLUDE = D:\Dev\NanoOS\Src\Application
   Set macro GCC_BIN_DIR to D:\Dev\gcc (note that in this example gcc.exe, cc1.exe etc. in D:\Dev\gcc directory) :
      GCC_BIN_DIR = D:\Dev\gcc
   And then save this file.
   Note that in the Makefile file there is additional NanoApi.c to compile, this because we use NanoOS API.
   
7. Setup project build command: right click Hello project and then click `Properties`, in the 
   `Configuration Properties` choose `NMake` and then setup these parameters:
   Build Command Line       : nmake /nologo _DEBUG=1 all
   Rebuild All Command Line : nmake /nologo _DEBUG=1 rebuild
   Clean Command Line       : nmake /nologo _DEBUG=1 clean
   Note that the above comands is for debug target, for release target remove the _DEBUG=1 from that line.
   
8. Now we're ready to build the project, just right the `Hello' project then click Build. If success it will produce
   Hello.bin and Hello.elf to directory D:\Dev\Hello\Hello\Bin and you can install Hello.bin file to NanoOS. You 
   can use NTerminal for this (please see NTerminal above) or you can use STLink debugger and its utility (please 
   see BUILD_INSTALL.txt).
   
Alternatively you can start from the included project in NanoOS directory called Hello. This is more or less the 
same as the above example. Or you can use NTerminal to generate simple NanoOS Application Solution and/or Project
in Microsoft Visual Studio C++ 2008 Express Edition and start from there.

If you want to run this application in SRAM, use NanoAppSRAM.ld instead of NanoApp.ld in step 4 and also please see
the sample project named RunInSRAM. Note that the binary files may not fits in SRAM because SRAM size is only 10K 
bytes for application to use and that include global variables defined by application if any.

If you need to use NanoOS functions directly, include NanoOS.h from NanoOS source directory into your source and use 
NanoOS.elf as 'some short of library' by adding switch -R in the LINK_OPTS macro of Makefile, in the above example 
it should look like:
-----------------------------------------
...
LINK_OPTS			= \
                      -RNanoOS.elf\
					  --gc-sections\
					  -TNanoApp.ld\
					  -o$(OUT_DIR)\$(ELF)
...
-----------------------------------------
The NanoOS.elf is produced when building NanoOS (please see BUID_INSTALL.txt) and copy this file to your current
project directory. This is usefull when you want to handle an interrupt from some I/O controller in the chip since
NanoOS API doesn't support to be called in exception or interrupt handler. Note that not all function in the 
NanoOS.h suitable for the application.


=================================
Writing NanoOS Application In C++
---------------------------------
Although NanoOS support C++ but does has some notes:
1. NanoOS doesn't support dynamic memory allocation.
2. NanoOS initialize and de-initialize global object (call constructor and destructor of global objects) 
   in the main thread only.
3. NanoOS may not initialize and/or de-initialize global object because of resource limitation, in this case SRAM,
   and there is no warning about this.
4. NanoOS currently doesn't support float variable type and variable type that longer 32 bits such as long long 
   and double.

Writing application in C++ on NanoOS is basically the same as writing application in C on NanoOS (please see the 
above section: 'Writing NanoOS Application'). In addition you need to copy g++.exe and cc1plus.exe file to GCC_BIN_DIR,
in the above example GCC_BIN_DIR is D:\Dev\gcc, and then use Makefile in the source tree to compile C++ code.
For a start please take a look to NanoStd project included in NanoOS solution. This project demonstrate how to write 
application in C++. It create some short of standard input and output using USB Serial IO, so user can 'communicate'
with the program through it. Alternatively you can start a project by generate C++ solution and/or project of Visual
Studio 2008 Express Edition.
Since NanoOS don't provide dynamic memory allocation, application can't use 'new' and 'delete' operator 'blindly'. To 
overcome that, use the class as some short variable in the global and/or local space, as the following example:
In the header file define a class and state an object that already allocated in the other source file or in the 
implementation file.
+------------------------------------------+
// File: Test.h
// Desc.: Test class definition

class Test
{
private:
	int	i;
	
public:
	Test();
	~Test();
	void Set(int a);
};

extern Test	TestInst1;	// Tell the compiler that there is an already allocated object in the other 
						// source file such as implementation file.
...
+-----------------------------------------+

In the implemenation file you declare an object, Test object in this case, as global variable, as follows:
+-----------------------------------------+
// File : Test.cpp
// Desc. : Implementation of Test class

Test TestInst1;		// declare this to allocate Test object as TestInst1 variable

Test::Test() 
{
	i = 0;
}

Test::~Test() {}

void Test::Set(int a) 
{
	i = a;
}
...
+----------------------------------------+

In this way, if you want to use Test class in another source file, just include the header, Test.h, and 
then use TestInst1 as follows:
+----------------------------------------+
...
#include "Test.h"

int main(int argc, char *argv[])
{
	TestInst1.Set(20);
	return 20;
}
...
+----------------------------------------+

Or alternatively, declare another object if you don't want to use currently allocated object as follows:
+----------------------------------------+
...
#include "Test.h"

Test	TestInts2;		// declare Test obejct as TestInst2 variable

int main(int argc, char *argv[])
{
	TestInst2.Set(20);
	return 20;
}
...
+----------------------------------------+

Please note that if every time you declare new object as variable, it will consume more resources,
which you probably don't want to because you have relatively small resources.
If, for some reason, you want to use 'new' and 'delete' operator, overload 'new' and 'delete' operator
with relevan procedure. For example you can implement 'single instance object' model that everytime you 
use or call 'new' operator it will point to the same already declared or allocated object as the following
examples:
Define a class in a header:
+----------------------------------------+
// File: Test.h
// Desc.: Test class definition

class Test
{
private:
	int	i;
	
public:
	Test();
	~Test();
	void Set(int a);
	
	void *operator new(unsigned int uiSize);	// Overload new operator
	void operator delete(void * pObj);			// Overload delete operator
};
...
+----------------------------------------+

And the Test class implemtation as follows:
+----------------------------------------+
// File : Test.cpp
// Desc. : Implementation of Test class

Test TestInst1;		// declare this to allocate Test object as TestInst1 variable

/*
 * return the pointer to currently allocated object (TestInst1)
 */
void * Test::operator new(unsigned int uiSize)
{
	return (void *) &TestInst1;
}

/* No need deletion procedure (just 'empty' function), because this is 'single instance object' model */
void Test::operator delete(void *pObj)
{
}
...
+----------------------------------------+

To be more clear, please take a look a project called UsbIo in NanoOS solution. This project purpose is
to create some short of interface between PC application and the controllers available on chipset. This 
project use that 'single instance object' model above.

NanoOS only call global objects constructor and destructor in main thread only. This mean if main thread 
exits the object may not valid anymore, because the main thread calls destructor when exit eventhough the 
object still exist in the memory (SRAM) as the Test class in the example above. This may become trouble 
when another thread is still using them. There are some ways to overcome this. One is try not to exit the 
main thread while another thread is still using it, this must done in the codes. Way two is if you write 
a class and you instantiate as global variable ensure you does nothing in the constructor and/or destructor 
and, if required, write additional functions to initialize and deinitialize the object as replacement of 
contructor and destructor respectively so threads can optionally call them. Note that NanoOS is currently 
thread oriented system rather than process oriented system and C++ seems to aim to process oriented system.

NanoOS has no direct support for C++ RTTI (Run Time Type Information) and exception. Those features need
a specific implementation in a mechanism such as library. Since NanoOS currently has no concept of library
the implementation can be written down in to the source code. TInfo and Exception project in this distribution
show that kind of implementation. TInfo project implement RTTI and Exception project implement exception.
Note that Exception implementation need RTTI implementation. They are very simple implementations and just
satisfying the compiler rather than complying with standard ABI. Also may not work on some untested cases.


============================================================
Using NanoOS Port Library (NPortLib.lib and/or NPortLib.dll)
------------------------------------------------------------
Actually PC application or program can access NanoOS Port directly through COM or serial port provided by operating 
system but NPortLib provide an easier way to do that and offer callback mechanism for system or programming language
which support callback mechanism such as C# on Windows.
To use NPortLib:
1. Include NPortLib.h in you source code.
2. Call the function provided by NPortLib.h.
3. Compile and link against the NPortLib.lib.
If your system and/or programming language support dynamic library loading, e.g. LoadLibrary()/FreeLibrary(), you 
can skip the step 3 above. Note that in run time, you still need NPortLib.dll in both cases, make sure your binary 
can access this dll. Please see NPortLibTest project included in this packet for more.

In the source code call NPL_Open() and provide callback parameters if required to start using NanoOS Port and then 
later on call NPL_Close() when you have finished using it. The NPL_Open() will activate NanoOS Port detection, when 
NanoOS Port is connected it will automatically open NanoOS Port and when disconnected it will automatically close 
NanoOS Port. When you provide 'data received callback' parameter in the call to NPL_Open() the library will call
this callback when it receive a data from NanoOS Port, if not you have to read from NanoOS Port 'manually' via 
NPL_Read() if required. Note that NPL_Read() will always fail if 'data receive callback' is set. Please see 
NPortLibTest project included in this distribution for more. Also note that NPL_Open() can fail too if other PC 
application (or process), such as NTerminal, already open the NanoOS Port.

NPortLib provide installer functions to install NanoOS application on NanoOS port. Make sure NanoOS port is 
connected and opened before you call NPL_InstallNApplication(), call NPL_IsOpened() to do this if you don't provide 
'connection change callback' when you call NPL_Open(). NPL_InstallNApplication() is asynchronous call, it will run 
in the 'backgroud' or another thread. If you don't provide 'progress callback' when you call it, you can call 
NPL_IsInstalling() to query or check if installer is running. You can also cancel currently running installer by 
using NPL_CancelInstall(). Note that cancelling currently running installer will leave application segment on NanoOS 
unexecutable (can't be executed by NanoOS), and there is no 'roll-back' operation. If you want to handle error in 
a callback, provide a 'error callback' when you call NPL_Open(), this callback will be triggered when error occured 
on NanoOS port. If you want to run the NanoOS application right after the installation complete and success, set the
'auto_run' to 'ena' and then save the configuration in the NanoOS Built-in console, please see 'Built-in Console' 
section above.

In addition, NPortLib provide access to NPortSvc service, a service that share NanoOS Port so it can be accessed from
multiple processes. Please see NPortLib.h and the NPortSvcTest project for more. Note that this is simple service and 
don't provide a security mechanism or facility.