From 431e784a7e6f5af72772d37a7ddab50d1e6cd948 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Thu, 7 Oct 2021 21:20:02 -0400 Subject: [PATCH] big cleanup of SPI and I2C doc; fix arg names on SPI --- .../adafruit_bus_device/I2CDevice.c | 66 ++++++++++--------- shared-bindings/bitbangio/I2C.c | 33 ++++++---- shared-bindings/bitbangio/SPI.c | 54 +++++++++------ shared-bindings/busio/I2C.c | 41 +++++++----- shared-bindings/busio/SPI.c | 64 +++++++++++------- 5 files changed, 153 insertions(+), 105 deletions(-) diff --git a/shared-bindings/adafruit_bus_device/I2CDevice.c b/shared-bindings/adafruit_bus_device/I2CDevice.c index 211bde201a..a6ec8a2dfb 100644 --- a/shared-bindings/adafruit_bus_device/I2CDevice.c +++ b/shared-bindings/adafruit_bus_device/I2CDevice.c @@ -63,7 +63,8 @@ //| device.readinto(bytes_read) //| # A second transaction //| with device: -//| device.write(bytes_read)""" +//| device.write(bytes_read) +//| """ //| ... //| STATIC mp_obj_t adafruit_bus_device_i2cdevice_make_new(const mp_obj_type_t *type, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -111,15 +112,16 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(adafruit_bus_device_i2cdevice___exit_ //| import sys //| def readinto(self, buffer: WriteableBuffer, *, start: int = 0, end: int = sys.maxsize) -> None: -//| """Read into ``buffer`` from the device. The number of bytes read will be the -//| length of ``buffer``. -//| If ``start`` or ``end`` is provided, then the buffer will be sliced -//| as if ``buffer[start:end]``. This will not cause an allocation like -//| ``buffer[start:end]`` will so it saves memory. +//| """Read into ``buffer`` from the device. //| -//| :param bytearray buffer: buffer to write into -//| :param int start: Index to start writing at -//| :param int end: Index to write up to but not include; if None, use ``len(buffer)``""" +//| If ``start`` or ``end`` is provided, then the buffer will be sliced +//| as if ``buffer[start:end]`` were passed. +//| The number of bytes read will be the length of ``buffer[start:end]``. +//| +//| :param WriteableBuffer buffer: read bytes into this buffer +//| :param int start: beginning of buffer slice +//| :param int end: end of buffer slice; if not specified, use ``len(buffer)`` +//| """ //| ... //| STATIC mp_obj_t adafruit_bus_device_i2cdevice_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { @@ -158,13 +160,14 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(adafruit_bus_device_i2cdevice_readinto_obj, 1, //| import sys //| def write(self, buffer: ReadableBuffer, *, start: int = 0, end: int = sys.maxsize) -> None: //| """Write the bytes from ``buffer`` to the device, then transmit a stop bit. -//| If ``start`` or ``end`` is provided, then the buffer will be sliced -//| as if ``buffer[start:end]``. This will not cause an allocation like -//| ``buffer[start:end]`` will so it saves memory. //| -//| :param bytearray buffer: buffer containing the bytes to write -//| :param int start: Index to start writing from -//| :param int end: Index to read up to but not include; if None, use ``len(buffer)`` +//| If ``start`` or ``end`` is provided, then the buffer will be sliced +//| as if ``buffer[start:end]`` were passed, but without copying the data. +//| The number of bytes written will be the length of ``buffer[start:end]``. +//| +//| :param ReadableBuffer buffer: write out bytes from this buffer +//| :param int start: beginning of buffer slice +//| :param int end: end of buffer slice; if not specified, use ``len(buffer)`` //| """ //| ... //| @@ -202,25 +205,24 @@ MP_DEFINE_CONST_FUN_OBJ_KW(adafruit_bus_device_i2cdevice_write_obj, 1, adafruit_ //| import sys -//| def write_then_readinto(self, out_buffer: WriteableBuffer, in_buffer: ReadableBuffer, *, out_start: int = 0, out_end: int = sys.maxsize, in_start: int = 0, in_end: int = sys.maxsize) -> None: +//| def write_then_readinto(self, out_buffer: ReadableBuffer, in_buffer: WriteableBuffer, *, out_start: int = 0, out_end: int = sys.maxsize, in_start: int = 0, in_end: int = sys.maxsize) -> None: //| """Write the bytes from ``out_buffer`` to the device, then immediately -//| reads into ``in_buffer`` from the device. The number of bytes read -//| will be the length of ``in_buffer``. -//| If ``out_start`` or ``out_end`` is provided, then the output buffer -//| will be sliced as if ``out_buffer[out_start:out_end]``. This will -//| not cause an allocation like ``buffer[out_start:out_end]`` will so -//| it saves memory. -//| If ``in_start`` or ``in_end`` is provided, then the input buffer -//| will be sliced as if ``in_buffer[in_start:in_end]``. This will not -//| cause an allocation like ``in_buffer[in_start:in_end]`` will so -//| it saves memory. +//| reads into ``in_buffer`` from the device. //| -//| :param bytearray out_buffer: buffer containing the bytes to write -//| :param bytearray in_buffer: buffer containing the bytes to read into -//| :param int out_start: Index to start writing from -//| :param int out_end: Index to read up to but not include; if not specified, use ``len(out_buffer)`` -//| :param int in_start: Index to start writing at -//| :param int in_end: Index to write up to but not include; if not specified, use ``len(in_buffer)`` +//| If ``out_start`` or ``out_end`` is provided, then the buffer will be sliced +//| as if ``out_buffer[out_start:out_end]`` were passed, but without copying the data. +//| The number of bytes written will be the length of ``out_buffer[out_start:out_end]``. +//| +//| If ``in_start`` or ``in_end`` is provided, then the input buffer will be sliced +//| as if ``in_buffer[in_start:in_end]`` were passed, +//| The number of bytes read will be the length of ``out_buffer[in_start:in_end]``. +//| +//| :param ReadableBuffer out_buffer: write out bytes from this buffer +//| :param WriteableBuffer in_buffer: read bytes into this buffer +//| :param int out_start: beginning of ``out_buffer`` slice +//| :param int out_end: end of ``out_buffer`` slice; if not specified, use ``len(out_buffer)`` +//| :param int in_start: beginning of ``in_buffer`` slice +//| :param int in_end: end of ``in_buffer slice``; if not specified, use ``len(in_buffer)`` //| """ //| ... //| diff --git a/shared-bindings/bitbangio/I2C.c b/shared-bindings/bitbangio/I2C.c index a4de6a35be..3599cad48f 100644 --- a/shared-bindings/bitbangio/I2C.c +++ b/shared-bindings/bitbangio/I2C.c @@ -176,7 +176,7 @@ MP_DEFINE_CONST_FUN_OBJ_1(bitbangio_i2c_unlock_obj, bitbangio_i2c_obj_unlock); //| ``buf[start:end]`` will so it saves memory. //| //| :param int address: 7-bit device address -//| :param ~_typing.WriteableBuffer buffer: buffer to write into +//| :param WriteableBuffer buffer: buffer to write into //| :param int start: Index to start writing at //| :param int end: Index to write up to but not include""" //| ... @@ -225,16 +225,17 @@ MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_i2c_readfrom_into_obj, 1, bitbangio_i2c_rea //| before a read. //| //| If ``start`` or ``end`` is provided, then the buffer will be sliced -//| as if ``buffer[start:end]``. This will not cause an allocation like -//| ``buffer[start:end]`` will so it saves memory. +//| as if ``buffer[start:end]`` were passed, but without copying the data. +//| The number of bytes written will be the length of ``buffer[start:end]``. //| //| Writing a buffer or slice of length zero is permitted, as it can be used //| to poll for the existence of a device. //| //| :param int address: 7-bit device address -//| :param ~_typing.ReadableBuffer buffer: buffer containing the bytes to write -//| :param int start: Index to start writing from -//| :param int end: Index to read up to but not include. If not specified, use ``len(buffer)``""" +//| :param ReadableBuffer buffer: buffer containing the bytes to write +//| :param int start: beginning of buffer slice +//| :param int end: end of buffer slice; if not specified, use ``len(buffer)`` +//| """ //| ... //| // Shared arg parsing for writeto and writeto_then_readfrom. @@ -282,17 +283,23 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_i2c_writeto_obj, 1, bitbangio_i2c_wr //| bit, generate a repeated start and read into ``in_buffer``. ``out_buffer`` and //| ``in_buffer`` can be the same buffer because they are used sequentially. //| -//| If ``start`` or ``end`` is provided, then the corresponding buffer will be sliced -//| as if ``buffer[start:end]``. This will not cause an allocation like ``buf[start:end]`` -//| will so it saves memory. +//| If ``out_start`` or ``out_end`` is provided, then the buffer will be sliced +//| as if ``out_buffer[out_start:out_end]`` were passed, but without copying the data. +//| The number of bytes written will be the length of ``out_buffer[start:end]``. //| +//| If ``in_start`` or ``in_end`` is provided, then the input buffer will be sliced +//| as if ``in_buffer[in_start:in_end]`` were passed, +//| The number of bytes read will be the length of ``out_buffer[in_start:in_end]``. + //| :param int address: 7-bit device address //| :param ~_typing.ReadableBuffer out_buffer: buffer containing the bytes to write //| :param ~_typing.WriteableBuffer in_buffer: buffer to write into -//| :param int out_start: Index to start writing from -//| :param int out_end: Index to read up to but not include. If not specified, use ``len(buffer)`` -//| :param int in_start: Index to start writing at -//| :param int in_end: Index to write up to but not include. If not specified, use ``len(buffer)``""" +//| :param int out_start: beginning of ``out_buffer`` slice +//| :param int out_end: end of ``out_buffer`` slice; if not specified, use ``len(out_buffer)`` +//| :param int in_start: beginning of ``in_buffer`` slice +//| :param int in_end: end of ``in_buffer slice``; if not specified, use ``len(in_buffer)`` +//| """ +//| ... //| STATIC mp_obj_t bitbangio_i2c_writeto_then_readfrom(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_address, ARG_out_buffer, ARG_in_buffer, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; diff --git a/shared-bindings/bitbangio/SPI.c b/shared-bindings/bitbangio/SPI.c index 4141a07184..0f453b3807 100644 --- a/shared-bindings/bitbangio/SPI.c +++ b/shared-bindings/bitbangio/SPI.c @@ -230,13 +230,17 @@ MP_DEFINE_CONST_FUN_OBJ_2(bitbangio_spi_write_obj, bitbangio_spi_write); //| The SPI object must be locked. //| If the number of bytes to read is 0, nothing happens. //| -//| :param bytearray buffer: Read data into this buffer -//| :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]`` -//| :param int end: End of the slice; this index is not included. If not specified, use ``len(buffer)`` -//| :param int write_value: Value to write while reading.""" +//| If ``start`` or ``end`` is provided, then the buffer will be sliced +//| as if ``buffer[start:end]`` were passed. +//| The number of bytes read will be the length of ``buffer[start:end]``. +//| +//| :param WriteableBuffer buffer: read bytes into this buffer +//| :param int start: beginning of buffer slice +//| :param int end: end of buffer slice; if not specified, use ``len(buffer)`` +//| :param int write_value: value to write while reading +//| """ //| ... //| - STATIC mp_obj_t bitbangio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { enum { ARG_buffer, ARG_start, ARG_end, ARG_write_value }; static const mp_arg_t allowed_args[] = { @@ -270,26 +274,36 @@ STATIC mp_obj_t bitbangio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, MP_DEFINE_CONST_FUN_OBJ_KW(bitbangio_spi_readinto_obj, 1, bitbangio_spi_readinto); //| import sys -//| def write_readinto(self, buffer_out: ReadableBuffer, buffer_in: ReadableBuffer, *, out_start: int = 0, out_end: int = sys.maxsize, in_start: int = 0, in_end: int = sys.maxsize) -> None: -//| """Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. +//| def write_readinto(self, out_buffer: ReadableBuffer, in_buffer: WriteableBuffer, *, out_start: int = 0, out_end: int = sys.maxsize, in_start: int = 0, in_end: int = sys.maxsize) -> None: +//| """Write out the data in ``out_buffer`` while simultaneously reading data into ``in_buffer``. //| The SPI object must be locked. -//| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` -//| must be equal. +//| +//| If ``out_start`` or ``out_end`` is provided, then the buffer will be sliced +//| as if ``out_buffer[out_start:out_end]`` were passed, but without copying the data. +//| The number of bytes written will be the length of ``out_buffer[out_start:out_end]``. +//| +//| If ``in_start`` or ``in_end`` is provided, then the input buffer will be sliced +//| as if ``in_buffer[in_start:in_end]`` were passed, +//| The number of bytes read will be the length of ``out_buffer[in_start:in_end]``. +//| +//| The lengths of the slices defined by ``out_buffer[out_start:out_end]`` +//| and ``in_buffer[in_start:in_end]`` must be equal. //| If buffer slice lengths are both 0, nothing happens. //| -//| :param ~_typing.ReadableBuffer buffer_out: Write out the data in this buffer -//| :param ~_typing.WriteableBuffer buffer_in: Read data into this buffer -//| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` -//| :param int out_end: End of the slice; this index is not included. If not specified, use ``len(buffer_out)`` -//| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` -//| :param int in_end: End of the slice; this index is not included. If not specified, use ``len(buffer_in)``""" +//| :param ReadableBuffer out_buffer: write out bytes from this buffer +//| :param WriteableBuffer in_buffer: read bytes into this buffer +//| :param int out_start: beginning of ``out_buffer`` slice +//| :param int out_end: end of ``out_buffer`` slice; if not specified, use ``len(out_buffer)`` +//| :param int in_start: beginning of ``in_buffer`` slice +//| :param int in_end: end of ``in_buffer slice``; if not specified, use ``len(in_buffer)`` +//| """ //| ... //| STATIC mp_obj_t bitbangio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { - enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; + enum { ARG_out_buffer, ARG_in_buffer, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; static const mp_arg_t allowed_args[] = { - { MP_QSTR_buffer_out, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} }, - { MP_QSTR_buffer_in, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} }, + { MP_QSTR_out_buffer, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} }, + { MP_QSTR_in_buffer, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} }, { MP_QSTR_out_start, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 0} }, { MP_QSTR_out_end, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = INT_MAX} }, { MP_QSTR_in_start, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 0} }, @@ -303,13 +317,13 @@ STATIC mp_obj_t bitbangio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_ mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); mp_buffer_info_t buf_out_info; - mp_get_buffer_raise(args[ARG_buffer_out].u_obj, &buf_out_info, MP_BUFFER_READ); + mp_get_buffer_raise(args[ARG_out_buffer].u_obj, &buf_out_info, MP_BUFFER_READ); int32_t out_start = args[ARG_out_start].u_int; size_t out_length = buf_out_info.len; normalize_buffer_bounds(&out_start, args[ARG_out_end].u_int, &out_length); mp_buffer_info_t buf_in_info; - mp_get_buffer_raise(args[ARG_buffer_in].u_obj, &buf_in_info, MP_BUFFER_WRITE); + mp_get_buffer_raise(args[ARG_in_buffer].u_obj, &buf_in_info, MP_BUFFER_WRITE); int32_t in_start = args[ARG_in_start].u_int; size_t in_length = buf_in_info.len; normalize_buffer_bounds(&in_start, args[ARG_in_end].u_int, &in_length); diff --git a/shared-bindings/busio/I2C.c b/shared-bindings/busio/I2C.c index d6778e175c..740bd7cca4 100644 --- a/shared-bindings/busio/I2C.c +++ b/shared-bindings/busio/I2C.c @@ -179,17 +179,16 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_i2c_unlock_obj, busio_i2c_obj_unlock); //| import sys //| def readfrom_into(self, address: int, buffer: WriteableBuffer, *, start: int = 0, end: int = sys.maxsize) -> None: //| """Read into ``buffer`` from the device selected by ``address``. -//| The number of bytes read will be the length of ``buffer``. //| At least one byte must be read. //| //| If ``start`` or ``end`` is provided, then the buffer will be sliced -//| as if ``buffer[start:end]``. This will not cause an allocation like -//| ``buf[start:end]`` will so it saves memory. +//| as if ``buffer[start:end]`` were passed, but without copying the data. +//| The number of bytes read will be the length of ``buffer[start:end]``. //| //| :param int address: 7-bit device address -//| :param ~_typing.WriteableBuffer buffer: buffer to write into -//| :param int start: Index to start writing at -//| :param int end: Index to write up to but not include. If not specified, use ``len(buffer)``""" +//| :param WriteableBuffer buffer: buffer to write into +//| :param int start: beginning of buffer slice +//| :param int end: end of buffer slice; if not specified, use ``len(buffer)``""" //| ... //| // Shared arg parsing for readfrom_into and writeto_then_readfrom. @@ -235,16 +234,17 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_readfrom_into_obj, 1, busio_i2c_readfrom_in //| then transmit a stop bit. //| //| If ``start`` or ``end`` is provided, then the buffer will be sliced -//| as if ``buffer[start:end]``. This will not cause an allocation like -//| ``buffer[start:end]`` will so it saves memory. +//| as if ``buffer[start:end]`` were passed, but without copying the data. +//| The number of bytes written will be the length of ``buffer[start:end]``. //| //| Writing a buffer or slice of length zero is permitted, as it can be used //| to poll for the existence of a device. //| //| :param int address: 7-bit device address -//| :param ~_typing.ReadableBuffer buffer: buffer containing the bytes to write -//| :param int start: Index to start writing from -//| :param int end: Index to read up to but not include. If not specified, use ``len(buffer)``""" +//| :param ReadableBuffer buffer: buffer containing the bytes to write +//| :param int start: beginning of buffer slice +//| :param int end: end of buffer slice; if not specified, use ``len(buffer)`` +//| """ //| ... //| // Shared arg parsing for writeto and writeto_then_readfrom. @@ -290,17 +290,22 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(busio_i2c_writeto_obj, 1, busio_i2c_writeto); //| bit, generate a repeated start and read into ``in_buffer``. ``out_buffer`` and //| ``in_buffer`` can be the same buffer because they are used sequentially. //| -//| If ``start`` or ``end`` is provided, then the corresponding buffer will be sliced -//| as if ``buffer[start:end]``. This will not cause an allocation like ``buf[start:end]`` -//| will so it saves memory. +//| If ``out_start`` or ``out_end`` is provided, then the buffer will be sliced +//| as if ``out_buffer[out_start:out_end]`` were passed, but without copying the data. +//| The number of bytes written will be the length of ``out_buffer[start:end]``. //| +//| If ``in_start`` or ``in_end`` is provided, then the input buffer will be sliced +//| as if ``in_buffer[in_start:in_end]`` were passed, +//| The number of bytes read will be the length of ``out_buffer[in_start:in_end]``. + //| :param int address: 7-bit device address //| :param ~_typing.ReadableBuffer out_buffer: buffer containing the bytes to write //| :param ~_typing.WriteableBuffer in_buffer: buffer to write into -//| :param int out_start: Index to start writing from -//| :param int out_end: Index to read up to but not include. If not specified, use ``len(buffer)`` -//| :param int in_start: Index to start writing at -//| :param int in_end: Index to write up to but not include. If not specified, use ``len(buffer)``""" +//| :param int out_start: beginning of ``out_buffer`` slice +//| :param int out_end: end of ``out_buffer`` slice; if not specified, use ``len(out_buffer)`` +//| :param int in_start: beginning of ``in_buffer`` slice +//| :param int in_end: end of ``in_buffer slice``; if not specified, use ``len(in_buffer)`` +//| """ //| ... //| STATIC mp_obj_t busio_i2c_writeto_then_readfrom(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { diff --git a/shared-bindings/busio/SPI.c b/shared-bindings/busio/SPI.c index 8aff8f16b8..ceebce974b 100644 --- a/shared-bindings/busio/SPI.c +++ b/shared-bindings/busio/SPI.c @@ -242,9 +242,14 @@ MP_DEFINE_CONST_FUN_OBJ_1(busio_spi_unlock_obj, busio_spi_obj_unlock); //| """Write the data contained in ``buffer``. The SPI object must be locked. //| If the buffer is empty, nothing happens. //| -//| :param ~_typing.ReadableBuffer buffer: Write out the data in this buffer -//| :param int start: Start of the slice of ``buffer`` to write out: ``buffer[start:end]`` -//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)``""" +//| If ``start`` or ``end`` is provided, then the buffer will be sliced +//| as if ``buffer[start:end]`` were passed, but without copying the data. +//| The number of bytes written will be the length of ``buffer[start:end]``. +//| +//| :param ReadableBuffer buffer: write out bytes from this buffer +//| :param int start: beginning of buffer slice +//| :param int end: end of buffer slice; if not specified, use ``len(buffer)`` +//| """ //| ... //| @@ -286,10 +291,15 @@ MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_write_obj, 1, busio_spi_write); //| The SPI object must be locked. //| If the number of bytes to read is 0, nothing happens. //| -//| :param ~_typing.WriteableBuffer buffer: Read data into this buffer -//| :param int start: Start of the slice of ``buffer`` to read into: ``buffer[start:end]`` -//| :param int end: End of the slice; this index is not included. Defaults to ``len(buffer)`` -//| :param int write_value: Value to write while reading. (Usually ignored.)""" +//| If ``start`` or ``end`` is provided, then the buffer will be sliced +//| as if ``buffer[start:end]`` were passed. +//| The number of bytes read will be the length of ``buffer[start:end]``. +//| +//| :param WriteableBuffer buffer: read bytes into this buffer +//| :param int start: beginning of buffer slice +//| :param int end: end of buffer slice; if not specified, use ``len(buffer)`` +//| :param int write_value: value to write while reading +//| """ //| ... //| @@ -326,27 +336,37 @@ STATIC mp_obj_t busio_spi_readinto(size_t n_args, const mp_obj_t *pos_args, mp_m MP_DEFINE_CONST_FUN_OBJ_KW(busio_spi_readinto_obj, 1, busio_spi_readinto); //| import sys -//| def write_readinto(self, buffer_out: ReadableBuffer, buffer_in: WriteableBuffer, *, out_start: int = 0, out_end: int = sys.maxsize, in_start: int = 0, in_end: int = sys.maxsize) -> None: -//| """Write out the data in ``buffer_out`` while simultaneously reading data into ``buffer_in``. +//| def write_readinto(self, out_buffer: ReadableBuffer, in_buffer: WriteableBuffer, *, out_start: int = 0, out_end: int = sys.maxsize, in_start: int = 0, in_end: int = sys.maxsize) -> None: +//| """Write out the data in ``out_buffer`` while simultaneously reading data into ``in_buffer``. //| The SPI object must be locked. -//| The lengths of the slices defined by ``buffer_out[out_start:out_end]`` and ``buffer_in[in_start:in_end]`` -//| must be equal. +//| +//| If ``out_start`` or ``out_end`` is provided, then the buffer will be sliced +//| as if ``out_buffer[out_start:out_end]`` were passed, but without copying the data. +//| The number of bytes written will be the length of ``out_buffer[out_start:out_end]``. +//| +//| If ``in_start`` or ``in_end`` is provided, then the input buffer will be sliced +//| as if ``in_buffer[in_start:in_end]`` were passed, +//| The number of bytes read will be the length of ``out_buffer[in_start:in_end]``. +//| +//| The lengths of the slices defined by ``out_buffer[out_start:out_end]`` +//| and ``in_buffer[in_start:in_end]`` must be equal. //| If buffer slice lengths are both 0, nothing happens. //| -//| :param ~_typing.ReadableBuffer buffer_out: Write out the data in this buffer -//| :param ~_typing.WriteableBuffer buffer_in: Read data into this buffer -//| :param int out_start: Start of the slice of buffer_out to write out: ``buffer_out[out_start:out_end]`` -//| :param int out_end: End of the slice; this index is not included. If not specified, use ``len(buffer_out)`` -//| :param int in_start: Start of the slice of ``buffer_in`` to read into: ``buffer_in[in_start:in_end]`` -//| :param int in_end: End of the slice; this index is not included. If not specified, use ``len(buffer_in)``""" +//| :param ReadableBuffer out_buffer: write out bytes from this buffer +//| :param WriteableBuffer in_buffer: read bytes into this buffer +//| :param int out_start: beginning of ``out_buffer`` slice +//| :param int out_end: end of ``out_buffer`` slice; if not specified, use ``len(out_buffer)`` +//| :param int in_start: beginning of ``in_buffer`` slice +//| :param int in_end: end of ``in_buffer slice``; if not specified, use ``len(in_buffer)`` +//| """ //| ... //| STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { - enum { ARG_buffer_out, ARG_buffer_in, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; + enum { ARG_out_buffer, ARG_in_buffer, ARG_out_start, ARG_out_end, ARG_in_start, ARG_in_end }; static const mp_arg_t allowed_args[] = { - { MP_QSTR_buffer_out, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} }, - { MP_QSTR_buffer_in, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} }, + { MP_QSTR_out_buffer, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} }, + { MP_QSTR_in_buffer, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} }, { MP_QSTR_out_start, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 0} }, { MP_QSTR_out_end, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = INT_MAX} }, { MP_QSTR_in_start, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 0} }, @@ -359,13 +379,13 @@ STATIC mp_obj_t busio_spi_write_readinto(size_t n_args, const mp_obj_t *pos_args mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args); mp_buffer_info_t buf_out_info; - mp_get_buffer_raise(args[ARG_buffer_out].u_obj, &buf_out_info, MP_BUFFER_READ); + mp_get_buffer_raise(args[ARG_out_buffer].u_obj, &buf_out_info, MP_BUFFER_READ); int32_t out_start = args[ARG_out_start].u_int; size_t out_length = buf_out_info.len; normalize_buffer_bounds(&out_start, args[ARG_out_end].u_int, &out_length); mp_buffer_info_t buf_in_info; - mp_get_buffer_raise(args[ARG_buffer_in].u_obj, &buf_in_info, MP_BUFFER_WRITE); + mp_get_buffer_raise(args[ARG_in_buffer].u_obj, &buf_in_info, MP_BUFFER_WRITE); int32_t in_start = args[ARG_in_start].u_int; size_t in_length = buf_in_info.len; normalize_buffer_bounds(&in_start, args[ARG_in_end].u_int, &in_length);