Zephyr Project API 4.2.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
13#ifndef ZEPHYR_INCLUDE_ZEPHYR_BINDESC_H_
14#define ZEPHYR_INCLUDE_ZEPHYR_BINDESC_H_
15
22#include <zephyr/sys/util_macro.h>
23
24#ifdef __cplusplus
25extern "C" {
26#endif /* __cplusplus */
27
28/*
29 * Corresponds to the definitions in scripts/west_commands/bindesc.py.
30 * Do not change without syncing the definitions in both files!
31 */
32
34#define BINDESC_MAGIC 0xb9863e5a7ea46046
36#define BINDESC_ALIGNMENT 4
37
40#define BINDESC_TYPE_UINT 0x0
41#define BINDESC_TYPE_STR 0x1
42#define BINDESC_TYPE_BYTES 0x2
43#define BINDESC_TYPE_DESCRIPTORS_END 0xf
47/* Needed as sizeof ignores the data as it's a flexible array */
48#define BINDESC_ENTRY_HEADER_SIZE (sizeof(struct bindesc_entry))
49
57/*
58 * Corresponds to the definitions in scripts/west_commands/bindesc.py.
59 * Do not change without syncing the definitions in both files!
60 */
61
63#define BINDESC_ID_APP_VERSION_STRING 0x800
64
66#define BINDESC_ID_APP_VERSION_MAJOR 0x801
67
69#define BINDESC_ID_APP_VERSION_MINOR 0x802
70
72#define BINDESC_ID_APP_VERSION_PATCHLEVEL 0x803
73
75#define BINDESC_ID_APP_VERSION_NUMBER 0x804
76
78#define BINDESC_ID_APP_BUILD_VERSION 0x805
79
81#define BINDESC_ID_KERNEL_VERSION_STRING 0x900
82
84#define BINDESC_ID_KERNEL_VERSION_MAJOR 0x901
85
87#define BINDESC_ID_KERNEL_VERSION_MINOR 0x902
88
90#define BINDESC_ID_KERNEL_VERSION_PATCHLEVEL 0x903
91
93#define BINDESC_ID_KERNEL_VERSION_NUMBER 0x904
94
96#define BINDESC_ID_KERNEL_BUILD_VERSION 0x905
97
99#define BINDESC_ID_BUILD_TIME_YEAR 0xa00
100
102#define BINDESC_ID_BUILD_TIME_MONTH 0xa01
103
105#define BINDESC_ID_BUILD_TIME_DAY 0xa02
106
108#define BINDESC_ID_BUILD_TIME_HOUR 0xa03
109
111#define BINDESC_ID_BUILD_TIME_MINUTE 0xa04
112
114#define BINDESC_ID_BUILD_TIME_SECOND 0xa05
115
117#define BINDESC_ID_BUILD_TIME_UNIX 0xa06
118
120#define BINDESC_ID_BUILD_DATE_TIME_STRING 0xa07
121
123#define BINDESC_ID_BUILD_DATE_STRING 0xa08
124
126#define BINDESC_ID_BUILD_TIME_STRING 0xa09
127
129#define BINDESC_ID_HOST_NAME 0xb00
130
132#define BINDESC_ID_C_COMPILER_NAME 0xb01
133
135#define BINDESC_ID_C_COMPILER_VERSION 0xb02
136
138#define BINDESC_ID_CXX_COMPILER_NAME 0xb03
139
141#define BINDESC_ID_CXX_COMPILER_VERSION 0xb04
142
144#define BINDESC_TAG_DESCRIPTORS_END BINDESC_TAG(DESCRIPTORS_END, 0x0fff)
145
150/*
151 * Utility macro to generate a tag from a type and an ID
152 *
153 * type - Type of the descriptor, UINT, STR or BYTES
154 * id - Unique ID for the descriptor, must fit in 12 bits
155 */
156#define BINDESC_TAG(type, id) ((BINDESC_TYPE_##type & 0xf) << 12 | (id & 0x0fff))
157
163#define BINDESC_GET_TAG_TYPE(tag) ((tag >> 12) & 0xf)
164
169#if !defined(_LINKER) || defined(__DOXYGEN__)
170
171#include <zephyr/sys/byteorder.h>
172#include <zephyr/device.h>
173
178/*
179 * Utility macro to get the name of a bindesc entry
180 */
181#define BINDESC_NAME(name) bindesc_entry_##name
182
183/* Convenience helper for declaring a binary descriptor entry. */
184#define __BINDESC_ENTRY_DEFINE(name) \
185 __aligned(BINDESC_ALIGNMENT) const struct bindesc_entry BINDESC_NAME(name) \
186 __in_section(_bindesc_entry, static, name) __used __noasan
187
206#define BINDESC_STR_DEFINE(name, id, value) \
207 __BINDESC_ENTRY_DEFINE(name) = { \
208 .tag = BINDESC_TAG(STR, id), \
209 .len = (uint16_t)sizeof(value), \
210 .data = value, \
211 }; \
212 BUILD_ASSERT(sizeof(value) <= CONFIG_BINDESC_DEFINE_MAX_DATA_SIZE, \
213 "Bindesc " STRINGIFY(name) " exceeded maximum size, consider reducing the" \
214 " size or changing CONFIG_BINDESC_DEFINE_MAX_DATA_SIZE. ")
215
230#define BINDESC_UINT_DEFINE(name, id, value) \
231 __BINDESC_ENTRY_DEFINE(name) = { \
232 .tag = BINDESC_TAG(UINT, id), \
233 .len = (uint16_t)sizeof(uint32_t), \
234 .data = sys_uint32_to_array(value), \
235 }
236
255#define BINDESC_BYTES_DEFINE(name, id, value) \
256 __BINDESC_ENTRY_DEFINE(name) = { \
257 .tag = BINDESC_TAG(BYTES, id), \
258 .len = (uint16_t)sizeof((uint8_t [])__DEBRACKET value), \
259 .data = __DEBRACKET value, \
260 }; \
261 BUILD_ASSERT(sizeof((uint8_t [])__DEBRACKET value) <= \
262 CONFIG_BINDESC_DEFINE_MAX_DATA_SIZE, \
263 "Bindesc " STRINGIFY(name) " exceeded maximum size, consider reducing the" \
264 " size or changing CONFIG_BINDESC_DEFINE_MAX_DATA_SIZE. ")
265
275#define BINDESC_GET_STR(name) BINDESC_NAME(name).data
276
286#define BINDESC_GET_UINT(name) *(uint32_t *)&(BINDESC_NAME(name).data)
287
300#define BINDESC_GET_BYTES(name) BINDESC_NAME(name).data
301
311#define BINDESC_GET_SIZE(name) BINDESC_NAME(name).len
312
335
337/*
338 * We're assuming that `struct bindesc_entry` has a specific layout in
339 * memory, so it's worth making sure that the layout is really what we
340 * think it is. If these assertions fail for your toolchain/platform,
341 * please open a bug report.
342 */
343BUILD_ASSERT(offsetof(struct bindesc_entry, tag) == 0, "Incorrect memory layout");
344BUILD_ASSERT(offsetof(struct bindesc_entry, len) == 2, "Incorrect memory layout");
345BUILD_ASSERT(offsetof(struct bindesc_entry, data) == 4, "Incorrect memory layout");
351struct bindesc_handle {
353 const uint8_t *address;
354 enum {
355 BINDESC_HANDLE_TYPE_RAM,
356 BINDESC_HANDLE_TYPE_MEMORY_MAPPED_FLASH,
357 BINDESC_HANDLE_TYPE_FLASH,
358 } type;
359 size_t size_limit;
360#if IS_ENABLED(CONFIG_BINDESC_READ_FLASH)
361 const struct device *flash_device;
362 uint8_t buffer[sizeof(struct bindesc_entry) +
363 CONFIG_BINDESC_READ_FLASH_MAX_DATA_SIZE] __aligned(BINDESC_ALIGNMENT);
364#endif /* IS_ENABLED(CONFIG_BINDESC_READ_FLASH) */
366};
367
376typedef int (*bindesc_callback_t)(const struct bindesc_entry *entry, void *user_data);
377
392int bindesc_open_memory_mapped_flash(struct bindesc_handle *handle, size_t offset);
393
412int bindesc_open_ram(struct bindesc_handle *handle, const uint8_t *address, size_t max_size);
413
432int bindesc_open_flash(struct bindesc_handle *handle, size_t offset,
433 const struct device *flash_device);
434
448int bindesc_foreach(struct bindesc_handle *handle, bindesc_callback_t callback, void *user_data);
449
464int bindesc_find_str(struct bindesc_handle *handle, uint16_t id, const char **result);
465
480int bindesc_find_uint(struct bindesc_handle *handle, uint16_t id, const uint32_t **result);
481
497int bindesc_find_bytes(struct bindesc_handle *handle, uint16_t id, const uint8_t **result,
498 size_t *result_size);
499
512int bindesc_get_size(struct bindesc_handle *handle, size_t *result);
513
518#if defined(CONFIG_BINDESC_KERNEL_VERSION_STRING)
519extern const struct bindesc_entry BINDESC_NAME(kernel_version_string);
520#endif /* defined(CONFIG_BINDESC_KERNEL_VERSION_STRING) */
521
522#if defined(CONFIG_BINDESC_KERNEL_VERSION_MAJOR)
523extern const struct bindesc_entry BINDESC_NAME(kernel_version_major);
524#endif /* defined(CONFIG_BINDESC_KERNEL_VERSION_MAJOR) */
525
526#if defined(CONFIG_BINDESC_KERNEL_VERSION_MINOR)
527extern const struct bindesc_entry BINDESC_NAME(kernel_version_minor);
528#endif /* defined(CONFIG_BINDESC_KERNEL_VERSION_MINOR) */
529
530#if defined(CONFIG_BINDESC_KERNEL_VERSION_PATCHLEVEL)
531extern const struct bindesc_entry BINDESC_NAME(kernel_version_patchlevel);
532#endif /* defined(CONFIG_BINDESC_KERNEL_VERSION_PATCHLEVEL) */
533
534#if defined(CONFIG_BINDESC_KERNEL_VERSION_NUMBER)
535extern const struct bindesc_entry BINDESC_NAME(kernel_version_number);
536#endif /* defined(CONFIG_BINDESC_KERNEL_VERSION_NUMBER) */
537
538#if defined(CONFIG_BINDESC_KERNEL_BUILD_VERSION)
539extern const struct bindesc_entry BINDESC_NAME(kernel_build_version);
540#endif /* defined(CONFIG_BINDESC_KERNEL_BUILD_VERSION) */
541
542#if defined(CONFIG_BINDESC_APP_VERSION_STRING)
543extern const struct bindesc_entry BINDESC_NAME(app_version_string);
544#endif /* defined(CONFIG_BINDESC_APP_VERSION_STRING) */
545
546#if defined(CONFIG_BINDESC_APP_VERSION_MAJOR)
547extern const struct bindesc_entry BINDESC_NAME(app_version_major);
548#endif /* defined(CONFIG_BINDESC_APP_VERSION_MAJOR) */
549
550#if defined(CONFIG_BINDESC_APP_VERSION_MINOR)
551extern const struct bindesc_entry BINDESC_NAME(app_version_minor);
552#endif /* defined(CONFIG_BINDESC_APP_VERSION_MINOR) */
553
554#if defined(CONFIG_BINDESC_APP_VERSION_PATCHLEVEL)
555extern const struct bindesc_entry BINDESC_NAME(app_version_patchlevel);
556#endif /* defined(CONFIG_BINDESC_APP_VERSION_PATCHLEVEL) */
557
558#if defined(CONFIG_BINDESC_APP_VERSION_NUMBER)
559extern const struct bindesc_entry BINDESC_NAME(app_version_number);
560#endif /* defined(CONFIG_BINDESC_APP_VERSION_NUMBER) */
561
562#if defined(CONFIG_BINDESC_APP_BUILD_VERSION)
563extern const struct bindesc_entry BINDESC_NAME(app_build_version);
564#endif /* defined(CONFIG_BINDESC_APP_BUILD_VERSION) */
565
566#if defined(CONFIG_BINDESC_BUILD_TIME_YEAR)
567extern const struct bindesc_entry BINDESC_NAME(build_time_year);
568#endif /* defined(CONFIG_BINDESC_BUILD_TIME_YEAR) */
569
570#if defined(CONFIG_BINDESC_BUILD_TIME_MONTH)
571extern const struct bindesc_entry BINDESC_NAME(build_time_month);
572#endif /* defined(CONFIG_BINDESC_BUILD_TIME_MONTH) */
573
574#if defined(CONFIG_BINDESC_BUILD_TIME_DAY)
575extern const struct bindesc_entry BINDESC_NAME(build_time_day);
576#endif /* defined(CONFIG_BINDESC_BUILD_TIME_DAY) */
577
578#if defined(CONFIG_BINDESC_BUILD_TIME_HOUR)
579extern const struct bindesc_entry BINDESC_NAME(build_time_hour);
580#endif /* defined(CONFIG_BINDESC_BUILD_TIME_HOUR) */
581
582#if defined(CONFIG_BINDESC_BUILD_TIME_MINUTE)
583extern const struct bindesc_entry BINDESC_NAME(build_time_minute);
584#endif /* defined(CONFIG_BINDESC_BUILD_TIME_MINUTE) */
585
586#if defined(CONFIG_BINDESC_BUILD_TIME_SECOND)
587extern const struct bindesc_entry BINDESC_NAME(build_time_second);
588#endif /* defined(CONFIG_BINDESC_BUILD_TIME_SECOND) */
589
590#if defined(CONFIG_BINDESC_BUILD_TIME_UNIX)
591extern const struct bindesc_entry BINDESC_NAME(build_time_unix);
592#endif /* defined(CONFIG_BINDESC_BUILD_TIME_UNIX) */
593
594#if defined(CONFIG_BINDESC_BUILD_DATE_TIME_STRING)
595extern const struct bindesc_entry BINDESC_NAME(build_date_time_string);
596#endif /* defined(CONFIG_BINDESC_BUILD_DATE_TIME_STRING) */
597
598#if defined(CONFIG_BINDESC_BUILD_DATE_STRING)
599extern const struct bindesc_entry BINDESC_NAME(build_date_string);
600#endif /* defined(CONFIG_BINDESC_BUILD_DATE_STRING) */
601
602#if defined(CONFIG_BINDESC_BUILD_TIME_STRING)
603extern const struct bindesc_entry BINDESC_NAME(build_time_string);
604#endif /* defined(CONFIG_BINDESC_BUILD_TIME_STRING) */
605
606#if defined(CONFIG_BINDESC_HOST_NAME)
607extern const struct bindesc_entry BINDESC_NAME(host_name);
608#endif /* defined(CONFIG_BINDESC_HOST_NAME) */
609
610#if defined(CONFIG_BINDESC_C_COMPILER_NAME)
611extern const struct bindesc_entry BINDESC_NAME(c_compiler_name);
612#endif /* defined(CONFIG_BINDESC_C_COMPILER_NAME) */
613
614#if defined(CONFIG_BINDESC_C_COMPILER_VERSION)
615extern const struct bindesc_entry BINDESC_NAME(c_compiler_version);
616#endif /* defined(CONFIG_BINDESC_C_COMPILER_VERSION) */
617
618#if defined(CONFIG_BINDESC_CXX_COMPILER_NAME)
619extern const struct bindesc_entry BINDESC_NAME(cxx_compiler_name);
620#endif /* defined(CONFIG_BINDESC_CXX_COMPILER_NAME) */
621
622#if defined(CONFIG_BINDESC_CXX_COMPILER_VERSION)
623extern const struct bindesc_entry BINDESC_NAME(cxx_compiler_version);
624#endif /* defined(CONFIG_BINDESC_CXX_COMPILER_VERSION) */
625
626#endif /* !defined(_LINKER) */
627
628#ifdef __cplusplus
629}
630#endif
631
636#endif /* ZEPHYR_INCLUDE_ZEPHYR_BINDESC_H_ */
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:376
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.
BINDESC_ALIGNMENT
#define BINDESC_ALIGNMENT
Required memory alignment for binary descriptor entries.
Definition bindesc.h:36
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
Structure for a binary descriptor entry.
Definition bindesc.h:327
bindesc_entry::data
uint8_t data[]
Value of the entry.
Definition bindesc.h:333
bindesc_entry::tag
uint16_t tag
Tag of the entry.
Definition bindesc.h:329
bindesc_entry::len
uint16_t len
Length of the descriptor data.
Definition bindesc.h:331
bindesc_handle
Handle for reading binary descriptors from firmware images.
Definition bindesc.h:351
device
Runtime device structure (in ROM) per driver instance.
Definition device.h:510
byteorder.h
Byte order helpers.
util_macro.h
Macro utilities.