next up previous
Next: The user_controller.c API Up: Generating a user_controller.c File Previous: Generating a user_controller.c File

Necessary Functions

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:

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:

  1. 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.

  2. 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.

  3. 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:

  1. 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.

  2. 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 up previous
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