Revision 1304b12b README.txt
README.txt | ||
---|---|---|
93 | 93 |
The files are structured as follows: |
94 | 94 |
./ |
95 | 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
|
|
96 |
│ a makefile that allows to easily integrate the project. Furthermore, two
|
|
97 | 97 |
│ interface headers are provided: amiro-lld.h and periphALtypes.h. These are |
98 | 98 |
│ entry points for any utilizing superproject, so it is not required (and not |
99 | 99 |
│ recommended) to include each driver individually. |
100 | 100 |
│ |
101 |
├── include/ |
|
101 |
├── docs/ |
|
102 |
│ UML graphs (using PlantUML; see plantuml.com for further information) |
|
103 |
│ visualize the structure of the AMiRo-LLD project. Doxygen related files |
|
104 |
│ can be used to gererate a documentation of the whole project (wip). |
|
105 |
│ |
|
106 |
├── drivers/ |
|
102 | 107 |
│ For each supported hardware device, there is exactly one directory in this |
103 | 108 |
│ folder. Further subfolders may contain various versions of a driver (e.g. |
104 | 109 |
│ 'v1/', 'v2/', etc.). By convention the root directory of a driver is named |
... | ... | |
107 | 112 |
│ <product_name> is a placeholder for the exact name of the according |
108 | 113 |
│ hardware, or the product familiy, if the driver is compatible with all |
109 | 114 |
│ 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. |
|
115 |
│ Each driver must provide a makefile script, which adds the required |
|
116 |
│ include folders to the AMIROLLD_INC variable and all C source files to the |
|
117 |
│ AMIROLLD_CSRC variable. |
|
121 | 118 |
│ |
122 | 119 |
└── 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.
|
|
120 |
AMiRo-LLD expects a configuration header "alldconf.h" to be found in the
|
|
121 |
include paths. An according template for such file can be found here.
|
|
122 |
There is no template for an implementation of periphAL, though. The
|
|
123 |
provided interface header in the root directory (periphAL.h) should give
|
|
124 |
you all required information for such an implementation anyway.
|
|
128 | 125 |
|
129 | 126 |
|
130 | 127 |
|
... | ... | |
137 | 134 |
descriptions of the guides provide additional information about the underlying |
138 | 135 |
concepts and mechanisms, a short summary is provided at the end of each chapter. |
139 | 136 |
|
137 |
|
|
140 | 138 |
3.1 Adding a Device |
141 | 139 |
-------------------- |
142 | 140 |
|
143 | 141 |
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). |
|
142 |
according folder in the drivers/ directory. For this guide, we will add the |
|
143 |
fictional DEVICE1234. For this example the folders to be created are |
|
144 |
"drivers/DEVICE1234/" and "drivers/DEVICE1234/v1/". In case there already exists |
|
145 |
a driver implementation for this device, but you want to implement another |
|
146 |
version from scratch (not just an update), the version subfolder must be named |
|
147 |
accordingly (e.g. "drivers/DEVICE1234/v42/"). |
|
148 |
|
|
149 |
Most drivers will consist of exactly three files: |
|
150 |
- alld_DEVICE1234.mk |
|
151 |
- alld_DEVICE1234.h |
|
152 |
- alld_DEVICE1234.c |
|
153 |
However, some drivers may feature multiple .h and/or .c files or even come with |
|
154 |
additional subfolders. In any case, all those required folders, including the |
|
155 |
driver root folder (i.e. "drivers/DEVICE1234/v1/"), as well as all C source |
|
156 |
files must be added to the according makefile variables AMIROLLD_INC and |
|
157 |
AMIROLLD_CSRC by the makefile script. |
|
158 |
It is highly recommended that files in the driver root directory (i.e. |
|
159 |
"drivers/DEVICE1234/v1/") use the prefix "alld_" in their names. This not only |
|
160 |
helps to achieve an easy to understand file structure, but also prevents |
|
161 |
compilation issues due to naming conflicts of header files. |
|
158 | 162 |
|
159 | 163 |
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.
|
|
164 |
1) create device and version folders.
|
|
165 |
2) add a makefile script.
|
|
166 |
3) add header- and source files as well as subfulders, implementing the diver
|
|
163 | 167 |
|
164 | 168 |
|
165 | 169 |
3.2 Implementing a Driver |
166 | 170 |
-------------------------- |
167 | 171 |
|
168 |
Implementation of a new driver usually is very straight-forward. You most
|
|
172 |
Implementation of a new driver usually is very straightforward. You most |
|
169 | 173 |
probably have a comprehensive datasheet of the device, or the manufacturer even |
170 | 174 |
provides a reference driver implementation. |
171 | 175 |
|
172 | 176 |
For the former case, you should first write a comprehensive header, containing |
173 | 177 |
all information like constants, register maps, etc. and according abstract |
174 | 178 |
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.). |
|
179 |
to common functionalities). Only then you implement those functions, using |
|
180 |
periphAL to interface any hardware interfaces (e.g. I2C, SPI, etc.) in a |
|
181 |
separate C source file, or 'inline' in the header file itself. |
|
177 | 182 |
|
178 | 183 |
For the latter case, the reference implementation will specify some interface |
179 | 184 |
functions to interact with the hardware (e.g. I2C, SPI etc.). Even though all |
180 | 185 |
functionality should be covered by the reference driver, you still need to |
181 |
implement those interface functions. |
|
186 |
implement those interface functions and map them to periphAL.
|
|
182 | 187 |
|
183 | 188 |
Since AMiRo-LLD does not rely on specific hardware or operating system, the only |
184 | 189 |
valid way to interact with both is through periphAL. Under no circumstances you |
185 | 190 |
must use any function of your operating system and directly or indirectly access |
186 | 191 |
the hardware of your platform. For your driver, there is no knowledge about the |
187 | 192 |
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. |
|
193 |
can do one of the following: |
|
194 |
1) Think again if you really need that funcionality or whether it can be |
|
195 |
replicated by the existing API. |
|
196 |
2) File a feature request to extend periphAL. |
|
197 |
3) Write a custom patch that modifies periphAL to meet your requirements. |
|
192 | 198 |
|
193 | 199 |
Summing up, you have to |
194 | 200 |
1) Get and read the datasheet of the device (A) or |
Also available in: Unified diff