From 5d6ecfa3ca2c20eb8faec94a2041c0fd8c7b74c1 Mon Sep 17 00:00:00 2001 From: Gregory Nutt Date: Tue, 17 Oct 2017 06:25:46 -0600 Subject: [PATCH] Update a document, a README, and some comments. --- Documentation/NXGraphicsSubsystem.html | 214 ++++++++++++++++++------- configs/sim/README.txt | 125 ++++++++++----- graphics/nxmu/nx_start.c | 5 - include/nuttx/nx/nx.h | 5 - 4 files changed, 237 insertions(+), 112 deletions(-) diff --git a/Documentation/NXGraphicsSubsystem.html b/Documentation/NXGraphicsSubsystem.html index 0c5f3dd356..3a58de35fc 100644 --- a/Documentation/NXGraphicsSubsystem.html +++ b/Documentation/NXGraphicsSubsystem.html @@ -12,7 +12,7 @@

NX Graphics Subsystem

-

Last Updated: October 15, 2017

+

Last Updated: October 17, 2017

@@ -90,40 +90,47 @@

@@ -921,9 +928,94 @@ struct nx_callback_s }; -

2.3.3 NX Server Callbacks

+

2.3.3 Starting the NX Server

+

+ The NX Server is a kernel daemon that receives and serializes graphic commands. + Before you can use the NX graphics system, you must first start this daemon. + There are two ways that this can be done: +

+
    +
  1. +

    + The NX server may be started in your board startup logic by simply calling the function nx_start(). + The board startup logic usually resides the the configs/board/src directory. + The boar board startup logic can run automatically during the early system if CONFIG_BOARD_INITIALIZE is defined in the configuration. + Or, the board startup logic can execute under control of the application by calling the boardctl(BOARDIOC_INIT, arg) OS interface. +

    +

    + The board initialization logic will run in either case and the simple call to nx_start() will start the NX server. +

    +
    2. +
  2. + The NX server may also be started later by the application via the boardctl(BOARDIOC_NX_START, arg) +
    3. +
-

2.3.3.1 redraw()

+

2.3.3.1 nx_start()

+

Function Prototype:

+
    +#include <nuttx/nx/nx.h>
+
+int nx_start(void);
+
+

+ Description: + nx_start() provides a wrapper function to simplify and standardize the starting of the NX server. +

+

+ Input Parameters: + None +

+

+ Returned Value: + Zero (OK) is returned on success. + This indicates that the NX server has been successfully started, is running, and waiting to accept connections from NX clients. +

+

+ A negated errno value is returned on failure. + The errno value indicates the nature of the failure. +

+ +

2.3.3.1 boardctl()

+

Function Prototype:

+
    +#include <sys/boardctl.h>
+
+
+

+ Description: + boardctl() is a generic NuttX interface that among many of it functions, may also be used to start the NX server. +

+ In a small embedded system, there will typically be a much greater interaction between application and low-level board features. + The canonically correct to implement such interactions is by implementing a character driver and performing the interactions via low level ioctl() calls. + This, however, may not be practical in many cases and will lead to "correct" but awkward implementations. +

+

+ boardctl() is non-standard OS interface to alleviate the problem. + It basically circumvents the normal device driver ioctl interlace and allows the application to perform direction IOCTL-like calls to the board-specific logic. + In it is especially useful for setting up board operational and test configurations. +

+

+ When called with the cmd of BOARDIOC_NX_START, then the boardctl() will call nx_start indirectly on behalf of the appication. + In this case the arg parameter is ignored. +

+

+ Input Parameters: +

    +
    cmd +
    Identifies the board command to be executed +
    arg +
    The argument that accompanies the command. The nature of the argument is determined by the specific command. +
+

+

+ Returned Value: + On success zero (OKERROR) is returned on failure with the errno variable to to indicate the nature of the failure. +

+ +

2.3.4 NX Server Callbacks

+ +

2.3.4.1 redraw()

Callback Function Prototype:

     void redraw(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
@@ -952,7 +1044,7 @@ void redraw(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
   Returned Value: None
 
    
 
-
    2.3.3.2 position()
    
+
    2.3.4.2 position()
    
 
    Callback Function Prototype:
    
 
       void position(NXWINDOW hwnd, FAR const struct nxgl_size_s *size,
@@ -986,7 +1078,7 @@ void position(NXWINDOW hwnd, FAR const struct nxgl_size_s *size,
   Returned Value: None
 
      
 
-
      2.3.3.3 mousein()
      
+
      2.3.4.3 mousein()
      
 
      Callback Function Prototype:
      
 
         #ifdef CONFIG_NX_XYINPUT
@@ -1016,7 +1108,7 @@ void mousein(NXWINDOW hwnd, FAR const struct nxgl_point_s *pos,
   Returned Value: None
 
        
 
-
        2.3.3.4 kbdin()
        
+
        2.3.4.4 kbdin()
        
 
        Callback Function Prototype:
        
 
           #ifdef CONFIG_NX_KBD
@@ -1045,7 +1137,7 @@ void (*kbdin)(NXWINDOW hwnd, uint8_t nch, FAR const uint8_t *ch, FAR void *arg);
   Returned Value: None
 
          
 
-
          2.3.4 nx_runinstance() (and nx_run() macro)
          
+
          2.3.5 nx_runinstance() (and nx_run() macro)
          
 
          Function Prototype:
          
 
             #include <nuttx/nx/nxglib.h>
@@ -1082,7 +1174,7 @@ int nx_runinstance(FAR const char *mqname, FAR struct fb_vtable_s *fb);
   return ERROR and errno will be set appropriately.
 
            
 
-
            2.3.5 nx_connectinstance() (and nx_connect() macro)
            
+
            2.3.6 nx_connectinstance() (and nx_connect() macro)
            
 
            Function Prototype:
            
 
               #include <nuttx/nx/nxglib.h>
@@ -1131,7 +1223,7 @@ NXHANDLE nx_connectinstance(FAR const char *svrmqname);
     Failure:  NULL is returned and errno is set appropriately.
 
            
 
-
            2.3.6 nx_disconnect()
            
+
            2.3.7 nx_disconnect()
            
 
            Function Prototype:
            
 
               #include <nuttx/nx/nxglib.h>
@@ -1155,7 +1247,7 @@ void nx_disconnect(NXHANDLE handle);
   Returned Value: None.
 
              
 
-
              2.3.7 nx_eventhandler()
              
+
              2.3.8 nx_eventhandler()
              
 
              Function Prototype:
              
 
                 #include <nuttx/nx/nxglib.h>
@@ -1199,7 +1291,7 @@ int nx_eventhandler(NXHANDLE handle);
   
 
              
 
-
              2.3.8 nx_eventnotify()
              
+
              2.3.9 nx_eventnotify()
              
 
              Function Prototype:
              
 
                 #include <nuttx/nx/nxglib.h>
@@ -1245,7 +1337,7 @@ int nx_eventnotify(NXHANDLE handle, int signo);
   ERROR on failure with errno set appropriately
 
                
 
-
                2.3.9 nx_openwindow()
                
+
                2.3.10 nx_openwindow()
                
 
                Function Prototype:
                
 
                   #include <nuttx/nx/nxglib.h>
@@ -1277,7 +1369,7 @@ NXWINDOW nx_openwindow(NXHANDLE handle,
     Failure:  NULL is returned and errno is set appropriately.
 
                
 
-
                2.3.10 nx_closewindow()
                
+
                2.3.11 nx_closewindow()
                
 
                Function Prototype:
                
 
                   #include <nuttx/nx/nxglib.h>
@@ -1305,7 +1397,7 @@ int nx_closewindow(NXWINDOW hwnd);
   ERROR on failure with errno set appropriately
 
                  
 
-
                  2.3.11 nx_requestbkgd()
                  
+
                  2.3.12 nx_requestbkgd()
                  
 
                  Function Prototype:
                  
 
                     #include <nuttx/nx/nxglib.h>
@@ -1375,7 +1467,7 @@ int nx_requestbkgd(NXHANDLE handle,
   ERROR on failure with errno set appropriately
 
                    
 
-
                    2.3.12 nx_releasebkgd()
                    
+
                    2.3.13 nx_releasebkgd()
                    
 
                    Function Prototype:
                    
 
                       #include <nuttx/nx/nxglib.h>
@@ -1405,7 +1497,7 @@ int nx_releasebkgd(NXWINDOW hwnd);
   ERROR on failure with errno set appropriately
 
                      
 
-
                      2.3.13 nx_getposition()
                      
+
                      2.3.14 nx_getposition()
                      
 
                      Function Prototype:
                      
 
                         #include <nuttx/nx/nxglib.h>
@@ -1433,7 +1525,7 @@ int nx_getposition(NXWINDOW hwnd);
   ERROR on failure with errno set appropriately
 
                        
 
-
                        2.3.14 nx_setposition()
                        
+
                        2.3.15 nx_setposition()
                        
 
                        Function Prototype:
                        
 
                           #include <nuttx/nx/nxglib.h>
@@ -1462,7 +1554,7 @@ int nx_setposition(NXWINDOW hwnd, FAR struct nxgl_point_s *pos);
   ERROR on failure with errno set appropriately
 
                          
 
-
                          2.3.15 nx_setsize()
                          
+
                          2.3.16 nx_setsize()
                          
 
                          Function Prototype:
                          
 
                             #include <nuttx/nx/nxglib.h>
@@ -1490,7 +1582,7 @@ int nx_setsize(NXWINDOW hwnd, FAR struct nxgl_size_s *size);
   ERROR on failure with errno set appropriately
 
                            
 
-
                            2.3.16 nx_raise()
                            
+
                            2.3.17 nx_raise()
                            
 
                            Function Prototype:
                            
 
                               #include <nuttx/nx/nxglib.h>
@@ -1518,7 +1610,7 @@ int nx_raise(NXWINDOW hwnd);
   ERROR on failure with errno set appropriately
 
                              
 
-
                              2.3.17 nx_lower()
                              
+
                              2.3.18 nx_lower()
                              
 
                              Function Prototype:
                              
 
                                 #include <nuttx/nx/nxglib.h>
@@ -1546,7 +1638,7 @@ int nx_lower(NXWINDOW hwnd);
   ERROR on failure with errno set appropriately
 
                                
 
-
                                2.3.18 nx_fill()
                                
+
                                2.3.19 nx_fill()
                                
 
                                Function Prototype:
                                
 
                                   #include <nuttx/nx/nxglib.h>
@@ -1577,7 +1669,7 @@ int nx_fill(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
   ERROR on failure with errno set appropriately
 
                                  
 
-
                                  2.3.19 nx_getrectangle()
                                  
+
                                  2.3.20 nx_getrectangle()
                                  
 
                                  Function Prototype:
                                  
 
                                     #include <nuttx/nx/nxglib.h>
@@ -1617,7 +1709,7 @@ void nx_getrectangle(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
   ERROR on failure with errno set appropriately
 
                                    
 
-
                                    2.3.20 nx_filltrapezoid()
                                    
+
                                    2.3.21 nx_filltrapezoid()
                                    
 
                                    Function Prototype:
                                    
 
                                       #include <nuttx/nx/nxglib.h>
@@ -1651,7 +1743,7 @@ int nx_filltrapezoid(NXWINDOW hwnd, FAR const struct nxgl_rect_s *clip,
   ERROR on failure with errno set appropriately
 
                                      
 
-
                                      2.3.21 nx_drawline()
                                      
+
                                      2.3.22 nx_drawline()
                                      
 
                                      Function Prototype:
                                      
 
                                         #include <nuttx/nx/nxglib.h>
@@ -1699,7 +1791,7 @@ int nx_drawline(NXWINDOW hwnd, FAR struct nxgl_vector_s *vector,
   ERROR on failure with errno set appropriately
 
                                        
 
-
                                        2.3.22 nx_drawcircle()
                                        
+
                                        2.3.23 nx_drawcircle()
                                        
 
                                        Function Prototype:
                                        
 
                                           #include <nuttx/nx/nxglib.h>
@@ -1735,7 +1827,7 @@ int nx_drawcircle(NXWINDOW hwnd, FAR const struct nxgl_point_s *center,
   ERROR on failure with errno set appropriately
 
                                          
 
-
                                          2.3.23 nx_fillcircle()
                                          
+
                                          2.3.24 nx_fillcircle()
                                          
 
                                          Function Prototype:
                                          
 
                                             #include <nuttx/nx/nxglib.h>
@@ -1768,7 +1860,7 @@ int nx_fillcircle(NXWINDOW hwnd, FAR const struct nxgl_point_s *center,
   ERROR on failure with errno set appropriately
 
                                            
 
-
                                            2.3.24 nx_setbgcolor()
                                            
+
                                            2.3.25 nx_setbgcolor()
                                            
 
                                            Function Prototype:
                                            
 
                                               #include <nuttx/nx/nxglib.h>
@@ -1796,7 +1888,7 @@ int nx_setbgcolor(NXHANDLE handle,
   ERROR on failure with errno set appropriately
 
                                              
 
-
                                              2.3.25 nx_move()
                                              
+
                                              2.3.26 nx_move()
                                              
 
                                              Function Prototype:
                                              
 
                                                 #include <nuttx/nx/nxglib.h>
@@ -1827,7 +1919,7 @@ int nx_move(NXWINDOW hwnd, FAR const struct nxgl_rect_s *rect,
   ERROR on failure with errno set appropriately
 
                                                
 
-
                                                2.3.26 nx_bitmap()
                                                
+
                                                2.3.27 nx_bitmap()
                                                
 
                                                Function Prototype:
                                                
 
                                                   #include <nuttx/nx/nxglib.h>
@@ -1869,7 +1961,7 @@ int nx_bitmap(NXWINDOW hwnd, FAR const struct nxgl_rect_s *dest,
   ERROR on failure with errno set appropriately
 
                                                  
 
-
                                                  2.3.27 nx_kbdin()
                                                  
+
                                                  2.3.28 nx_kbdin()
                                                  
 
                                                  Function Prototype:
                                                  
 
                                                     #include <nuttx/nx/nxglib.h>
@@ -1892,7 +1984,7 @@ int nx_kbdin(NXHANDLE handle, uint8_t nch, FAR const uint8_t *ch);
   ERROR on failure with errno set appropriately
 
                                                    
 
-
                                                    2.3.28 nx_mousein()
                                                    
+
                                                    2.3.29 nx_mousein()
                                                    
 
                                                    Function Prototype:
                                                    
 
                                                       #include <nuttx/nx/nxglib.h>
diff --git a/configs/sim/README.txt b/configs/sim/README.txt
index 6e3b880451..6c826bc1d3 100644
--- a/configs/sim/README.txt
+++ b/configs/sim/README.txt
@@ -12,6 +12,7 @@ Contents
     - 64-bit Issues
     - Compiler differences
     - Stack Size Issues
+    - Symbol Collisions
     - Networking Issues
     - X11 Issues
     - Cygwin64 Issues
@@ -24,20 +25,21 @@ Overview
 
 Description
 -----------
-This README file describes the contents of the build configurations available
-for the NuttX "sim" target.  The sim target is a NuttX port that runs as a
-user-space program under Linux or Cygwin.  It is a very "low fidelity" embedded
-system simulation: This environment does not support any kind of asynchronous
-events -- there are nothing like interrupts in this context.  Therefore, there
-can be no pre-empting events.
+This README file describes the contents of the build configurations
+available for the NuttX "sim" target.  The sim target is a NuttX port that
+runs as a user-space program under Linux or Cygwin.  It is a very "low
+fidelity" embedded system simulation:  This environment does not support
+any kind of asynchronous events -- there are nothing like interrupts in this
+context.  Therefore, there can be no pre-empting events.
 
 Fake Interrupts
 ---------------
-In order to get timed behavior, the system timer "interrupt handler" is called
-from the sim target's IDLE loop.  The IDLE runs whenever there is no other task
-running.  So, for example, if a task calls sleep(), then that task will suspend
-wanting for the time to elapse.  If nothing else is available to run, then the
-IDLE loop runs and the timer increments, eventually re-awakening the sleeping task.
+In order to get timed behavior, the system timer "interrupt handler" is
+called from the sim target's IDLE loop.  The IDLE runs whenever there is no
+other task running.  So, for example, if a task calls sleep(), then that
+task will suspend wanting for the time to elapse.  If nothing else is
+available to run, then the IDLE loop runs and the timer increments,
+eventually re-awakening the sleeping task.
 
 Context switching is based on logic similar to setjmp() and longjmp().
 
@@ -47,14 +49,16 @@ application that I know of.
 
 Timing Fidelity
 ---------------
-NOTE:  In order to facility fast testing, the sim target's IDLE loop, by default,
-calls the system "interrupt handler" as fast as possible.  As a result, there
-really are no noticeable delays when a task sleeps.  However, the task really does
-sleep -- but the time scale is wrong.  If you want behavior that is closer to
-normal timing, then you can define CONFIG_SIM_WALLTIME=y in your configuration
-file.  This configuration setting will cause the sim target's IDLE loop to delay
-on each call so that the system "timer interrupt" is called at a rate approximately
-correct for the system timer tick rate.  With this definition in the configuration,
+NOTE:  In order to facility fast testing, the sim target's IDLE loop, by
+default, calls the system "interrupt handler" as fast as possible.  As a
+result, there really are no noticeable delays when a task sleeps.  However,
+the task really does sleep -- but the time scale is wrong.  If you want
+behavior that is closer to normal timing, then you can define
+CONFIG_SIM_WALLTIME=y in your configuration file.  This configuration
+setting will cause the sim target's IDLE loop to delay on each call so that
+the system "timer interrupt" is called at a rate approximately correct for
+
+the system timer tick rate.  With this definition in the configuration,
 sleep() behavior is more or less normal.
 
 Debugging
@@ -141,44 +145,83 @@ steps for increasing the stack size in that case:
   vi builtin_list.h     # Edit this file and increase the stack size of the add-on
   rm .built *.o         # This will force the builtin apps logic to rebuild
 
+Symbol Collisions
+-----------------
+The simulation build is a two pass build:
+
+  1. On the first pass, an intermediate, partially relocatable object is
+    created called nuttx.rel.  This includes all of the files that are part
+    of the NuttX "domain."
+
+  2. On the second pass, the files are are in the host OS domain are build
+     and then linked with nuttx.rel to generate the simulation program.
+
+NuttX is a POSIX compliant RTOS and is normally build on a POSIX compliant
+host environment (like Linux or Cygwin).  As a result, the same symbols are
+exported by both the NuttX doman and the host domain.  How can we keep them
+separate?
+
+This is done using the special file nuttx-name.dat.  This file just contains
+a list of original function names and a new function name.  For example
+the NuttX printf() will get the new name NXprintf().
+
+This nuttx-names.dat file is used by the objcopy program between pass1 and
+pass2 to rename all of the symbols in the nuttx.rel object so that they do
+not collide with names provided by the host OS in the host PC domain.
+
+Occasionally, as you test new functionality, you will find that you need to
+add more names to the nuttx-names.dat file.  If there is a missing name
+mapping in nuttx-name.dat, the symptoms may be very obscure and difficult to
+debug.  What happens in this case is that when logic in nuttx.rel intended
+to call the NuttX domain function, it instead calls into the host OS
+function of the same name.
+
+Often you can survive such events.  For example, it really should not matter
+which version of strlen() you call.  Other times, it can cause subtle,
+mysterious errors.  Usually, however, callng the wrong function in the wrong
+OS results in a fatal crash.
+
 Networking Issues
 -----------------
-I never did get networking to work on the sim target.  It tries to use the tap device
-(/dev/net/tun) to emulate an Ethernet NIC, but I never got it correctly integrated
-with the NuttX networking (I probably should try using raw sockets instead).
+I never did get networking to work on the sim target.  It tries to use the
+tap device (/dev/net/tun) to emulate an Ethernet NIC, but I never got it
+correctly integrated with the NuttX networking (I probably should try using
+raw sockets instead).
 
-Update:  Max Holtzberg reports to me that the tap device actually does work properly,
-but not in an NSH configuration because of stdio operations freeze the simulation.
+Update:  Max Holtzberg reports to me that the tap device actually does work
+properly, but not in an NSH configuration because of stdio operations freeze
+the simulation.
 
-REVISIT: This may not long be an issue even with NSH because of the recent redesign
-of how the stdio devices are handled in the simulation (they should no longer freeze
-the simulation).
+REVISIT: This may not long be an issue even with NSH because of the recent
+redesign of how the stdio devices are handled in the simulation (they should
+no longer freeze the simulation).
 
 X11 Issues
 ----------
-There is an X11-based framebuffer driver that you can use exercise the NuttX graphics
-subsystem on the simulator (see the sim/nx11 configuration below).  This may require a
-lot of tinkering to get working, depending upon where your X11 installation stores
-libraries and header files and how it names libraries.
+There is an X11-based framebuffer driver that you can use exercise the NuttX
+graphics subsystem on the simulator (see the sim/nx11 configuration below).
+This may require a lot of tinkering to get working, depending upon where
+your X11 installation stores libraries and header files and how it names
+libraries.
 
-For example, on UBuntu 9.09, I had to do the following to get a clean build:
+For example, on Ubuntu 9.09, I had to do the following to get a clean build:
 
     cd /usr/lib/
     sudo ln -s libXext.so.6.4.0 libXext.so
 
-(I also get a segmentation fault at the conclusion of the NX test -- that will need
-to get looked into as well).
+(I also get a segmentation fault at the conclusion of the NX test -- that
+will need to get looked into as well).
 
-The X11 examples builds on Cygwin, but does not run.  The last time I tried it,
-XOpenDisplay() aborted the program.  UPDATE:  This was caused by the small stack
-size and can be fixed by increasing the size of the NuttX stack that calls into
-X11.  See the discussion "Stack Size Issues" above.
+The X11 examples builds on Cygwin, but does not run.  The last time I tried
+it, XOpenDisplay() aborted the program.  UPDATE:  This was caused by the
+small stack size and can be fixed by increasing the size of the NuttX stack
+that calls into X11.  See the discussion "Stack Size Issues" above.
 
 Cygwin64 Issues
 ---------------
-There are some additional issues using the simulator with Cygwin64.  Below is the
-summary of the changes that I had to make to get the simulator working in that
-environment:
+There are some additional issues using the simulator with Cygwin64.  Below
+is the summary of the changes that I had to make to get the simulator
+working in that environment:
 
   CONFIG_HOST_X86_64=y
   CONFIG_SIM_M32=n
diff --git a/graphics/nxmu/nx_start.c b/graphics/nxmu/nx_start.c
index e2f53952e4..36b40fad15 100644
--- a/graphics/nxmu/nx_start.c
+++ b/graphics/nxmu/nx_start.c
@@ -159,11 +159,6 @@ int nx_server(int argc, char *argv[])
  *   nx_start() provides a wrapper function to simplify and standardize the
  *   starting of the NX server.
  *
- *   NOTE:  Currently, many applications include logic to start the NX
- *   server from application initialization logic.  That, of course, cannot
- *   work in the NuttX kernel build because the resources required by the
- *   NX server are private to the kernel mode logic.
- *
  *   nx_start() can be called (indirectly) from applications via the
  *   boardctl() interface with the BOARDIOC_NX_START command.
  *
diff --git a/include/nuttx/nx/nx.h b/include/nuttx/nx/nx.h
index 552dcc7b70..912f92b723 100644
--- a/include/nuttx/nx/nx.h
+++ b/include/nuttx/nx/nx.h
@@ -276,11 +276,6 @@ int nx_runinstance(FAR const char *mqname, FAR NX_DRIVERTYPE *dev);
  *   nx_start() provides a wrapper function to simplify and standardize the
  *   starting of the NX server.
  *
- *   NOTE:  Currently, many applications include logic to start the NX
- *   server from application initialization logic.  That, of course, cannot
- *   work in the NuttX kernel build because the resources required by the
- *   NX server are private to the kernel mode logic.
- *
  *   nx_start() can be called (indirectly) from applications via the
  *   boardctl() interface with the BOARDIOC_NX_START command.
  *