[sw] Update GPIO DIF Return Codes
This is based on the naming and return code order proposed in #2212.
Signed-off-by: Sam Elliott <selliott@lowrisc.org>
diff --git a/sw/device/lib/dif/dif_gpio.c b/sw/device/lib/dif/dif_gpio.c
index 3f774d8..b4801a5 100644
--- a/sw/device/lib/dif/dif_gpio.c
+++ b/sw/device/lib/dif/dif_gpio.c
@@ -88,7 +88,7 @@
dif_gpio_result_t dif_gpio_init(const dif_gpio_config_t *config,
dif_gpio_t *gpio) {
if (config == NULL || gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
// Save internal state in the given `dif_gpio_t` instance.
@@ -96,12 +96,12 @@
// Reset the GPIO device at the given `base_addr`.
dif_gpio_reset(gpio);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_reset(const dif_gpio_t *gpio) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
mmio_region_write32(gpio->base_addr, GPIO_INTR_ENABLE_REG_OFFSET, 0);
@@ -115,201 +115,201 @@
// Also clear all pending interrupts
mmio_region_write32(gpio->base_addr, GPIO_INTR_STATE_REG_OFFSET, 0xFFFFFFFFu);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_all_read(const dif_gpio_t *gpio,
uint32_t *pin_values) {
if (gpio == NULL || pin_values == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
*pin_values = mmio_region_read32(gpio->base_addr, GPIO_DATA_IN_REG_OFFSET);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_pin_read(const dif_gpio_t *gpio, uint32_t index,
bool *pin_value) {
if (gpio == NULL || pin_value == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
*pin_value =
mmio_region_get_bit32(gpio->base_addr, GPIO_DATA_IN_REG_OFFSET, index);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_all_write(const dif_gpio_t *gpio, uint32_t val) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
mmio_region_write32(gpio->base_addr, GPIO_DIRECT_OUT_REG_OFFSET, val);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_pin_write(const dif_gpio_t *gpio, uint32_t index,
bool val) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
gpio_masked_bit_write(gpio, GPIO_MASKED_OUT_LOWER_REG_OFFSET,
GPIO_MASKED_OUT_UPPER_REG_OFFSET, index, val);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_masked_write(const dif_gpio_t *gpio, uint32_t mask,
uint32_t val) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
gpio_masked_write(gpio, GPIO_MASKED_OUT_LOWER_REG_OFFSET,
GPIO_MASKED_OUT_UPPER_REG_OFFSET, mask, val);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_output_mode_all_set(const dif_gpio_t *gpio,
uint32_t val) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
mmio_region_write32(gpio->base_addr, GPIO_DIRECT_OE_REG_OFFSET, val);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_output_mode_pin_set(const dif_gpio_t *gpio,
uint32_t index, bool val) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
gpio_masked_bit_write(gpio, GPIO_MASKED_OE_LOWER_REG_OFFSET,
GPIO_MASKED_OE_UPPER_REG_OFFSET, index, val);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_output_mode_masked_set(const dif_gpio_t *gpio,
uint32_t mask, uint32_t val) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
gpio_masked_write(gpio, GPIO_MASKED_OE_LOWER_REG_OFFSET,
GPIO_MASKED_OE_UPPER_REG_OFFSET, mask, val);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_irq_pin_test(const dif_gpio_t *gpio,
uint32_t index) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
mmio_region_write32(gpio->base_addr, GPIO_INTR_TEST_REG_OFFSET,
index_to_mask(index));
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_irq_all_read(const dif_gpio_t *gpio,
uint32_t *interrupt_states) {
if (gpio == NULL || interrupt_states == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
*interrupt_states =
mmio_region_read32(gpio->base_addr, GPIO_INTR_STATE_REG_OFFSET);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_irq_pin_read(const dif_gpio_t *gpio, uint32_t index,
bool *interrupt_state) {
if (gpio == NULL || interrupt_state == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
*interrupt_state =
mmio_region_get_bit32(gpio->base_addr, GPIO_INTR_STATE_REG_OFFSET, index);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_irq_pin_clear(const dif_gpio_t *gpio,
uint32_t index) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
mmio_region_write32(gpio->base_addr, GPIO_INTR_STATE_REG_OFFSET,
index_to_mask(index));
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_input_noise_filter_masked_enable(
const dif_gpio_t *gpio, uint32_t mask) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
mmio_region_nonatomic_set_mask32(
gpio->base_addr, GPIO_CTRL_EN_INPUT_FILTER_REG_OFFSET, mask, 0);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_input_noise_filter_masked_disable(
const dif_gpio_t *gpio, uint32_t mask) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
mmio_region_nonatomic_clear_mask32(
gpio->base_addr, GPIO_CTRL_EN_INPUT_FILTER_REG_OFFSET, mask, 0);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_irq_masked_enable(const dif_gpio_t *gpio,
uint32_t mask) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
mmio_region_nonatomic_set_mask32(gpio->base_addr, GPIO_INTR_ENABLE_REG_OFFSET,
mask, 0);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_irq_masked_disable(const dif_gpio_t *gpio,
uint32_t mask) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
mmio_region_nonatomic_clear_mask32(gpio->base_addr,
GPIO_INTR_ENABLE_REG_OFFSET, mask, 0);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_irq_trigger_masked_disable(const dif_gpio_t *gpio,
uint32_t mask) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
// Disable all interrupt triggers for the given mask
@@ -322,14 +322,14 @@
mmio_region_nonatomic_clear_mask32(
gpio->base_addr, GPIO_INTR_CTRL_EN_LVLLOW_REG_OFFSET, mask, 0);
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
dif_gpio_result_t dif_gpio_irq_trigger_masked_config(const dif_gpio_t *gpio,
uint32_t mask,
dif_gpio_irq_t config) {
if (gpio == NULL) {
- return kDifGpioResultInvalidArgument;
+ return kDifGpioBadArg;
}
// Disable all interrupt triggers for the given mask
@@ -371,8 +371,8 @@
gpio->base_addr, GPIO_INTR_CTRL_EN_LVLHIGH_REG_OFFSET, mask, 0);
break;
default:
- return kDifGpioResultGeneralError;
+ return kDifGpioError;
}
- return kDifGpioResultOK;
+ return kDifGpioOk;
}
diff --git a/sw/device/lib/dif/dif_gpio.h b/sw/device/lib/dif/dif_gpio.h
index 8d09ee7..8253703 100644
--- a/sw/device/lib/dif/dif_gpio.h
+++ b/sw/device/lib/dif/dif_gpio.h
@@ -25,15 +25,28 @@
/**
* Generic return codes for the functions in this library.
- *
- * `kDifGpioResultInvalidArgument` signals that there is a problem with the
- * argument(s) but the function did not have any side effects.
- * `kDifGpioResultGeneralError` covers other error cases.
*/
typedef enum dif_gpio_result {
- kDifGpioResultOK,
- kDifGpioResultInvalidArgument,
- kDifGpioResultGeneralError,
+ /**
+ * The function succeeded.
+ */
+ kDifGpioOk,
+ /**
+ * The function failed a non-specific assertion.
+ *
+ * This error is not recoverable.
+ */
+ kDifGpioError,
+ /**
+ * There is a problem with the argument(s) to the function.
+ *
+ * This return code is only returned before the function has any side effects.
+ *
+ * This error is recoverable and the operation can be retried after correcting
+ * the problem with the argument(s).
+ */
+ kDifGpioBadArg,
+
} dif_gpio_result_t;
/**
@@ -58,8 +71,8 @@
* @param config Configuration for initializing a GPIO device.
* @param gpio GPIO instance that will store the internal state of the
* initialized GPIO device.
- * @return `kDifGpioResultInvalidArgument` if `config` or `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `config` or `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_init(const dif_gpio_config_t *config,
dif_gpio_t *gpio);
@@ -71,8 +84,8 @@
* reset values. Disables interrupts, output, and input filter.
*
* @param gpio GPIO instance
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_reset(const dif_gpio_t *gpio);
@@ -85,8 +98,8 @@
*
* @param gpio GPIO instance.
* @param pin_values Pin values.
- * @return `kDifGpioResultInvalidArgument` if `gpio` or `pin_values` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` or `pin_values` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_all_read(const dif_gpio_t *gpio,
uint32_t *pin_values);
@@ -101,8 +114,8 @@
* @param gpio GPIO instance.
* @param index Zero-based index of the pin to read from.
* @param pin_value Pin value.
- * @return `kDifGpioResultInvalidArgument` if `gpio` or `pin_values` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` or `pin_values` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_pin_read(const dif_gpio_t *gpio, uint32_t index,
bool *pin_value);
@@ -114,8 +127,8 @@
*
* @param gpio GPIO instance.
* @param val Value to write.
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_all_write(const dif_gpio_t *gpio, uint32_t val);
@@ -127,8 +140,8 @@
* @param gpio GPIO instance.
* @param index Zero-based index of the pin to write to.
* @param val Value to write.
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_pin_write(const dif_gpio_t *gpio, uint32_t index,
bool val);
@@ -141,8 +154,8 @@
* @param gpio GPIO instance
* @param mask Mask that identifies the pins to write to.
* @param val Value to write.
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_masked_write(const dif_gpio_t *gpio, uint32_t mask,
uint32_t val);
@@ -154,8 +167,8 @@
*
* @param gpio GPIO instance.
* @param val Output modes of the pins.
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_output_mode_all_set(const dif_gpio_t *gpio,
uint32_t val);
@@ -168,8 +181,8 @@
* @param gpio GPIO instance
* @param index Zero-based index of the pin.
* @param val Output mode of the pin.
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_output_mode_pin_set(const dif_gpio_t *gpio,
uint32_t index, bool val);
@@ -182,8 +195,8 @@
* @param gpio GPIO instance
* @param mask Mask that identifies the pins whose output modes will be set.
* @param val Output modes of the pins.
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_output_mode_masked_set(const dif_gpio_t *gpio,
uint32_t mask, uint32_t val);
@@ -197,8 +210,8 @@
*
* @param gpio GPIO instance.
* @param index Zero-based index of the pin.
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_pin_test(const dif_gpio_t *gpio, uint32_t index);
@@ -207,8 +220,8 @@
*
* @param gpio GPIO instance.
* @param interrupt_states Interrupt states of all pins.
- * @return `kDifGpioResultInvalidArgument` if `gpio` or `interrupt_states` is
- * `NULL`, `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` or `interrupt_states` is
+ * `NULL`, `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_all_read(const dif_gpio_t *gpio,
uint32_t *interrupt_states);
@@ -220,8 +233,8 @@
* @param index Zero-based index of the pin.
* @param interrupt_state Interrupt state of the pin. True if there is a pending
* interrupt, false otherwise.
- * @return `kDifGpioResultInvalidArgument` if `gpio` or `interrupt_state` is
- * `NULL`, `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` or `interrupt_state` is
+ * `NULL`, `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_pin_read(const dif_gpio_t *gpio, uint32_t index,
bool *interrupt_state);
@@ -231,8 +244,8 @@
*
* @param gpio GPIO instance.
* @param index Zero-based index of the pin.
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_pin_clear(const dif_gpio_t *gpio,
uint32_t index);
@@ -246,8 +259,8 @@
* @param gpio GPIO instance.
* @param mask Mask that identifies the pins for which input noise filter will
* be enabled.
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_input_noise_filter_masked_enable(
const dif_gpio_t *gpio, uint32_t mask);
@@ -260,8 +273,8 @@
* @param gpio GPIO instance.
* @param mask Mask that identifies the pins for which input noise filter will
* be disabled.
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_input_noise_filter_masked_disable(
const dif_gpio_t *gpio, uint32_t mask);
@@ -277,8 +290,8 @@
* @param gpio GPIO instance.
* @param mask Mask that identifies the pins for which interrupts will be
* enabled.
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_masked_enable(const dif_gpio_t *gpio,
uint32_t mask);
@@ -291,8 +304,8 @@
* @param gpio GPIO instance.
* @param mask Mask that identifies the pins for which interrupts will be
* disabled.
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_masked_disable(const dif_gpio_t *gpio,
uint32_t mask);
@@ -306,8 +319,8 @@
* @param gpio GPIO instance.
* @param mask Mask that identifies the pins whose interrupt triggers will be
* disabled.
- * @return `kDifGpioResultInvalidArgument` if `gpio` is `NULL`,
- * `kDifGpioResultOK` otherwise.
+ * @return `kDifGpioBadArg` if `gpio` is `NULL`,
+ * `kDifGpioOk` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_trigger_masked_disable(const dif_gpio_t *gpio,
uint32_t mask);
@@ -323,8 +336,8 @@
* @param mask Mask that identifies the pins whose interrupt triggers will be
* configured.
* @param config New configuration of interrupt triggers.
- * @return `kDifGpioResultOK` if the function is successful,
- * `kDifGpioResultInvalidArgument` otherwise.
+ * @return `kDifGpioOk` if the function is successful,
+ * `kDifGpioBadArg` otherwise.
*/
dif_gpio_result_t dif_gpio_irq_trigger_masked_config(const dif_gpio_t *gpio,
uint32_t mask,
