Next: The user_controller.c API
Up: Generating a user_controller.c File
Previous: Generating a user_controller.c File
The user must create a file, user_controller.c which must
reside inside of the rtic-*.*.*/user directory. The user is
limited to only including the following header files:
- #include ``main.h'': this header file contains all of the
RTiC-Lab macros and definitions, as described in the next section. It
must be present in ALL user_controller.c files.
- #include
math.h
: this header file is the standard
math library. This include file is optional, and depends on the user's
controller.
If you find that you need to include any other include files, then you
are probably doing something wrong. The code that you write here is
going to be inserted into the kernel space of Linux. As a consequence,
there are very limited things that it can do. Thus, you cannot use
any screen I/O commands such as printf, nor any dynamic memory
allocation schemes such as malloc and calloc. In short,
your user_controller.c file must contain only mathematical
functions, mathematical manipulation (e.g.
,
,
,
, etc.),
and the macros supplied by RTiC-Lab.
The user must then create three functions within this file, none of
which need to be declared:
- int control_init(void): This function initializes the
user's controller. More specifically, all of the controller states
need to be initialized in this function. This function is called
immediately after the ``RUN'' button is pressed. The return value of
this function must be either success (0) or failure (-1). If a failure
is detected, then the controller will not run and xrtic will a
status error. This function should not take any arguments.
- void control_run(void): This function is called once per
period ad infinitum. Therefore, it must contain the actual controller
code necessary to execute the user's controller. This function both
takes in no arguments, and returns nothing.
- int control_stop(void): This function is called
immediately after the ``STOP'' button is pressed in case the user
needs to perform any activities after the controller is shutdown. This
function takes no arguments and returns either (0) for success, or (-1)
for failure.
Because of the fact that this controller is to be implemented into
kernel space, then the controller designer must keep certain points in mind:
- there is no memory protection. This means that if your code
causes a segmentation fault, then the entire computer will be rendered
unstable, thus requiring that you restart the computer. A test suite,
test_user_controller is currently being developed that will
test the user's controller prior to inserting it into kernel
space. However, at this point, this code does not quite perform too
many sanity checks. Consequently, as of the time of this writing, you
are responsible for testing the sanity of your code.
- there is no access to functions such as ``printf''. Therefore,
you must use the RETURN_VAL macro (described in the next
section) in order to debug the logic of your code.
In order to simplify the code implementation, a simple to use API
(Advanced Programming Interface) has been developed to aid in the
controller implementation. This API is described in detail in what
follows.
Next: The user_controller.c API
Up: Generating a user_controller.c File
Previous: Generating a user_controller.c File
Michael Barabanov
2001-06-19