doc/general-introduction

   1 /*!
   2 <!--
   3 This document is automatically processed by Doxygen (http://www.doxygen.org/).
   4 Don't remove special formatting tags.
   5 This section won't be processed unless enabled.
   6
   7 See STATUS for further information and tips about Doxygen tags.
   8 -->
   9 \page oop Object Oriented Programming
  10
  11 BeRTOS uses object oriented programming concepts for the base interfaces.
  12 If used in the right way, OOP elegantly solves a broad range of problems
  13 linked with the creation of common and reusable interfaces that allow
  14 you to save development time and precious memory space.
  15 Have a look at <a href="">KFile tutorial</a> on BeRTOS web site for
  16 a more complete introduction to object oriented programming.
  17
  18 <h2>OOP in C</h2>
  19 Object oriented programming in C requires a context struct and a few interface
  20 functions that operate on that context.
  21 The base class is implemented with a struct with a few function pointers
  22 that point to the implementation specific for the context.
  23
  24 Inherited classes are created by defining a struct with the following
  25 members:
  26  \li a base class member
  27  \li context specific members
  28
  29 Then you can call interface functions by simply using the base class member
  30 as the context of the function.
  31 Note that base classes usually don't have an init function, because they are
  32 not meant to be used directly and it wouldn't make sense anyway, since they
  33 provide no functionality, only the interface.
  34 The usage pattern requires you to declare a context (eg. Flash), initialize
  35 the context with a specific function call (eg. flash_init()) then use the
  36 interface funtions to access the context.
  37
  38 To make an example, in BeRTOS the Serial driver is a derived class of the
  39 KFile interface.
  40 The KFile interface defines a few interface functions, which can be used to
  41 extract data from the Serial context.
  42 \code
  43 // declare the serial context
  44 Serial ser;
  45 // read buffer
  46 uint8_t buf[20];
  47
  48 int main()
  49 {
  50    // initialize the serial driver
  51    ser_init(&ser, SER_UART0);
  52    ser_setbaudrate(115200);
  53    // now access using the interface functions
  54    // read...
  55    kfile_read(&ser.fd, buf, 20);
  56    // ...and write
  57    kfile_printf(&ser.fd, "Writing to serial using KFile interface...\n");
  58    // close the driver
  59    kfile_close(&ser.fd);
  60 }
  61 \endcode
  62
  63
  64 */
  65
  66
  67 /**
  68 \page short_introduction A 5 minute introduction to BeRTOS
  69
  70 \section installation Installing BeRTOS on your system
  71
  72 What do you need when developing an embedded project with BeRTOS?
  73 \li a toolchain for your CPU
  74 \li BeRTOS source code :)
  75 \li supporting binaries for BeRTOS build system
  76 \li supporting tools for BeRTOS Wizard
  77
  78 See the <a href="http://www.bertos.org/use/tutorial-front-page/installation-instructions/">
  79 installation instructions page</a> online for help on installing BeRTOS on your system.
  80
  81 Strictly speaking, BeRTOS doesn't need to be 'installed', you can just
  82 take .c files and compile them in your project.
  83
  84 However, BeRTOS is a complex system with many dependencies between modules.
  85 It's not easy to track the dependencies for each module, so we have developed
  86 a set of tools to make dependency tracking automatic.
  87
  88 Contact the <a href="http://forum.bertos.org">support forum</a> and look at
  89 the section \ref coding  if you want
  90 help on using BeRTOS without the supporting tools. Be warned, though, that
  91 this method is not supported and we can only point you in the right direction.
  92
  93 \section organization Project's organization
  94
  95 Each project has its own full BeRTOS sources, configuration and HAL files.
  96 Why? Because we think that each project has its own life and it must not
  97 interfere with any other project.
  98 Let's say you use a shared BeRTOS version for all of your projects. Each
  99 time you update, you need to check that each and every project still works
 100 correctly. We don't want to do this (and I bet you don't want either).
 101 However, it's still easy to update a single project if you want to.
 102
 103 A project named Foo is organized as follows:
 104 \li bertos/ - BeRTOS source directory
 105 \li Makefile - BeRTOS build system Makefile
 106 \li project.bertos - Wizard's configuration file
 107 \li foo/ - your project's main directory
 108 \li foo/hw/ - low level HAL files
 109 \li foo/cfg/ - configuration directory
 110 \li foo/foo_user.mk - makefile fragment that you can edit
 111 \li foo/foo.mk - makefile fragment changed by the Wizard, don't edit
 112
 113 See <a href="http://www.bertos.org/use/tutorial-front-page/basic-hal/">BeRTOS HAL system</a>
 114 for more information on HAL files.
 115
 116 \section coding Coding guidelines
 117
 118 BeRTOS assumes that the BeRTOS source directory and the project's root directory
 119 (as indicated above) are in the include path.
 120 This means that you should include configuration files using "..." rather than
 121 <...> style, otherwise you will use default configuration values instead of
 122 your project's values.
 123
 124 Also, you should change configuration settings using the Wizard. This is because
 125 sometimes there are more actions to be done than simply changing a define
 126 value.
 127
 128
 129 */
 130
 131
 132 /*!
 133  * \defgroup drivers BeRTOS peripherals drivers
 134  *
 135  * This section includes all BeRTOS drivers. They may be internal CPU drivers
 136  * or CPU independent drivers
 137  */
 138
 139
 140 /*!
 141  * \defgroup core BeRTOS core functionality
 142  *
 143  * This section includes BeRTOS core functionalities and interfaces.
 144  */
 145
 146
 147 /*!
 148  * \defgroup kern Kernel facilities
 149  *
 150  * This section describes the kernel facilities and the synchronization
 151  * primitives available in BeRTOS.
 152  */
 153
 154 /*!
 155  * \defgroup mware Middleware facilities
 156  *
 157  * This section describes various algorithms and standalone code
 158  * useful in day to day programming.
 159  */
 160
 161 /*!
 162  * \defgroup graphics General purpose graphical routines
 163  *
 164  */
 165
 166 /*!
 167  * \defgroup gui BeRTOS GUI toolkit
 168  *
 169  */
 170
 171 /*!
 172  * \defgroup struct Embedded optimized general purpose data types
 173  */