BASEplatform API Reference Manual - JBLopenContents iii bp_time_sleep_busy32() . . . . . . . . . . ....

RM0001

July 9, 2019

JBLopenEmbedded Software Insight

BASEplatformAPIReferenceManual

Copyright© 2017-2019 JBLopen Inc.All rights reserved. No part of this document and any associated software may be reproduced,distributed or transmitted in any form or by any means without the prior written consent of JBLopen Inc.

DisclaimerWhile JBLopen Inc. has made every attempt to ensure the accuracy of the information contained in thispublication, JBLopen Inc. cannot warrant the accuracy of completeness of such information. JBLopenInc. may change, add or remove any content in this publication at any time without notice.

All the information contained in this publication as well as any associated material, including software,scripts, and examples are provided “as is”. JBLopen Inc. makes no express or implied warranty of anykind, including warranty of merchantability, noninfringement of intellectual property, or fitness for aparticular purpose. In no event shall JBLopen Inc. be held liable for any damage resulting from the useor inability to use the information contained therein or any other associated material.

TrademarkJBLopen, the JBLopen logo, and BASEplatformTM are trademarks of JBLopen Inc. All other trademarksare trademarks or registered trademarks of their respective owners.

Contents

1 Overview 1About the BASEplatform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Elements of the API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Function Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Blocking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5ISR-Safe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Critical Safe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Thread-Safe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Function Attributes in Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

API Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Numerical Values of Macros and Enumeration Constants . . . . . . . . . . . . . . . . . . . . 8

Driver API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Advanced Driver API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Accessing the Drivers Directly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2 Architecture 9bp_irq_flag_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9BP_ARCH_ALIGN_MAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9BP_ARCH_COMPILER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10BP_ARCH_CORE_ID_GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10BP_ARCH_CPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10BP_ARCH_DEBUG_BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10BP_ARCH_ENDIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10BP_ARCH_INT_DIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10BP_ARCH_INT_EN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11BP_ARCH_IS_CRIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11BP_ARCH_IS_INT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

BASEplatform API Reference Manual www.jblopen.com

https://www.jblopen.com

JBLopenEmbedded Software Insight Contents ii

BP_ARCH_IS_INT_OR_CRIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11BP_ARCH_MB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11BP_ARCH_PANIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12BP_ARCH_RMB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12BP_ARCH_SEV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12BP_ARCH_WFE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12BP_ARCH_WFI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12BP_ARCH_WMB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3 Cache Management 14bp_cache_dcache_inv_all() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14bp_cache_dcache_max_line_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15bp_cache_dcache_min_line_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15bp_cache_dcache_range_clean() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16bp_cache_dcache_range_cleaninv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16bp_cache_dcache_range_inv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17bp_cache_icache_inv_all() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

4 Spinlocks 19bp_critical_section_enter() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19bp_critical_section_exit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20bp_slock_acquire() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20bp_slock_acquire_irq_dis() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20bp_slock_acquire_irq_save() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21bp_slock_release() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21bp_slock_release_irq_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22bp_slock_release_irq_restore() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22bp_slock_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

5 Time 24bp_time_freq_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24bp_time_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25bp_time_get32() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25bp_time_get_ms() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25bp_time_get_ms32() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26bp_time_get_ns() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26bp_time_get_ns32() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27bp_time_halt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27bp_time_init() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27bp_time_ms_to_raw() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28bp_time_ms_to_raw32() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28bp_time_ns_to_raw() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29bp_time_ns_to_raw32() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29bp_time_raw_to_ms() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30bp_time_raw_to_ms32() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30bp_time_raw_to_ns() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31bp_time_raw_to_ns32() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31bp_time_resume() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32bp_time_sleep() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32bp_time_sleep32() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33bp_time_sleep_busy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33



JBLopenEmbedded Software Insight Contents iii

bp_time_sleep_busy32() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34bp_time_sleep_busy_ms() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34bp_time_sleep_busy_ns() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35bp_time_sleep_ms() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36bp_time_sleep_ns() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36bp_time_sleep_yield() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37bp_time_sleep_yield32() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37bp_time_sleep_yield_ms() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38bp_time_sleep_yield_ns() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

6 Timers 40bp_timer_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40bp_timer_destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41bp_timer_halt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41bp_timer_init() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41bp_timer_restart() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42bp_timer_restart_ms() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42bp_timer_restart_ns() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43bp_timer_resume() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44bp_timer_start() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44bp_timer_start_ms() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45bp_timer_start_ns() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45bp_timer_stop() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46bp_timer_target_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46bp_timer_action_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47bp_timer_cb_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47bp_timer_hndl_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

7 Platform Clocks 49bp_clock_dis() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49bp_clock_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50bp_clock_freq_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50bp_clock_gate_id_is_valid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51bp_clock_id_is_valid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51bp_clock_is_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

8 Platform Resets 53bp_periph_reset_assert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53bp_periph_reset_deassert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54bp_periph_reset_id_is_valid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54bp_periph_reset_is_asserted() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

9 Interrupt Management 56bp_int_arg_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56bp_int_dis() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57bp_int_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57bp_int_id_is_valid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58bp_int_init() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58bp_int_prio_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59bp_int_prio_highest_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59bp_int_prio_lowest_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59bp_int_prio_next_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60



JBLopenEmbedded Software Insight Contents iv

bp_int_prio_prev_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60bp_int_prio_set() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61bp_int_reg() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61bp_int_src_dis() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62bp_int_src_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62bp_int_src_is_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63bp_int_trig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63bp_int_type_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64bp_int_type_set() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64bp_int_type_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65bp_int_handler_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65BP_INT_ID_NONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

10 Interrupt SMP Extension 67bp_int_smp_src_dis() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67bp_int_smp_src_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68bp_int_smp_trig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

11 GPIO 69bp_gpio_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69bp_gpio_data_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70bp_gpio_data_set() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71bp_gpio_data_tog() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71bp_gpio_destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72bp_gpio_dir_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72bp_gpio_dir_set() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73bp_gpio_dis() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74bp_gpio_drv_hndl_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74bp_gpio_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75bp_gpio_hndl_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75bp_gpio_is_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76bp_gpio_reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76bp_gpio_dir_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77bp_gpio_board_def_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77bp_gpio_drv_hndl_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78bp_gpio_hndl_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78bp_gpio_soc_def_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78BP_GPIO_HNDL_IS_NULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79BP_GPIO_NULL_HNDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

12 I2C 80bp_i2c_acquire() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80bp_i2c_addr_is_10b() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81bp_i2c_addr_is_valid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81bp_i2c_cfg_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82bp_i2c_cfg_set() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82bp_i2c_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84bp_i2c_destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85bp_i2c_dis() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85bp_i2c_drv_hndl_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86bp_i2c_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87



JBLopenEmbedded Software Insight Contents v

bp_i2c_flush() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87bp_i2c_hndl_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88bp_i2c_idle_wait() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88bp_i2c_is_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89bp_i2c_release() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89bp_i2c_reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90bp_i2c_xfer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90bp_i2c_xfer_async() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92bp_i2c_xfer_async_abort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93bp_i2c_action_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94bp_i2c_dir_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94bp_i2c_async_cb_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94bp_i2c_board_def_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95bp_i2c_cfg_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96bp_i2c_drv_hndl_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96bp_i2c_hndl_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96bp_i2c_soc_def_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96bp_i2c_tf_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97BP_I2C_10B_SLV_ADDR_MASK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97BP_I2C_HNDL_IS_NULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98BP_I2C_MAX_10B_SLV_ADDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98BP_I2C_MAX_SLV_ADDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98BP_I2C_MIN_10B_SLV_ADDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98BP_I2C_NULL_HNDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98BP_I2C_SLV_ADDR_MASK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

13 SPI 100bp_spi_cfg_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100bp_spi_cfg_set() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101bp_spi_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102bp_spi_destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103bp_spi_dis() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104bp_spi_drv_hndl_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105bp_spi_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105bp_spi_flush() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106bp_spi_hndl_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106bp_spi_idle_wait() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107bp_spi_is_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107bp_spi_reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108bp_spi_slave_desel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108bp_spi_slave_sel() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109bp_spi_xfer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110bp_spi_xfer_async() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111bp_spi_xfer_async_abort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112bp_spi_action_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112bp_spi_async_cb_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113bp_spi_board_def_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114bp_spi_cfg_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114bp_spi_drv_hndl_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114bp_spi_hndl_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115bp_spi_soc_def_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115



JBLopenEmbedded Software Insight Contents vi

bp_spi_tf_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115BP_SPI_HNDL_IS_NULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116BP_SPI_NULL_HNDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116BP_SPI_SS_NONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

14 UART 117bp_uart_acquire() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117bp_uart_cfg_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118bp_uart_cfg_set() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118bp_uart_create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120bp_uart_destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121bp_uart_dis() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122bp_uart_drv_hndl_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122bp_uart_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123bp_uart_hndl_get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123bp_uart_is_en() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124bp_uart_release() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124bp_uart_reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125bp_uart_rx() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125bp_uart_rx_async() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126bp_uart_rx_async_abort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127bp_uart_rx_flush() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128bp_uart_rx_idle_wait() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128bp_uart_tx() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129bp_uart_tx_async() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129bp_uart_tx_async_abort() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130bp_uart_tx_flush() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131bp_uart_tx_idle_wait() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131bp_uart_action_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132bp_uart_parity_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132bp_uart_stop_bits_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133bp_uart_async_cb_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133bp_uart_board_def_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134bp_uart_cfg_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134bp_uart_drv_hndl_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135bp_uart_hndl_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135bp_uart_soc_def_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135bp_uart_tf_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136BP_UART_HNDL_IS_NULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136BP_UART_NULL_HNDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136BP_UART_PARITY_IS_VALID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137BP_UART_STOP_BITS_IS_VALID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

15 Error Codes 138RTNC_* . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

16 Architecture Definitions 139BP_ARCH_CPU_ARM_V5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139BP_ARCH_CPU_ARM_V6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139BP_ARCH_CPU_ARM_V6M . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139BP_ARCH_CPU_ARM_V7AR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139



JBLopenEmbedded Software Insight Contents vii

BP_ARCH_CPU_ARM_V7M . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140BP_ARCH_CPU_ARM_V8A . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140BP_ARCH_CPU_ARM_V8M . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140BP_ARCH_CPU_ARM_V8R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140BP_ARCH_CPU_LINUX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140BP_ARCH_CPU_MICROBLAZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140BP_ARCH_CPU_NONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141BP_ARCH_CPU_SPARCV8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141BP_ARCH_CPU_SPARCV9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

17 GPIO Driver 142bp_gpio_drv_create_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142bp_gpio_drv_data_get_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143bp_gpio_drv_data_set_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143bp_gpio_drv_data_tog_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144bp_gpio_drv_destroy_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144bp_gpio_drv_dir_get_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145bp_gpio_drv_dir_set_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145bp_gpio_drv_dis_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146bp_gpio_drv_en_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146bp_gpio_drv_is_en_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147bp_gpio_drv_reset_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147BP_GPIO_DRV_HNDL_IS_NULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148BP_GPIO_DRV_NULL_HNDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

18 I2C Driver 149bp_i2c_drv_cfg_get_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149bp_i2c_drv_cfg_set_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150bp_i2c_drv_create_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150bp_i2c_drv_destroy_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151bp_i2c_drv_dis_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151bp_i2c_drv_en_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152bp_i2c_drv_flush_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152bp_i2c_drv_idle_wait_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153bp_i2c_drv_is_en_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153bp_i2c_drv_reset_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154bp_i2c_drv_xfer_async_abort_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154bp_i2c_drv_xfer_async_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155bp_i2c_drv_xfer_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155BP_I2C_DRV_HNDL_IS_NULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156BP_I2C_DRV_NULL_HNDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

19 SPI Driver 157bp_spi_drv_cfg_get_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157bp_spi_drv_cfg_set_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158bp_spi_drv_create_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159bp_spi_drv_destroy_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159bp_spi_drv_dis_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160bp_spi_drv_en_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160bp_spi_drv_flush_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161bp_spi_drv_idle_wait_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161



JBLopenEmbedded Software Insight Contents viii

bp_spi_drv_is_en_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162bp_spi_drv_reset_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162bp_spi_drv_slave_desel_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162bp_spi_drv_slave_sel_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163bp_spi_drv_xfer_async_abort_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163bp_spi_drv_xfer_async_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164bp_spi_drv_xfer_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165BP_SPI_DRV_HNDL_IS_NULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165BP_SPI_DRV_NULL_HNDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

20 UART Driver 166bp_uart_cfg_get_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166bp_uart_drv_cfg_set_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167bp_uart_drv_create_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167bp_uart_drv_destroy_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168bp_uart_drv_dis_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168bp_uart_drv_en_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169bp_uart_drv_is_en_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169bp_uart_drv_reset_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170bp_uart_drv_rx_async_abort_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170bp_uart_drv_rx_async_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171bp_uart_drv_rx_flush_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171bp_uart_drv_rx_idle_wait_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172bp_uart_drv_rx_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172bp_uart_drv_tx_async_abort_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173bp_uart_drv_tx_async_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173bp_uart_drv_tx_flush_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174bp_uart_drv_tx_idle_wait_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174bp_uart_drv_tx_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175BP_UART_DRV_HNDL_IS_NULL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175BP_UART_DRV_NULL_HNDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

21 Timer Implementation 177bp_timer_impl_halt() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177bp_timer_impl_init() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177bp_timer_impl_next_update() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178bp_timer_impl_resume() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

22 Document Revision History 180



Chapter

1Overview

Welcome to the BASEplatformTM API reference manual. This reference manual covers the BASEplatformcore API functions, data types and preprocessor definitions along with description and usageinformation for each API element. The core API is written in ISO/IEC 9899:1999 (C99) compliant C anddesigned to be portable between platforms and toolchains. Additional platform specific modules andAPIs are documented in separate manuals dedicated to each supported platforms.

For convenience during development, all the information related to each individual API elements is alsoreproduced within the relevant header source files in human readable format.

About the BASEplatformThe BASEplatform is a collection of low-level interface modules, drivers and board support packages(BSPs) designed to provide the foundation for an embedded software application. The BASEplatformcan support a variety of free or commercial RTOSes as well as bare-metal applications, both inmulti-core and single core configurations. BASEplatform packages are created specifically for anapplication’s needs, and usually include support for an RTOS or bare-metal, low level I/Os, such as UART,I2C, GPIO etc. as well as communication and storage stacks, as selected by the application developer,alongside the necessary drivers, integration and IDE files to get everything working out of the box.



JBLopenEmbedded Software Insight Chapter 1 Overview 2

Elements of the API ReferenceEach documented API element, be it a function, data type or preprocessor definition is presented usinga similar layout which are described below. This section briefly describes the various elements of theAPI reference.

FunctionsThe most numerous and important API elements documented are functions. Below is an example of APIreference for a hypothetical function named bp_example_func():

bp_example_func()Function

Example function description.

Prototype int bp_example_func ( uint32_t arg1,uint32_t arg2 );

Attributes Blocking ISR-safe Critical safe Thread-safe

7 3 3 3

Parameters arg1 First argument’s description.arg2 Second argument’s description.

ReturnedErrors

RTNC_SUCCESSRTNC_FATAL

Example

uint32_t a = 0u;uint32_t b = 1u;int result;

result = bp_example_func(a, b);if(result != RTNC_SUCCESS) \{

// Handle error.\}

Function NameAt the top of each API is the name of the function or object as it appears in the source code.BASEplatform functions are always prefixed with bp_ followed by the module name and then thefunction’s specific name.




HeaderFollowing the name is the header file where the declaration of the documented API can be found. It isrecommended to use the displayed path relative to the root of the source directory of the BASEplatformwhen including BASEplatform’s headers.

For example, to include the UART module header file bp_uart.h the following include directive isrecommended.

#include

The root of the BASEplatform source directory should be added to the include path of the compiler.

DescriptionA description of the API element including basic usage information.

PrototypeFor functions, the full signature of the API along with parameter names, types, and function return type.

AttributesFor functions only, this section lists the relevant function attributes. See the function attributes sectionof this manual for a detailed description of each attribute.

ParametersFunction parameters list along with a short description of each parameter.

Returned Errors or Return ValuesFor functions that return a BASEplatform standard error code, this section is named Returned Errors andlists the relevant errors that can be returned. See the error handling convention section of this manualfor more information on the BASEplatform error handling.

For other functions that do not return a standard error code, this section lists the possible output valuesof the function. In this case the section is named ”Returned Values”.

ExampleSome API functions may include a small code example to illustrate usage. Note that these examples arefor documentation purpose and may not include error handling and checking to keep the examplesconcise.

Data TypesData types include structure definitions, enumerated types as well as scalar type definitions. They allfollow a similar documentation layout, below is an example of API reference for a hypothetical structuredefinition named bp_example_struct_t:




bp_example_struct_tData Type

Example structure description.

Members

member1 uint32_t First member’s description.

member2 uint32_t Second member’s description.

Data Type NameAt the top of each API is the name of the data type as it appears in the source code. In the case ofstructures and enumerated types, this is always the typedef’d data type. BASEplatform types alwaysprefixed with bp_ followed by the module name and then the type’s specific name. Types are alsoalways suffixed with _t to differentiate them from other definitions.


DescriptionA description of the data type including basic usage information.

Members/Enumeration ValuesIf documented, the API reference will list the structure members or the list of enumeration constantsalong with a short description of each member. The list of members for opaque types with no publiclyaccessible members are omitted from the list of members in the API documentation.

MacrosRelevant and preprocessor macros that are part of the public API are documented in the API reference.This includes function-like macros as well as object-like macros. The latter is often referred to aspreprocessor definitions or simply defines. Below is an example of function-like macro namedBP_EXAMPLE_MACRO():

BP_EXAMPLE_MACRO()Macro

Example macro description.

Prototype BP_EXAMPLE_MACRO ( arg1,arg2 );

Parameters arg1 First argument’s description.arg2 First argument’s description.




Expansion Macro expansion’s description.

Macro NameAt the top of each API is the name of the macro as it appears in the source code. BASEplatformpreprocessor definitions are always in capital letters and prefixed with BP_ followed by the modulename and then the macro’s specific name.


DescriptionA description of the macro including basic usage information.

ParametersMacro parameters list along with a short description of each parameter.

ExpansionFor function-like macros an expansion section describes the macro’s expansion including the type ifapplicable.

Function AttributesThe API reference documentation for API functions includes a set of attributes that clarifies in whichcontext it is safe to call a specific API function. The attributes are as follows:

• Blocking• ISR-safe• Critical-safe• Thread-safe

BlockingThe function is potentially blocking, which means it can wait or pend on a kernel object such as asemaphore or mutex, in order to wait for a resource to be available or for an operation to complete.Some functions may be optionally blocking depending on the function’s arguments. Those functions arealways marked as blocking in the API reference regardless.

In a bare-metal environment, any function marked as blocking can potentially suspend the backgroundtask while waiting for a specific interrupt. Many of those functions take a timeout parameter that canbe set to 0 to make them non-blocking (polling) if suspension of the background task is undesired.




As a general rule, blocking functions should not be called from an interrupt service routine, also knownas interrupt handler or while the CPU interrupts are disabled. In addition, some RTOSes allowsuspending or locking the scheduler, when this is the case, blocking functions should not be called whilethe scheduler is suspended or locked.

ISR-SafeAn ISR-safe function can be called from within an interrupt service routine. This also includes callbackfunctions that are called from an interrupt context. Note that while an ISR-safe function is usuallycritical-safe this is not always the case. Also an ISR-safe function may not necessarily be thread-safe.

Critical SafeCritical safe functions can be called when the CPU interrupts are disabled, this is also called a criticalcontext or sometimes a critical section. Critical sections are usually entered by calling a spinlock acquireor critical section enter function. Calling a non-critical-safe function from within a critical section cancorrupt the state of the CPU’s interrupt disable flags and cause runtime faults or data corruption.

Thread-SafeA thread safe function guarantees correct operations between multiple threads or tasks when runningunder a multitasking kernel. In the context of the BASEplatform API, thread-safe also implies threadsafety on an SMP system, which means it is safe to use the API function from different threads inparallel. Due to the design of the BASEplatform, thread-safe functions are also re-entrant assuming thatthe other function attributes, such as ISR safety, are respected.

Function Attributes in Header FilesFunction attributes are documented slightly differently in the source header files in order to be moreconcise and easier to maintain. The attributes are documented under an ”Attributes” section and arenamed as follows:

• non-blocking• non-thread-safe• ISR-safe• critical-section-safe

Absence of an attribute implies that the opposite attribute applies to the function. For example, in theabsence of any explicit function attribute in the header documentation, a function is assumed to beblocking, thread-safe and not safe to call from ISRs and critical sections.

API ConventionsThe BASEplatform API adheres to a few conventions with respect to the naming, error handling andtimeouts that are useful for the application developers.




NamingThe BASEplatform API function names are all written in lower case, except preprocessor macros whichare in upper case. Words within an object name are separated by underscores and the whole name isprefixed with bp_ followed by the module name and finally the function specific part of the name.

For example, the time module function to get the current time is written as follows:

bp_time_get()

And the memory barrier macro from the architecture module, ”arch” for short, is named as follows:

BP_ARCH_MB()

Error HandlingMost API functions return a status in the form of a plain int as the function’s return value. As a generalexception, some functions that cannot fail are allowed to return nothing (void) or another value.

In general, the BASEplatform attempts to minimize the number of different error codes to simplify theapplication’s error handling and improve performance. The list of possible error codes is included withinevery function’s documentation. The meaning of each error code is also documented in a function’sdescription. See the Error Codes chapter for a list of defined error codes.

As with other preprocessor macros and enumeration constants, the application should never rely on theexact numerical value of any specific error code. However, two guarantees are made with respect to theerror code numerical values. The first is that RTNC_SUCCESS will always expand to 0. The second isthat all other error codes are negative. Positive values are not used for any valid error code. Anyundefined or unexpected error code returned by a function should be treated as a fatal error.

Two error codes have the exact same meaning for all the functions, namely RTNC_SUCCESS andRTNC_FATAL.

RTNC_SUCCESS is returned when a function completed successfully without issue.

RTNC_FATAL is returned if and only if an unexpected situation that should not happen at runtime isdetected. This includes invalid function arguments, internal data corruption and assertion failures withinthe code. In addition, any unexpected error code returned from a function should be treated as a fatalerror. It is up to the application to decide on the proper action to perform upon receiving a fatal error.As a general rule, the application should not perform any other calls to that module instance. Safetycritical applications should consider an RTNC_FATAL error code as a severe assertion failure and actaccordingly.

Some modules, especially IO modules such as UART and I2C, provides a reset API call that can be usedto reset the internal state of a module as well as the underlying peripheral. This can be used to attemptto recover from a fatal error in case the error condition is temporary.

TimeoutsMost of the blocking functions have a timeout argument that takes a timeout value in milliseconds. Thetimeout period is guaranteed to be at least the requested value rounded up to the next multiple of thekernel’s tick rate if necessary. Internally, the BASEplatform modules and drivers will attempt to respectthe timeout value as closely as possible while guaranteeing the minimum timeout value. However, RTOS




scheduling, higher priority tasks and interrupt response time may increase the amount of time taken toreturn from a timeout condition.

For all functions that take a timeout value, specifying a timeout value of 0 means that the function willreturn immediately instead of blocking when having to wait on a mutex or an interrupt. A value ofTIMEOUT_INF or -1 will result in an infinite timeout.

Numerical Values of Macros and Enumeration ConstantsTo ease maintainability and ensure compatibility with future versions, the application should never relyon enumeration constants and macros numerical value.

Driver APIMany of the BASEplatform modules, especially the IO modules, use drivers to perform hardware access.In those situations the top-level module provides lifecycle management as well as thread-safety.However, it may be desirable in some circumstances to access the driver API directly. The various driverfunction signatures are gathered at the end of this manual but additional details may be available fromeach platform’s reference manual.

Advanced Driver APIEach driver is allowed to implement additional, driver specific, functionalities not available from the toplevel module API. These functions are usually meant to control advanced features of the underlyingperipherals. Each I/O module provides an API to retrieve the driver’s handle which can be used toaccess those advanced functions directly. There is also an optional locking mechanism that can be usedto ensure thread safety while performing direct operations on the drivers.

Accessing the Drivers DirectlyIt is also possible to access the drivers standard operation directly at the driver level. This reduces theoverhead associated the kernel mutexes and driver dereference at the cost of thread safety. As such,direct driver access should be done with care. As with the case of the advanced driver features, there isan optional exclusive lock mechanism that can be used to ensure thread safety.



Chapter

2Architecture

The architecture module, or ARCH module provides low-level CPU control functionalities as well asimportant compiler abstractions. These include CPU interrupt flag manipulation, memory barriers,endianness and compiler detection, alignment requirements, and more. The ARCH module is divided invarious ports specific to a CPU and compiler combination. When necessary, additional files and APIspecific to certain CPU cores are also included in the ARCH module.

The current architecture and toolchain need to be selected at compile time by including the relevantport’s header file in a master configuration file named bp_arch_def_cfg.h.

bp_irq_flag_tData Type

Type used to store the CPU interrupt status flag returned by bp_slock_acquire_irq_save() andbp_critical_section_enter().

The value returned by those functions should not be manipulated by the application.

BP_ARCH_ALIGN_MAXMacro

Defined by the architecture port to the largest required alignment across all the fundamental data types.



JBLopenEmbedded Software Insight Chapter 2 Architecture 10

BP_ARCH_COMPILERMacro

Defined by the architecture port to the current compiler. The list of defined compilers can be found inbp_arch_def.h.

BP_ARCH_CORE_ID_GET()Macro

Returns the CPU id of the current core. On single core platforms, BP_ARCH_CORE_ID_GET() alwaysreturns 0.

BP_ARCH_CPUMacro

Defined by the architecture port to the current CPU architecture. The list of defined architectures canbe found in bp_arch_def.h.

BP_ARCH_DEBUG_BREAK()Macro

Inserts a software breakpoint. The current CPU core will break to the debugger if supported. The resultof hitting a software breakpoint with no debugger connected is platform specific but will usually triggera form of CPU fault or exception.

BP_ARCH_ENDIANMacro

Defined by the architecture port to the endianness of the current platform. The list of endiannessdefinitions can be found in bp_arch_def.h.

BP_ARCH_INT_DIS()Macro

core’s interrupts are disabled. The result can be assigned to a variable of type bp_irq_flag_t to savethe current state of the interrupt flags.




Critical sections such as bp_critical_section_enter() and bp_critical_section_exit()or spinlocks, bp_slock_acquire_irq_save() and bp_slock_release_irq_restore() areusually preferable to unconditionally disabling and enabling interrupts.

BP_ARCH_INT_EN()Macro

Unconditionally enables CPU interrupts. On multi-core platforms only the current core’s interrupts areenabled.

Critical sections such as bp_critical_section_enter() and bp_critical_section_exit()or spinlocks, bp_slock_acquire_irq_save() and bp_slock_release_irq_restore() areusually preferable to unconditionally disabling and enabling interrupts.

BP_ARCH_IS_CRIT()Macro

Returns a non-zero value if interrupts are disabled, i.e. inside a critical context.

BP_ARCH_IS_INT()Macro

Returns a non-zero value if called from within an interrupt service routine.

BP_ARCH_IS_INT_OR_CRIT()Macro

Returns a non-zero value if currently called from an interrupt service routine or if interrupts are disabled.

BP_ARCH_MB()Macro

Memory barrier.




BP_ARCH_PANIC()Macro

Panic, usually disables interrupts and breaks into an infinite loop or the debugger.

BP_ARCH_RMB()Macro

Read memory barrier, defaults to BP_ARCH_MB() for architectures without a specific read memorybarrier.

BP_ARCH_SEV()Macro

Send event. The BP_ARCH_SEV() macro expands to the current architecture’s send event instructionused for SMP signalling between cores. On architectures without any send event instruction this macroexpands to a no-op instruction.

BP_ARCH_WFE()Macro

Wait for events. The BP_ARCH_WFE() macro expands to the current architecture’s wait for eventinstruction used for SMP signalling between cores. On architectures without any wait for eventinstruction this macro expands to a no-op instruction.

The difference between a wait for event and a wait for interrupt is architecture dependent. In casethere is no dedicated wait for event instruction this macro expands to BP_ARCH_WFI().

BP_ARCH_WFI()Macro

Wait for interrupts. The BP_ARCH_WFI() macro expands to the current architecture’s wait for interruptinstruction. On architectures without any wait for interrupt instruction this macro expands to a no-opinstruction.




BP_ARCH_WMB()Macro

Write memory barrier, defaults to BP_ARCH_MB() for architectures without a specific write memorybarrier.



Chapter

3Cache Management

The cache management module enables drivers and applications to perform cache maintenanceoperations in a platform-independent manner. The various cache maintenance functions can be used toensure cache coherency when handling hardware buffers, shared memory and similar operations withnon-coherent masters in a SoC.

All the maintenance functions, regardless of the implementation, includes a suitable memory barrier atthe start and at the end of all the cache maintenance operations. This applies even if a length of zero ispassed to functions operating on a range as well as on platforms with no caches or with cache disabled.

The cache operations are not atomic and won’t disable interrupts unless required by the platform. If acache operation must not be interrupted, a critical section or spinlock should be used around the call.The cache operations are, however, thread-safe and re-entrant which means they can be used in parallelwithout issues.

Cache operations can take a considerable amount of time depending on the range, state of the cacheand CPU/RAM performance. While they are marked as non-blocking, care should be taken not toperform excessively long operations from within an interrupt or a critical context.

bp_cache_dcache_inv_all()Function

Invalidates the entire data cache. The entire data cache hierarchy and unified caches will be invalidated.

Invalidating the cache means clearing entries from the cache without writing them to main memory ifdirty.

Prototype void bp_cache_dcache_inv_all ( );



JBLopenEmbedded Software Insight Chapter 3 Cache Management 15


7 3 3 3

bp_cache_dcache_max_line_get()Function

Returns the largest effective data cache line size. Usually this would be the largest cache line size in thedata cache hierarchy.

The special value 0 is returned when no cache is present or if the data cache line size is unknown.

Caches are usually assumed to be fully enabled. The return value of this function reflects the largestdata cache line size as if the entire data cache hierarchy was enabled.

Prototype uint32_t bp_cache_dcache_max_line_get ( );


7 3 3 3

ReturnedValues

Largest data cache line size in bytes if known, 0 otherwise.

bp_cache_dcache_min_line_get()Function

Returns the smallest effective data cache line size. Usually this would be the smallest cache line size inthe data cache hierarchy.

The special value 0 is returned when no cache is present or if the data cache line size is unknown.

Caches are usually assumed to be fully enabled. The return value of this function reflects the smallestdata cache line size as if the entire data cache hierarchy was enabled.

When considering the minimum alignment of DMA buffers, the largest cache line size should usually beused. See bp_cache_dcache_max_line_get()

Prototype uint32_t bp_cache_dcache_min_line_get ( );


7 3 3 3




ReturnedValues

Smallest cache line size in bytes if known, 0 otherwise.

bp_cache_dcache_range_clean()Function

Cleans an address range from the data cache.

A start address unaligned to a cache line will be truncated to be aligned with the next lowest cache line.

A length which is not a multiple of the cache line size will be rounded up to the next multiple of thecache line size.

Cleaning the cache means writing the dirty cache lines but keeping them stored in the cache.

This function cannot fail and supports cleaning from address 0. Callingbp_cache_dcache_range_clean() with a len of 0 will have no effect other than executing amemory barrier.

Prototype void bp_cache_dcache_range_clean ( void * p_addr,size_t len );


7 3 3 3

Parameters p_addr Start of the address range.len Length of the range to clean in bytes.

bp_cache_dcache_range_cleaninv()Function

Cleans and invalidates an address range from the data cache.



Combines operation of both bp_cache_dcache_range_clean() andbp_cache_dcache_range_inv() in one call. Some platforms may have optimized way ofperforming the combined operation.

It should not be assumed that the clean and invalidate operation are atomic between each other.




This function cannot fail and supports cleaning from address 0. Callingbp_cache_dcache_range_cleaninv() with a len of 0 will have no effect other than executing amemory barrier.

Prototype void bp_cache_dcache_range_cleaninv ( void * p_addr,size_t len );


7 3 3 3

Parameters p_addr Start of the address range.len Length of the range to clean and invalidate in bytes.

bp_cache_dcache_range_inv()Function

Invalidates an address range from the data cache.




This function cannot fail and supports cleaning from address 0. Callingbp_cache_dcache_range_inv() with a len of 0 will have no effect other than executing a memorybarrier.

Prototype void bp_cache_dcache_range_inv ( void * p_addr,size_t len );


7 3 3 3

Parameters p_addr Start of the address range.len Length of the range to invalidate in bytes.




bp_cache_icache_inv_all()Function

Cleans the entire instruction cache. bp_cache_icache_inv_all() will clean the entire instructioncache hierarchy.

bp_cache_icache_inv_all() will not invalidate unified caches when present. It is the caller’sresponsibility of correctly handling any code that could be stored in the unified cache(s).


Prototype void bp_cache_icache_inv_all ( );


7 3 3 3



Chapter

4Spinlocks

The spinlock module, shortened to slock, provides spinlocks and critical sections enabling atomicoperations on both uni-processor and symmetric multiprocessor systems.

On uni-processor systems, the spinlocks reduces to simple critical sections, as such they can be used towrite code compatible with both uni- and multi-processor.

bp_critical_section_enter()Function

Enters a critical section, disabling the interrupts and returning the CPU’s interrupt flag state prior to thecall to bp_critical_section_enter(). An appropriate memory barrier will be executed by theimplementation to ensure proper synchronization.

The exact return value is implementation specific and should not be manipulated by the calling code.

bp_critical_section_enter() and bp_critical_section_exit() are compatible withbare-metal, single core RTOS and SMP RTOSes and can be used as a simpler alternative to spinlocks.However for maximum performance under SMP RTOSes, spinlocks are recommended.

Prototype bp_irq_flag_t bp_critical_section_enter ( );


7 3 3 3

ReturnedValues

Interrupt status flag prior to calling bp_critical_section_enter().



JBLopenEmbedded Software Insight Chapter 4 Spinlocks 20

bp_critical_section_exit()Function

Exits a critical section, restoring the interrupt state from the flag argument. An appropriate memorybarrier will be executed by the implementation to ensure proper synchronization.

The exact values that flag can take is implementation specific and should not be manipulated by thecalling code. The result of passing any value except one returned by a previous call tobp_critical_section_enter() is undefined.

bp_critical_section_enter() and bp_critical_section_exit() are compatible withbare-metal, single core RTOS and SMP RTOSes and can be used as a simpler alternative to spinlocks.However for maximum performance under SMP RTOSes, spinlocks are recommended.

Prototype void bp_critical_section_exit ( );


7 3 3 3

bp_slock_acquire()Function

Acquires a spinlock. Under an SMP RTOS, bp_slock_acquire() will busy wait (spin) until the lock isavailable. In a single core system bp_slock_acquire() will be reduced to a memory barrier.

Note that bp_slock_acquire() will not disable interrupts which is necessary to guarantee atomicityand prevent deadlocks. bp_slock_acquire_irq_save() and bp_slock_acquire_irq_dis()can be used instead when interrupts need to be disabled.

Prototype void bp_slock_acquire ( bp_slock_t * p_lock );


7 3 3 3

Parameters p_lock Pointer to the spinlock.

bp_slock_acquire_irq_dis()Function

Acquires a spinlock and disables interrupts. Under an SMP RTOS, bp_slock_acquire_irq_dis()will busy wait (spin) until the lock is available. In a single core system bp_slock_acquire_irq_dis()




will disable interrupts and execute a memory barrier to enforce synchronization.

bp_slock_acquire_irq_dis() and bp_slock_release_irq_en() used in pairs willunconditionally disable and enable interrupts on entry and exit of the critical section. They can be usedas a leaner version of spinlocks when saving the interrupt flag state is unnecessary. Otherwisebp_slock_acquire_irq_save() and bp_slock_release_irq_restore() should be usedwhen calling from within a critical section where interrupts could be disabled.

Prototype void bp_slock_acquire_irq_dis ( bp_slock_t * p_lock );


7 3 7 3


bp_slock_acquire_irq_save()Function

Acquires a spinlock, disables interrupts and returns the CPU’s interrupt flag state. Under an SMP RTOS,bp_slock_acquire_irq_save() will busy wait (spin) until the lock is available. In a single coresystem bp_slock_acquire_irq_save() will disable the interrupts and return the interrupt statusflag as well as executing a memory barrier to enforce synchronization.

The exact return value is implementation specific and should not be manipulated by the calling code.

Prototype bp_irq_flag_t bp_slock_acquire_irq_save ( bp_slock_t * p_lock );


7 3 3 3


ReturnedValues

Interrupt status flag prior to calling bp_slock_acquire_irq_save().

bp_slock_release()Function

Releases a spinlock. Under an SMP RTOS, bp_slock_release() will release the spinlock and signalother cores which may be waiting on the lock. In a single core system bp_slock_release() will be




reduced to a memory barrier.

Prototype void bp_slock_release ( bp_slock_t * p_lock );


7 3 3 3


bp_slock_release_irq_en()Function

Releases a spinlock and enables interrupts. Under an SMP RTOS, bp_slock_release_irq_en() willrelease the spinlock and signal other cores which may be waiting on the lock. In a single core systembp_slock_release_irq_en() will enable interrupts and execute a memory barrier to enforcesynchronization.

bp_slock_acquire_irq_dis() and bp_slock_release_irq_en() in a pair will unconditionallydisable and enable interrupts on entry and exit of the critical section. They can be used as a leanerversion of spinlocks when saving the interrupt flag state is unnecessary. Otherwisebp_slock_acquire_irq_save() and bp_slock_release_irq_restore() should be usedwhen calling from within a critical section where interrupts are disabled.

Prototype void bp_slock_release_irq_en ( bp_slock_t * p_lock );


7 3 7 3


bp_slock_release_irq_restore()Function

Releases a spinlock and restores the interrupt state. Under an SMP RTOS,bp_slock_release_irq_restore() will release the spinlock and signal other cores which may bewaiting on the lock. In a single core system bp_slock_release_irq_restore() will restore theinterrupts as well as execute a memory barrier to enforce synchronization.

The exact values that flag can take is implementation specific and should not be manipulated by thecalling code. The result of passing any value except one returned by a previous call tobp_slock_acquire_irq_save() is undefined.




Prototype void bp_slock_release_irq_restore ( bp_slock_t * p_lock,bp_irq_flag_t flag );


7 3 3 3

Parameters p_lock Pointer to the spinlock.flag Saved interrupt flag to restore.

bp_slock_tData Type

Spinlock datatype. Any spinlock variable should be cleared by setting them* to 0 prior to use.



Chapter

5Time

The time module is responsible for the system’s primary timebase as well as providing high resolutiontime delays and time measurements. It is also the time base used by the generic timer module.

When running with an RTOS, the time module usually provides the kernel reference tick, with supportfor dynamic or tickless mode for RTOSes that supports it.

Additionally, when running within and RTOS, the time delays provided by the time module areimplemented independently of the kernel software timers and delays. As such, they usually support ahigher resolution than the kernel offers and can be used where fine timing is required.

bp_time_freq_get()Function

Returns the frequency of the primary time base.

This function cannot fail and in normal operation should always return a non-zero value. In special caseswhere the frequency is unknown, 0 is returned.

Prototype uint32_t bp_time_freq_get ( );


7 3 3 3

ReturnedValues

Frequency of the primary time base in hertz.



JBLopenEmbedded Software Insight Chapter 5 Time 25

bp_time_get()Function

Returns the raw value of the primary time base counter.

This function cannot fail and in normal operation will always return a non-zero value. In special caseswhere there is no active timebase, 0 is returned.

Prototype uint64_t bp_time_get ( );


7 3 3 3

ReturnedValues

Raw 64-bit value of the primary counter.

bp_time_get32()Function

Returns the raw value of the primary time base counter, 32-bit version. The value returned is the sameas would result from truncating the returned value of bp_time_get() to the least significant 32 bits.


Prototype uint32_t bp_time_get32 ( );


7 3 3 3

ReturnedValues

Raw 32-bit value of the primary counter.

bp_time_get_ms()Function

Returns the current value of the primary time base counter in milliseconds.





Prototype uint64_t bp_time_get_ms ( );


7 3 3 3

ReturnedValues

64-bit counter value in milliseconds.

bp_time_get_ms32()Function

Returns the current value of the primary time base counter in milliseconds, 32-bit version.


Prototype uint32_t bp_time_get_ms32 ( );


7 3 3 3

ReturnedValues

32-bit counter value in milliseconds.

bp_time_get_ns()Function

Returns the current value of the primary time base counter in nanoseconds.


Prototype uint64_t bp_time_get_ns ( );


7 3 3 3




ReturnedValues

64-bit counter value in nanoseconds.

bp_time_get_ns32()Function

Returns the current value of the primary time base counter in nanoseconds. 32-bit version.


Prototype uint32_t bp_time_get_ns32 ( );


7 3 3 3

ReturnedValues

32-bit counter value in nanoseconds.

bp_time_halt()Function

Halts the primary time base. The primary timebase is halted until bp_time_resume() is called.

Halting and resuming the primary time base should be done for testing and debugging purpose only.

Prototype int bp_time_halt ( );


7 3 3 3

ReturnedErrors


bp_time_init()Function

Initializes the time module and the primary time base.




bp_time_init() should be called before any other services that is dependent on the systemtimebase are used.

bp_time_init() should only be called once. The result of subsequent calls after the first is undefined.

Prototype int bp_time_init ( );


7 7 3 3

ReturnedErrors


bp_time_ms_to_raw()Function

Converts milliseconds to the raw time base unit.

This function cannot fail and in normal operation should always return a non-zero value for a non-zeroinput. In special cases where the frequency is unknown, 0 is returned.

Prototype uint64_t bp_time_ms_to_raw ( );


7 3 3 3

Parameters

ReturnedValues

Time value in the raw time base unit.

bp_time_ms_to_raw32()Function

Converts milliseconds to the raw time base unit, 32-bit version.


Prototype uint32_t bp_time_ms_to_raw32 ( uint32_t time_ms );





7 3 3 3

Parameters time_ms Time value in milliseconds.

ReturnedValues


bp_time_ns_to_raw()Function

Converts nanoseconds to the raw time base unit.


Prototype uint64_t bp_time_ns_to_raw ( uint64_t time_ns );


7 3 3 3

Parameters time_ns Time value in milliseconds.

ReturnedValues


bp_time_ns_to_raw32()Function

Converts nanoseconds to the raw time base unit, 32-bit version.


Prototype uint32_t bp_time_ns_to_raw32 ( uint32_t time_ns );


7 3 3 3




Parameters time_ns Time value in milliseconds.

ReturnedValues


bp_time_raw_to_ms()Function

Converts a time value from the raw time base unit to milliseconds.


Prototype uint64_t bp_time_raw_to_ms ( uint64_t time_raw );


7 3 3 3

Parameters time_raw Time value in the unit of the system time base.

ReturnedValues

Time value in milliseconds.

bp_time_raw_to_ms32()Function

Converts a time value in the raw time base unit to milliseconds, 32-bit version.


Prototype uint32_t bp_time_raw_to_ms32 ( uint32_t time_raw );


7 3 3 3





ReturnedValues

Time value in milliseconds.

bp_time_raw_to_ns()Function

Converts a time value in the raw time base unit to nanoseconds.


Prototype uint64_t bp_time_raw_to_ns ( uint64_t time_raw );


7 3 3 3


ReturnedValues

Time value in nanoseconds.

bp_time_raw_to_ns32()Function

Converts a time value in the raw time base unit to nanoseconds, 32-bit version.


Prototype uint32_t bp_time_raw_to_ns32 ( uint32_t time_raw );


7 3 3 3


ReturnedValues

Time value in nanoseconds.




bp_time_resume()Function

Resumes the primary time base. Resumes the primary time base from where it was stopped bybp_time_halt(). The result of calling resume when the timebase isn’t halted is undefined.

Halting and resuming the primary time base should be done for testing and debugging purpose only.

Prototype int bp_time_resume ( );


7 3 3 3

ReturnedErrors


bp_time_sleep()Function

Sleeps for a specified amount of time in the platform’s raw timebase unit.

The wait method is chosen by the underlying implementation and will usually be a busy loop for smalldelays and a timer interrupt for larger delays.

The amount of time slept is guaranteed to be at least the specified amount.

bp_time_sleep() should not be called from an interrupt service routine or with the interruptsdisabled. bp_time_sleep_busy() should be used instead. However long delays within interruptservice routines or critical section could have a negative impact on the system performance and shouldbe used sparingly.

Prototype int bp_time_sleep ( uint64_t time_raw );


3 7 7 3

Parameters time_raw Amount of time to sleep in the platform’s raw timebase unit.

ReturnedErrors





bp_time_sleep32()Function

Sleeps for a specified amount of time in the platform’s raw timebase unit, 32-bit version.

The wait method is chosen by the underlying implementation and

Date post:	12-Feb-2021
Category:	Documents
Upload:	others
View:	0 times
Download:	0 times

BASEplatform API Reference Manual - JBLopenContents iii bp_time_sleep_busy32() . . . . . . . . . . ....

Documents