view __README__Code_Overview.txt @ 256:2bcf37fd50c6

Prev msg should have been: isolated valgrind with a new compiler switch use SERVICES__TURN_ON_VALGRIND in order to compile valgrind support into vmalloc
author Sean Halle <>
date Mon, 10 Sep 2012 01:26:51 -0700
parents 10a72bcedbf0
children 999f2966a3e5
line source
2 This file is intended to help those new to VMS to find their way around the code.
4 Some observations:
5 -] VMS.h is the top header file, and is the root of a tree of #includes that pulls in all the other headers
7 -] Defines directory contains all the header files that hold #define statements
9 -] VMS has several kinds of function, grouped according to what kind of code should call them: VMS_App_.. for applications to call, VMS_WL_.. for wrapper-library code to call, VMS_PI_.. for plugin code to call, and VMS_int_.. for VMS to use internally. Sometimes VMS_int_ functions are called from the wrapper library or plugin, but this should only be done by programmers who have gained an in-depth knowledge of VMS's implementation and understand that VMS_int_ functions are not protected for concurrent use..
11 -] VMS has its own version of malloc, unfortunately, which is due to the system malloc breaking when the stack-pointer register is manipulated, which VMS must do. The VMS form of malloc must be used in code that runs inside the VMS system, especially all application code that uses a VMS-based language. However, a complication is that the malloc implementation is not protected with a lock. However, mallocs performed in the main thread, outside the VMS-language program, cannot use VMS malloc.. this presents some issues crossing the boundary..
13 -] Things in the code are turned on and off by using #define in combination with #ifdef. All defines for doing this are found in Defines/VMS_defs__turn_on_and_off.h. The rest of the files in Defines directory contain macro definitions, hardware constants, and any other #define statements.
15 -] VMS has many macros used in the code.. such as for measurements and debug.. all measurement, debug, and statistics gathering statements can be turned on or off by commenting-out or uncommenting the appropriate #define.
17 -] The best way to learn VMS is to uncomment DEBUG__TURN_ON_SEQUENTIAL_MODE, which allows using a normal debugger while sequentially executing through both application code and VMS internals. Setting breakpoints at various spots in the code is a good way to see the VMS system in operation.
19 -] VMS has several "VMS primitives" implemented with assembly code. The net effect of these assembly functions is to perform the switching between application code and the VMS system.
21 -] The heart of this multi-core version of VMS is the AnimationMaster and CoreController. Those files have large comments explaining the nature of VMS and this implementation. Those comments are the best place to start reading, to get an understanding of the code before tracing through it.