amiro-lld / README.md @ 99ca7610
History | View | Annotate | Download (8.527 KB)
1 | 99ca7610 | Thomas Schöpping | About & License |
---|---|---|---|
2 | =============== |
||
3 | |||
4 | AMiRo-LLD is a compilation of low-level hardware drivers for the base version of |
||
5 | the Autonomous Mini Robot (AMiRo) [1]. It provides directional interfaces for an |
||
6 | operating system to access the drivers and for the drivers to access the |
||
7 | communication infrastructure via the operating system. |
||
8 | |||
9 | Copyright (C) 2016..2020 Thomas Schöpping et al. |
||
10 | (a complete list of all authors is given below) |
||
11 | |||
12 | This program is free software: you can redistribute it and/or modify |
||
13 | it under the terms of the GNU Lesser General Public License as published by |
||
14 | the Free Software Foundation, either version 3 of the License, or (at |
||
15 | your option) any later version. |
||
16 | |||
17 | This program is distributed in the hope that it will be useful, but |
||
18 | WITHOUT ANY WARRANTY; without even the implied warranty of |
||
19 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
||
20 | Lesser General Public License for more details. |
||
21 | |||
22 | You should have received a copy of the GNU Lesser General Public License |
||
23 | along with this program. If not, see <http://www.gnu.org/licenses/>. |
||
24 | |||
25 | This research/work was supported by the Cluster of Excellence |
||
26 | Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld |
||
27 | University, which is funded by the German Research Foundation (DFG). |
||
28 | |||
29 | Authors: |
||
30 | |||
31 | - Thomas Schöpping (tschoepp@cit-ec.uni-bielefeld.de) |
||
32 | - Marc Rothmann |
||
33 | |||
34 | References: |
||
35 | |||
36 | [1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A |
||
37 | modular & customizable open-source mini robot platform," 2016 20th |
||
38 | International Conference on System Theory, Control and Computing (ICSTCC), |
||
39 | Sinaia, 2016, pp. 687-692. |
||
40 | |||
41 | -------------------------------------------------------------------------------- |
||
42 | |||
43 | Contents |
||
44 | ======== |
||
45 | |||
46 | 1. About the Project |
||
47 | 2. File Structure |
||
48 | 3. Developer Guides |
||
49 | 1. Adding a Device |
||
50 | 2. Implementing a Driver |
||
51 | |||
52 | -------------------------------------------------------------------------------- |
||
53 | |||
54 | 1 About the Project |
||
55 | =================== |
||
56 | |||
57 | AMiRo-LLD is a compilation of low-level hardware drivers, originally developed |
||
58 | for the Autonomous Mini Robot (AMiRo) [1]. It provides a modular design, so that |
||
59 | each driver can be unsed and configured individually as required. Interface |
||
60 | functions allow for bidirectional comunication with an operating system. On the |
||
61 | one hand drivers access according hardware interfaces via defined interface |
||
62 | functions (which need to be implemented by the operating system), on the other |
||
63 | hand any applications (or the operating system itself) can take advantage of the |
||
64 | drivers by their individual interfaces. The abstraction layer of the hardware |
||
65 | interfaces is called "periphAL", which is defined by this project. In order to |
||
66 | further configure individual drivers, the project expects an according file |
||
67 | "alldconf.h" to be found in the include paths when compiling the drivers. |
||
68 | |||
69 | Although this compilation was originally designed to be used in combination with |
||
70 | the AMiRo operating system (AMiRo-OS; cf. |
||
71 | https://opensource.cit-ec.de/projects/amiro-os/), it is not limited to this use |
||
72 | case. The included drivers may be used for any purpose and contributions of |
||
73 | further drivers, even if the according hardware is not present on the AMiRo |
||
74 | platform, are highly appreciated. |
||
75 | |||
76 | 2 File Structure |
||
77 | ================ |
||
78 | |||
79 | The files are structured as follows: |
||
80 | |||
81 | * `./` |
||
82 | The project root directory contains this file, a `license.html` file as well |
||
83 | as a makefile `amiro-lld.mk` that allows to easily integrate the project. |
||
84 | Furthermore, two interface headers are provided: amiro-lld.h and periphALh. |
||
85 | * `./docs/` |
||
86 | UML graphs (using PlantUML; see <https://plantuml.com> for further |
||
87 | information) visualize the structure of the AMiRo-LLD project. Doxygen |
||
88 | related files can be used to gererate a documentation of the whole |
||
89 | project (wip). |
||
90 | * `./drivers/` |
||
91 | For each supported hardware device, there is exactly one directory in |
||
92 | this folder. Further subfolders contain various versions of a driver |
||
93 | (e.g. `v1/`, `v2/`, etc.). By convention, the root directory of a driver |
||
94 | is named by the exact product name of the according hardware, or the |
||
95 | product familiy, if the driver is compatible with all parts. Each driver |
||
96 | must provide a makefile script, which adds the required include paths to |
||
97 | the `AMIROLLD_INC` variable and all C source files to the |
||
98 | `AMIROLLD_CSRC` variable. |
||
99 | * `./templates/` |
||
100 | AMiRo-LLD expects a configuration header file "alldconf.h" to be found in |
||
101 | the include paths. An according template for such file can be found here. |
||
102 | There is no template for an implementation of periphAL, though. The |
||
103 | interface header in the root directory (`./periphAL.h`) provides all |
||
104 | required information for an implementation. |
||
105 | |||
106 | |||
107 | |||
108 | 3 Developer Guides |
||
109 | ================== |
||
110 | |||
111 | In order to keep all code within this project as homogeneous as possible, the |
||
112 | guides in this chapter should help developers to achieve functional and clean |
||
113 | results, which are portable and maintainable for future use. Whereas the textual |
||
114 | descriptions of the guides provide in-depth information about the underlying |
||
115 | concepts and mechanisms, a short summary is provided at the end of each chapter. |
||
116 | |||
117 | |||
118 | 3.1 Adding a Device |
||
119 | ------------------- |
||
120 | |||
121 | When adding a new device to the project, the very first step is to create the |
||
122 | according folder in the `./drivers/` directory. For this guide, we will add the |
||
123 | fictional device `DEVICE1234`. The folders to be created in this case are hence |
||
124 | `./drivers/DEVICE1234/` and `./drivers/DEVICE1234/v1/`. In case there already |
||
125 | exists a driver implementation for this device, but you want to implement |
||
126 | another version, the version subfolder must be named accordingly (e.g. |
||
127 | `./drivers/DEVICE1234/v2/`). |
||
128 | |||
129 | Most drivers will consist of exactly three files: |
||
130 | |||
131 | * alld_DEVICE1234.mk |
||
132 | * alld_DEVICE1234.h |
||
133 | * alld_DEVICE1234.c |
||
134 | |||
135 | Some drivers, however, may feature multiple header and/or source files or even |
||
136 | come with additional subfolders. In any case, all those required folders, |
||
137 | including the driver root folder (i.e. `./drivers/DEVICE1234/v1/`), as well as |
||
138 | all source files must be added to the according makefile variables |
||
139 | `AMIROLLD_INC` and `AMIROLLD_CSRC` by the makefile script. |
||
140 | It is highly recommended that files in the driver root directory (i.e. |
||
141 | `./drivers/DEVICE1234/v1/`) use the prefix `alld_` in their names. This not only |
||
142 | helps to achieve an easy to understand file structure, but also prevents |
||
143 | compilation issues due to naming conflicts of header files. |
||
144 | |||
145 | **Summing up, you have to** |
||
146 | |||
147 | 1. create device and version folders. |
||
148 | 2. add a makefile script. |
||
149 | 3. add header and source files as well as subfulders, implementing the driver. |
||
150 | |||
151 | |||
152 | 3.2 Implementing a Driver |
||
153 | ------------------------- |
||
154 | |||
155 | Implementation of a new driver usually is very straightforward. You will most |
||
156 | probably start with a comprehensive datasheet of the device, or the manufacturer |
||
157 | even provides a reference driver implementation. |
||
158 | |||
159 | For the former case, you should first write a comprehensive header, containing |
||
160 | all information like constants, register maps, etc. and according abstract |
||
161 | access functions (e.g. for reading and writing registers, and convenient access |
||
162 | to common functionalities). Only then you implement those functions, using |
||
163 | periphAL to interface any hardware interfaces (e.g. I2C, SPI, etc.) in a |
||
164 | separate C source file, or 'inline' in the header file itself. |
||
165 | For the latter case, the reference implementation will specify some interface |
||
166 | functions to interact with the hardware (e.g. I2C, SPI etc.). Even though all |
||
167 | functionality should be covered by the reference driver, you still need to |
||
168 | implement those interface functions and map them to periphAL. |
||
169 | |||
170 | Since AMiRo-LLD does not rely on specific hardware or operating system, the only |
||
171 | valid way to interact with both is through periphAL. Under no circumstances you |
||
172 | must use any function of your operating system directly to interact with the |
||
173 | hardware or the operating system! For your driver, there is no knowledge about |
||
174 | the world beyond periphAL. If periphAL does not provide the functionality you |
||
175 | need, you should do the following: |
||
176 | |||
177 | 1. Think again if you really need that funcionality or whether it can be |
||
178 | replicated by the existing API. |
||
179 | 2. File a feature request to extend periphAL. |
||
180 | 3. Write a custom patch that modifies periphAL to meet your requirements. |
||
181 | |||
182 | **Summing up, you have to** |
||
183 | |||
184 | 1. Get and read the datasheet of the device (A) |
||
185 | or acquire a copy of the reference implementation (B). |
||
186 | 2. Case A: Define constants, register map and access functions in a header |
||
187 | file. |
||
188 | Case B: Identify the interface functions of the reference implementation. |
||
189 | 3. Implement all required functions using periphAL. |