From 9cc7148211db81341c24f4f3e79d1a6b58627933 Mon Sep 17 00:00:00 2001 From: David Sidrane Date: Fri, 15 Sep 2017 11:55:52 -1000 Subject: [PATCH] board_common:Documentation clean up merged --- src/drivers/boards/common/board_common.h | 356 ++++++++++++++++++----- 1 file changed, 291 insertions(+), 65 deletions(-) diff --git a/src/drivers/boards/common/board_common.h b/src/drivers/boards/common/board_common.h index e2c6fd0920..1c8667edd8 100644 --- a/src/drivers/boards/common/board_common.h +++ b/src/drivers/boards/common/board_common.h @@ -50,9 +50,10 @@ ************************************************************************************/ /* SPI bus defining tools + * * For new boards we use a board_config.h to define all the SPI functionality * A board provides SPI bus definitions and a set of buses that should be - * enumerated as well as chip selects that will be interatorable + * enumerated as well as chip selects that will be iterateable * * We will use these in macros place of the uint32_t enumeration to select a * specific SPI device on given SPI1 bus. @@ -84,7 +85,7 @@ * * The PX4_xxxx_BUS_FIRST_CS and PX4_xxxxx_BUS_LAST_CS * #define PX4_SENSORS_BUS_FIRST_CS PX4_SPIDEV_ICM_20689 - * #define PX4_SENSORS_BUS_LAST_CS PX4_SPIDEV_BMI055_ACCEL + * #define PX4_SENSORS_BUS_LAST_CS PX4_SPIDEV_BMI055_ACCEL * * */ @@ -146,8 +147,6 @@ /* Provide define for Bricks and Battery */ -/* Legacy default */ - /* Define the default maximum voltage resulting from the bias on ADC termination */ #if !defined(BOARD_ADC_OPEN_CIRCUIT_V) @@ -162,6 +161,8 @@ # define BOARD_VALID_UV (3.7f) #endif +/* Legacy default */ + #if !defined(BOARD_NUMBER_BRICKS) # define BOARD_NUMBER_BRICKS 1 # if !defined(BOARD_ADC_BRICK_VALID) @@ -279,26 +280,6 @@ # define HW_VER_FMUV2MINI HW_VER_SIMPLE(HW_VER_FMUV2MINI_STATE) #endif -/* Provide an interface for reading the connected state of VBUS */ - -/************************************************************************************ - * Name: board_read_VBUS_state - * - * Description: - * All boards must provide a way to read the state of VBUS, this my be simple - * digital input on a GPIO. Or something more complicated like a Analong input - * or reading a bit from a USB controller register. - * - * Returns - 0 if connected. - * - ************************************************************************************/ - -#if defined(GPIO_OTGFS_VBUS) -# define board_read_VBUS_state() (px4_arch_gpioread(GPIO_OTGFS_VBUS) ? 0 : 1) -#else -int board_read_VBUS_state(void); -#endif - /************************************************************************************ * Public Data ************************************************************************************/ @@ -330,7 +311,10 @@ typedef enum board_power_button_state_notification_e { typedef int (*power_button_state_notification_t)(board_power_button_state_notification_e request); -/* Defined the types used for board UUID and MFG UID + +/* UUID + * + * Define the types used for board UUID, MFG UID and PX4 GUID * * A type suitable for holding the byte format of the UUID * @@ -342,16 +326,39 @@ typedef int (*power_button_state_notification_t)(board_power_button_state_notifi * I was bit 95 and L was bit 64 * * Since the string was used by some manufactures to identify the units - * it must be preserved. + * it must be preserved. DEPRECATED - This will be removed in PX4 Release + * 1.7.0. * - * For new targets moving forward we will use - * IJKL EFGH ABCD + * For new targets moving forward we will use an 18 byte globally unique + * PX4 GUID in the form: + * + * [MNOP] IJKL EFGH ABCD + * + * Where are a monotonic ordinal number assigned by + * PX4 to a chip architecture (PX4_SOC_ARCH_ID). The 2 bytes are used to + * create a globally unique ID when prepended to a padded CPU UUID. + * + * In the case where the MFG UUID is shorter than 16 bytes it will be + * padded with 0's starting at offset [2] until + * PX4_GUID_BYTE_LENGTH-PX4_CPU_UUID_BYTE_LENGTH -1 + * + * I.E. For the STM32 + * offset:0 1 2 3 4 5 6 - 17 + * [0][0][0][0]... + * + * I.E. For the Kinetis + * offset:0 1 2 - 17 + * ... */ -/* A type suitable for defining the 8 bit format of the UUID */ +/* Define the PX4 Globally unique ID (GUID) length and format size */ +#define PX4_GUID_BYTE_LENGTH 18 +#define PX4_GUID_FORMAT_SIZE ((2*PX4_GUID_BYTE_LENGTH)+1) + +/* DEPRICATED as of 1.7.0 A type suitable for defining the 8 bit format of the CPU UUID */ typedef uint8_t uuid_byte_t[PX4_CPU_UUID_BYTE_LENGTH]; -/* A type suitable for defining the 32bit format of the UUID */ +/* DEPRICATED as of 1.7.0 A type suitable for defining the 32bit format of the CPU UUID */ typedef uint32_t uuid_uint32_t[PX4_CPU_UUID_WORD32_LENGTH]; /* A type suitable for defining the 8 bit format of the MFG UID @@ -359,6 +366,12 @@ typedef uint32_t uuid_uint32_t[PX4_CPU_UUID_WORD32_LENGTH]; */ typedef uint8_t mfguid_t[PX4_CPU_MFGUID_BYTE_LENGTH]; +/* A type suitable for defining the 8 bit format of the px4 globally unique + * PX4 GUID. This is always returned as MSD @ index 0 -LSD @ index + * PX4_CPU_GUID_BYTE_LENGTH-1 + */ +typedef uint8_t px4_guid_t[PX4_GUID_BYTE_LENGTH]; + /************************************************************************************ * Private Functions ************************************************************************************/ @@ -367,6 +380,30 @@ typedef uint8_t mfguid_t[PX4_CPU_MFGUID_BYTE_LENGTH]; * Public Functions ************************************************************************************/ +/* Provide an interface for reading the connected state of VBUS */ + +/************************************************************************************ + * Name: board_read_VBUS_state + * + * Description: + * All boards must provide a way to read the state of VBUS, this my be simple + * digital input on a GPIO. Or something more complicated like a Analong input + * or reading a bit from a USB controller register. + * + * Input Parameters: + * None + * + * Returned Value: + * 0 if connected. + * + ************************************************************************************/ + +#if defined(GPIO_OTGFS_VBUS) +# define board_read_VBUS_state() (px4_arch_gpioread(GPIO_OTGFS_VBUS) ? 0 : 1) +#else +int board_read_VBUS_state(void); +#endif + /************************************************************************************ * Name: board_dma_alloc_init * @@ -376,6 +413,13 @@ typedef uint8_t mfguid_t[PX4_CPU_MFGUID_BYTE_LENGTH]; * * Provision is controlled by declaring BOARD_DMA_ALLOC_POOL_SIZE in board_config.h * + * Input Parameters: + * None + * + * Returned Value: + * Zero (OK) is returned on success; a negated errno value is returned on failure + * EPERM - board does not support function + * ENOMEM - There is not enough memory to satisfy allocation. * ************************************************************************************/ #if defined(BOARD_DMA_ALLOC_POOL_SIZE) @@ -393,6 +437,15 @@ __EXPORT int board_dma_alloc_init(void); * * Provision is controlled by declaring BOARD_DMA_ALLOC_POOL_SIZE in board_config.h * + * Input Parameters: + * dma_total - A pointer to receive the total allocation size of the memory + * allocated with board_dma_alloc_init. It should be equal to + * BOARD_DMA_ALLOC_POOL_SIZE. + * dma_used - A pointer to receive the current allocation in use. + * dma_peak_used - A pointer to receive the peak allocation used. + * + * Returned Value: + * Zero (OK) is returned on success; * ************************************************************************************/ #if defined(BOARD_DMA_ALLOC_POOL_SIZE) @@ -406,9 +459,16 @@ __EXPORT int board_get_dma_usage(uint16_t *dma_total, uint16_t *dma_used, uint16 * * Description: * All boards my optionally provide this API to invert the Serial RC input. - * This is needed on SoCs that support the notion RXINV or TXINV as apposed to + * This is needed on SoCs that support the notion RXINV or TXINV as opposed to * and external XOR controlled by a GPIO * + * Input Parameters: + * invert_on - A positive logic value, that when true (on) will set the HW in + * inverted NRZ mode where a MARK will be 0 and SPACE will be a 1. + * + * Returned Value: + * None + * ************************************************************************************/ #if defined(INVERT_RC_INPUT) # if !defined(GPIO_SBUS_INV) @@ -422,9 +482,22 @@ __EXPORT void board_rc_input(bool invert_on); * Description: * Optionally provided function called on entry to board_system_reset * It should perform any house keeping prior to the rest. + * For example setting PWM outputs to the off state to avoid + * triggering a motor spin. * - * status - 1 if resetting to boot loader - * 0 if just resetting + * As a workaround for the bug seen on some ESC, the code will delay + * rebooting the flight controller to insure that the 3.2 ms pulse + * that occurs from the delay from reset to GPIO init due to memory + * initialization is pushed out from the last PWM by > 6 Ms. + * + * Input Parameters: + * status - 1 Resetting to boot loader + * 0 Just resetting CPU + * -1 used internally by board init to to initialize + * PWM IO pins with delay. + * + * Returned Value: + * None * ************************************************************************************/ @@ -440,6 +513,14 @@ __EXPORT void board_on_reset(int status); * Description: * All boards my optionally provide this API to reset the board * + * Input Parameters: + * status - 1 Resetting to boot loader + * 0 Just resetting CPU + * + * Returned Value: + * If function is supported by board it will not return. + * If not supported it is a noop. + * ************************************************************************************/ #if defined(BOARD_HAS_NO_RESET) # define board_system_reset(status) @@ -454,6 +535,18 @@ __EXPORT void board_system_reset(int status) noreturn_function; * All boards my optionally provide this API to enter configure the entry to * boot loader mode on the next system reset. * + * Input Parameters: + * mode - is an board_reset_e that controls the type of reset. + * board_reset_normal Perform a normal reset + * board_reset_extended Perform an extend reset as defined by board + * board_reset_power_off Reset to the boot loader, signaling a power off + * board_reset_enter_bootloader Perform a reset to the boot loader + * + * + * Returned Value: + * Zero (OK) is returned on success; a negated EINVAL value is returned if an + * invalid mode is requested. + * ************************************************************************************/ #if defined(BOARD_HAS_NO_BOOTLOADER) @@ -466,8 +559,13 @@ __EXPORT int board_set_bootload_mode(board_reset_e mode); * Name: board_get_hw_type * * Description: - * Optional returns a string defining the HW type + * Optional returns a 0 terminated string defining the HW type. * + * Input Parameters: + * None + * + * Returned Value: + * a 0 terminated string defining the HW type. This my be a 0 length string "" * ************************************************************************************/ @@ -483,6 +581,13 @@ __EXPORT const char *board_get_hw_type_name(void); * Description: * Optional returns a integer HW version * + * Input Parameters: + * None + * + * Returned Value: + * An integer value of this boards hardware version. + * A value of 0 is the default for boards not supporting the BOARD_HAS_VERSIONING API. + * A value of -1 is the default for boards supporting the API but not having version. * ************************************************************************************/ @@ -498,6 +603,13 @@ __EXPORT int board_get_hw_version(void); * Description: * Optional returns a integer HW revision * + * Input Parameters: + * None + * + * Returned Value: + * An integer value of this boards hardware revision. + * A value of 0 is the default for boards not supporting the BOARD_HAS_VERSIONING API. + * A value of -1 is the default for boards supporting the API but not having revision. * ************************************************************************************/ @@ -509,57 +621,80 @@ __EXPORT int board_get_hw_revision(void); #if !defined(BOARD_OVERRIDE_UUID) /************************************************************************************ - * Name: board_get_uuid + * Name: board_get_uuid DEPRICATED use board_get_px4_guid * * Description: * All boards either provide a way to read a uuid of PX4_CPU_UUID_BYTE_LENGTH * from PX4_CPU_UUID_ADDRESS in the SoC's address space OR define * BOARD_OVERRIDE_UUID as an array of bytes that is PX4_CPU_UUID_BYTE_LENGTH * + * Input Parameters: + * uuid_bytes - uuid_byte_t and array of bytes PX4_CPU_UUID_BYTE_LENGTH in length. + * + * Returned Value: + * The uuid_bytes array is populated with the CPU uuid in the legacy format for + * STM32. + * ************************************************************************************/ -__EXPORT void board_get_uuid(uuid_byte_t uuid_bytes); + +__EXPORT void board_get_uuid(uuid_byte_t uuid_bytes); // DEPRICATED use board_get_px4_guid /************************************************************************************ - * Name: board_get_uuid32 + * Name: board_get_uuid32 DEPRICATED use board_get_px4_guid * * Description: * All boards either provide a way to read a uuid of PX4_CPU_UUID_WORD32_LENGTH * from PX4_CPU_UUID_ADDRESS in the Soc's address space OR define * BOARD_OVERRIDE_UUID as an array of bytes that is PX4_CPU_UUID_BYTE_LENGTH - * On Legacy (stm32) targets the raw32 format is the result of coping returning - * the 32bit words from low memory to high memory. On new targets the result + * On Legacy (stm32) targets the uuid_words format is the result of coping + * returning the 32bit words from low memory to high memory. On new targets the result * will be an array of words with the MSW at index 0 and the LSW: at index * PX4_CPU_UUID_WORD32_LENGTH-1. * - * The ordering can optionally be set by defining - * PX4_CPU_UUID_WORD32_FORMAT_ORDER + * Input Parameters: + * uuid_words - a uuid_uint32_t and array of 32 bit words PX4_CPU_UUID_WORD32_ + * LENGTH in length. + * + * Returned Value: + * The uuid_words array is populated with the CPU uuid. * ************************************************************************************/ -__EXPORT void board_get_uuid32(uuid_uint32_t uuid_words); +__EXPORT void board_get_uuid32(uuid_uint32_t uuid_words); // DEPRICATED use board_get_px4_guid /************************************************************************************ - * Name: board_get_uuid32_formated + * Name: board_get_uuid32_formated DEPRICATED use board_get_px4_guid_formated * * Description: * All boards either provide a way to retrieve a uuid and format it * or define BOARD_OVERRIDE_UUID - * The format can optionally be reordered if PX4_CPU_UUID_WORD32_FORMAT_ORDER is - * defined and printed with the optional separator + * This function is used to populate a buffer with the UUID to be a printed + * with the optional separator * - * With seperator = ":" - * 31-00:63-32:95-64 - * 32383336:412038:33355110 - * With seperator = " " - * 31-00:63-32:95-64 - * 32383336 412038 33355110 - * With seperator = NULL - * 31-00:63-32:95-64 - * 3238333641203833355110 + * Input Parameters: + * format_buffer - A pointer to a bufferer of at least PX4_CPU_UUID_WORD32_FORMAT_SIZE + * that will contain a 0 terminated string formated as described + * the format string and optional separator. + * size - The size of the buffer (should be atleaset PX4_CPU_UUID_WORD32_FORMAT_SIZE) + * format - The fort mat specifier for the hex digit see CPU_UUID_FORMAT + * separator - Optional pointer to a 0 terminated string or NULL: + * With separator = ":" + * 31-00:63-32:95-64 + * 32383336:412038:33355110 + * With separator = " " + * 31-00:63-32:95-64 + * 32383336 412038 33355110 + * With separator = NULL + * 31-00:63-32:95-64 + * 3238333641203833355110 + * + * Returned Value: + * The format buffer is populated with a 0 terminated string formated as described. + * Zero (OK) is returned on success; * ************************************************************************************/ __EXPORT int board_get_uuid32_formated(char *format_buffer, int size, const char *format, - const char *seperator); + const char *seperator); // DEPRICATED use board_get_px4_guid_formated #endif // !defined(BOARD_OVERRIDE_UUID) #if !defined(BOARD_OVERRIDE_MFGUID) @@ -567,26 +702,106 @@ __EXPORT int board_get_uuid32_formated(char *format_buffer, int size, * Name: board_get_mfguid * * Description: - * All boards either provide a way to retrieve a manafactuers Uniqe ID or + * All boards either provide a way to retrieve a manufactures Unique ID or * define BOARD_OVERRIDE_MFGUID. * The MFGUID is returned as an array of bytes in * MSD @ index 0 - LSD @ index PX4_CPU_MFGUID_BYTE_LENGTH-1 * + * Input Parameters: + * mfgid - mfguid_t and array of bytes PX4_CPU_MFGUID_BYTE_LENGTH in length. + * + * Returned Value: + * The mfguid_t array is populated with the CPU uuid with the MSD @ index 0 + * and the LSD @ index PX4_CPU_MFGUID_BYTE_LENGTH-1. + * ************************************************************************************/ int board_get_mfguid(mfguid_t mfgid); +/************************************************************************************ + * Name: board_get_mfguid_formated DEPRICATED use board_get_px4_guid_formated + * + * Description: + * All boards either provide a way to retrieve a formatted string of the + * manufactures unique ID or define BOARD_OVERRIDE_MFGUID + * + * Input Parameters: + * format_buffer - A pointer to a bufferer of at least PX4_CPU_MFGUID_FORMAT_SIZE + * that will contain a 0 terminated string formated as 0 prefixed + * lowercase hex. 2 charaters per digit of the mfguid_t. + * + * Returned Value: + * format_buffer is populated with a 0 terminated string of hex digits. The + * return value is the number of printable in the string. + * Usually PX4_CPU_MFGUID_FORMAT_SIZE-1 + * + ************************************************************************************/ + +int board_get_mfguid_formated(char *format_buffer, int size); // DEPRICATED use board_get_px4_guid_formated +#endif // !defined(BOARD_OVERRIDE_MFGUID) + +#if !defined(BOARD_OVERRIDE_PX4_GUID) +/************************************************************************************ + * Name: board_get_px4_guid + * + * Description: + * All boards either provide a way to retrieve a PX4 Globally unique ID or + * define BOARD_OVERRIDE_PX4_GUID. + * + * The form of the GUID is as follows: + * offset:0 1 2 - 17 + * ... + * + * Where are a monotonic ordinal number assigned by + * PX4 to a chip architecture (PX4_SOC_ARCH_ID). The 2 bytes are used to + * create a globally unique ID when prepended to a padded CPU ID. + * + * In the case where the CPU's UUID is shorter than 16 bytes it will be + * padded with 0's starting at offset [2] until + * PX4_CPU_MFGUID_BYTE_LENGTH-PX4_CPU_UUID_BYTE_LENGTH -1 + * I.E. For the STM32 + * offset:0 1 2 3 4 5 6 - 17 + * [0][0][0][0]... + * + * I.E. For as CPU with a 16 byte UUID + * offset:0 1 2 - 17 + * ... + * + * Input Parameters: + * guid - a px4_guid_t which is byte array of PX4_GUID_BYTE_LENGTH length. + * + * Returned Value: + * guid is populated as ... + * the return value is PX4_GUID_BYTE_LENGTH + * + ************************************************************************************/ + +int board_get_px4_guid(px4_guid_t guid); + /************************************************************************************ * Name: board_get_mfguid_formated * * Description: * All boards either provide a way to retrieve a formatted string of the - * manafactuers Uniqe ID or define BOARD_OVERRIDE_MFGUID + * manufactures Unique ID or define BOARD_OVERRIDE_PX4_GUID + * + * Input Parameters: + * format_buffer - A buffer to receive the 0 terminated formated px4 + * guid string. + * size - Size of the buffer provided. Normally this would + * be PX4_GUID_FORMAT_SIZE. + * If the size is less than PX4_GUID_FORMAT_SIZE the string + * returned will be truncated from the MSD end and even + * in length. + * + * Returned Value: + * The number of printable characters. This value will be even and one less the + * the size passed in. * ************************************************************************************/ -int board_get_mfguid_formated(char *format_buffer, int size); -#endif // !defined(BOARD_OVERRIDE_MFGUID) +int board_get_px4_guid_formated(char *format_buffer, int size); +#endif // !defined(BOARD_OVERRIDE_PX4_GUID) /************************************************************************************ * Name: board_mcu_version @@ -595,11 +810,13 @@ int board_get_mfguid_formated(char *format_buffer, int size); * All boards either provide a way to retrieve the cpu revision * Or define BOARD_OVERRIDE_CPU_VERSION * + * Input Parameters: * rev - The silicon revision character * revstr - The full chip name string * errata -The eratta if any. * - * return - The silicon revision / version number as integer + * Returned Value: + * The silicon revision / version number as integer * or -1 on error and rev, revstr and errata will * not be set */ @@ -620,9 +837,11 @@ __EXPORT int board_mcu_version(char *rev, const char **revstr, const char **erra * N.B. this call back may be called off an interrupt. Do not attempt to block * or run any long threads. * - * cb - A pointer to a power button state notification function. + * Input Parameters: + * cb - A pointer to a power button state notification function. * - * return - OK + * Returned Value: + * Zero (OK) is returned on success; */ int board_register_power_state_notification_cb(power_button_state_notification_t cb); @@ -633,7 +852,11 @@ int board_register_power_state_notification_cb(power_button_state_notification_t * Description: * boards may provide a function to power off the board. * - * return - OK, or -errno + * Input Parameters: + * None. + * Returned Value: + * - If supported the function will not return. + * OK, or -EINVAL if unsupported. */ int board_shutdown(void); @@ -648,10 +871,13 @@ static inline int board_shutdown(void) { return -EINVAL; } * Description: * Board may provide a list of GPI pins to get initialized * + * Input Parameters: * list - A list of GPIO pins to be initialized * count - Size of the list * - * return - Nothing - ************************************************************************************/ + * Returned Value: + * Nothing + * + ************************************************************************************/ __EXPORT void board_gpio_init(const uint32_t list[], int count);