Zephyr API Documentation 4.0.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
bindesc.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2023 Yonatan Schachter
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7#ifndef ZEPHYR_INCLUDE_ZEPHYR_BINDESC_H_
8#define ZEPHYR_INCLUDE_ZEPHYR_BINDESC_H_
9
10#include <zephyr/sys/util_macro.h>
11
12#ifdef __cplusplus
13extern "C" {
14#endif /* __cplusplus */
15
16/*
17 * Corresponds to the definitions in scripts/west_commands/bindesc.py.
18 * Do not change without syncing the definitions in both files!
19 */
20#define BINDESC_MAGIC 0xb9863e5a7ea46046
21#define BINDESC_ALIGNMENT 4
22#define BINDESC_TYPE_UINT 0x0
23#define BINDESC_TYPE_STR 0x1
24#define BINDESC_TYPE_BYTES 0x2
25#define BINDESC_TYPE_DESCRIPTORS_END 0xf
26/* sizeof ignores the data as it's a flexible array */
27#define BINDESC_ENTRY_HEADER_SIZE (sizeof(struct bindesc_entry))
28
36/*
37 * Corresponds to the definitions in scripts/west_commands/bindesc.py.
38 * Do not change without syncing the definitions in both files!
39 */
40
42#define BINDESC_ID_APP_VERSION_STRING 0x800
43
45#define BINDESC_ID_APP_VERSION_MAJOR 0x801
46
48#define BINDESC_ID_APP_VERSION_MINOR 0x802
49
51#define BINDESC_ID_APP_VERSION_PATCHLEVEL 0x803
52
54#define BINDESC_ID_APP_VERSION_NUMBER 0x804
55
57#define BINDESC_ID_APP_BUILD_VERSION 0x805
58
60#define BINDESC_ID_KERNEL_VERSION_STRING 0x900
61
63#define BINDESC_ID_KERNEL_VERSION_MAJOR 0x901
64
66#define BINDESC_ID_KERNEL_VERSION_MINOR 0x902
67
69#define BINDESC_ID_KERNEL_VERSION_PATCHLEVEL 0x903
70
72#define BINDESC_ID_KERNEL_VERSION_NUMBER 0x904
73
75#define BINDESC_ID_KERNEL_BUILD_VERSION 0x905
76
78#define BINDESC_ID_BUILD_TIME_YEAR 0xa00
79
81#define BINDESC_ID_BUILD_TIME_MONTH 0xa01
82
84#define BINDESC_ID_BUILD_TIME_DAY 0xa02
85
87#define BINDESC_ID_BUILD_TIME_HOUR 0xa03
88
90#define BINDESC_ID_BUILD_TIME_MINUTE 0xa04
91
93#define BINDESC_ID_BUILD_TIME_SECOND 0xa05
94
96#define BINDESC_ID_BUILD_TIME_UNIX 0xa06
97
99#define BINDESC_ID_BUILD_DATE_TIME_STRING 0xa07
100
102#define BINDESC_ID_BUILD_DATE_STRING 0xa08
103
105#define BINDESC_ID_BUILD_TIME_STRING 0xa09
106
108#define BINDESC_ID_HOST_NAME 0xb00
109
111#define BINDESC_ID_C_COMPILER_NAME 0xb01
112
114#define BINDESC_ID_C_COMPILER_VERSION 0xb02
115
117#define BINDESC_ID_CXX_COMPILER_NAME 0xb03
118
120#define BINDESC_ID_CXX_COMPILER_VERSION 0xb04
121
122#define BINDESC_TAG_DESCRIPTORS_END BINDESC_TAG(DESCRIPTORS_END, 0x0fff)
123
128/*
129 * Utility macro to generate a tag from a type and an ID
130 *
131 * type - Type of the descriptor, UINT, STR or BYTES
132 * id - Unique ID for the descriptor, must fit in 12 bits
133 */
134#define BINDESC_TAG(type, id) ((BINDESC_TYPE_##type & 0xf) << 12 | (id & 0x0fff))
135
141#define BINDESC_GET_TAG_TYPE(tag) ((tag >> 12) & 0xf)
142
147#if !defined(_LINKER) || defined(__DOXYGEN__)
148
149#include <zephyr/sys/byteorder.h>
150#include <zephyr/device.h>
151
156/*
157 * Utility macro to get the name of a bindesc entry
158 */
159#define BINDESC_NAME(name) bindesc_entry_##name
160
161/* Convenience helper for declaring a binary descriptor entry. */
162#define __BINDESC_ENTRY_DEFINE(name) \
163 __aligned(BINDESC_ALIGNMENT) const struct bindesc_entry BINDESC_NAME(name) \
164 __in_section(_bindesc_entry, static, name) __used __noasan
165
184#define BINDESC_STR_DEFINE(name, id, value) \
185 __BINDESC_ENTRY_DEFINE(name) = { \
186 .tag = BINDESC_TAG(STR, id), \
187 .len = (uint16_t)sizeof(value), \
188 .data = value, \
189 }; \
190 BUILD_ASSERT(sizeof(value) <= CONFIG_BINDESC_DEFINE_MAX_DATA_SIZE, \
191 "Bindesc " STRINGIFY(name) " exceeded maximum size, consider reducing the" \
192 " size or changing CONFIG_BINDESC_DEFINE_MAX_DATA_SIZE. ")
193
208#define BINDESC_UINT_DEFINE(name, id, value) \
209 __BINDESC_ENTRY_DEFINE(name) = { \
210 .tag = BINDESC_TAG(UINT, id), \
211 .len = (uint16_t)sizeof(uint32_t), \
212 .data = sys_uint32_to_array(value), \
213 }
214
233#define BINDESC_BYTES_DEFINE(name, id, value) \
234 __BINDESC_ENTRY_DEFINE(name) = { \
235 .tag = BINDESC_TAG(BYTES, id), \
236 .len = (uint16_t)sizeof((uint8_t [])__DEBRACKET value), \
237 .data = __DEBRACKET value, \
238 }; \
239 BUILD_ASSERT(sizeof((uint8_t [])__DEBRACKET value) <= \
240 CONFIG_BINDESC_DEFINE_MAX_DATA_SIZE, \
241 "Bindesc " STRINGIFY(name) " exceeded maximum size, consider reducing the" \
242 " size or changing CONFIG_BINDESC_DEFINE_MAX_DATA_SIZE. ")
243
253#define BINDESC_GET_STR(name) BINDESC_NAME(name).data
254
264#define BINDESC_GET_UINT(name) *(uint32_t *)&(BINDESC_NAME(name).data)
265
278#define BINDESC_GET_BYTES(name) BINDESC_NAME(name).data
279
289#define BINDESC_GET_SIZE(name) BINDESC_NAME(name).len
290
295/*
296 * An entry of the binary descriptor header. Each descriptor is
297 * described by one of these entries.
298 */
307
308/*
309 * We're assuming that `struct bindesc_entry` has a specific layout in
310 * memory, so it's worth making sure that the layout is really what we
311 * think it is. If these assertions fail for your toolchain/platform,
312 * please open a bug report.
313 */
314BUILD_ASSERT(offsetof(struct bindesc_entry, tag) == 0, "Incorrect memory layout");
315BUILD_ASSERT(offsetof(struct bindesc_entry, len) == 2, "Incorrect memory layout");
316BUILD_ASSERT(offsetof(struct bindesc_entry, data) == 4, "Incorrect memory layout");
317
318struct bindesc_handle {
319 const uint8_t *address;
320 enum {
321 BINDESC_HANDLE_TYPE_RAM,
322 BINDESC_HANDLE_TYPE_MEMORY_MAPPED_FLASH,
323 BINDESC_HANDLE_TYPE_FLASH,
324 } type;
325 size_t size_limit;
326#if IS_ENABLED(CONFIG_BINDESC_READ_FLASH)
327 const struct device *flash_device;
328 uint8_t buffer[sizeof(struct bindesc_entry) +
329 CONFIG_BINDESC_READ_FLASH_MAX_DATA_SIZE] __aligned(BINDESC_ALIGNMENT);
330#endif /* IS_ENABLED(CONFIG_BINDESC_READ_FLASH) */
331};
332
348typedef int (*bindesc_callback_t)(const struct bindesc_entry *entry, void *user_data);
349
364int bindesc_open_memory_mapped_flash(struct bindesc_handle *handle, size_t offset);
365
384int bindesc_open_ram(struct bindesc_handle *handle, const uint8_t *address, size_t max_size);
385
402int bindesc_open_flash(struct bindesc_handle *handle, size_t offset,
403 const struct device *flash_device);
404
418int bindesc_foreach(struct bindesc_handle *handle, bindesc_callback_t callback, void *user_data);
419
434int bindesc_find_str(struct bindesc_handle *handle, uint16_t id, const char **result);
435
450int bindesc_find_uint(struct bindesc_handle *handle, uint16_t id, const uint32_t **result);
451
467int bindesc_find_bytes(struct bindesc_handle *handle, uint16_t id, const uint8_t **result,
468 size_t *result_size);
469
482int bindesc_get_size(struct bindesc_handle *handle, size_t *result);
483
488#if defined(CONFIG_BINDESC_KERNEL_VERSION_STRING)
489extern const struct bindesc_entry BINDESC_NAME(kernel_version_string);
490#endif /* defined(CONFIG_BINDESC_KERNEL_VERSION_STRING) */
491
492#if defined(CONFIG_BINDESC_KERNEL_VERSION_MAJOR)
493extern const struct bindesc_entry BINDESC_NAME(kernel_version_major);
494#endif /* defined(CONFIG_BINDESC_KERNEL_VERSION_MAJOR) */
495
496#if defined(CONFIG_BINDESC_KERNEL_VERSION_MINOR)
497extern const struct bindesc_entry BINDESC_NAME(kernel_version_minor);
498#endif /* defined(CONFIG_BINDESC_KERNEL_VERSION_MINOR) */
499
500#if defined(CONFIG_BINDESC_KERNEL_VERSION_PATCHLEVEL)
501extern const struct bindesc_entry BINDESC_NAME(kernel_version_patchlevel);
502#endif /* defined(CONFIG_BINDESC_KERNEL_VERSION_PATCHLEVEL) */
503
504#if defined(CONFIG_BINDESC_KERNEL_VERSION_NUMBER)
505extern const struct bindesc_entry BINDESC_NAME(kernel_version_number);
506#endif /* defined(CONFIG_BINDESC_KERNEL_VERSION_NUMBER) */
507
508#if defined(CONFIG_BINDESC_KERNEL_BUILD_VERSION)
509extern const struct bindesc_entry BINDESC_NAME(kernel_build_version);
510#endif /* defined(CONFIG_BINDESC_KERNEL_BUILD_VERSION) */
511
512#if defined(CONFIG_BINDESC_APP_VERSION_STRING)
513extern const struct bindesc_entry BINDESC_NAME(app_version_string);
514#endif /* defined(CONFIG_BINDESC_APP_VERSION_STRING) */
515
516#if defined(CONFIG_BINDESC_APP_VERSION_MAJOR)
517extern const struct bindesc_entry BINDESC_NAME(app_version_major);
518#endif /* defined(CONFIG_BINDESC_APP_VERSION_MAJOR) */
519
520#if defined(CONFIG_BINDESC_APP_VERSION_MINOR)
521extern const struct bindesc_entry BINDESC_NAME(app_version_minor);
522#endif /* defined(CONFIG_BINDESC_APP_VERSION_MINOR) */
523
524#if defined(CONFIG_BINDESC_APP_VERSION_PATCHLEVEL)
525extern const struct bindesc_entry BINDESC_NAME(app_version_patchlevel);
526#endif /* defined(CONFIG_BINDESC_APP_VERSION_PATCHLEVEL) */
527
528#if defined(CONFIG_BINDESC_APP_VERSION_NUMBER)
529extern const struct bindesc_entry BINDESC_NAME(app_version_number);
530#endif /* defined(CONFIG_BINDESC_APP_VERSION_NUMBER) */
531
532#if defined(CONFIG_BINDESC_APP_BUILD_VERSION)
533extern const struct bindesc_entry BINDESC_NAME(app_build_version);
534#endif /* defined(CONFIG_BINDESC_APP_BUILD_VERSION) */
535
536#if defined(CONFIG_BINDESC_BUILD_TIME_YEAR)
537extern const struct bindesc_entry BINDESC_NAME(build_time_year);
538#endif /* defined(CONFIG_BINDESC_BUILD_TIME_YEAR) */
539
540#if defined(CONFIG_BINDESC_BUILD_TIME_MONTH)
541extern const struct bindesc_entry BINDESC_NAME(build_time_month);
542#endif /* defined(CONFIG_BINDESC_BUILD_TIME_MONTH) */
543
544#if defined(CONFIG_BINDESC_BUILD_TIME_DAY)
545extern const struct bindesc_entry BINDESC_NAME(build_time_day);
546#endif /* defined(CONFIG_BINDESC_BUILD_TIME_DAY) */
547
548#if defined(CONFIG_BINDESC_BUILD_TIME_HOUR)
549extern const struct bindesc_entry BINDESC_NAME(build_time_hour);
550#endif /* defined(CONFIG_BINDESC_BUILD_TIME_HOUR) */
551
552#if defined(CONFIG_BINDESC_BUILD_TIME_MINUTE)
553extern const struct bindesc_entry BINDESC_NAME(build_time_minute);
554#endif /* defined(CONFIG_BINDESC_BUILD_TIME_MINUTE) */
555
556#if defined(CONFIG_BINDESC_BUILD_TIME_SECOND)
557extern const struct bindesc_entry BINDESC_NAME(build_time_second);
558#endif /* defined(CONFIG_BINDESC_BUILD_TIME_SECOND) */
559
560#if defined(CONFIG_BINDESC_BUILD_TIME_UNIX)
561extern const struct bindesc_entry BINDESC_NAME(build_time_unix);
562#endif /* defined(CONFIG_BINDESC_BUILD_TIME_UNIX) */
563
564#if defined(CONFIG_BINDESC_BUILD_DATE_TIME_STRING)
565extern const struct bindesc_entry BINDESC_NAME(build_date_time_string);
566#endif /* defined(CONFIG_BINDESC_BUILD_DATE_TIME_STRING) */
567
568#if defined(CONFIG_BINDESC_BUILD_DATE_STRING)
569extern const struct bindesc_entry BINDESC_NAME(build_date_string);
570#endif /* defined(CONFIG_BINDESC_BUILD_DATE_STRING) */
571
572#if defined(CONFIG_BINDESC_BUILD_TIME_STRING)
573extern const struct bindesc_entry BINDESC_NAME(build_time_string);
574#endif /* defined(CONFIG_BINDESC_BUILD_TIME_STRING) */
575
576#if defined(CONFIG_BINDESC_HOST_NAME)
577extern const struct bindesc_entry BINDESC_NAME(host_name);
578#endif /* defined(CONFIG_BINDESC_HOST_NAME) */
579
580#if defined(CONFIG_BINDESC_C_COMPILER_NAME)
581extern const struct bindesc_entry BINDESC_NAME(c_compiler_name);
582#endif /* defined(CONFIG_BINDESC_C_COMPILER_NAME) */
583
584#if defined(CONFIG_BINDESC_C_COMPILER_VERSION)
585extern const struct bindesc_entry BINDESC_NAME(c_compiler_version);
586#endif /* defined(CONFIG_BINDESC_C_COMPILER_VERSION) */
587
588#if defined(CONFIG_BINDESC_CXX_COMPILER_NAME)
589extern const struct bindesc_entry BINDESC_NAME(cxx_compiler_name);
590#endif /* defined(CONFIG_BINDESC_CXX_COMPILER_NAME) */
591
592#if defined(CONFIG_BINDESC_CXX_COMPILER_VERSION)
593extern const struct bindesc_entry BINDESC_NAME(cxx_compiler_version);
594#endif /* defined(CONFIG_BINDESC_CXX_COMPILER_VERSION) */
595
596#endif /* !defined(_LINKER) */
597
598#ifdef __cplusplus
599}
600#endif
601
602#endif /* ZEPHYR_INCLUDE_ZEPHYR_BINDESC_H_ */
BINDESC_ALIGNMENT
#define BINDESC_ALIGNMENT
Definition bindesc.h:21
bindesc_open_memory_mapped_flash
int bindesc_open_memory_mapped_flash(struct bindesc_handle *handle, size_t offset)
Open an image's binary descriptors for reading, from a memory mapped flash.
bindesc_find_str
int bindesc_find_str(struct bindesc_handle *handle, uint16_t id, const char **result)
Find a specific descriptor of type string.
bindesc_callback_t
int(* bindesc_callback_t)(const struct bindesc_entry *entry, void *user_data)
Callback type to be called on descriptors found during a walk.
Definition bindesc.h:348
bindesc_open_flash
int bindesc_open_flash(struct bindesc_handle *handle, size_t offset, const struct device *flash_device)
Open an image's binary descriptors for reading, from flash.
bindesc_get_size
int bindesc_get_size(struct bindesc_handle *handle, size_t *result)
Get the size of an image's binary descriptors.
bindesc_foreach
int bindesc_foreach(struct bindesc_handle *handle, bindesc_callback_t callback, void *user_data)
Walk the binary descriptors and run a user defined callback on each of them.
bindesc_find_uint
int bindesc_find_uint(struct bindesc_handle *handle, uint16_t id, const uint32_t **result)
Find a specific descriptor of type uint.
bindesc_open_ram
int bindesc_open_ram(struct bindesc_handle *handle, const uint8_t *address, size_t max_size)
Open an image's binary descriptors for reading, from RAM.
bindesc_find_bytes
int bindesc_find_bytes(struct bindesc_handle *handle, uint16_t id, const uint8_t **result, size_t *result_size)
Find a specific descriptor of type bytes.
uint32_t
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
uint8_t
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
uint16_t
__UINT16_TYPE__ uint16_t
Definition stdint.h:89
bindesc_entry
Definition bindesc.h:299
bindesc_entry::data
uint8_t data[]
Value of the entry.
Definition bindesc.h:305
bindesc_entry::tag
uint16_t tag
Tag of the entry.
Definition bindesc.h:301
bindesc_entry::len
uint16_t len
Length of the descriptor data.
Definition bindesc.h:303
bindesc_handle
Definition bindesc.h:318
bindesc_handle::address
const uint8_t * address
Definition bindesc.h:319
bindesc_handle::BINDESC_HANDLE_TYPE_RAM
@ BINDESC_HANDLE_TYPE_RAM
Definition bindesc.h:321
bindesc_handle::BINDESC_HANDLE_TYPE_MEMORY_MAPPED_FLASH
@ BINDESC_HANDLE_TYPE_MEMORY_MAPPED_FLASH
Definition bindesc.h:322
bindesc_handle::BINDESC_HANDLE_TYPE_FLASH
@ BINDESC_HANDLE_TYPE_FLASH
Definition bindesc.h:323
bindesc_handle::size_limit
size_t size_limit
Definition bindesc.h:325
bindesc_handle::type
enum bindesc_handle::@68 type
device
Runtime device structure (in ROM) per driver instance.
Definition device.h:411
byteorder.h
Byte order helpers.
util_macro.h
Macro utilities.