diff --git a/docs/library/errno.rst b/docs/library/errno.rst index 10ecd4d2c79..89f09741d2e 100644 --- a/docs/library/errno.rst +++ b/docs/library/errno.rst @@ -7,7 +7,21 @@ |see_cpython_module| :mod:`python:errno`. This module provides access to symbolic error codes for `OSError` exception. -Some codes are not available on the smallest CircuitPython builds, such as SAMD21, for space reasons. +Most SAMD21 boards, including all SAMD21 boards without external flash, do not include :mod:`errno`. +A few other small builds also do not include it. +To check a particular board, see the :ref:`module-support-matrix`. + +The available codes depend on the build: + +* Most builds provide ``EACCES``, ``EADDRINUSE``, ``EAGAIN``, ``EALREADY``, ``EBADF``, + ``EBUSY``, ``ECONNABORTED``, ``ECONNREFUSED``, ``ECONNRESET``, ``EEXIST``, + ``EHOSTUNREACH``, ``EINPROGRESS``, ``EINVAL``, ``EIO``, ``EISDIR``, ``ENOBUFS``, + ``ENODEV``, ``ENOENT``, ``ENOMEM``, ``ENOSPC``, ``ENOTCONN``, ``EOPNOTSUPP``, + ``EPERM``, ``EROFS``, and ``ETIMEDOUT``. +* SAMD21 builds that include :mod:`errno` provide only ``EACCES``, ``EAGAIN``, ``EEXIST``, + ``EINVAL``, ``EIO``, ``EISDIR``, ``ENODEV``, ``ENOENT``, ``ENOMEM``, and ``EPERM``. + +``dir(errno)`` lists the codes available on a particular board. Constants --------- diff --git a/ports/atmel-samd/mpconfigport.h b/ports/atmel-samd/mpconfigport.h index d6d21c35817..715b0c4266f 100644 --- a/ports/atmel-samd/mpconfigport.h +++ b/ports/atmel-samd/mpconfigport.h @@ -27,6 +27,7 @@ #define MICROPY_PY_REVERSE_SPECIAL_METHODS (0) #define MICROPY_PY_COLLECTIONS_DEQUE (0) #define MICROPY_PY_COLLECTIONS_ORDEREDDICT (0) +// docs/library/errno.rst lists these names. Update it if this list changes. #define MICROPY_PY_ERRNO_LIST \ X(EPERM) \ X(ENOENT) \ diff --git a/py/moderrno.c b/py/moderrno.c index e70b89bce5a..8ea6cdfd65c 100644 --- a/py/moderrno.c +++ b/py/moderrno.c @@ -36,6 +36,7 @@ // specific port's needs. If it's not defined then we provide a default. #ifndef MICROPY_PY_ERRNO_LIST // CIRCUITPY-CHANGE: add ENOSPC and EROFS, because they are in mp_common_errno_to_str(). +// CIRCUITPY-CHANGE: docs/library/errno.rst lists these names. Update it if this list changes. #define MICROPY_PY_ERRNO_LIST \ X(EPERM) \ X(ENOENT) \ diff --git a/shared-bindings/alarm/touch/TouchAlarm.c b/shared-bindings/alarm/touch/TouchAlarm.c index eac3f37b8f4..09a27bfd29d 100644 --- a/shared-bindings/alarm/touch/TouchAlarm.c +++ b/shared-bindings/alarm/touch/TouchAlarm.c @@ -20,8 +20,7 @@ //| :param microcontroller.Pin pin: The pin to monitor. On some ports, the choice of pin //| may be limited due to hardware restrictions, particularly for deep-sleep alarms. //| -//| **Limitations:** Not available on SAMD, Nordic, or RP2040. -//| On Espressif, only available on ESP32, ESP32-S2, ESP32-S3, and ESP32-P4. +//| **Limitations:** Available only on Espressif ESP32, ESP32-S2, ESP32-S3, and ESP32-P4. //| """ //| ... //| diff --git a/shared-bindings/analogio/AnalogOut.c b/shared-bindings/analogio/AnalogOut.c index 24f6fb87d3a..c6b27c7a560 100644 --- a/shared-bindings/analogio/AnalogOut.c +++ b/shared-bindings/analogio/AnalogOut.c @@ -18,8 +18,9 @@ //| class AnalogOut: //| """Output analog values (a specific voltage). //| -//| **Limitations:** Not available on Nordic, RP2040, Spresense, as there is no on-chip DAC. -//| On Espressif, available only on ESP32 and ESP32-S2; other chips do not have a DAC. +//| **Limitations:** Available only on chips with an on-chip DAC: +//| SAMD21, SAMD51, ESP32, ESP32-S2, STM32F405, STM32F407, and EFR32MG24. +//| On Zephyr-based boards, available only if the board defines a DAC. //| On ESP32-S2 boards, GPIO18 (DAC2) is often connected to a pull-up resistor, which causes //| `unexpected output values in the lower part of the output range //| `_. diff --git a/shared-bindings/audiobusio/PDMIn.c b/shared-bindings/audiobusio/PDMIn.c index 79fb6bff1e4..b4289ed1313 100644 --- a/shared-bindings/audiobusio/PDMIn.c +++ b/shared-bindings/audiobusio/PDMIn.c @@ -47,7 +47,7 @@ //| to allow microphone to turn on. Most require only 0.01s; some require 0.1s. Longer is safer. //| Must be in range 0.0-1.0 seconds. //| -//| **Limitations:** On SAMD and RP2040, supports only 8 or 16 bit mono input, with 64x oversampling. +//| **Limitations:** On SAMD and RP2xxx, supports only 8 or 16 bit mono input, with 64x oversampling. //| On nRF52840, supports only 16 bit mono input at 16 kHz; oversampling is fixed at 64x. Not provided //| on nRF52833 for space reasons. On Espressif, only available on ESP32, ESP32-S3, and ESP32-P4. //| diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index b619dfa1140..c2288135da2 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -115,6 +115,10 @@ static void check_lock(busio_i2c_obj_t *self) { //| def probe(self, address: int) -> bool: //| """Check if a device at the specified address responds. //| +//| **Limitations:** On Zephyr-based nRF boards, `probe()` does not work reliably +//| at 400 kHz. Use 100 kHz. +//| See `#11604 `_. +//| //| :param int address: 7-bit device address //| :return: ``True`` if a device at ``address`` responds; ``False`` otherwise //| :rtype: bool""" @@ -134,6 +138,10 @@ MP_DEFINE_CONST_FUN_OBJ_2(busio_i2c_probe_obj, busio_i2c_probe); //| """Scan all I2C addresses between 0x08 and 0x77 inclusive and return a //| list of those that respond. //| +//| **Limitations:** On Zephyr-based nRF boards, `scan()` does not work reliably +//| at 400 kHz. Use 100 kHz. +//| See `#11604 `_. +//| //| :return: List of device ids on the I2C bus //| :rtype: list""" //| ... @@ -157,6 +165,12 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_scan_obj, busio_i2c_scan); //| def try_lock(self) -> bool: //| """Attempts to grab the I2C lock. Returns True on success. //| +//| .. warning:: Ideally, release the lock with `unlock()` as soon as you are done with the bus. +//| Use :class:`~adafruit_bus_device.I2CDevice`, which holds the lock only +//| during each transaction. +//| On Espressif boards, holding the lock for a long time while using WiFi +//| can starve the WiFi and USB tasks, and the board may hang or restart in safe mode. +//| //| :return: True when lock has been grabbed //| :rtype: bool""" //| ... diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index 6411fdaa627..e876e7c2094 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -208,6 +208,12 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_configure_obj, 1, busio_spi_configure); //| def try_lock(self) -> bool: //| """Attempts to grab the SPI lock. Returns True on success. //| +//| .. warning:: Ideally, release the lock with `unlock()` as soon as you are done with the bus. +//| Use :class:`~adafruit_bus_device.SPIDevice`, which holds the lock only +//| during each transaction. +//| On Espressif boards, holding the lock for a long time while using WiFi +//| can starve the WiFi and USB tasks, and the board may hang or restart in safe mode. +//| //| :return: True when lock has been grabbed //| :rtype: bool""" //| ... diff --git a/shared-bindings/busio/UART.c b/shared-bindings/busio/UART.c index da05b226fd7..f579d15ae38 100644 --- a/shared-bindings/busio/UART.c +++ b/shared-bindings/busio/UART.c @@ -77,8 +77,8 @@ //| *New in CircuitPython 4.0:* ``timeout`` has incompatibly changed units from milliseconds to seconds. //| The new upper limit on ``timeout`` is meant to catch mistaken use of milliseconds. //| -//| **Limitations:** RS485 is not supported on SAMD, Nordic, Spresense, or STM. -//| On i.MX and Raspberry Pi RP2040, RS485 support is implemented in software: +//| **Limitations:** RS485 is available only on Espressif, i.MX, and Raspberry Pi RP2xxx. +//| On i.MX and RP2xxx, RS485 support is implemented in software: //| The timing for the ``rs485_dir`` pin signal is done on a best-effort basis, and may not meet //| RS485 specifications intermittently. //| """ diff --git a/shared-bindings/countio/Counter.c b/shared-bindings/countio/Counter.c index 9f8bd00645c..9c03098e72b 100644 --- a/shared-bindings/countio/Counter.c +++ b/shared-bindings/countio/Counter.c @@ -47,7 +47,7 @@ //| pin_counter.reset() //| print(pin_counter.count) //| -//| **Limitations:** On RP2040, `Counter` uses the PWM peripheral, and +//| **Limitations:** On RP2xxx, `Counter` uses the PWM peripheral, and //| is limited to using PWM channel B pins due to hardware restrictions. //| See the pin assignments for your board to see which pins can be used. //| """ diff --git a/shared-bindings/countio/Edge.c b/shared-bindings/countio/Edge.c index 9ace6a923ff..7453720d12a 100644 --- a/shared-bindings/countio/Edge.c +++ b/shared-bindings/countio/Edge.c @@ -30,7 +30,7 @@ MAKE_ENUM_VALUE(countio_edge_type, edge, RISE_AND_FALL, EDGE_RISE_AND_FALL); //| RISE_AND_FALL: Edge //| """Count the rising and falling edges. //| -//| **Limitations:** ``RISE_AND_FALL`` is not available to RP2040 due to hardware limitations. +//| **Limitations:** ``RISE_AND_FALL`` is not available on RP2xxx due to hardware limitations. //| """ //| //| diff --git a/shared-bindings/microcontroller/Processor.c b/shared-bindings/microcontroller/Processor.c index 9a6e1938e80..e0fd68be2ad 100644 --- a/shared-bindings/microcontroller/Processor.c +++ b/shared-bindings/microcontroller/Processor.c @@ -132,7 +132,8 @@ MP_PROPERTY_GETTER(mcu_processor_reset_reason_obj, //| //| Is `None` if the temperature is not available. //| -//| **Limitations:** Not available on ESP32 or ESP32-S3. On small SAMD21 builds without external flash, +//| **Limitations:** Not available on ESP32, MAX32, Spresense, STM chips other than STM32F4, +//| or Zephyr-based boards. On small SAMD21 builds without external flash, //| the reported temperature has reduced accuracy and precision, to save code space. //| """ static mp_obj_t mcu_processor_get_temperature(mp_obj_t self) { diff --git a/shared-bindings/rtc/RTC.c b/shared-bindings/rtc/RTC.c index b0cf3ce3caa..a65db08cbb2 100644 --- a/shared-bindings/rtc/RTC.c +++ b/shared-bindings/rtc/RTC.c @@ -78,7 +78,7 @@ MP_PROPERTY_GETSET(rtc_rtc_datetime_obj, //| //| A positive value speeds up the clock and a negative value slows it down. //| -//| **Limitations:** Calibration not supported on SAMD, Nordic, RP2040, Spresense, and STM. +//| **Limitations:** Calibration is supported only on SAMD. On other ports, setting it raises `NotImplementedError`. //| //| Range and value is hardware specific, but one step is often approximately 1 ppm:: //| diff --git a/shared-bindings/wifi/Radio.c b/shared-bindings/wifi/Radio.c index f94c5f3bbd1..5dc58d0510b 100644 --- a/shared-bindings/wifi/Radio.c +++ b/shared-bindings/wifi/Radio.c @@ -147,7 +147,8 @@ MP_PROPERTY_GETSET(wifi_radio_hostname_obj, //| """MAC address for the station. When the address is altered after interface is connected //| the changes would only be reflected once the interface reconnects. //| -//| **Limitations:** Not settable on RP2040 CYW43 boards, such as Pi Pico W. +//| **Limitations:** Settable on Espressif. +//| Not settable on Raspberry Pi RP2xxx CYW43 boards, such as Pico W and Pico 2 W. //| """ @@ -232,7 +233,8 @@ MP_PROPERTY_GETSET(wifi_radio_power_management_obj, //| """MAC address for the AP. When the address is altered after interface is started //| the changes would only be reflected once the interface restarts. //| -//| **Limitations:** Not settable on RP2040 CYW43 boards, such as Pi Pico W. +//| **Limitations:** Settable on Espressif. +//| Not settable on Raspberry Pi RP2xxx CYW43 boards, such as Pico W and Pico 2 W. //| """ //| static mp_obj_t wifi_radio_get_mac_address_ap(mp_obj_t self_in) { @@ -277,7 +279,7 @@ MP_PROPERTY_GETTER(wifi_radio_mac_address_ap_obj, //| //| .. note:: //| -//| In the raspberrypi port (RP2040 CYW43), ``start_channel`` and ``stop_channel`` are ignored. +//| In the raspberrypi port (RP2xxx CYW43), ``start_channel`` and ``stop_channel`` are ignored. //| """ //| ... //| @@ -378,7 +380,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(wifi_radio_stop_station_obj, wifi_radio_stop_station); //| //| .. note:: //| -//| In the raspberrypi port (RP2040 CYW43), ``max_connections`` is ignored +//| In the raspberrypi port (RP2xxx CYW43), ``max_connections`` is ignored //| and only 2.4 GHz channels (1-13) are accepted. //| """ //| ... @@ -635,7 +637,7 @@ MP_PROPERTY_GETTER(wifi_radio_ipv4_subnet_ap_obj, //| //| .. note:: //| -//| In the raspberrypi port (RP2040 CYW43), the access point needs to be started before the IP v4 address can be set. +//| In the raspberrypi port (RP2xxx CYW43), the access point needs to be started before the IP v4 address can be set. //| """ //| ... //|