6.1 minor release

ports_smp/linux/gnu/readme_threadx.txt

@@ -0,0 +1,155 @@
+                         Microsoft's Azure RTOS ThreadX SMP for Linux 
+
+                              Using the GNU GCC Tools
+
+1.  Building the ThreadX SMP run-time Library
+
+First make sure you are in the "example_build" directory. Also, make sure that
+you have setup your path and other environment variables necessary for the GNU
+development environment. The following command retrieves and installs GCC
+multilib on a Ubuntu system:
+ 
+sudo apt-get install gcc-multilib
+
+At this point you may run the GNU make command to build the ThreadX SMP core 
+library. This will build the ThreadX SMP run-time environment in the 
+"example_build" directory. 
+
+   make tx.a
+
+you should now observe the compilation of the ThreadX SMP library source. At the 
+end of the make, they are all combined into the run-time library file: tx.a.
+This file must be linked with your application in order to use ThreadX.
+ 
+
+2.  Demonstration System
+
+Building the demonstration is easy; simply execute the GNU make command while 
+inside the "example_build" directory. 
+
+   make sample_threadx
+
+You should observe the compilation of sample_threadx.c (which is the demonstration 
+application) and linking with tx.a. The resulting file DEMO is a binary file 
+that can be executed.
+
+
+3.  System Initialization
+
+The system entry point is at main(), which is defined in the application. 
+Once the application calls tx_kernel_enter, ThreadX SMP starts running and 
+performs various initialization duties prior to starting the scheduler. The 
+Linux-specific initialization is done in the function _tx_initialize_low_level,
+which is located in the file tx_initialize_low_level.c. This function is 
+responsible for setting up various system data structures and simulated 
+interrupts - including the periodic timer interrupt source for ThreadX.
+
+In addition, _tx_initialize_low_level determines the first available 
+address for use by the application. In Linux, this is basically done
+by using malloc to get a big block of memory from Linux.
+
+
+4.  Linux Implementation
+
+ThreadX SMP for Linux is implemented using POSIX pthreads. Each application
+thread in ThreadX SMP actually runs as a Linux pthread. The determination of
+which application thread to run is made by the ThreadX SMP scheduler, which 
+itself is a Linux pthread. The ThreadX SMP scheduler is the highest priority 
+thread in the system.
+
+Interrupts in ThreadX_SMP Linux are also simulated by pthreads. A good example
+is the ThreadX SMP system timer interrupt, which can be found in 
+tx_initialize_low_level.c.
+
+ThreadX SMP for linux utilizes the API pthread_setschedparam() which requires
+the ThreadX SMP application running with privilege. The following command is used
+to run a ThreadX SMP application:
+
+./sample_threadx
+
+5.  Improving Performance
+
+The distribution version of ThreadX SMP is built without any compiler 
+optimizations. This makes it easy to debug because you can trace or set 
+breakpoints inside of ThreadX SMP itself. Of course, this costs some 
+performance. To make it run faster, you can change the makefile to 
+enable all compiler optimizations. In addition, you can eliminate the 
+ThreadX SMP basic API error checking by compiling your application code with the 
+symbol TX_DISABLE_ERROR_CHECKING defined.
+
+
+6.  Interrupt Handling
+
+ThreadX SMP provides simulated interrupt handling with Linux pthreads. Simulated
+interrupt threads may be created by the application or may be added to the
+simulated timer interrupt defined in tx_initialize_low_level.c. The following 
+format for creating simulated interrupts should be used:
+
+6.1  Data structures
+
+Here is an example of how to define the Linux data structures and prototypes
+necessary to create a simulated interrupt thread:
+
+pthread_t    _sample_linux_interrupt_thread;
+void        *_sample_linux_interrupt_entry(void *p);
+
+6.2  Creating a Simulated Interrupt Thread
+
+Here is an example of how to create a simulated interrupt thread in Linux.
+This may be done inside of tx_initialize_low_level.c or from your application code
+
+
+struct sched_param sp;
+
+       /* Create the ISR thread */
+       pthread_create(&_sample_linux_interrupt_thread, NULL, _sample_linux_interrupt_entry, &_sample_linux_interrupt_thread);
+
+       /* Set up the ISR priority */
+       sp.sched_priority = TX_LINUX_PRIORITY_ISR;
+       pthread_setschedparam(_sample_linux_interrupt_thread, SCHED_FIFO, &sp);
+
+
+
+6.3  Simulated Interrupt Thread Template
+
+The following is a template for the simulated interrupt thread. This interrupt will occur on
+a periodic basis. 
+
+void    *_sample_linux_interrupt_entry(void *p)
+{
+struct timespec ts;
+
+    while(1)
+    {
+
+        ts.tv_sec = 0;
+        ts.tv_nsec = 10000;
+        while(nanosleep(&ts, &ts));
+
+        /* Call ThreadX SMP context save for interrupt preparation.  */
+        _tx_thread_context_save();
+
+        /* Call the real ISR routine */
+        _sample_linux_interrupt_isr();
+
+        /* Call ThreadX SMP context restore for interrupt completion.  */
+        _tx_thread_context_restore();
+    } 
+}
+
+
+
+7.  Revision History
+
+For generic code revision information, please refer to the readme_threadx_generic.txt
+file, which is included in your distribution. The following details the revision
+information associated with this specific port of ThreadX:
+
+09-30-2020  Initial ThreadX SMP 6.1 version for Linux using GNU GCC tools.
+
+
+Copyright(c) 1996-2020 Microsoft Corporation
+
+
+https://azure.com/rtos
+