amiro-lld / README.txt @ 7394be9e
History | View | Annotate | Download (9.43 KB)
1 |
AMiRo-LLD is a compilation of low-level hardware drivers for the base version of |
---|---|
2 |
the Autonomous Mini Robot (AMiRo) [1]. It provides directional interfaces for an |
3 |
operating system to access the drivers and for the drivers to access the |
4 |
communication infrastructure via the operating system. |
5 |
|
6 |
Copyright (C) 2016..2019 Thomas Schöpping et al. |
7 |
(a complete list of all authors is given below) |
8 |
|
9 |
This program is free software: you can redistribute it and/or modify |
10 |
it under the terms of the GNU Lesser General Public License as published by |
11 |
the Free Software Foundation, either version 3 of the License, or (at |
12 |
your option) any later version. |
13 |
|
14 |
This program is distributed in the hope that it will be useful, but |
15 |
WITHOUT ANY WARRANTY; without even the implied warranty of |
16 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
17 |
Lesser General Public License for more details. |
18 |
|
19 |
You should have received a copy of the GNU Lesser General Public License |
20 |
along with this program. If not, see <http://www.gnu.org/licenses/>. |
21 |
|
22 |
This research/work was supported by the Cluster of Excellence |
23 |
Cognitive Interaction Technology 'CITEC' (EXC 277) at Bielefeld |
24 |
University, which is funded by the German Research Foundation (DFG). |
25 |
|
26 |
Authors: |
27 |
- Thomas Schöpping <tschoepp[at]cit-ec.uni-bielefeld.de> |
28 |
- Marc Rothmann |
29 |
|
30 |
References: |
31 |
[1] S. Herbrechtsmeier, T. Korthals, T. Schopping and U. Rückert, "AMiRo: A |
32 |
modular & customizable open-source mini robot platform," 2016 20th |
33 |
International Conference on System Theory, Control and Computing (ICSTCC), |
34 |
Sinaia, 2016, pp. 687-692. |
35 |
|
36 |
|
37 |
|
38 |
################################################################################ |
39 |
# # |
40 |
# RRRRRRRR EEEEEEEE AAA DDDDDDDD MM MM EEEEEEEE # |
41 |
# RR RR EE AA AA DD DD MMM MMM EE # |
42 |
# RR RR EE AA AA DD DD MMMM MMMM EE # |
43 |
# RRRRRRRR EEEEEE AA AA DD DD MM MMM MM EEEEEE # |
44 |
# RR RR EE AAAAAAAAA DD DD MM MM EE # |
45 |
# RR RR EE AA AA DD DD MM MM EE # |
46 |
# RR RR EEEEEEEE AA AA DDDDDDDD MM MM EEEEEEEE # |
47 |
# # |
48 |
################################################################################ |
49 |
|
50 |
This file provides information about the purpose of this project, the file |
51 |
structure and some helpful guides for development of code. |
52 |
|
53 |
================================================================================ |
54 |
|
55 |
CONTENTS: |
56 |
|
57 |
1 About the Project |
58 |
2 File Structure |
59 |
3 Developer Guides |
60 |
3.1 Adding a Device |
61 |
3.2 Implementing a Driver |
62 |
|
63 |
================================================================================ |
64 |
|
65 |
|
66 |
|
67 |
1 - ABOUT THE PROJECT |
68 |
===================== |
69 |
|
70 |
AMiRo-LLD is a compilation of low-level hardware drivers, originally developed |
71 |
for the Autonomous Mini Robot (AMiRo) [1]. It provides a modular design, so that |
72 |
each driver can be activated individually as required. Interface functions allow |
73 |
for bidirectional comunication with an operating system. On the one hand drivers |
74 |
access according hardware interfaces via defined interface functions (which need |
75 |
to be implemented by the operating system) and any applications (or the |
76 |
operating system itself) can take advantage of the drivers by their individual |
77 |
interfaces. The abstraction layer of the hardware interfaces is called |
78 |
"periphAL", which is defined by this project. In order to configure which |
79 |
drivers should be used in which version, the project expects an according file |
80 |
"alldconf.h" to be found in the include paths. |
81 |
|
82 |
Although this compilation was originally designed to be used in combination with |
83 |
the AMiRo operating system (AMiRo-OS; cf. https://opensource.cit-ec.de/projects/amiro-os/), |
84 |
it is not limited to this use case. The included drivers may be used for any |
85 |
purpose and contributions of further drivers, even if the according hardware is |
86 |
not present on the AMiRo platform, are highly appreciated. |
87 |
|
88 |
|
89 |
|
90 |
2 - FILE STRUCTURE |
91 |
================== |
92 |
|
93 |
The files are structured as follows: |
94 |
./ |
95 |
│ The project root directory contains this file, a license.html file as well as |
96 |
│ a Makefile that allows to easily integrate the project. Furthermore, two |
97 |
│ interface headers are provided: amiro-lld.h and periphALtypes.h. These are |
98 |
│ entry points for any utilizing superproject, so it is not required (and not |
99 |
│ recommended) to include each driver individually. |
100 |
│ |
101 |
├── include/ |
102 |
│ For each supported hardware device, there is exactly one directory in this |
103 |
│ folder. Further subfolders may contain various versions of a driver (e.g. |
104 |
│ 'v1/', 'v2/', etc.). By convention the root directory of a driver is named |
105 |
│ by the form |
106 |
│ "<product_name>/" |
107 |
│ <product_name> is a placeholder for the exact name of the according |
108 |
│ hardware, or the product familiy, if the driver is compatible with all |
109 |
│ parts. |
110 |
│ The root header consequently follows the naming scheme |
111 |
│ "alld_<product_name>.h" |
112 |
│ and header files within the version folders shall be named like |
113 |
│ "alld<product_name>_<driver_version>.h" |
114 |
│ |
115 |
├── source/ |
116 |
│ Any source files are placed in this directory. Naming conventions for |
117 |
│ folders and files are the same as described before for the include |
118 |
│ directory, as is the file structure. There is a dedicated folder for each |
119 |
│ device and further subfolders for multiple driver versions. Source files |
120 |
│ should only be put in these version folders. |
121 |
│ |
122 |
└── templates/ |
123 |
AMiRo-LLD requires an implementation of the defined interface and an |
124 |
configuration header to be accessible in the include paths at compile |
125 |
time. Template files for both can be found in this folder. It is |
126 |
recommended to place according implementations of these templated not in |
127 |
the AMiRo-LLD project, but the superproject which includes AMiRo-LLD. |
128 |
|
129 |
|
130 |
|
131 |
3 - DEVELOPER GUIDES |
132 |
==================== |
133 |
|
134 |
In order to keep all code within this project as homogeneous as possible, the |
135 |
guides of these chapters should help developers to achieve functional and clean |
136 |
results, which are portable and maintainable for future use. Whereas the textual |
137 |
descriptions of the guides provide additional information about the underlying |
138 |
concepts and mechanisms, a short summary is provided at the end of each chapter. |
139 |
|
140 |
3.1 Adding a Device |
141 |
-------------------- |
142 |
|
143 |
When adding new device to the project, the very first step is to create the |
144 |
according folders in the include/ and source/ directories. For this guide, we |
145 |
will add the fictional DEVICE1234. For this example the folders to be created |
146 |
are "include/DEVICE1234/" and "source/DEVICE1234/". |
147 |
|
148 |
The first file should be the root header: "include/DEVICE1234/alld_DEVICE1234.h" |
149 |
Have a look at existing drivers and use one of those as template. This header |
150 |
should introduce a new configuration to be set in the alldconf.h file and check |
151 |
it using the preprocessor. Eventually, another header is included, pointing to |
152 |
the selected driver version/implementation. |
153 |
|
154 |
Such implementations are to be put in further subfolders, e.g. |
155 |
"include/DEVICE1234/v1/" and "source/DEVICE1234/v1/". The header and C-source |
156 |
files in those folders do not follow a strict scheme, although there are some |
157 |
conventions to consider (i.e. naming conventions, cf. chapter 2). |
158 |
|
159 |
Summing up, you have to |
160 |
1) create device folders. |
161 |
2) add a root header. |
162 |
3) add further subfolders and implement the driver there. |
163 |
|
164 |
|
165 |
3.2 Implementing a Driver |
166 |
-------------------------- |
167 |
|
168 |
Implementation of a new driver usually is very straight-forward. You most |
169 |
probably have a comprehensive datasheet of the device, or the manufacturer even |
170 |
provides a reference driver implementation. |
171 |
|
172 |
For the former case, you should first write a comprehensive header, containing |
173 |
all information like constants, register maps, etc. and according abstract |
174 |
access functions (e.g. for reading and writing registers, and convenient access |
175 |
to common functionalities). Only the you implement those functions, using |
176 |
periphAL to interface any hardware interfaces (e.g. I2C, SPI, etc.). |
177 |
|
178 |
For the latter case, the reference implementation will specify some interface |
179 |
functions to interact with the hardware (e.g. I2C, SPI etc.). Even though all |
180 |
functionality should be covered by the reference driver, you still need to |
181 |
implement those interface functions. |
182 |
|
183 |
Since AMiRo-LLD does not rely on specific hardware or operating system, the only |
184 |
valid way to interact with both is through periphAL. Under no circumstances you |
185 |
must use any function of your operating system and directly or indirectly access |
186 |
the hardware of your platform. For your driver, there is no knowledge about the |
187 |
world beyond periphAL! If periphAL does not provide the function you need, you |
188 |
can do the following: 1) Think again if you really need that funcionality or |
189 |
whether it can be replicated by existing functions. 2) File a feature request |
190 |
to extend periphAL. 3) Write a custom patch that modifies periphAL to meet your |
191 |
requirements. |
192 |
|
193 |
Summing up, you have to |
194 |
1) Get and read the datasheet of the device (A) or |
195 |
acquire a copy of the reference implementation (B). |
196 |
2) Case A: define constants, register map and access functions in a header file. |
197 |
Case B: identify the interface functions of the reference implementation. |
198 |
3) Implement the missing functions using periphAL. |
199 |
|
200 |
================================================================================ |
201 |
|