From f365025c9c699a4a42c103b9ff01071ebc8d57c8 Mon Sep 17 00:00:00 2001 From: David P Date: Sat, 12 Jun 2021 14:53:44 +1000 Subject: [PATCH] stm32: Replace master/slave with controller/peripheral in I2C and SPI. Replace "master" with "controller" and "slave" with "peripheral" in comments, errors, and debug messages. Add CONTROLLER and PERIPHERAL constants to pyb.SPI and pyb.I2C classes; retain MASTER and SLAVE constants for backward compatiblity. --- ports/stm32/pyb_i2c.c | 63 ++++++++++++++++++++++-------------------- ports/stm32/pyb_spi.c | 19 +++++++------ ports/stm32/spi.c | 4 +-- tests/pyb/i2c.py | 2 +- tests/pyb/i2c_accel.py | 2 +- tests/pyb/i2c_error.py | 2 +- tests/pyb/pyb_f405.py | 2 +- tests/pyb/spi.py | 14 ++++++---- tests/pyb/spi.py.exp | 4 +-- 9 files changed, 60 insertions(+), 52 deletions(-) diff --git a/ports/stm32/pyb_i2c.c b/ports/stm32/pyb_i2c.c index f0bd38333d..dbcf4bcb81 100644 --- a/ports/stm32/pyb_i2c.c +++ b/ports/stm32/pyb_i2c.c @@ -49,14 +49,14 @@ /// from pyb import I2C /// /// i2c = I2C(1) # create on bus 1 -/// i2c = I2C(1, I2C.MASTER) # create and init as a master -/// i2c.init(I2C.MASTER, baudrate=20000) # init as a master -/// i2c.init(I2C.SLAVE, addr=0x42) # init as a slave with given address -/// i2c.deinit() # turn off the peripheral +/// i2c = I2C(1, I2C.CONTROLLER) # create and init as a controller +/// i2c.init(I2C.CONTROLLER, baudrate=20000) # init as a controller +/// i2c.init(I2C.PERIPHERAL, addr=0x42) # init as a peripheral with given address +/// i2c.deinit() # turn off the I2C unit /// /// Printing the i2c object gives you information about its configuration. /// -/// Basic methods for slave are send and recv: +/// Basic methods for peripheral are send and recv: /// /// i2c.send('abc') # send 3 bytes /// i2c.send(0x42) # send a single byte, given by the number @@ -71,19 +71,19 @@ /// /// i2c.send(b'123', timeout=2000) # timout after 2 seconds /// -/// A master must specify the recipient's address: +/// A controller must specify the recipient's address: /// -/// i2c.init(I2C.MASTER) -/// i2c.send('123', 0x42) # send 3 bytes to slave with address 0x42 +/// i2c.init(I2C.CONTROLLER) +/// i2c.send('123', 0x42) # send 3 bytes to peripheral with address 0x42 /// i2c.send(b'456', addr=0x42) # keyword for address /// /// Master also has other methods: /// -/// i2c.is_ready(0x42) # check if slave 0x42 is ready -/// i2c.scan() # scan for slaves on the bus, returning +/// i2c.is_ready(0x42) # check if peripheral 0x42 is ready +/// i2c.scan() # scan for peripherals on the bus, returning /// # a list of valid addresses -/// i2c.mem_read(3, 0x42, 2) # read 3 bytes from memory of slave 0x42, -/// # starting at address 2 in the slave +/// i2c.mem_read(3, 0x42, 2) # read 3 bytes from memory of peripheral 0x42, +/// # starting at address 2 in the peripheral /// i2c.mem_write('abc', 0x42, 2, timeout=1000) #define PYB_I2C_MASTER (0) #define PYB_I2C_SLAVE (1) @@ -578,7 +578,7 @@ STATIC void pyb_i2c_print(const mp_print_t *print, mp_obj_t self_in, mp_print_ki mp_printf(print, "I2C(%u)", i2c_num); } else { if (in_master_mode(self)) { - mp_printf(print, "I2C(%u, I2C.MASTER, baudrate=%u" + mp_printf(print, "I2C(%u, I2C.CONTROLLER, baudrate=%u" #if PYB_I2C_TIMINGR ", timingr=0x%08x" #endif @@ -588,7 +588,7 @@ STATIC void pyb_i2c_print(const mp_print_t *print, mp_obj_t self_in, mp_print_ki #endif ); } else { - mp_printf(print, "I2C(%u, I2C.SLAVE, addr=0x%02x)", i2c_num, (self->i2c->Instance->OAR1 >> 1) & 0x7f); + mp_printf(print, "I2C(%u, I2C.PERIPHERAL, addr=0x%02x)", i2c_num, (self->i2c->Instance->OAR1 >> 1) & 0x7f); } } } @@ -597,9 +597,9 @@ STATIC void pyb_i2c_print(const mp_print_t *print, mp_obj_t self_in, mp_print_ki /// /// Initialise the I2C bus with the given parameters: /// -/// - `mode` must be either `I2C.MASTER` or `I2C.SLAVE` -/// - `addr` is the 7-bit address (only sensible for a slave) -/// - `baudrate` is the SCL clock rate (only sensible for a master) +/// - `mode` must be either `I2C.CONTROLLER` or `I2C.PERIPHERAL` +/// - `addr` is the 7-bit address (only sensible for a peripheral) +/// - `baudrate` is the SCL clock rate (only sensible for a controller) /// - `gencall` is whether to support general call mode STATIC mp_obj_t pyb_i2c_init_helper(const pyb_i2c_obj_t *self, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { static const mp_arg_t allowed_args[] = { @@ -621,7 +621,7 @@ STATIC mp_obj_t pyb_i2c_init_helper(const pyb_i2c_obj_t *self, size_t n_args, co I2C_InitTypeDef *init = &self->i2c->Init; if (args[0].u_int == PYB_I2C_MASTER) { - // use a special address to indicate we are a master + // use a special address to indicate we are a controller init->OwnAddress1 = PYB_I2C_MASTER_ADDRESS; } else { init->OwnAddress1 = (args[1].u_int << 1) & 0xfe; @@ -697,12 +697,12 @@ STATIC mp_obj_t pyb_i2c_deinit(mp_obj_t self_in) { STATIC MP_DEFINE_CONST_FUN_OBJ_1(pyb_i2c_deinit_obj, pyb_i2c_deinit); /// \method is_ready(addr) -/// Check if an I2C device responds to the given address. Only valid when in master mode. +/// Check if an I2C device responds to the given address. Only valid when in controller mode. STATIC mp_obj_t pyb_i2c_is_ready(mp_obj_t self_in, mp_obj_t i2c_addr_o) { pyb_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); if (!in_master_mode(self)) { - mp_raise_TypeError(MP_ERROR_TEXT("I2C must be a master")); + mp_raise_TypeError(MP_ERROR_TEXT("I2C must be a controller")); } mp_uint_t i2c_addr = mp_obj_get_int(i2c_addr_o) << 1; @@ -720,12 +720,12 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_2(pyb_i2c_is_ready_obj, pyb_i2c_is_ready); /// \method scan() /// Scan all I2C addresses from 0x08 to 0x77 and return a list of those that respond. -/// Only valid when in master mode. +/// Only valid when in controller mode. STATIC mp_obj_t pyb_i2c_scan(mp_obj_t self_in) { pyb_i2c_obj_t *self = MP_OBJ_TO_PTR(self_in); if (!in_master_mode(self)) { - mp_raise_TypeError(MP_ERROR_TEXT("I2C must be a master")); + mp_raise_TypeError(MP_ERROR_TEXT("I2C must be a controller")); } mp_obj_t list = mp_obj_new_list(0, NULL); @@ -745,7 +745,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_1(pyb_i2c_scan_obj, pyb_i2c_scan); /// Send data on the bus: /// /// - `send` is the data to send (an integer to send, or a buffer object) -/// - `addr` is the address to send to (only required in master mode) +/// - `addr` is the address to send to (only required in controller mode) /// - `timeout` is the timeout in milliseconds to wait for the send /// /// Return value: `None`. @@ -824,7 +824,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pyb_i2c_send_obj, 1, pyb_i2c_send); /// /// - `recv` can be an integer, which is the number of bytes to receive, /// or a mutable buffer, which will be filled with received bytes -/// - `addr` is the address to receive from (only required in master mode) +/// - `addr` is the address to receive from (only required in controller mode) /// - `timeout` is the timeout in milliseconds to wait for the receive /// /// Return value: if `recv` is an integer then a new buffer of the bytes received, @@ -910,7 +910,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pyb_i2c_recv_obj, 1, pyb_i2c_recv); /// - `addr_size` selects width of memaddr: 8 or 16 bits /// /// Returns the read data. -/// This is only valid in master mode. +/// This is only valid in controller mode. STATIC const mp_arg_t pyb_i2c_mem_read_allowed_args[] = { { MP_QSTR_data, MP_ARG_REQUIRED | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL} }, { MP_QSTR_addr, MP_ARG_REQUIRED | MP_ARG_INT, {.u_int = 0} }, @@ -926,7 +926,7 @@ STATIC mp_obj_t pyb_i2c_mem_read(size_t n_args, const mp_obj_t *pos_args, mp_map mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(pyb_i2c_mem_read_allowed_args), pyb_i2c_mem_read_allowed_args, args); if (!in_master_mode(self)) { - mp_raise_TypeError(MP_ERROR_TEXT("I2C must be a master")); + mp_raise_TypeError(MP_ERROR_TEXT("I2C must be a controller")); } // get the buffer to read into @@ -986,7 +986,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pyb_i2c_mem_read_obj, 1, pyb_i2c_mem_read); /// - `addr_size` selects width of memaddr: 8 or 16 bits /// /// Returns `None`. -/// This is only valid in master mode. +/// This is only valid in controller mode. STATIC mp_obj_t pyb_i2c_mem_write(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { // parse args (same as mem_read) pyb_i2c_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]); @@ -994,7 +994,7 @@ STATIC mp_obj_t pyb_i2c_mem_write(size_t n_args, const mp_obj_t *pos_args, mp_ma mp_arg_parse_all(n_args - 1, pos_args + 1, kw_args, MP_ARRAY_SIZE(pyb_i2c_mem_read_allowed_args), pyb_i2c_mem_read_allowed_args, args); if (!in_master_mode(self)) { - mp_raise_TypeError(MP_ERROR_TEXT("I2C must be a master")); + mp_raise_TypeError(MP_ERROR_TEXT("I2C must be a controller")); } // get the buffer to write from @@ -1051,8 +1051,11 @@ STATIC const mp_rom_map_elem_t pyb_i2c_locals_dict_table[] = { { MP_ROM_QSTR(MP_QSTR_mem_write), MP_ROM_PTR(&pyb_i2c_mem_write_obj) }, // class constants - /// \constant MASTER - for initialising the bus to master mode - /// \constant SLAVE - for initialising the bus to slave mode + /// \constant CONTROLLER - for initialising the bus to controller mode + /// \constant PERIPHERAL - for initialising the bus to peripheral mode + { MP_ROM_QSTR(MP_QSTR_CONTROLLER), MP_ROM_INT(PYB_I2C_MASTER) }, + { MP_ROM_QSTR(MP_QSTR_PERIPHERAL), MP_ROM_INT(PYB_I2C_SLAVE) }, + // TODO - remove MASTER/SLAVE when CONTROLLER/PERIPHERAL gain wide adoption { MP_ROM_QSTR(MP_QSTR_MASTER), MP_ROM_INT(PYB_I2C_MASTER) }, { MP_ROM_QSTR(MP_QSTR_SLAVE), MP_ROM_INT(PYB_I2C_SLAVE) }, }; diff --git a/ports/stm32/pyb_spi.c b/ports/stm32/pyb_spi.c index 99a1cd77b4..abb7ba41db 100644 --- a/ports/stm32/pyb_spi.c +++ b/ports/stm32/pyb_spi.c @@ -32,18 +32,18 @@ /******************************************************************************/ // MicroPython bindings for legacy pyb API -// class pyb.SPI - a master-driven serial protocol +// class pyb.SPI - a controller-driven serial protocol // -// SPI is a serial protocol that is driven by a master. At the physical level +// SPI is a serial protocol that is driven by a controller. At the physical level // there are 3 lines: SCK, MOSI, MISO. // // See usage model of I2C; SPI is very similar. Main difference is // parameters to init the SPI bus: // // from pyb import SPI -// spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=0, crc=0x7) +// spi = SPI(1, SPI.CONTROLLER, baudrate=600000, polarity=1, phase=0, crc=0x7) // -// Only required parameter is mode, SPI.MASTER or SPI.SLAVE. Polarity can be +// Only required parameter is mode, SPI.CONTROLLER or SPI.PERIPHERAL. Polarity can be // 0 or 1, and is the level the idle clock line sits at. Phase can be 0 or 1 // to sample data on the first or second clock edge respectively. Crc can be // None for no CRC, or a polynomial specifier. @@ -72,8 +72,8 @@ STATIC void pyb_spi_print(const mp_print_t *print, mp_obj_t self_in, mp_print_ki // init(mode, baudrate=328125, *, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None) // // Initialise the SPI bus with the given parameters: -// - `mode` must be either `SPI.MASTER` or `SPI.SLAVE`. -// - `baudrate` is the SCK clock rate (only sensible for a master). +// - `mode` must be either `SPI.CONTROLLER` or `SPI.PERIPHERAL`. +// - `baudrate` is the SCK clock rate (only sensible for a controller). STATIC mp_obj_t pyb_spi_init_helper(const pyb_spi_obj_t *self, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) { static const mp_arg_t allowed_args[] = { { MP_QSTR_mode, MP_ARG_REQUIRED | MP_ARG_INT, {.u_int = 0} }, @@ -319,10 +319,13 @@ STATIC const mp_rom_map_elem_t pyb_spi_locals_dict_table[] = { { MP_ROM_QSTR(MP_QSTR_send_recv), MP_ROM_PTR(&pyb_spi_send_recv_obj) }, // class constants - /// \constant MASTER - for initialising the bus to master mode - /// \constant SLAVE - for initialising the bus to slave mode + /// \constant CONTROLLER - for initialising the bus to controller mode + /// \constant PERIPHERAL - for initialising the bus to peripheral mode /// \constant MSB - set the first bit to MSB /// \constant LSB - set the first bit to LSB + { MP_ROM_QSTR(MP_QSTR_CONTROLLER), MP_ROM_INT(SPI_MODE_MASTER) }, + { MP_ROM_QSTR(MP_QSTR_PERIPHERAL), MP_ROM_INT(SPI_MODE_SLAVE) }, + // TODO - remove MASTER/SLAVE when CONTROLLER/PERIPHERAL gain wide adoption { MP_ROM_QSTR(MP_QSTR_MASTER), MP_ROM_INT(SPI_MODE_MASTER) }, { MP_ROM_QSTR(MP_QSTR_SLAVE), MP_ROM_INT(SPI_MODE_SLAVE) }, { MP_ROM_QSTR(MP_QSTR_MSB), MP_ROM_INT(SPI_FIRSTBIT_MSB) }, diff --git a/ports/stm32/spi.c b/ports/stm32/spi.c index d3b3a784e8..0ce6b5abc6 100644 --- a/ports/stm32/spi.c +++ b/ports/stm32/spi.c @@ -640,14 +640,14 @@ void spi_print(const mp_print_t *print, const spi_t *spi_obj, bool legacy) { #endif uint baudrate = spi_get_source_freq(spi) >> log_prescaler; if (legacy) { - mp_printf(print, ", SPI.MASTER"); + mp_printf(print, ", SPI.CONTROLLER"); } mp_printf(print, ", baudrate=%u", baudrate); if (legacy) { mp_printf(print, ", prescaler=%u", 1 << log_prescaler); } } else { - mp_printf(print, ", SPI.SLAVE"); + mp_printf(print, ", SPI.PERIPHERAL"); } mp_printf(print, ", polarity=%u, phase=%u, bits=%u", spi->Init.CLKPolarity == SPI_POLARITY_LOW ? 0 : 1, spi->Init.CLKPhase == SPI_PHASE_1EDGE ? 0 : 1, spi->Init.DataSize == SPI_DATASIZE_8BIT ? 8 : 16); if (spi->Init.CRCCalculation == SPI_CRCCALCULATION_ENABLE) { diff --git a/tests/pyb/i2c.py b/tests/pyb/i2c.py index bc9dba8781..c968843273 100644 --- a/tests/pyb/i2c.py +++ b/tests/pyb/i2c.py @@ -11,6 +11,6 @@ for bus in (-1, 0, 1): i2c = I2C(1) -i2c.init(I2C.MASTER, baudrate=400000) +i2c.init(I2C.CONTROLLER, baudrate=400000) print(i2c.scan()) i2c.deinit() diff --git a/tests/pyb/i2c_accel.py b/tests/pyb/i2c_accel.py index 8c74fa60e6..8b87d406d0 100644 --- a/tests/pyb/i2c_accel.py +++ b/tests/pyb/i2c_accel.py @@ -11,7 +11,7 @@ accel_addr = 76 pyb.Accel() # this will init the MMA for us -i2c = I2C(1, I2C.MASTER, baudrate=400000) +i2c = I2C(1, I2C.CONTROLLER, baudrate=400000) print(i2c.scan()) print(i2c.is_ready(accel_addr)) diff --git a/tests/pyb/i2c_error.py b/tests/pyb/i2c_error.py index b17a26325d..1228962f5f 100644 --- a/tests/pyb/i2c_error.py +++ b/tests/pyb/i2c_error.py @@ -11,7 +11,7 @@ if not hasattr(pyb, "Accel"): pyb.Accel() # get I2C bus -i2c = I2C(1, I2C.MASTER, dma=True) +i2c = I2C(1, I2C.CONTROLLER, dma=True) # test polling mem_read pyb.disable_irq() diff --git a/tests/pyb/pyb_f405.py b/tests/pyb/pyb_f405.py index 243381056e..d7431a11a1 100644 --- a/tests/pyb/pyb_f405.py +++ b/tests/pyb/pyb_f405.py @@ -10,7 +10,7 @@ print(pyb.freq()) print(type(pyb.rng())) # test HAL error specific to F405 -i2c = pyb.I2C(2, pyb.I2C.MASTER) +i2c = pyb.I2C(2, pyb.I2C.CONTROLLER) try: i2c.recv(1, 1) except OSError as e: diff --git a/tests/pyb/spi.py b/tests/pyb/spi.py index 73d39e7245..7df6aeb457 100644 --- a/tests/pyb/spi.py +++ b/tests/pyb/spi.py @@ -11,12 +11,14 @@ for bus in (-1, 0, 1, 2): spi = SPI(1) print(spi) -spi = SPI(1, SPI.MASTER) -spi = SPI(1, SPI.MASTER, baudrate=500000) -spi = SPI(1, SPI.MASTER, 500000, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None) -print(str(spi)[:28], str(spi)[49:]) # don't print baudrate/prescaler +spi = SPI(1, SPI.CONTROLLER) +spi = SPI(1, SPI.CONTROLLER, baudrate=500000) +spi = SPI( + 1, SPI.CONTROLLER, 500000, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None +) +print(str(spi)[:32], str(spi)[53:]) # don't print baudrate/prescaler -spi.init(SPI.SLAVE, phase=1) +spi.init(SPI.PERIPHERAL, phase=1) print(spi) try: # need to flush input before we get an error (error is what we want to test) @@ -25,7 +27,7 @@ try: except OSError: print("OSError") -spi.init(SPI.MASTER) +spi.init(SPI.CONTROLLER) spi.send(1, timeout=100) print(spi.recv(1, timeout=100)) print(spi.send_recv(1, timeout=100)) diff --git a/tests/pyb/spi.py.exp b/tests/pyb/spi.py.exp index 473c173a58..661bace900 100644 --- a/tests/pyb/spi.py.exp +++ b/tests/pyb/spi.py.exp @@ -3,8 +3,8 @@ ValueError 0 SPI 1 SPI 2 SPI(1) -SPI(1, SPI.MASTER, baudrate= , polarity=1, phase=0, bits=8) -SPI(1, SPI.SLAVE, polarity=1, phase=1, bits=8) +SPI(1, SPI.CONTROLLER, baudrate= , polarity=1, phase=0, bits=8) +SPI(1, SPI.PERIPHERAL, polarity=1, phase=1, bits=8) OSError b'\xff' b'\xff'