[PATCH] Creation of the Quick Start / Build Your Application section

[William]

Been sitting on this patch for a while now, figured I should finally 
submit it...

About a month ago I saw someone saying that they wanted to have this 
section of the users guide added in, followed all of the steps of the 
userguide up to the point just prior and then wrote this.

One thing to note, the GDB simulation did not work, I couldn't get it to 
link up to the SIS simulator (GDB didn't even know what `target sim` 
meant). That's why I have written on how to use SIS directly. No idea 
where I could track that problem down.

---
  user/start/app.rst | 88 
+++++++++++++++++++++++++++++++++++++++++++++++++++++-
  1 file changed, 87 insertions(+), 1 deletion(-)

diff --git a/user/start/app.rst b/user/start/app.rst
index fdf6bb7..7e87da8 100644
--- a/user/start/app.rst
+++ b/user/start/app.rst
@@ -8,4 +8,90 @@
  Build Your Application
  ======================

-TODO
+An RTEMS application is largely built the same as any other program 
using GCC.
+However, target specific flags will need to be presented to the 
compiler in
+order to build for your specific target. There are also some 
differences in
+symbols needed as part of a standard RTEMS application.
+
+At minimum, some features of RTEMS need to be configured. Configuration 
of the
+OS is achieved through a series of ``#define`` macros. The full list of
+options is in the RTEMS Classic API Guide - Configuring a System.
+
+.. code-block:: c
+
+    /* Includes the RTEMS OS Library */
+    #include <rtems.h>
+
+    /* Includes the BSP specific functions */
+    #include <bsp.h>
+
+    #include <stdio.h>
+
+    /* Enables the Console Driver for the application */
+    #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
+
+    /* Enables the Clock driver for the application */
+    #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
+
+    /* Initializes RTEMS Task System */
+    #define CONFIGURE_MAXIMUM_TASKS 1
+    #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
+    #define CONFIGURE_INIT
+
+    /* Applies the specified configuration */
+    #include <rtems/confdefs.h>
+
+    rtems_task Init(rtems_task_argument args){
+
+        printf("Welcome to RTEMS!\n");
+        fflush(stdout);
+
+        rtems_task_delete(RTEMS_SELF);
+
+    }
+
+In addition, the typical ``main`` symbol is overriden and the 
application code
+entry point is ``Init``, shown with the correct signature above. From that
+point the user application would take over control just like any other
+C / C++ program.
+
+To compile, invoke the installed RTEMS specific GCC with a series of 
special
+flags. Place the above sample file into ``quick-start.c``
+
+.. code-block:: none
+
+    $HOME/quick-start/rtems/5/bin/sparc-rtems5-gcc 
-B$HOME/quick-start/rtems/5/sparc-rtems5/erc32/lib/ -specs bsp_specs 
-qrtems -o quick-start.exe quick-start.c
+
+Keeping inline with the GCC compilation flag set, any extra or needed
+compilation flags can be passed in (e.g. floating point controls,
+profile, debugging, etc).
+
+To test the file, you can use the SPARC Instruction Simulator (SIS) 
that is
+built as part of the SPARC toolchain.
+
+.. code-block:: none
+
+    $HOME/quick-start/rtems/5/bin/sparc-rtems5-gcc quick-start.exe
+
+In the prompt type ``run`` and the simulator will start and execute the 
program
+
+.. code-block:: none
+
+    $HOME/quick-start/rtems/5/bin/sparc-rtems5-sis -erc32 quick-start.elf
+
+    SIS - SPARC/RISCV instruction simulator 2.20,  copyright Jiri 
Gaisler 2019
+    Bug-reports to jiri at gaisler.se
+
+    ERC32 emulation enabled
+
+    Loaded quick-start.elf, entry 0x02000000
+    sis> run
+    Welcome to RTEMS!
+
+Hit CTRL-C to break the simulation
+
+.. warning::
+
+    Sometimes the SIS simulator may start executing at a very low rate, 
in that
+    case use CTRL-C and then Enter to break the simulation, then use 
the 'cont'
+    command to resume execution at a higher rate
\ No newline at end of file
-- 
2.11.0

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20200319/26f1dcb4/attachment.html>