3bca93b2d0
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>
|
||
|---|---|---|
| .. | ||
| boards | ||
| mcu | ||
| modules | ||
| Makefile | ||
| README.md | ||
| clock_config.h | ||
| fatfs_port.c | ||
| help.c | ||
| machine_adc.c | ||
| machine_bitstream.c | ||
| machine_dac.c | ||
| machine_i2c.c | ||
| machine_pin.c | ||
| machine_pwm.c | ||
| machine_rtc.c | ||
| machine_spi.c | ||
| machine_uart.c | ||
| machine_wdt.c | ||
| main.c | ||
| modmachine.c | ||
| modmachine.h | ||
| modos.c | ||
| modsamd.c | ||
| modtime.c | ||
| mpconfigport.h | ||
| mphalport.c | ||
| mphalport.h | ||
| pendsv.c | ||
| pendsv.h | ||
| pin_af.c | ||
| pin_af.h | ||
| qstrdefsport.h | ||
| samd_flash.c | ||
| samd_isr.c | ||
| samd_qspiflash.c | ||
| samd_soc.c | ||
| samd_soc.h | ||
| samd_spiflash.c | ||
| sections.ld | ||
| usbd.c | ||
README.md
Port of MicroPython to Microchip SAMD MCUs
Supports SAMD21 and SAMD51. For each supported device there is a
subdirectory in the boards/ directory.
The entry point for the specific port documentation is at https://docs.micropython.org/en/latest/samd/quickref.html, which also shows the assignment of IO-Functions to pins. The generic MicroPython documentation applies for anything not specific for the SAM port.
Due to the different flash sizes of SAMD21 and SAMD51 devices, the coverage of MicroPython modules differ. Use help("modules") to tell, which MicroPython modules are provided.
Build instructions
Before building the firmware for a given board the MicroPython cross-compiler must be built; it will be used to pre-compile some of the built-in scripts to bytecode. The cross-compiler is built and run on the host machine, using:
$ make -C mpy-cross
This command should be executed from the root directory of this repository. All other commands below should be executed from the ports/stm32/ directory.
An ARM compiler is required for the build, along with the associated binary
utilities. The default compiler is arm-none-eabi-gcc, which is available for
Arch Linux via the package arm-none-eabi-gcc, for Ubuntu via instructions
here, or
see here for the main GCC ARM
Embedded page. The compiler can be changed using the CROSS_COMPILE variable
when invoking make.
Next, the board to build must be selected. There is no default board. Any
of the names of the subdirectories in the boards/ directory is a valid board.
The board name must be passed as the argument to BOARD= when invoking make.
All boards require certain submodules to be obtained before they can be built.
The correct set of submodules can be initialised using (with
ADAFRUIT_ITSYBITSY_M4_EXPRESS as an example of the selected board):
$ make BOARD=ADAFRUIT_ITSYBITSY_M4_EXPRESS submodules
Then to build the board's firmware run:
$ make BOARD=ADAFRUIT_ITSYBITSY_M4_EXPRESS clean
$ make BOARD=ADAFRUIT_ITSYBITSY_M4_EXPRESS
The above command produces binary images in the
build-ADAFRUIT_ITSYBITSY_M4_EXPRESS/ subdirectory (or the equivalent
directory for the board specified).
Flashing the Firmware
Most SAMD21 and SAMD51 boards have a built in firmware loader. To start it, push
the reset button of the boards twice. The speed varies a little bit. If the
firmware loader starts, a drive will appear in the file manager of your PC.
Copy the created firmware.uf2 file to that drive. If the upload is finished, the
drive will disappear and the board will reboot.