mirrors
/
micropython
mirror of https://github.com/micropython/micropython.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
micropython/py/mphal.h

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

115 lines
3.3 KiB
C
Raw Normal View History

all: Add py/mphal.h and use it in all ports. py/mphal.h contains declarations for generic mp_hal_XXX functions, such as stdio and delay/ticks, which ports should provide definitions for. A port will also provide mphalport.h with further HAL declarations.
2015-10-30 23:03:58 +00:00
/*
all: Use the name MicroPython consistently in comments There were several different spellings of MicroPython present in comments, when there should be only one.
2017-06-30 08:22:17 +01:00
* This file is part of the MicroPython project, http://micropython.org/
all: Add py/mphal.h and use it in all ports. py/mphal.h contains declarations for generic mp_hal_XXX functions, such as stdio and delay/ticks, which ports should provide definitions for. A port will also provide mphalport.h with further HAL declarations.
2015-10-30 23:03:58 +00:00
*
* The MIT License (MIT)
*
* Copyright (c) 2015 Damien P. George
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
all: Unify header guard usage. The code conventions suggest using header guards, but do not define how those should look like and instead point to existing files. However, not all existing files follow the same scheme, sometimes omitting header guards altogether, sometimes using non-standard names, making it easy to accidentally pick a "wrong" example. This commit ensures that all header files of the MicroPython project (that were not simply copied from somewhere else) follow the same pattern, that was already present in the majority of files, especially in the py folder. The rules are as follows. Naming convention: * start with the words MICROPY_INCLUDED * contain the full path to the file * replace special characters with _ In addition, there are no empty lines before #ifndef, between #ifndef and one empty line before #endif. #endif is followed by a comment containing the name of the guard macro. py/grammar.h cannot use header guards by design, since it has to be included multiple times in a single C file. Several other files also do not need header guards as they are only used internally and guaranteed to be included only once: * MICROPY_MPHALPORT_H * mpconfigboard.h * mpconfigport.h * mpthreadport.h * pin_defs_*.h * qstrdefs*.h
2017-06-29 22:14:58 +01:00
#ifndef MICROPY_INCLUDED_PY_MPHAL_H
#define MICROPY_INCLUDED_PY_MPHAL_H
all: Add py/mphal.h and use it in all ports. py/mphal.h contains declarations for generic mp_hal_XXX functions, such as stdio and delay/ticks, which ports should provide definitions for. A port will also provide mphalport.h with further HAL declarations.
2015-10-30 23:03:58 +00:00
py/mphal.h: Introduce mp_hal_time_ns and implement on various ports. This should return a 64-bit value being the number of nanoseconds since 1970/1/1. Signed-off-by: Damien George <damien@micropython.org>
2020-08-01 14:50:23 +01:00
#include <stdint.h>
all: Add py/mphal.h and use it in all ports. py/mphal.h contains declarations for generic mp_hal_XXX functions, such as stdio and delay/ticks, which ports should provide definitions for. A port will also provide mphalport.h with further HAL declarations.
2015-10-30 23:03:58 +00:00
#include "py/mpconfig.h"
#ifdef MICROPY_MPHALPORT_H
#include MICROPY_MPHALPORT_H
#else
#include <mphalport.h>
#endif
py/mphal: Move configuration of ATOMIC_SECTION macros to mphal.h. MICROPY_BEGIN_ATOMIC_SECTION/MICROPY_END_ATOMIC_SECTION belong more to the MicroPython HAL rather than build configuration settings, so move their default configuration to py/mphal.h, and require all users of these macros to include py/mphal.h (here, py/objexcept.c and py/scheduler.c). This helps ports separate configuration from their HAL implementations, and can improve build times (because mpconfig.h is included everywhere, whereas mphal.h is not). Signed-off-by: Damien George <damien@micropython.org>
2023-12-01 02:24:19 +00:00
// On embedded platforms, these will typically enable/disable irqs.
#ifndef MICROPY_BEGIN_ATOMIC_SECTION
#define MICROPY_BEGIN_ATOMIC_SECTION() (0)
#endif
#ifndef MICROPY_END_ATOMIC_SECTION
#define MICROPY_END_ATOMIC_SECTION(state) (void)(state)
#endif
lib/utils/sys_stdio_mphal: Add support to poll sys.stdin and sys.stdout. A port must provide the following function for this to work: uintptr_t mp_hal_stdio_poll(uintptr_t poll_flags);
2019-06-19 05:02:08 +01:00
#ifndef mp_hal_stdio_poll
uintptr_t mp_hal_stdio_poll(uintptr_t poll_flags);
#endif
all: Add py/mphal.h and use it in all ports. py/mphal.h contains declarations for generic mp_hal_XXX functions, such as stdio and delay/ticks, which ports should provide definitions for. A port will also provide mphalport.h with further HAL declarations.
2015-10-30 23:03:58 +00:00
#ifndef mp_hal_stdin_rx_chr
int mp_hal_stdin_rx_chr(void);
#endif
#ifndef mp_hal_stdout_tx_str
void mp_hal_stdout_tx_str(const char *str);
#endif
#ifndef mp_hal_stdout_tx_strn
ports: Fix sys.stdout.buffer.write() return value. MicroPython code may rely on the return value of sys.stdout.buffer.write() to reflect the number of bytes actually written. While in most scenarios a write() operation is successful, there are cases where it fails, leading to data loss. This problem arises because, currently, write() merely returns the number of bytes it was supposed to write, without indication of failure. One scenario where write() might fail, is where USB is used and the receiving end doesn't read quickly enough to empty the receive buffer. In that case, write() on the MicroPython side can timeout, resulting in the loss of data without any indication, a behavior observed notably in communication between a Pi Pico as a client and a Linux host using the ACM driver. A complex issue arises with mp_hal_stdout_tx_strn() when it involves multiple outputs, such as USB, dupterm and hardware UART. The challenge is in handling cases where writing to one output is successful, but another fails, either fully or partially. This patch implements the following solution: mp_hal_stdout_tx_strn() attempts to write len bytes to all of the possible destinations for that data, and returns the minimum successful write length. The implementation of this is complicated by several factors: - multiple outputs may be enabled or disabled at compiled time - multiple outputs may be enabled or disabled at runtime - mp_os_dupterm_tx_strn() is one such output, optionally containing multiple additional outputs - each of these outputs may or may not be able to report success - each of these outputs may or may not be able to report partial writes As a result, there's no single strategy that fits all ports, necessitating unique logic for each instance of mp_hal_stdout_tx_strn(). Note that addressing sys.stdout.write() is more complex due to its data modification process ("cooked" output), and it remains unchanged in this patch. Developers who are concerned about accurate return values from write operations should use sys.stdout.buffer.write(). This patch might disrupt some existing code, but it's also expected to resolve issues, considering that the peculiar return value behavior of sys.stdout.buffer.write() is not well-documented and likely not widely known. Therefore, it's improbable that much existing code relies on the previous behavior. Signed-off-by: Maarten van der Schrieck <maarten@thingsconnected.nl>
2023-06-18 10:46:25 +01:00
mp_uint_t mp_hal_stdout_tx_strn(const char *str, size_t len);
all: Add py/mphal.h and use it in all ports. py/mphal.h contains declarations for generic mp_hal_XXX functions, such as stdio and delay/ticks, which ports should provide definitions for. A port will also provide mphalport.h with further HAL declarations.
2015-10-30 23:03:58 +00:00
#endif
#ifndef mp_hal_stdout_tx_strn_cooked
void mp_hal_stdout_tx_strn_cooked(const char *str, size_t len);
#endif
#ifndef mp_hal_delay_ms
void mp_hal_delay_ms(mp_uint_t ms);
#endif
py/mphal.h: Provide default prototypes for mp_hal_delay_us/mp_hal_ticks_us. Similar to existing mp_hal_delay_ms/mp_hal_ticks_ms.
2016-05-21 00:12:11 +01:00
#ifndef mp_hal_delay_us
void mp_hal_delay_us(mp_uint_t us);
#endif
all: Add py/mphal.h and use it in all ports. py/mphal.h contains declarations for generic mp_hal_XXX functions, such as stdio and delay/ticks, which ports should provide definitions for. A port will also provide mphalport.h with further HAL declarations.
2015-10-30 23:03:58 +00:00
#ifndef mp_hal_ticks_ms
mp_uint_t mp_hal_ticks_ms(void);
#endif
py/mphal.h: Provide default prototypes for mp_hal_delay_us/mp_hal_ticks_us. Similar to existing mp_hal_delay_ms/mp_hal_ticks_ms.
2016-05-21 00:12:11 +01:00
#ifndef mp_hal_ticks_us
mp_uint_t mp_hal_ticks_us(void);
#endif
extmod/utime_mphal: Factor out implementations in terms of mp_hal_* for reuse. As long as a port implement mp_hal_sleep_ms(), mp_hal_ticks_ms(), etc. functions, it can just use standard implementations of utime.sleel_ms(), utime.ticks_ms(), etc. Python-level functions.
2016-10-14 18:13:02 +01:00
#ifndef mp_hal_ticks_cpu
mp_uint_t mp_hal_ticks_cpu(void);
#endif
py/mphal.h: Introduce mp_hal_time_ns and implement on various ports. This should return a 64-bit value being the number of nanoseconds since 1970/1/1. Signed-off-by: Damien George <damien@micropython.org>
2020-08-01 14:50:23 +01:00
#ifndef mp_hal_time_ns
all: Rename absolute time-based functions to include "epoch". For time-based functions that work with absolute time there is the need for an Epoch, to set the zero-point at which the absolute time starts counting. Such functions include time.time() and filesystem stat return values. And different ports may use a different Epoch. To make it clearer what functions use the Epoch (whatever it may be), and make the ports more consistent with their use of the Epoch, this commit renames all Epoch related functions to include the word "epoch" in their name (and remove references to "2000"). Along with this rename, the following things have changed: - mp_hal_time_ns() is now specified to return the number of nanoseconds since the Epoch, rather than since 1970 (but since this is an internal function it doesn't change anything for the user). - littlefs timestamps on the esp8266 have been fixed (they were previously off by 30 years in nanoseconds). Otherwise, there is no functional change made by this commit. Signed-off-by: Damien George <damien@micropython.org>
2020-09-14 03:15:03 +01:00
// Nanoseconds since the Epoch.
py/mphal.h: Introduce mp_hal_time_ns and implement on various ports. This should return a 64-bit value being the number of nanoseconds since 1970/1/1. Signed-off-by: Damien George <damien@micropython.org>
2020-08-01 14:50:23 +01:00
uint64_t mp_hal_time_ns(void);
#endif
extmod/virtpin: Initial implementation of open-ended C-level Pin interface. Using usual method of virtual method tables. Single virtual method, ioctl, is defined currently for all operations. This universal and extensible vtable-based method is also defined as a default MPHAL GPIO implementation, but a specific port may override it with its own implementation (e.g. close-ended, but very efficient, e.g. avoiding virtual method dispatch).
2016-05-26 22:57:18 +01:00
// If port HAL didn't define its own pin API, use generic
// "virtual pin" API from the core.
#ifndef mp_hal_pin_obj_t
#define mp_hal_pin_obj_t mp_obj_t
#define mp_hal_get_pin_obj(pin) (pin)
#define mp_hal_pin_read(pin) mp_virtual_pin_read(pin)
#define mp_hal_pin_write(pin, v) mp_virtual_pin_write(pin, v)
py/mphal.h: If virtpin API is used, automagically include its header.
2016-06-18 22:12:37 +01:00
#include "extmod/virtpin.h"
extmod/virtpin: Initial implementation of open-ended C-level Pin interface. Using usual method of virtual method tables. Single virtual method, ioctl, is defined currently for all operations. This universal and extensible vtable-based method is also defined as a default MPHAL GPIO implementation, but a specific port may override it with its own implementation (e.g. close-ended, but very efficient, e.g. avoiding virtual method dispatch).
2016-05-26 22:57:18 +01:00
#endif
py: Add port-agnostic inline functions for event handling. These are intended to replace MICROPY_EVENT_POLL_HOOK and MICROPY_EVENT_POLL_HOOK_FAST, which are insufficient for tickless ports. This implementation is along the lines suggested here: https://github.com/micropython/micropython/issues/12925#issuecomment-1803038430 Currently any usage of these functions expands to use the existing hook macros, but this can be switched over port by port. This work was funded through GitHub Sponsors. Signed-off-by: Angus Gratton <angus@redyak.com.au>
2023-11-30 05:06:32 +00:00
// Event handling and wait-for-event functions.
#ifndef MICROPY_INTERNAL_WFE
// Fallback definition for ports that don't need to suspend the CPU.
#define MICROPY_INTERNAL_WFE(TIMEOUT_MS) (void)0
#endif
#ifndef MICROPY_INTERNAL_EVENT_HOOK
// Fallback definition for ports that don't need any port-specific
// non-blocking event processing.
#define MICROPY_INTERNAL_EVENT_HOOK (void)0
#endif
all: Unify header guard usage. The code conventions suggest using header guards, but do not define how those should look like and instead point to existing files. However, not all existing files follow the same scheme, sometimes omitting header guards altogether, sometimes using non-standard names, making it easy to accidentally pick a "wrong" example. This commit ensures that all header files of the MicroPython project (that were not simply copied from somewhere else) follow the same pattern, that was already present in the majority of files, especially in the py folder. The rules are as follows. Naming convention: * start with the words MICROPY_INCLUDED * contain the full path to the file * replace special characters with _ In addition, there are no empty lines before #ifndef, between #ifndef and one empty line before #endif. #endif is followed by a comment containing the name of the guard macro. py/grammar.h cannot use header guards by design, since it has to be included multiple times in a single C file. Several other files also do not need header guards as they are only used internally and guaranteed to be included only once: * MICROPY_MPHALPORT_H * mpconfigboard.h * mpconfigport.h * mpthreadport.h * pin_defs_*.h * qstrdefs*.h
2017-06-29 22:14:58 +01:00
#endif // MICROPY_INCLUDED_PY_MPHAL_H