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