VSF Documented
vsf_template_instance_declaration.h
Go to the documentation of this file.
1/*****************************************************************************
2 * Copyright(C)2009-2022 by VSF Team *
3 * *
4 * Licensed under the Apache License, Version 2.0 (the "License"); *
5 * you may not use this file except in compliance with the License. *
6 * You may obtain a copy of the License at *
7 * *
8 * http://www.apache.org/licenses/LICENSE-2.0 *
9 * *
10 * Unless required by applicable law or agreed to in writing, software *
11 * distributed under the License is distributed on an "AS IS" BASIS, *
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
13 * See the License for the specific language governing permissions and *
14 * limitations under the License. *
15 * *
16 ****************************************************************************/
17
19//
20// Example - In your custom driver declaration file (e.g. driver.h that you need to provide):
21// device.h
22// #define VSF_HW_SPI_COUNT 4
23// #define VSF_HW_SPI0_IRQN SPI0_IRQn
24// #define VSF_HW_SPI0_IRQHandler SPI0_Handler
25// ...
26//
27// driver.h:
28// #include "hal/driver/common/template/vsf_template_spi.h" // Include VSF HAL provided template
29// #define VSF_SPI_CFG_DEC_PREFIX vsf_hw
30// #define VSF_SPI_CFG_DEC_UPCASE_PREFIX VSF_HW
31// #include "hal/driver/common/spi/spi_template.h" // Include VSF HAL provided template
32//
33// Note: VSF HAL already provides templates like spi_template.h that define:
34// #define VSF_HAL_TEMPLATE_DEC_NAME _spi
35// #define VSF_HAL_TEMPLATE_DEC_UPCASE_NAME _SPI
36//
37// These examples demonstrate the configuration pattern where you provide the driver-specific
38// configuration in your declaration file, and then include the VSF HAL provided templates.
39
40/**************************** prefix *******************************************/
41
42// VSF_SPI_CFG_DEC_UPCASE_PREFIX -> VSF_SPI_CFG_DEC_RENAME_DEVICE_PREFIX -> ENABLED or DISABLED
43#ifndef VSF_HAL_TEMPLATE_DEC_RENAME_DEVICE_PREFIX
44# define VSF_HAL_TEMPLATE_DEC_RENAME_DEVICE_PREFIX VSF_MCONNECT(VSF, VSF_HAL_TEMPLATE_DEC_UPCASE_NAME, _CFG_DEC_RENAME_DEVICE_PREFIX)
45#endif
46
47// VSF_HAL_TEMPLATE_DEC_PREFIX -> VSF_SPI_CFG_DEC_PREFIX -> vsf_hw (default) or other(for example, vsf_example)
48#ifndef VSF_HAL_TEMPLATE_DEC_PREFIX
49# define VSF_HAL_TEMPLATE_DEC_PREFIX VSF_MCONNECT(VSF, VSF_HAL_TEMPLATE_DEC_UPCASE_NAME, _CFG_DEC_PREFIX)
50#endif
51
52// VSF_HAL_TEMPLATE_DEC_UPCASE_PREFIX -> VSF_SPI_CFG_DEC_UPCASE_PREFIX -> VSF_HW (default) or other(for example, VSF_EXAMPLE)
53#ifndef VSF_HAL_TEMPLATE_DEC_UPCASE_PREFIX
54# define VSF_HAL_TEMPLATE_DEC_UPCASE_PREFIX VSF_MCONNECT(VSF, VSF_HAL_TEMPLATE_DEC_UPCASE_NAME, _CFG_DEC_UPCASE_PREFIX)
55#endif
56
57
58#ifndef VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX
59# if VSF_HAL_TEMPLATE_DEC_RENAME_DEVICE_PREFIX == ENABLED
60// VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX -> VSF_SPI_CFG_DEC_DEVICE_PREFIX -> vsf_hw_qspi (for example)
61// This is used when you need different device names (e.g., QSPI vs SPI) with different drivers.
62# define VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX VSF_MCONNECT(VSF, VSF_HAL_TEMPLATE_DEC_UPCASE_NAME, _CFG_DEC_DEVICE_PREFIX)
63# else
64// VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX -> VSF_SPI_CFG_DEC_DEVICE_PREFIX -> vsf_hw_spi (default)
65// Default naming pattern (PREFIX + NAME) is used when peripherals share the same driver
66// (e.g., USART/UART can use the same driver implementation with different prefixes).
67# define VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX VSF_MCONNECT(VSF_HAL_TEMPLATE_DEC_PREFIX, VSF_HAL_TEMPLATE_DEC_NAME)
68# endif
69#endif
70
71#ifndef VSF_HAL_TEMPLATE_DEC_REMAP
72# define VSF_HAL_TEMPLATE_DEC_REMAP VSF_MCONNECT(VSF, VSF_HAL_TEMPLATE_DEC_UPCASE_NAME, _CFG_DEC_REMAP)
73#endif
74
75// VSF_HAL_TEMPLATE_DEC_PREFIX -> VSF_SPI_CFG_DEC_REMAP_PREFIX -> vsf_hw(default) or other(for example, vsf_example)
76#ifndef VSF_HAL_TEMPLATE_DEC_REMAP_PREFIX
77# define VSF_HAL_TEMPLATE_DEC_REMAP_PREFIX VSF_MCONNECT(VSF, VSF_HAL_TEMPLATE_DEC_UPCASE_NAME, _CFG_DEC_REMAP_PREFIX)
78#endif
79
80// VSF_HAL_TEMPLATE_DEC_COUNT_MASK_PREFIX -> VSF_SPI_CFG_DEC_COUNT_MASK_PREFIX -> VSF_HW (default) or other(for example, VSF_EXAMPLE)
81#ifndef VSF_HAL_TEMPLATE_DEC_COUNT_MASK_PREFIX
82# if VSF_HAL_TEMPLATE_DEC_RENAME_DEVICE_PREFIX == ENABLED
83# define VSF_HAL_TEMPLATE_DEC_COUNT_MASK_PREFIX VSF_MCONNECT(VSF, VSF_HAL_TEMPLATE_DEC_UPCASE_NAME, _CFG_DEC_DEVICE_UPCASE_PREFIX)
84# else
85# define __VSF_HAL_TEMPLATE_DEC_COUNT_MASK_PREFIX VSF_MCONNECT(VSF, VSF_HAL_TEMPLATE_DEC_UPCASE_NAME, _CFG_DEC_COUNT_MASK_PREFIX)
86# define VSF_HAL_TEMPLATE_DEC_COUNT_MASK_PREFIX VSF_MCONNECT(__VSF_HAL_TEMPLATE_DEC_COUNT_MASK_PREFIX, VSF_HAL_TEMPLATE_DEC_UPCASE_NAME)
87# endif
88#endif
89
90/**************************** remap declaration ********************************/
91
92// VSF_HAL_TEMPLATE_DEC_REMAP_TYPE -> vsf_hw_spi_t or vsf_example_spi_t
93#ifndef VSF_HAL_TEMPLATE_DEC_REMAP_TYPE
94# define VSF_HAL_TEMPLATE_DEC_REMAP_TYPE VSF_MCONNECT(VSF_HAL_TEMPLATE_DEC_REMAP_PREFIX, VSF_HAL_TEMPLATE_DEC_NAME, _t)
95#endif
96// VSF_HAL_TEMPLATE_DEC_TYPE -> vsf_hw_spi_t
97#ifndef VSF_HAL_TEMPLATE_DEC_TYPE
98# define VSF_HAL_TEMPLATE_DEC_TYPE VSF_MCONNECT(VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX, _t)
99#endif
100
101#if VSF_HAL_TEMPLATE_DEC_REMAP == ENABLED
102// expand to one of the following:
103// typedef vsf_remap_example_spi_t vsf_hw_spi_t;
105#else
106// expand to one of the following:
107// typedef vsf_hw_spi_t vsf_hw_spi_t;
109#endif
110
111/**************************** instance declaration ********************************/
112
113// VSF_HAL_TEMPLATE_DEC_INSTANCE_APIS -> VSF_SPI_APIS (vsf_template_spi.h)
114#ifndef VSF_HAL_TEMPLATE_DEC_INSTANCE_APIS
115# define VSF_HAL_TEMPLATE_DEC_INSTANCE_APIS VSF_MCONNECT(VSF, VSF_HAL_TEMPLATE_DEC_UPCASE_NAME, _APIS)
116#endif
117
118// VSF_SPI_APIS uses __VSF_HAL_TEMPLATE_API (example: when used for SPI)
119#undef __VSF_HAL_TEMPLATE_API
120#define __VSF_HAL_TEMPLATE_API VSF_HAL_TEMPLATE_API_EXTERN
121
122/*
123 * Example: When this template is used for SPI, the macro below expands to:
124 * extern vsf_err_t vsf_hw_spi_init(vsf_hw_spi_t *spi_ptr, vsf_spi_cfg_t *cfg_ptr);
125 * extern void vsf_hw_spi_fini(vsf_hw_spi_t *spi_ptr);
126 * extern vsf_err_t vsf_hw_spi_get_configuration(vsf_hw_spi_t *spi_ptr, vsf_spi_cfg_t *cfg_ptr);
127 * extern vsf_spi_capability_t vsf_hw_spi_capability(vsf_hw_spi_t *spi_ptr);
128 * extern fsm_rt_t vsf_hw_spi_enable(vsf_hw_spi_t *spi_ptr);
129 * extern fsm_rt_t vsf_hw_spi_disable(vsf_hw_spi_t *spi_ptr);
130 * extern void vsf_hw_spi_irq_enable(vsf_hw_spi_t *spi_ptr, vsf_spi_irq_mask_t irq_mask);
131 * extern void vsf_hw_spi_irq_disable(vsf_hw_spi_t *spi_ptr, vsf_spi_irq_mask_t irq_mask);
132 * extern vsf_spi_irq_mask_t vsf_hw_spi_irq_clear(vsf_hw_spi_t *spi_ptr, vsf_spi_irq_mask_t irq_mask);
133 * extern vsf_spi_status_t vsf_hw_spi_status(vsf_hw_spi_t *spi_ptr);
134 * extern vsf_err_t vsf_hw_spi_cs_active(vsf_hw_spi_t *spi_ptr, uint_fast8_t index);
135 * extern vsf_err_t vsf_hw_spi_cs_inactive(vsf_hw_spi_t *spi_ptr, uint_fast8_t index);
136 * extern vsf_err_t vsf_hw_spi_request_transfer(vsf_hw_spi_t *spi_ptr, void *out_buffer_ptr, void *in_buffer_ptr, uint_fast32_t count);
137 * extern vsf_err_t vsf_hw_spi_cancel_transfer(vsf_hw_spi_t *spi_ptr);
138 * ...
139 */
141
142
143#ifdef VSF_HAL_TEMPLATE_DEC_ADDITIONAL_API
144# ifndef VSF_HAL_TEMPLATE_DEC_INSTANCE_ADDITIONAL_API
145# define VSF_HAL_TEMPLATE_DEC_INSTANCE_ADDITIONAL_API VSF_MCONNECT(VSF, VSF_HAL_TEMPLATE_DEC_UPCASE_NAME, _ADDITIONAL_APIS)
146# endif
147VSF_HAL_TEMPLATE_DEC_INSTANCE_ADDITIONAL_API(VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX)
148#endif
149
150/**************************** multi class op ***********************************/
151
152#ifndef VSF_HAL_TEMPLATE_DEC_EXTERN_OP
153// VSF_HAL_TEMPLATE_DEC_EXTERN_OP -> VSF_SPI_CFG_DEC_EXTERN_OP
154# define VSF_HAL_TEMPLATE_DEC_EXTERN_OP VSF_MCONNECT(VSF, VSF_HAL_TEMPLATE_DEC_UPCASE_NAME, _CFG_DEC_EXTERN_OP)
155#endif
156
157#if VSF_HAL_TEMPLATE_DEC_EXTERN_OP == ENABLED
158# ifndef VSF_HAL_TEMPLATE_DEC_INSTANCE_OP_TYPE
159// VSF_HAL_TEMPLATE_DEC_INSTANCE_OP_TYPE -> vsf_hw_spi_op_t
160# define VSF_HAL_TEMPLATE_DEC_INSTANCE_OP_TYPE VSF_MCONNECT(vsf, VSF_HAL_TEMPLATE_DEC_NAME, _op_t)
161# endif
162// VSF_HAL_TEMPLATE_DEC_INSTANCE_OP_INSTANCE -> vsf_hw_spi_op
163# ifndef VSF_HAL_TEMPLATE_DEC_INSTANCE_OP_INSTANCE
164# define VSF_HAL_TEMPLATE_DEC_INSTANCE_OP_INSTANCE VSF_MCONNECT(VSF_HAL_TEMPLATE_DEC_PREFIX, VSF_HAL_TEMPLATE_DEC_NAME, _op)
165# endif
166// extern const vsf_hw_spi_op_t vsf_hw_spi_op;
168#endif
169
170/**************************** instance declaration *****************************/
171
172#ifndef VSF_HAL_TEMPLATE_DEC_INSTANCE_TYPE
173// VSF_HAL_TEMPLATE_DEC_INSTANCE_TYPE -> vsf_hw_spi_t
174# define VSF_HAL_TEMPLATE_DEC_INSTANCE_TYPE VSF_MCONNECT(VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX, _t)
175#endif
176
177#ifndef VSF_HAL_TEMPLATE_DEC_LV0
178// VSF_HAL_TEMPLATE_DEC_INSTANCE -> extern vsf_hw_spi_t vsf_hw_spi0;
179# define VSF_HAL_TEMPLATE_DEC_INSTANCE(__IDX, __DONT_CARE) \
180 extern VSF_HAL_TEMPLATE_DEC_INSTANCE_TYPE VSF_MCONNECT(VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX, __IDX);
181# define VSF_HAL_TEMPLATE_DEC_LV0 VSF_HAL_TEMPLATE_DEC_INSTANCE
182#endif
183
184#ifndef VSF_HAL_TEMPLATE_DEC_COUNT_SUFFIX
185# define VSF_HAL_TEMPLATE_DEC_COUNT_SUFFIX _COUNT
186#endif
187
188#ifndef VSF_HAL_TEMPLATE_DEC_MASK_SUFFIX
189# define VSF_HAL_TEMPLATE_DEC_MASK_SUFFIX _MASK
190#endif
191
192#ifndef VSF_HAL_TEMPLATE_DEC_DEFINED_COUNT
193// VSF_HAL_TEMPLATE_DEC_DEFINED_COUNT -> VSF_HW_SPI_COUNT -> Number (for example, 2, vsf_hw_spi0 and vsf_hw_spi1)
194# define VSF_HAL_TEMPLATE_DEC_DEFINED_COUNT VSF_MCONNECT(VSF_HAL_TEMPLATE_DEC_COUNT_MASK_PREFIX, VSF_HAL_TEMPLATE_DEC_COUNT_SUFFIX)
195#endif
196
197#ifndef VSF_HAL_TEMPLATE_DEC_DEFINED_MASK
198// VSF_HAL_TEMPLATE_DEC_DEFINED_MASK -> VSF_HW_SPI_MASK -> Number (for example, 0x05, vsf_hw_spi0 and vsf_hw_spi2)
199# define VSF_HAL_TEMPLATE_DEC_DEFINED_MASK VSF_MCONNECT(VSF_HAL_TEMPLATE_DEC_COUNT_MASK_PREFIX, VSF_HAL_TEMPLATE_DEC_MASK_SUFFIX)
200#endif
201
202#if !defined(VSF_HAL_TEMPLATE_DEC_COUNT) && VSF_HAL_TEMPLATE_DEC_DEFINED_COUNT
203# define VSF_HAL_TEMPLATE_DEC_COUNT VSF_HAL_TEMPLATE_DEC_DEFINED_COUNT
204#endif
205
206#if !defined(VSF_HAL_TEMPLATE_DEC_MASK) && VSF_HAL_TEMPLATE_DEC_DEFINED_MASK
207# define VSF_HAL_TEMPLATE_DEC_MASK VSF_HAL_TEMPLATE_DEC_DEFINED_MASK
208#endif
209
210#if defined(VSF_HAL_TEMPLATE_DEC_MASK) && !defined(VSF_HAL_TEMPLATE_DEC_COUNT)
211# define VSF_HAL_TEMPLATE_DEC_COUNT VSF_HAL_MASK_TO_COUNT(VSF_HAL_TEMPLATE_DEC_MASK)
212#endif
213
214#if defined(VSF_HAL_TEMPLATE_DEC_COUNT) && !defined(VSF_HAL_TEMPLATE_DEC_MASK)
215# define VSF_HAL_TEMPLATE_DEC_MASK VSF_HAL_COUNT_TO_MASK(VSF_HAL_TEMPLATE_DEC_COUNT)
216#endif
217
218/*
219extern vsf_hw_spi_t vsf_hw_spi0;
220extern vsf_hw_spi_t vsf_hw_spi1;
221....
222 */
223#define __VSF_HAL_TEMPLATE_MASK VSF_HAL_TEMPLATE_DEC_MASK
224#define __VSF_HAL_TEMPLATE_MACRO VSF_HAL_TEMPLATE_DEC_LV0
225#define __VSF_HAL_TEMPLATE_ARG VSF_HAL_TEMPLATE_DEC_OP
227
228/**************************** instance's array declaration *********************/
229
230#if !defined(VSF_HAL_TEMPLATE_DEC_REMOVE_ARRAY) && (VSF_HAL_TEMPLATE_DEC_MASK != 0)
231# ifndef VSF_HAL_TEMPLATE_DEC_INSTANCE_ARRAY
232# define VSF_HAL_TEMPLATE_DEC_INSTANCE_ARRAY VSF_MCONNECT(VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX, s)
233# endif
234/*
235extern vsf_hw_spi_t *const vsf_hw_spis[2];
236 */
237extern VSF_HAL_TEMPLATE_DEC_INSTANCE_TYPE *const VSF_HAL_TEMPLATE_DEC_INSTANCE_ARRAY[VSF_HAL_TEMPLATE_DEC_COUNT];
238
239# ifndef VSF_HAL_TEMPLATE_DEC_INSTANCE_INDEX_ARRAY
240# define VSF_HAL_TEMPLATE_DEC_INSTANCE_INDEX_ARRAY VSF_MCONNECT(VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX, _indexs)
241# endif
242/*
243extern const uint8_t vsf_hw_spi_indexs[2];
244 */
245extern const uint8_t VSF_HAL_TEMPLATE_DEC_INSTANCE_INDEX_ARRAY[VSF_HAL_TEMPLATE_DEC_COUNT];
246
247#ifndef VSF_HAL_TEMPLATE_DEC_INSTANCE_NAME_ARRAY
248# define VSF_HAL_TEMPLATE_DEC_INSTANCE_NAME_ARRAY VSF_MCONNECT(VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX, _names)
249#endif
250/*
251extern const uint8_t vsf_hw_spi_names[2];
252 */
253extern const char *VSF_HAL_TEMPLATE_DEC_INSTANCE_NAME_ARRAY[VSF_HAL_TEMPLATE_DEC_COUNT];
254
255# ifndef VSF_HAL_TEMPLATE_DEC_DEVICE_ARRAY
256# define VSF_HAL_TEMPLATE_DEC_DEVICE_ARRAY VSF_MCONNECT(VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX, _devices)
257# endif
258
259/*
260extern const uint8_t vsf_hw_spi_devices[2];
261 */
262extern const vsf_hal_device_t VSF_HAL_TEMPLATE_DEC_DEVICE_ARRAY[VSF_HAL_TEMPLATE_DEC_COUNT];
263#endif
264
265/**************************** undef ********************************************/
266
267#undef VSF_HAL_TEMPLATE_DEC_NAME
268#undef VSF_HAL_TEMPLATE_DEC_UPCASE_NAME
269#undef VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX
270#undef VSF_HAL_TEMPLATE_DEC_COUNT_MASK_PREFIX
271#undef VSF_HAL_TEMPLATE_DEC_PREFIX
272#undef VSF_HAL_TEMPLATE_DEC_REMAP
273#undef VSF_HAL_TEMPLATE_DEC_REMAP_PREFIX
274#undef VSF_HAL_TEMPLATE_DEC_UPCASE_PREFIX
275#undef VSF_HAL_TEMPLATE_DEC_COUNT_MASK_PREFIX
276#undef VSF_HAL_TEMPLATE_DEC_EXTERN_OP
277#undef VSF_HAL_TEMPLATE_DEC_COUNT_SUFFIX
278#undef VSF_HAL_TEMPLATE_DEC_MASK_SUFFIX
279#undef VSF_HAL_TEMPLATE_DEC_DEFINED_COUNT
280#undef VSF_HAL_TEMPLATE_DEC_DEFINED_MASK
281#undef VSF_HAL_TEMPLATE_DEC_COUNT
282#undef VSF_HAL_TEMPLATE_DEC_MASK
283#undef VSF_HAL_TEMPLATE_DEC_TYPE
284#undef VSF_HAL_TEMPLATE_DEC_REMAP_TYPE
285#undef VSF_HAL_TEMPLATE_DEC_INSTANCE_TYPE
286#undef VSF_HAL_TEMPLATE_DEC_INSTANCE_APIS
287#undef VSF_HAL_TEMPLATE_DEC_ADDITIONAL_API
288#undef VSF_HAL_TEMPLATE_DEC_INSTANCE_OP_TYPE
289#undef VSF_HAL_TEMPLATE_DEC_INSTANCE_OP_INSTANCE
290#undef VSF_HAL_TEMPLATE_DEC_INSTANCE
291#undef VSF_HAL_TEMPLATE_DEC_INSTANCE_ARRAY
292#undef VSF_HAL_TEMPLATE_DEC_LV0
293#undef VSF_HAL_TEMPLATE_DEC_INSTANCE_INDEX_ARRAY
294#undef VSF_HAL_TEMPLATE_DEC_INSTANCE_NAME_ARRAY
295#undef VSF_HAL_TEMPLATE_DEC_REMOVE_ARRAY
296#undef VSF_HAL_TEMPLATE_DEC_DEVICE_ARRAY
#define VSF_HAL_TEMPLATE_DEC_COUNT
Definition pm_template.h:36
unsigned char uint8_t
Definition stdint.h:5
Definition vsf_template_hal_driver.h:184
#define VSF_HAL_TEMPLATE_DEC_INSTANCE_APIS
Definition vsf_template_instance_declaration.h:115
#define VSF_HAL_TEMPLATE_DEC_INSTANCE_OP_TYPE
Definition vsf_template_instance_declaration.h:160
#define VSF_HAL_TEMPLATE_DEC_REMAP_TYPE
Definition vsf_template_instance_declaration.h:94
#define VSF_HAL_TEMPLATE_DEC_DEVICE_PREFIX
Definition vsf_template_instance_declaration.h:62
struct VSF_HAL_TEMPLATE_DEC_REMAP_TYPE VSF_HAL_TEMPLATE_DEC_TYPE
Definition vsf_template_instance_declaration.h:104
#define VSF_HAL_TEMPLATE_DEC_INSTANCE_TYPE
Definition vsf_template_instance_declaration.h:174
#define VSF_HAL_TEMPLATE_DEC_INSTANCE_OP_INSTANCE
Definition vsf_template_instance_declaration.h:164
Generated from commit: vsfteam/vsf@9388752