From 48026bb824fd2d9cfb00ecd040db6ef3a416bae9 Mon Sep 17 00:00:00 2001 From: Clyne Sullivan Date: Fri, 22 Jan 2021 21:43:36 -0500 Subject: upload initial port --- ChibiOS_20.3.2/os/hal/dox/hal.dox | 32 +++++ ChibiOS_20.3.2/os/hal/dox/hal_adc.dox | 141 +++++++++++++++++++ ChibiOS_20.3.2/os/hal/dox/hal_buffers.dox | 20 +++ ChibiOS_20.3.2/os/hal/dox/hal_can.dox | 87 ++++++++++++ ChibiOS_20.3.2/os/hal/dox/hal_crypto.dox | 25 ++++ ChibiOS_20.3.2/os/hal/dox/hal_dac.dox | 26 ++++ ChibiOS_20.3.2/os/hal/dox/hal_efl.dox | 25 ++++ ChibiOS_20.3.2/os/hal/dox/hal_flash.dox | 52 +++++++ ChibiOS_20.3.2/os/hal/dox/hal_gpt.dox | 74 ++++++++++ ChibiOS_20.3.2/os/hal/dox/hal_i2c.dox | 98 +++++++++++++ ChibiOS_20.3.2/os/hal/dox/hal_i2s.dox | 27 ++++ ChibiOS_20.3.2/os/hal/dox/hal_icu.dox | 107 ++++++++++++++ ChibiOS_20.3.2/os/hal/dox/hal_interfaces.dox | 60 ++++++++ ChibiOS_20.3.2/os/hal/dox/hal_ioblock.dox | 100 +++++++++++++ ChibiOS_20.3.2/os/hal/dox/hal_mac.dox | 26 ++++ ChibiOS_20.3.2/os/hal/dox/hal_mfs.dox | 30 ++++ ChibiOS_20.3.2/os/hal/dox/hal_mii.dox | 23 +++ ChibiOS_20.3.2/os/hal/dox/hal_mmc_spi.dox | 35 +++++ ChibiOS_20.3.2/os/hal/dox/hal_mmcsd.dox | 24 ++++ ChibiOS_20.3.2/os/hal/dox/hal_norflash.dox | 54 +++++++ ChibiOS_20.3.2/os/hal/dox/hal_objects.dox | 20 +++ ChibiOS_20.3.2/os/hal/dox/hal_pal.dox | 70 +++++++++ ChibiOS_20.3.2/os/hal/dox/hal_peripherals.dox | 22 +++ ChibiOS_20.3.2/os/hal/dox/hal_pwm.dox | 65 +++++++++ ChibiOS_20.3.2/os/hal/dox/hal_queues.dox | 20 +++ ChibiOS_20.3.2/os/hal/dox/hal_rtc.dox | 26 ++++ ChibiOS_20.3.2/os/hal/dox/hal_sdc.dox | 33 +++++ ChibiOS_20.3.2/os/hal/dox/hal_serial.dox | 57 ++++++++ ChibiOS_20.3.2/os/hal/dox/hal_serial_usb.dox | 52 +++++++ ChibiOS_20.3.2/os/hal/dox/hal_sio.dox | 58 ++++++++ ChibiOS_20.3.2/os/hal/dox/hal_spi.dox | 90 ++++++++++++ ChibiOS_20.3.2/os/hal/dox/hal_st.dox | 24 ++++ ChibiOS_20.3.2/os/hal/dox/hal_trng.dox | 25 ++++ ChibiOS_20.3.2/os/hal/dox/hal_uart.dox | 117 ++++++++++++++++ ChibiOS_20.3.2/os/hal/dox/hal_usb.dox | 180 ++++++++++++++++++++++++ ChibiOS_20.3.2/os/hal/dox/hal_usb_cdc.dox | 23 +++ ChibiOS_20.3.2/os/hal/dox/hal_wdg.dox | 26 ++++ ChibiOS_20.3.2/os/hal/dox/hal_wspi.dox | 26 ++++ ChibiOS_20.3.2/os/hal/dox/main.dox | 195 ++++++++++++++++++++++++++ 39 files changed, 2195 insertions(+) create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_adc.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_buffers.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_can.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_crypto.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_dac.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_efl.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_flash.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_gpt.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_i2c.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_i2s.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_icu.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_interfaces.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_ioblock.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_mac.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_mfs.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_mii.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_mmc_spi.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_mmcsd.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_norflash.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_objects.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_pal.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_peripherals.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_pwm.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_queues.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_rtc.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_sdc.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_serial.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_serial_usb.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_sio.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_spi.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_st.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_trng.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_uart.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_usb.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_usb_cdc.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/hal_wdg.dox create mode 100755 ChibiOS_20.3.2/os/hal/dox/hal_wspi.dox create mode 100644 ChibiOS_20.3.2/os/hal/dox/main.dox (limited to 'ChibiOS_20.3.2/os/hal/dox') diff --git a/ChibiOS_20.3.2/os/hal/dox/hal.dox b/ChibiOS_20.3.2/os/hal/dox/hal.dox new file mode 100644 index 0000000..5c1ac3d --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal.dox @@ -0,0 +1,32 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup HAL HAL Driver + * @brief Hardware Abstraction Layer. + * @details The HAL (Hardware Abstraction Layer) driver performs the system + * initialization and includes the platform support code shared by + * the other drivers. This driver does contain any API function + * except for a general initialization function @p halInit() that + * must be invoked before any HAL service can be used, usually the + * HAL initialization should be performed immediately before the + * kernel initialization.
+ * Some HAL driver implementations also offer a custom early clock + * setup function that can be invoked before the C runtime + * initialization in order to accelerate the startup time. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_adc.dox b/ChibiOS_20.3.2/os/hal/dox/hal_adc.dox new file mode 100644 index 0000000..c80a0b4 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_adc.dox @@ -0,0 +1,141 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup ADC ADC Driver + * @brief Generic ADC Driver. + * @details This module implements a generic ADC (Analog to Digital Converter) + * driver supporting a variety of buffer and conversion modes. + * @pre In order to use the ADC driver the @p HAL_USE_ADC option + * must be enabled in @p halconf.h. + * + * @section adc_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @if LATEX_PDF + * @dot + digraph example { + rankdir="LR"; + size="5, 7"; + + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="ADC_STOP\nLow Power"]; + uninit [label="ADC_UNINIT", style="bold"]; + ready [label="ADC_READY\nClock Enabled"]; + active [label="ADC_ACTIVE\nConverting"]; + error [label="ADC_ERROR\nError"]; + complete [label="ADC_COMPLETE\nComplete"]; + + uninit -> stop [label="\n adcInit()", constraint=false]; + stop -> ready [label="\nadcStart()"]; + ready -> ready [label="\nadcStart()\nadcStopConversion()"]; + ready -> stop [label="\nadcStop()"]; + stop -> stop [label="\nadcStop()"]; + ready -> active [label="\nadcStartConversion() (async)\nadcConvert() (sync)"]; + active -> ready [label="\nadcStopConversion()\nsync return"]; + active -> active [label="\nasync callback (half buffer, circular)\nasync callback (full buffer)\n>acg_endcb<"]; + active -> complete [label="\n\nasync callback (full buffer)\n>end_cb<"]; + active -> error [label="\n\nasync callback (error)\n>error_cb<"]; + complete -> active [label="\nadcStartConversionI()\nthen\ncallback return"]; + complete -> ready [label="\ncallback return"]; + error -> active [label="\nadcStartConversionI()\nthen\ncallback return"]; + error -> ready [label="\ncallback return"]; + } + * @enddot + * @else + * @dot + digraph example { + rankdir="LR"; + + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="ADC_STOP\nLow Power"]; + uninit [label="ADC_UNINIT", style="bold"]; + ready [label="ADC_READY\nClock Enabled"]; + active [label="ADC_ACTIVE\nConverting"]; + error [label="ADC_ERROR\nError"]; + complete [label="ADC_COMPLETE\nComplete"]; + + uninit -> stop [label="\n adcInit()", constraint=false]; + stop -> ready [label="\nadcStart()"]; + ready -> ready [label="\nadcStart()\nadcStopConversion()"]; + ready -> stop [label="\nadcStop()"]; + stop -> stop [label="\nadcStop()"]; + ready -> active [label="\nadcStartConversion() (async)\nadcConvert() (sync)"]; + active -> ready [label="\nadcStopConversion()\nsync return"]; + active -> active [label="\nasync callback (half buffer, circular)\nasync callback (full buffer)\n>acg_endcb<"]; + active -> complete [label="\n\nasync callback (full buffer)\n>end_cb<"]; + active -> error [label="\n\nasync callback (error)\n>error_cb<"]; + complete -> active [label="\nadcStartConversionI()\nthen\ncallback return"]; + complete -> ready [label="\ncallback return"]; + error -> active [label="\nadcStartConversionI()\nthen\ncallback return"]; + error -> ready [label="\ncallback return"]; + } + * @enddot + * @endif + * + * @section adc_2 ADC Operations + * The ADC driver is quite complex, an explanation of the terminology and of + * the operational details follows. + * + * @subsection adc_2_1 ADC Conversion Groups + * The @p ADCConversionGroup is the objects that specifies a physical + * conversion operation. This structure contains some standard fields and + * several implementation-dependent fields.
+ * The standard fields define the CG mode, the number of channels belonging + * to the CG and the optional callbacks.
+ * The implementation-dependent fields specify the physical ADC operation + * mode, the analog channels belonging to the group and any other + * implementation-specific setting. Usually the extra fields just mirror + * the physical ADC registers, please refer to the vendor's MCU Reference + * Manual for details about the available settings. Details are also available + * into the documentation of the ADC low level drivers and in the various + * sample applications. + * + * @subsection adc_2_2 ADC Conversion Modes + * The driver supports several conversion modes: + * - One Shot, the driver performs a single group conversion then stops. + * - Linear Buffer, the driver performs a series of group conversions + * then stops. This mode is like a one shot conversion repeated N times, + * the buffer pointer increases after each conversion. The buffer is + * organized as an S(CG)*N samples matrix, when S(CG) is the conversion + * group size (number of channels) and N is the buffer depth (number of + * repeated conversions). + * - Circular Buffer, much like the linear mode but the operation does + * not stop when the buffer is filled, it is automatically restarted + * with the buffer pointer wrapping back to the buffer base. + * . + * @subsection adc_2_3 ADC Callbacks + * The driver is able to invoke callbacks during the conversion process. A + * callback is invoked when the operation has been completed or, in circular + * mode, when the buffer has been filled and the operation is restarted. In + * circular mode a callback is also invoked when the buffer is half filled.
+ * The "half filled" and "filled" callbacks in circular mode allow to + * implement "streaming processing" of the sampled data, while the driver is + * busy filling one half of the buffer the application can process the + * other half, this allows for continuous interleaved operations. + * + * The driver is not thread safe for performance reasons, if you need to access + * the ADC bus from multiple threads then use the @p adcAcquireBus() and + * @p adcReleaseBus() APIs in order to gain exclusive access. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_buffers.dox b/ChibiOS_20.3.2/os/hal/dox/hal_buffers.dox new file mode 100644 index 0000000..c5da714 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_buffers.dox @@ -0,0 +1,20 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup HAL_BUFFERS I/O Buffers Queues + * @ingroup HAL_INNER_CODE + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_can.dox b/ChibiOS_20.3.2/os/hal/dox/hal_can.dox new file mode 100644 index 0000000..5dd8104 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_can.dox @@ -0,0 +1,87 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup CAN CAN Driver + * @brief Generic CAN Driver. + * @details This module implements a generic CAN (Controller Area Network) + * driver allowing the exchange of information at frame level. + * @pre In order to use the CAN driver the @p HAL_USE_CAN option + * must be enabled in @p halconf.h. + * + * @section can_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @if LATEX_PDF + * @dot + digraph example { + size="5, 7"; + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="CAN_STOP\nLow Power"]; + uninit [label="CAN_UNINIT", style="bold"]; + starting [label="CAN_STARTING\nInitializing"]; + ready [label="CAN_READY\nClock Enabled"]; + sleep [label="CAN_SLEEP\nLow Power"]; + + uninit -> stop [label=" canInit()", constraint=false]; + stop -> stop [label="\ncanStop()"]; + stop -> ready [label="\ncanStart()\n(fast implementation)"]; + stop -> starting [label="\ncanStart()\n(slow implementation)"]; + starting -> ready [label="\ninitialization complete\n(all threads)"]; + ready -> stop [label="\ncanStop()"]; + ready -> ready [label="\ncanReceive()\ncanTransmit()"]; + ready -> sleep [label="\ncanSleep()"]; + sleep -> sleep [label="\ncanSleep()"]; + sleep -> ready [label="\ncanWakeup()"]; + sleep -> ready [label="\nhardware\nwakeup event"]; + } + * @enddot + * @else + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="CAN_STOP\nLow Power"]; + uninit [label="CAN_UNINIT", style="bold"]; + starting [label="CAN_STARTING\nInitializing"]; + ready [label="CAN_READY\nClock Enabled"]; + sleep [label="CAN_SLEEP\nLow Power"]; + + uninit -> stop [label=" canInit()", constraint=false]; + stop -> stop [label="\ncanStop()"]; + stop -> ready [label="\ncanStart()\n(fast implementation)"]; + stop -> starting [label="\ncanStart()\n(slow implementation)"]; + starting -> starting [label="\ncanStart()\n(other thread)"]; + starting -> ready [label="\ninitialization complete\n(all threads)"]; + ready -> stop [label="\ncanStop()"]; + ready -> ready [label="\ncanStart()\ncanReceive()\ncanTransmit()"]; + ready -> sleep [label="\ncanSleep()"]; + sleep -> sleep [label="\ncanSleep()"]; + sleep -> ready [label="\ncanWakeup()"]; + sleep -> ready [label="\nhardware\nwakeup event"]; + } + * @enddot + * @endif + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_crypto.dox b/ChibiOS_20.3.2/os/hal/dox/hal_crypto.dox new file mode 100644 index 0000000..b9ad2b1 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_crypto.dox @@ -0,0 +1,25 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup CRYPTO Crypto Driver + * @brief Generic Crypto Driver. + * @details This module implements a generic Cryptography driver. + * @pre In order to use the crypto driver the @p HAL_USE_CRY option + * must be enabled in @p halconf.h. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_dac.dox b/ChibiOS_20.3.2/os/hal/dox/hal_dac.dox new file mode 100644 index 0000000..381e201 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_dac.dox @@ -0,0 +1,26 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup DAC DAC Driver + * @brief Generic DAC Driver. + * @details This module implements a generic DAC (Digital to Analog Converter) + * driver. + * @pre In order to use the DAC driver the @p HAL_USE_DAC option + * must be enabled in @p halconf.h. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_efl.dox b/ChibiOS_20.3.2/os/hal/dox/hal_efl.dox new file mode 100644 index 0000000..02d8471 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_efl.dox @@ -0,0 +1,25 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup HAL_EFL EFL Driver + * @brief Generic Embedded Flash Driver. + * @details This module implements a generic embedded flash driver. + * @pre In order to use the EFL driver the @p HAL_USE_EFL option + * must be enabled in @p halconf.h. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_flash.dox b/ChibiOS_20.3.2/os/hal/dox/hal_flash.dox new file mode 100644 index 0000000..7488944 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_flash.dox @@ -0,0 +1,52 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup HAL_FLASH Generic Flash Interface + * @brief HAL Generic Flash Driver Interface. + * + * @section flash_1 Driver State Machine + * The flash driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + stop [label="FLS_STOP\nLow Power"]; + uninit [label="FLS_UNINIT", style="bold"]; + ready [label="FLS_READY\nClock Enabled"]; + read [label="FLS_READ\nReading"]; + pgm [label="FLS_PGM\nProgramming"]; + erase [label="FLS_ERASE\nErasing"]; + uninit -> stop [label=" xxxInit()", constraint=false]; + stop -> stop [label=" xxxStop()"]; + stop -> ready [label=" xxxStart()"]; + ready -> stop [label=" xStop()"]; + ready -> read [label=" flashRead()\nflashVerifyErase()"]; + read -> ready [label=" return"]; + ready -> pgm [label=" flashProgram()"]; + pgm -> ready [label=" return"]; + ready -> erase [label=" \n\nflashEraseAll()\nflashEraseSector()"]; + erase -> ready [label=" flashQueryErase()\nFLASH_NO_ERROR\nFLASH_ERROR_*"]; + erase -> erase [label=" flashQueryErase()\nflashProgram()\nflashRead()\nFLASH_BUSY_ERASING"]; + } + * @enddot + * + * @ingroup HAL_ABSTRACT_PERIPHERALS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_gpt.dox b/ChibiOS_20.3.2/os/hal/dox/hal_gpt.dox new file mode 100644 index 0000000..d75dab2 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_gpt.dox @@ -0,0 +1,74 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup GPT GPT Driver + * @brief Generic GPT Driver. + * @details This module implements a generic GPT (General Purpose Timer) + * driver. The timer can be programmed in order to trigger callbacks + * after a specified time period or continuously with a specified + * interval. + * @pre In order to use the GPT driver the @p HAL_USE_GPT option + * must be enabled in @p halconf.h. + * + * @section gpt_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", + width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="GPT_STOP\nLow Power"]; + uninit [label="GPT_UNINIT", style="bold"]; + ready [label="GPT_READY\nClock Enabled"]; + continuous [label="GPT_CONT..S\nContinuous\nMode"]; + oneshot [label="GPT_ONESHOT\nOne Shot\nMode"]; + + uninit -> stop [label=" gptInit()", constraint=false]; + stop -> stop [label="\ngptStop()"]; + stop -> ready [label="\ngptStart()"]; + ready -> stop [label="\ngptStop()"]; + ready -> ready [label="\ngptStart()"]; + ready -> continuous [label="\ngptStartContinuous()"]; + continuous -> ready [label="\ngptStopTimer()"]; + continuous -> continuous [label=">callback<"]; + ready -> oneshot [label="\ngptStartOneShot()\ngptPolledDelay()"]; + oneshot -> ready [label="\n>callback<\nor\nDelay Over"]; + } + * @enddot + * + * @section gpt_2 GPT Operations. + * This driver abstracts a generic timer composed of: + * - A clock prescaler. + * - A main up counter. + * - A comparator register that resets the main counter to zero when the limit + * is reached. A callback is invoked when this happens. + * . + * The timer can operate in three different modes: + * - Continuous Mode, a periodic callback is invoked until the driver + * is explicitly stopped. + * - One Shot Mode, a callback is invoked after the programmed period + * and then the timer automatically stops. + * - Delay Mode, the timer is used for inserting a brief delay into + * the execution flow, no callback is invoked in this mode. + * . + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_i2c.dox b/ChibiOS_20.3.2/os/hal/dox/hal_i2c.dox new file mode 100644 index 0000000..c5a39f3 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_i2c.dox @@ -0,0 +1,98 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup I2C I2C Driver + * @brief Generic I2C Driver. + * @details This module implements a generic I2C (Inter-Integrated Circuit) + * driver. + * @pre In order to use the I2C driver the @p HAL_USE_I2C option + * must be enabled in @p halconf.h. + * + * @section i2c_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @if LATEX_PDF + * @dot + digraph example { + size="5, 7"; + rankdir="LR"; + + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", + width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="I2C_STOP\nLow Power"]; + uninit [label="I2C_UNINIT", style="bold"]; + ready [label="I2C_READY\nClock Enabled"]; + active_tx [label="I2C_ACTIVE_TX\nBus TX Active"]; + active_rx [label="I2C_ACTIVE_RX\nBus RX Active"]; + locked [label="I2C_LOCKED\nBus Locked"]; + + uninit -> stop [label="i2cInit()", constraint=false]; + stop -> stop [label="i2cStop()"]; + stop -> ready [label="i2cStart()"]; + ready -> ready [label="i2cStart()"]; + ready -> stop [label="i2cStop()"]; + ready -> active_tx [label="i2cMasterTransmit()"]; + ready -> active_rx [label="i2cMasterReceive()"]; + active_tx -> ready [label="completed"]; + active_rx -> ready [label="completed"]; + active_tx -> locked [label="RDY_TIMEOUT"]; + active_rx -> locked [label="RDY_TIMEOUT"]; + locked -> stop [label="i2cStop()"]; + locked -> ready [label="i2cStart()"]; + } + * @else + * @dot + digraph example { + rankdir="LR"; + + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", + width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="I2C_STOP\nLow Power"]; + uninit [label="I2C_UNINIT", style="bold"]; + ready [label="I2C_READY\nClock Enabled"]; + active_tx [label="I2C_ACTIVE_TX\nBus TX Active"]; + active_rx [label="I2C_ACTIVE_RX\nBus RX Active"]; + locked [label="I2C_LOCKED\nBus Locked"]; + + uninit -> stop [label="i2cInit()", constraint=false]; + stop -> stop [label="i2cStop()"]; + stop -> ready [label="i2cStart()"]; + ready -> ready [label="i2cStart()"]; + ready -> stop [label="i2cStop()"]; + ready -> active_tx [label="i2cMasterTransmit()"]; + ready -> active_rx [label="i2cMasterReceive()"]; + active_tx -> ready [label="completed"]; + active_rx -> ready [label="completed"]; + active_tx -> locked [label="RDY_TIMEOUT"]; + active_rx -> locked [label="RDY_TIMEOUT"]; + locked -> stop [label="i2cStop()"]; + locked -> ready [label="i2cStart()"]; + } + * @enddot + * @endif + * The driver is not thread safe for performance reasons, if you need to access + * the I2C bus from multiple threads then use the @p i2cAcquireBus() and + * @p i2cReleaseBus() APIs in order to gain exclusive access. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_i2s.dox b/ChibiOS_20.3.2/os/hal/dox/hal_i2s.dox new file mode 100644 index 0000000..629b5e9 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_i2s.dox @@ -0,0 +1,27 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup I2S I2S Driver + * @brief Generic I2S Driver. + * @details This module implements a generic I2S driver. + * @pre In order to use the I2S driver the @p HAL_USE_I2S option + * must be enabled in @p halconf.h. + * + * @section i2s_1 Driver State Machine + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_icu.dox b/ChibiOS_20.3.2/os/hal/dox/hal_icu.dox new file mode 100644 index 0000000..710c388 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_icu.dox @@ -0,0 +1,107 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup ICU ICU Driver + * @brief Generic ICU Driver. + * @details This module implements a generic ICU (Input Capture Unit) driver. + * The purpose of the driver is to measure period and duty cycle of + * an input digital signal (PWM input). + * @pre In order to use the ICU driver the @p HAL_USE_ICU option + * must be enabled in @p halconf.h. + * + * @section icu_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @if LATEX_PDF + * @dot + digraph example { + size="5, 7"; + rankdir="LR"; + + node [shape=circle, fontname=Sans, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Sans, fontsize=8]; + + stop [label="ICU_STOP\nLow Power"]; + uninit [label="ICU_UNINIT", style="bold"]; + ready [label="ICU_READY\nClock Enabled"]; + waiting [label="ICU_WAITING"]; + active [label="ICU_ACTIVE"]; + + uninit -> stop [label=" icuInit()", constraint=false]; + stop -> stop [label="\nicuStop()"]; + stop -> ready [label="\nicuStart()"]; + ready -> stop [label="\nicuStop()"]; + ready -> ready [label="\nicuStart()\nicuStopCapture()"]; + ready -> waiting [label="\nicuStartCapture()"]; + waiting -> active [label="\nFirst Activation Edge\nicuWaitCapture()"]; + waiting -> ready [label="\nicuStopCapture()"]; + active -> ready [label="\nicuStopCapture()"]; + active -> active [label="\nActivation Edge\n>period_cb<"]; + active -> active [label="\nDe-activation Edge\n>width_cb<"]; + } + * @enddot + * @else + * @dot + digraph example { + rankdir="LR"; + + node [shape=circle, fontname=Sans, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Sans, fontsize=8]; + + stop [label="ICU_STOP\nLow Power"]; + uninit [label="ICU_UNINIT", style="bold"]; + ready [label="ICU_READY\nClock Enabled"]; + waiting [label="ICU_WAITING"]; + active [label="ICU_ACTIVE"]; + + uninit -> stop [label=" icuInit()", constraint=false]; + stop -> stop [label="\nicuStop()"]; + stop -> ready [label="\nicuStart()"]; + ready -> stop [label="\nicuStop()"]; + ready -> ready [label="\nicuStart()\nicuStopCapture()"]; + ready -> waiting [label="\nicuStartCapture()"]; + waiting -> active [label="\nFirst Activation Edge\nicuWaitCapture()"]; + waiting -> ready [label="\nicuStopCapture()"]; + active -> ready [label="\nicuStopCapture()"]; + active -> active [label="\nActivation Edge\n>period_cb<"]; + active -> active [label="\nDe-activation Edge\n>width_cb<"]; + } + * @enddot + * @endif + * + * @section icu_2 ICU Operations. + * This driver abstracts a generic Input Capture Unit composed of: + * - A clock prescaler. + * - A main up counter. + * - Two capture registers triggered by the rising and falling edges on + * the sampled input. + * . + * The ICU unit can be programmed to synchronize on the rising or falling + * edge of the sample input: + * - ICU_INPUT_ACTIVE_HIGH, a rising edge is the start signal. + * - ICU_INPUT_ACTIVE_LOW, a falling edge is the start signal. + * . + * Callbacks are optionally invoked when: + * - On the PWM de-activation edge. + * - On the PWM activation edge, measurements for the previous cycle are + * available from this callback and can be retrieved using + * @p icuGetPeriodX() and @p icuGetWidthX(). + * . + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_interfaces.dox b/ChibiOS_20.3.2/os/hal/dox/hal_interfaces.dox new file mode 100644 index 0000000..c27305a --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_interfaces.dox @@ -0,0 +1,60 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup HAL_BLOCKS Blocks + * @ingroup HAL_INTERFACES_CLASSES + */ + +/** + * @defgroup HAL_INTERFACES Streams + * @ingroup HAL_INTERFACES_CLASSES + */ + +/** + * @defgroup HAL_STREAMS Abstract Streams Interface + * @ingroup HAL_INTERFACES + */ + +/** + * @defgroup IO_CHANNEL Abstract I/O Channel Interface + * @ingroup HAL_INTERFACES + */ + +/** + * @defgroup HAL_FILES Abstract Files Interface + * @ingroup HAL_INTERFACES + */ + +/** + * @defgroup HAL_PERSISTENT Abstract Persistent Storage Interface + * @ingroup HAL_INTERFACES + */ + +/** + * @defgroup HAL_MEMORY_STREAMS Memory Streams Class + * @ingroup HAL_INTERFACES + */ + +/** + * @defgroup HAL_NULL_STREAMS Null Streams Class + * @ingroup HAL_INTERFACES + */ + +/** + * @defgroup HAL_CHPRINTF Output Formatter Utility + * @ingroup HAL_INTERFACES + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_ioblock.dox b/ChibiOS_20.3.2/os/hal/dox/hal_ioblock.dox new file mode 100644 index 0000000..cc83945 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_ioblock.dox @@ -0,0 +1,100 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup IO_BLOCK Abstract I/O Block Device + * @ingroup HAL_BLOCKS + * + * @section io_block_1 Driver State Machine + * The drivers implementing this interface shall implement the following + * state machine internally. Not all the driver functionalities can be used + * in any moment, any transition not explicitly shown in the following + * diagram has to be considered an error and shall be captured by an + * assertion (if enabled). + * @if LATEX_PDF + * @dot + digraph example { + size="5, 7"; + rankdir="LR"; + + node [shape=circle, fontname=Sans, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Sans, fontsize=8]; + + stop [label="BLK_STOP\nLow Power"]; + uninit [label="BLK_UNINIT", style="bold"]; + active [label="BLK_ACTIVE\nClock Enabled"]; + connecting [label="BLK_CONN.ING\nConnecting"]; + disconnecting [label="BLK_DISC.ING\nDisconnecting"]; + ready [label="BLK_READY\nCard Ready"]; + reading [label="BLK_READING\nReading"]; + writing [label="BLK_WRITING\nWriting"]; + + uninit -> stop [label=" blkInit()", constraint=false]; + stop -> stop [label="\nblkStop()"]; + stop -> active [label="\nblkStart()"]; + active -> stop [label="\nblkStop()"]; + active -> active [label="\nblkStart()\nblkDisconnect()"]; + active -> connecting [label="\nblkConnect()"]; + connecting -> ready [label="\nconnection\nsuccessful"]; + connecting -> ready [label="\nblkConnect()", dir="back"]; + connecting -> active [label="\nconnection\nfailed"]; + disconnecting -> ready [label="\nblkDisconnect()", dir="back"]; + active -> disconnecting [label="\ndisconnection\nfinished", dir="back"]; + ready -> reading [label="\nblkRead()"]; + reading -> ready [label="\nread finished\nread error"]; + ready -> writing [label="\nblkWrite()"]; + writing -> ready [label="\nwrite finished\nwrite error"]; + } + * @enddot + * @else + * @dot + digraph example { + rankdir="LR"; + + node [shape=circle, fontname=Sans, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Sans, fontsize=8]; + + stop [label="BLK_STOP\nLow Power"]; + uninit [label="BLK_UNINIT", style="bold"]; + active [label="BLK_ACTIVE\nClock Enabled"]; + connecting [label="BLK_CONN.ING\nConnecting"]; + disconnecting [label="BLK_DISC.ING\nDisconnecting"]; + ready [label="BLK_READY\nCard Ready"]; + reading [label="BLK_READING\nReading"]; + writing [label="BLK_WRITING\nWriting"]; + syncing [label="BLK_SYNCING\nSynchronizing"]; + + uninit -> stop [label=" blkInit()", constraint=false]; + stop -> stop [label="\nblkStop()"]; + stop -> active [label="\nblkStart()"]; + active -> stop [label="\nblkStop()"]; + active -> active [label="\nblkStart()\nblkDisconnect()"]; + active -> connecting [label="\nblkConnect()"]; + connecting -> ready [label="\nconnection\nsuccessful"]; + connecting -> ready [label="\nblkConnect()", dir="back"]; + connecting -> active [label="\nconnection\nfailed"]; + disconnecting -> ready [label="\nblkDisconnect()", dir="back"]; + active -> disconnecting [label="\ndisconnection\nfinished", dir="back"]; + ready -> reading [label="\nblkRead()"]; + reading -> ready [label="\nread finished\nread error"]; + ready -> writing [label="\nblkWrite()"]; + writing -> ready [label="\nwrite finished\nwrite error"]; + ready -> syncing [label="\nblkSync()"]; + syncing -> ready [label="\nsynchronization finished"]; + } + * @enddot + * @endif + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_mac.dox b/ChibiOS_20.3.2/os/hal/dox/hal_mac.dox new file mode 100644 index 0000000..c5e9c64 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_mac.dox @@ -0,0 +1,26 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup MAC MAC Driver + * @brief Generic MAC Driver. + * @details This module implements a generic MAC (Media Access Control) + * driver for Ethernet controllers. + * @pre In order to use the MAC driver the @p HAL_USE_MAC option + * must be enabled in @p halconf.h. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_mfs.dox b/ChibiOS_20.3.2/os/hal/dox/hal_mfs.dox new file mode 100644 index 0000000..88b8046 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_mfs.dox @@ -0,0 +1,30 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup HAL_MFS Managed Flash Storage Driver + * @brief Managed Flash Storage Driver. + * @details This module implements a managed flash storage able to store + * a finite number of variable-size records. Records are retrieved + * by their index number.
+ * The driver is automatically performs: + * - Wear leveling. + * - Auto repair after power loss. + * - Garbage collection in order to remove erased data. + * . + * + * @ingroup HAL_COMPLEX_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_mii.dox b/ChibiOS_20.3.2/os/hal/dox/hal_mii.dox new file mode 100644 index 0000000..cfd7a1e --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_mii.dox @@ -0,0 +1,23 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup MII MII/RMII Header + * @brief MII/RMII Support Header + * @details This header contains definitions and types related to MII/RMII. + * + * @ingroup HAL_SUPPORT + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_mmc_spi.dox b/ChibiOS_20.3.2/os/hal/dox/hal_mmc_spi.dox new file mode 100644 index 0000000..1dc4b27 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_mmc_spi.dox @@ -0,0 +1,35 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup MMC_SPI MMC over SPI Driver + * @brief Generic MMC driver. + * @details This module implements a portable MMC/SD driver that uses a SPI + * driver as physical layer. Hot plugging and removal are supported + * through kernel events. + * @pre In order to use the MMC_SPI driver the @p HAL_USE_MMC_SPI and + * @p HAL_USE_SPI options must be enabled in @p halconf.h. + * + * @section mmc_spi_1 Driver State Machine + * This driver implements a state machine internally, see the @ref IO_BLOCK + * module documentation for details. + * + * @section mmc_spi_2 Driver Operations + * This driver allows to read or write single or multiple 512 bytes blocks + * on a SD Card. + * + * @ingroup HAL_COMPLEX_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_mmcsd.dox b/ChibiOS_20.3.2/os/hal/dox/hal_mmcsd.dox new file mode 100644 index 0000000..3b8017c --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_mmcsd.dox @@ -0,0 +1,24 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup MMCSD MMC/SD Block Device + * @details This module implements a common ancestor for all device drivers + * accessing MMC or SD cards. This interface inherits the state + * machine and the interface from the @ref IO_BLOCK module. + * + * @ingroup HAL_INNER_CODE + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_norflash.dox b/ChibiOS_20.3.2/os/hal/dox/hal_norflash.dox new file mode 100644 index 0000000..24f30d9 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_norflash.dox @@ -0,0 +1,54 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup HAL_SERIAL_NOR Serial NOR Flash Driver + * @brief Serial NOR Flash driver. + * @details This module implements a generic driver for serial NOR Flash + * devices. + * + * @section snorflash_1 Driver State Machine + * The flash driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + stop [label="FLS_STOP\nLow Power"]; + uninit [label="FLS_UNINIT", style="bold"]; + ready [label="FLS_READY\nClock Enabled"]; + read [label="FLS_READ\nReading"]; + pgm [label="FLS_PGM\nProgramming"]; + erase [label="FLS_ERASE\nErasing"]; + uninit -> stop [label=" snorInit()", constraint=false]; + stop -> stop [label=" snorStop()"]; + stop -> ready [label=" snorStart()"]; + ready -> stop [label=" snorStop()"]; + ready -> read [label=" flashRead()\nflashVerifyErase()"]; + read -> ready [label=" return"]; + ready -> pgm [label=" flashProgram()"]; + pgm -> ready [label=" return"]; + ready -> erase [label=" \n\nflashEraseAll()\nflashEraseSector()"]; + erase -> ready [label=" flashQueryErase()\nFLASH_NO_ERROR\nFLASH_ERROR_*"]; + erase -> erase [label=" flashQueryErase()\nflashProgram()\nflashRead()\nFLASH_BUSY_ERASING"]; + } + * @enddot + * + * @ingroup HAL_COMPLEX_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_objects.dox b/ChibiOS_20.3.2/os/hal/dox/hal_objects.dox new file mode 100644 index 0000000..140fb3c --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_objects.dox @@ -0,0 +1,20 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup HAL_BASE_OBJECT Base Object + * @ingroup HAL_INTERFACES_CLASSES + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_pal.dox b/ChibiOS_20.3.2/os/hal/dox/hal_pal.dox new file mode 100644 index 0000000..d37fd09 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_pal.dox @@ -0,0 +1,70 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup PAL PAL Driver + * @brief I/O Ports Abstraction Layer + * @details This module defines an abstract interface for digital I/O ports. + * Note that most I/O ports functions are just macros. The macros + * have default software implementations that can be redefined in a + * PAL Low Level Driver if the target hardware supports special + * features like, for example, atomic bit set/reset/masking. Please + * refer to the ports specific documentation for details.
+ * The @ref PAL driver has the advantage to make the access to the I/O + * ports platform independent and still be optimized for the specific + * architectures.
+ * Note that the PAL Low Level Driver may also offer non standard + * macro and functions in order to support specific features but, + * of course, the use of such interfaces would not be portable. + * Such interfaces shall be marked with the architecture name inside + * the function names. + * @pre In order to use the PAL driver the @p HAL_USE_PAL option + * must be enabled in @p halconf.h. + * + * @section pal_1 Implementation Rules + * In implementing a PAL Low Level Driver there are some rules/behaviors that + * should be respected. + * + * @subsection pal_1_1 Writing on input pads + * The behavior is not specified but there are implementations better than + * others, this is the list of possible implementations, preferred options + * are on top: + * -# The written value is not actually output but latched, should the pads + * be reprogrammed as outputs the value would be in effect. + * -# The write operation is ignored. + * -# The write operation has side effects, as example disabling/enabling + * pull up/down resistors or changing the pad direction. This scenario is + * discouraged, please try to avoid this scenario. + * . + * @subsection pal_1_2 Reading from output pads + * The behavior is not specified but there are implementations better than + * others, this is the list of possible implementations, preferred options + * are on top: + * -# The actual pads states are read (not the output latch). + * -# The output latch value is read (regardless of the actual pads states). + * -# Unspecified, please try to avoid this scenario. + * . + * @subsection pal_1_3 Writing unused or unimplemented port bits + * The behavior is not specified. + * + * @subsection pal_1_4 Reading from unused or unimplemented port bits + * The behavior is not specified. + * + * @subsection pal_1_5 Reading or writing on pins associated to other functionalities + * The behavior is not specified. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_peripherals.dox b/ChibiOS_20.3.2/os/hal/dox/hal_peripherals.dox new file mode 100644 index 0000000..2d8560f --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_peripherals.dox @@ -0,0 +1,22 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup HAL_ABSTRACT_PERIPHERALS Peripheral Interfaces + * @brief HAL Abstract Peripheral Interfaces. + * + * @ingroup IO + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_pwm.dox b/ChibiOS_20.3.2/os/hal/dox/hal_pwm.dox new file mode 100644 index 0000000..39e0128 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_pwm.dox @@ -0,0 +1,65 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup PWM PWM Driver + * @brief Generic PWM Driver. + * @details This module implements a generic PWM (Pulse Width Modulation) + * driver. + * @pre In order to use the PWM driver the @p HAL_USE_PWM option + * must be enabled in @p halconf.h. + * + * @section pwm_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + uninit [label="PWM_UNINIT", style="bold"]; + stop [label="PWM_STOP\nLow Power"]; + ready [label="PWM_READY\nClock Enabled"]; + uninit -> stop [label="pwmInit()"]; + stop -> stop [label="pwmStop()"]; + stop -> ready [label="pwmStart()"]; + ready -> stop [label="pwmStop()"]; + ready -> ready [label="pwmEnableChannel()\npwmDisableChannel()"]; + } + * @enddot + * + * @section pwm_2 PWM Operations. + * This driver abstracts a generic PWM timer composed of: + * - A clock prescaler. + * - A main up counter. + * - A comparator register that resets the main counter to zero when the limit + * is reached. An optional callback can be generated when this happens. + * - An array of @p PWM_CHANNELS PWM channels, each channel has an output, + * a comparator and is able to invoke an optional callback when a comparator + * match with the main counter happens. + * . + * A PWM channel output can be in two different states: + * - IDLE, when the channel is disabled or after a match occurred. + * - ACTIVE, when the channel is enabled and a match didn't occur yet + * in the current PWM cycle. + * . + * Note that the two states can be associated to both logical zero or one in + * the @p PWMChannelConfig structure. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_queues.dox b/ChibiOS_20.3.2/os/hal/dox/hal_queues.dox new file mode 100644 index 0000000..60ce974 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_queues.dox @@ -0,0 +1,20 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup HAL_QUEUES I/O Bytes Queues + * @ingroup HAL_INNER_CODE + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_rtc.dox b/ChibiOS_20.3.2/os/hal/dox/hal_rtc.dox new file mode 100644 index 0000000..0923e61 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_rtc.dox @@ -0,0 +1,26 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup RTC RTC Driver + * @brief Generic RTC Driver. + * @details This module defines an abstract interface for a Real Time Clock + * Peripheral. + * @pre In order to use the RTC driver the @p HAL_USE_RTC option + * must be enabled in @p halconf.h. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_sdc.dox b/ChibiOS_20.3.2/os/hal/dox/hal_sdc.dox new file mode 100644 index 0000000..1a26006 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_sdc.dox @@ -0,0 +1,33 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup SDC SDC Driver + * @brief Generic SD Card Driver. + * @details This module implements a generic SDC (Secure Digital Card) driver. + * @pre In order to use the SDC driver the @p HAL_USE_SDC option + * must be enabled in @p halconf.h. + * + * @section sdc_1 Driver State Machine + * This driver implements a state machine internally, see the @ref IO_BLOCK + * module documentation for details. + * + * @section sdc_2 Driver Operations + * This driver allows to read or write single or multiple 512 bytes blocks + * on a SD Card. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_serial.dox b/ChibiOS_20.3.2/os/hal/dox/hal_serial.dox new file mode 100644 index 0000000..9acb0bc --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_serial.dox @@ -0,0 +1,57 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup SERIAL Serial Driver + * @brief Generic Serial Driver. + * @details This module implements a generic full duplex serial driver. The + * driver implements a @p SerialDriver interface and uses I/O Queues + * for communication between the upper and the lower driver. Event + * flags are used to notify the application about incoming data, + * outgoing data and other I/O events.
+ * The module also contains functions that make the implementation + * of the interrupt service routines much easier. + * @pre In order to use the SERIAL driver the @p HAL_USE_SERIAL option + * must be enabled in @p halconf.h. + * + * + * @section serial_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", + width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + uninit [label="SD_UNINIT", style="bold"]; + stop [label="SD_STOP\nLow Power"]; + ready [label="SD_READY\nClock Enabled"]; + + uninit -> stop [label=" sdInit()"]; + stop -> stop [label="\nsdStop()"]; + stop -> ready [label="\nsdStart()"]; + ready -> stop [label="\nsdStop()"]; + ready -> ready [label="\nsdStart()"]; + ready -> ready [label="\nAny I/O operation"]; + } + * @enddot + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_serial_usb.dox b/ChibiOS_20.3.2/os/hal/dox/hal_serial_usb.dox new file mode 100644 index 0000000..028d8bb --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_serial_usb.dox @@ -0,0 +1,52 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup SERIAL_USB Serial over USB Driver + * @brief Serial over USB Driver. + * @details This module implements an USB Communication Device Class + * (CDC) as a normal serial communication port accessible from + * the device application. + * @pre In order to use the USB over Serial driver the + * @p HAL_USE_SERIAL_USB option must be enabled in @p halconf.h. + * + * @section usb_serial_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", + width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + uninit [label="SDU_UNINIT", style="bold"]; + stop [label="SDU_STOP\nLow Power"]; + ready [label="SDU_READY\nClock Enabled"]; + + uninit -> stop [label=" sduInit()"]; + stop -> stop [label="\nsduStop()"]; + stop -> ready [label="\nsduStart()"]; + ready -> stop [label="\nsduStop()"]; + ready -> ready [label="\nsduStart()"]; + ready -> ready [label="\nAny I/O operation"]; + } + * @enddot + * + * @ingroup HAL_COMPLEX_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_sio.dox b/ChibiOS_20.3.2/os/hal/dox/hal_sio.dox new file mode 100644 index 0000000..57ff2ba --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_sio.dox @@ -0,0 +1,58 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup SIO SIO Driver + * @brief Generic SIO Driver. + * @details This driver abstracts a generic serial communication channel, + * usually an UART, this driver is similar to Serial and UART drivers + * but follows a different concept: + * - Very close to HW. + * - No buffering done in SW, the driver relies on the peripheral + * internal FIFO, if any. + * - Asynchronous, the API is always non blocking. + * - Callbacks capable, operations completion and other events are + * notified using callbacks. + * - Very short code paths, especially in ISRs. + * . + * @pre In order to use the SIO driver the @p HAL_USE_SIO option + * must be enabled in @p halconf.h. + * + * @section sio_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + uninit [label="SIO_UNINIT", style="bold"]; + stop [label="SIO_STOP\nLow Power"]; + ready [label="SIO_READY\nClock Enabled"]; + + uninit -> stop [label="\nsioInit()"]; + stop -> ready [label="\nsioStart()"]; + ready -> ready [label="\nsioStart()"]; + ready -> stop [label="\nsioStop()"]; + stop -> stop [label="\nsioStop()"]; + } + * @enddot + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_spi.dox b/ChibiOS_20.3.2/os/hal/dox/hal_spi.dox new file mode 100644 index 0000000..4307bac --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_spi.dox @@ -0,0 +1,90 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup SPI SPI Driver + * @brief Generic SPI Driver. + * @details This module implements a generic SPI (Serial Peripheral Interface) + * driver allowing bidirectional and monodirectional transfers, + * complex atomic transactions are supported as well. + * @pre In order to use the SPI driver the @p HAL_USE_SPI option + * must be enabled in @p halconf.h. + * + * @section spi_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @if LATEX_PDF + * @dot + digraph example { + size="5, 7"; + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", + width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="SPI_STOP\nLow Power"]; + uninit [label="SPI_UNINIT", style="bold"]; + ready [label="SPI_READY\nClock Enabled"]; + active [label="SPI_ACTIVE\nBus Active"]; + complete [label="SPI_COMPLETE\nComplete"]; + + uninit -> stop [label="\n spiInit()", constraint=false]; + stop -> ready [label="\nspiStart()"]; + ready -> ready [label="\nspiSelect()\nspiUnselect()\nspiStart()"]; + ready -> stop [label="\nspiStop()"]; + stop -> stop [label="\nspiStop()"]; + ready -> active [label="\nspiStartXXXI() (async)\nspiXXX() (sync)"]; + active -> ready [label="\nsync return"]; + active -> complete [label="\nasync callback\n>spc_endcb<"]; + complete -> active [label="\nspiStartXXXI() (async)\nthen\ncallback return"]; + complete -> ready [label="\ncallback return"]; + } + * @enddot + * @else + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="SPI_STOP\nLow Power"]; + uninit [label="SPI_UNINIT", style="bold"]; + ready [label="SPI_READY\nClock Enabled"]; + active [label="SPI_ACTIVE\nBus Active"]; + complete [label="SPI_COMPLETE\nComplete"]; + + uninit -> stop [label="\n spiInit()", constraint=false]; + stop -> ready [label="\nspiStart()"]; + ready -> ready [label="\nspiSelect()\nspiUnselect()\nspiStart()"]; + ready -> stop [label="\nspiStop()"]; + stop -> stop [label="\nspiStop()"]; + ready -> active [label="\nspiStartXXX() (async)\nspiXXX() (sync)"]; + active -> ready [label="\nsync return"]; + active -> complete [label="\nasync callback\n>spc_endcb<"]; + complete -> active [label="\nspiStartXXXI() (async)\nthen\ncallback return"]; + complete -> ready [label="\ncallback return"]; + } + * @enddot + * @endif + * + * The driver is not thread safe for performance reasons, if you need to access + * the SPI bus from multiple threads then use the @p spiAcquireBus() and + * @p spiReleaseBus() APIs in order to gain exclusive access. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_st.dox b/ChibiOS_20.3.2/os/hal/dox/hal_st.dox new file mode 100644 index 0000000..c6a8a64 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_st.dox @@ -0,0 +1,24 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup ST ST Driver + * @brief Generic System Tick Driver. + * @details This module implements a system tick timer in order to support + * the underlying operating system. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_trng.dox b/ChibiOS_20.3.2/os/hal/dox/hal_trng.dox new file mode 100644 index 0000000..e28c606 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_trng.dox @@ -0,0 +1,25 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup TRNG TRNG Driver + * @brief Generic True Random Numbers Generator Driver. + * @details This module implements a generic TRNG driver. + * @pre In order to use the TRNG driver the @p HAL_USE_TRNG option + * must be enabled in @p halconf.h. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_uart.dox b/ChibiOS_20.3.2/os/hal/dox/hal_uart.dox new file mode 100644 index 0000000..8af3127 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_uart.dox @@ -0,0 +1,117 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup UART UART Driver + * @brief Generic UART Driver. + * @details This driver abstracts a generic UART (Universal Asynchronous + * Receiver Transmitter) peripheral, the API is designed to be: + * - Unbuffered and copy-less, transfers are always directly performed + * from/to the application-level buffers without extra copy + * operations. + * - Asynchronous, the API is always non blocking. + * - Callbacks capable, operations completion and other events are + * notified using callbacks. + * . + * Special hardware features like deep hardware buffers, DMA transfers + * are hidden to the user but fully supportable by the low level + * implementations.
+ * This driver model is best used where communication events are + * meant to drive an higher level state machine, as example: + * - RS485 drivers. + * - Multipoint network drivers. + * - Serial protocol decoders. + * . + * If your application requires a synchronous buffered driver then + * the @ref SERIAL should be used instead. + * @pre In order to use the UART driver the @p HAL_USE_UART option + * must be enabled in @p halconf.h. + * + * @section uart_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + uninit [label="UART_UNINIT", style="bold"]; + stop [label="UART_STOP\nLow Power"]; + ready [label="UART_READY\nClock Enabled"]; + + uninit -> stop [label="\nuartInit()"]; + stop -> ready [label="\nuartStart()"]; + ready -> ready [label="\nuartStart()"]; + ready -> stop [label="\nuartStop()"]; + stop -> stop [label="\nuartStop()"]; + } + * @enddot + * + * @subsection uart_1_1 Transmitter sub State Machine + * The follow diagram describes the transmitter state machine, this diagram + * is valid while the driver is in the @p UART_READY state. This state + * machine is automatically reset to the @p TX_IDLE state each time the + * driver enters the @p UART_READY state. + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + tx_idle [label="TX_IDLE", style="bold"]; + tx_active [label="TX_ACTIVE"]; + tx_complete [label="TX_COMPLETE"]; + + tx_idle -> tx_active [label="\nuartStartSend()"]; + tx_idle -> tx_idle [label="\nuartStopSend()\n>txend2_cb<"]; + tx_active -> tx_complete [label="\nbuffer transmitted\n>txend1_cb<"]; + tx_active -> tx_idle [label="\nuartStopSend()"]; + tx_complete -> tx_active [label="\nuartStartSendI()\nthen\ncallback return"]; + tx_complete -> tx_idle [label="\ncallback return"]; + } + * @enddot + * + * @subsection uart_1_2 Receiver sub State Machine + * The follow diagram describes the receiver state machine, this diagram + * is valid while the driver is in the @p UART_READY state. This state + * machine is automatically reset to the @p RX_IDLE state each time the + * driver enters the @p UART_READY state. + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + rx_idle [label="RX_IDLE", style="bold"]; + rx_active [label="RX_ACTIVE"]; + rx_complete [label="RX_COMPLETE"]; + + rx_idle -> rx_idle [label="\nuartStopReceive()\n>rxchar_cb<\n>rxerr_cb<"]; + rx_idle -> rx_active [label="\nuartStartReceive()"]; + + rx_active -> rx_complete [label="\nbuffer filled\n>rxend_cb<"]; + rx_active -> rx_idle [label="\nuartStopReceive()"]; + rx_active -> rx_active [label="\nreceive error\n>rxerr_cb<"]; + rx_complete -> rx_active [label="\nuartStartReceiveI()"]; + rx_complete -> rx_idle [label="\ncallback return"]; + } + * @enddot + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_usb.dox b/ChibiOS_20.3.2/os/hal/dox/hal_usb.dox new file mode 100644 index 0000000..82de6cc --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_usb.dox @@ -0,0 +1,180 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup USB USB Driver + * @brief Generic USB Driver. + * @details This module implements a generic USB (Universal Serial Bus) driver + * supporting device-mode operations. + * @pre In order to use the USB driver the @p HAL_USE_USB option + * must be enabled in @p halconf.h. + * + * @section usb_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @if LATEX_PDF + * @dot + digraph example { + size="5, 7"; + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", + width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="USB_STOP\nLow Power"]; + uninit [label="USB_UNINIT", style="bold"]; + ready [label="USB_READY\nClock Enabled"]; + selected [label="\nUSB_SELECTED\naddress\nassigned"]; + active [label="\nUSB_ACTIVE\nconfiguration\nselected"]; + + uninit -> stop [label=" usbInit()", constraint=false]; + stop -> stop [label="\nusbStop()"]; + stop -> ready [label="\nusbStart()"]; + ready -> stop [label="\nusbStop()"]; + ready -> ready [label="\n\nusbStart()"]; + ready -> ready [label="\nSUSPEND/WAKEUP\n>event_cb<"]; + ready -> selected [label="\nSET_ADDRESS\n>event_cb<"]; + selected -> stop [label="\nusbStop()"]; + selected -> ready [label="\nUSB RESET\n>event_cb<"]; + selected -> selected [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<"]; + selected -> active [label="\nSET_CONF(n)\n>event_cb<"]; + active -> stop [label="\nusbStop()"]; + active -> selected [label="\nSET_CONF(0)\n>event_cb<"]; + active -> active [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<\n\nEndpoints Activity\n >in_cb< or >out_cb<"]; + active -> ready [label="\nUSB RESET\n>event_cb<"]; + } + * @enddot + * @else + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", + width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="USB_STOP\nLow Power"]; + uninit [label="USB_UNINIT", style="bold"]; + ready [label="USB_READY\nClock Enabled"]; + selected [label="\nUSB_SELECTED\naddress\nassigned"]; + active [label="\nUSB_ACTIVE\nconfiguration\nselected"]; + + uninit -> stop [label=" usbInit()", constraint=false]; + stop -> stop [label="\nusbStop()"]; + stop -> ready [label="\nusbStart()"]; + ready -> stop [label="\nusbStop()"]; + ready -> ready [label="\n\nusbStart()"]; + ready -> ready [label="\nSUSPEND/WAKEUP\n>event_cb<"]; + ready -> selected [label="\nSET_ADDRESS\n>event_cb<"]; + selected -> stop [label="\nusbStop()"]; + selected -> ready [label="\nUSB RESET\n>event_cb<"]; + selected -> selected [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<"]; + selected -> active [label="\nSET_CONF(n)\n>event_cb<"]; + active -> stop [label="\nusbStop()"]; + active -> selected [label="\nSET_CONF(0)\n>event_cb<"]; + active -> active [label="\nSUSPEND/WAKEUP\n>event_cb<\n\nValid EP0 Message\n>requests_hook_cb<\n\nGET DESCRIPTOR\n>get_descriptor_cb<\n\nEndpoints Activity\n >in_cb< or >out_cb<"]; + active -> ready [label="\nUSB RESET\n>event_cb<"]; + } + * @enddot + * @endif + * + * @section usb_2 USB Operations + * The USB driver is quite complex and USB is complex in itself, it is + * recommended to study the USB specification before trying to use the + * driver. + * + * @subsection usb_2_1 USB Implementation + * The USB driver abstracts the inner details of the underlying USB hardware. + * The driver works asynchronously and communicates with the application + * using callbacks. The application is responsible of the descriptors and + * strings required by the USB device class to be implemented and of the + * handling of the specific messages sent over the endpoint zero. Standard + * messages are handled internally to the driver. The application can use + * hooks in order to handle custom messages or override the handling of the + * default handling of standard messages. + * + * @subsection usb_2_2 USB Endpoints + * USB endpoints are the objects that the application uses to exchange + * data with the host. There are two kind of endpoints: + * - IN endpoints are used by the application to transmit data to + * the host.
+ * - OUT endpoints are used by the application to receive data from + * the host. + * . + * The driver invokes a callback after finishing an IN or OUT transaction. + * States diagram for OUT endpoints in transaction mode: + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", + width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + disabled [label="EP_DISABLED\nDisabled", style="bold"]; + receiving [label="EP_BUSY\nReceiving"]; + idle [label="EP_IDLE\nReady"]; + + disabled -> idle [label="\nusbInitEndpointI()"]; + idle -> receiving [label="\nusbPrepareReceive()\nusbStartReceiveI()"]; + receiving -> receiving [label="\nmore packets"]; + receiving -> idle [label="\nreception end\n>out_cb<"]; + receiving -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; + idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; + } + * @enddot + *

+ * States diagram for IN endpoints in transaction mode: + * @dot + digraph example { + rankdir="LR"; + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", + width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + disabled [label="EP_DISABLED\nDisabled", style="bold"]; + transmitting [label="EP_BUSY\nTransmitting"]; + idle [label="EP_IDLE\nReady"]; + + disabled -> idle [label="\usbInitEndpointI()"]; + idle -> transmitting [label="\nusbPrepareTransmit()\nusbStartTransmitI()"]; + transmitting -> transmitting [label="\nmore packets"]; + transmitting -> idle [label="\ntransmission end\n>in_cb<"]; + transmitting -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; + idle -> disabled [label="\nUSB RESET\nusbDisableEndpointsI()"]; + } + * @enddot + *

+ * + * @subsection usb_2_4 USB Callbacks + * The USB driver uses callbacks in order to interact with the application. + * There are several kinds of callbacks to be handled: + * - Driver events callback. As example errors, suspend event, reset event + * etc. + * - Messages Hook callback. This hook allows the application to implement + * handling of custom messages or to override the default handling of + * standard messages on endpoint zero. + * - Descriptor Requested callback. When the driver endpoint zero handler + * receives a GET DESCRIPTOR message and needs to send a descriptor to + * the host it queries the application using this callback. + * - Start of Frame callback. This callback is invoked each time a SOF + * packet is received. + * - Endpoint callbacks. Each endpoint informs the application about I/O + * conditions using those callbacks. + * . + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_usb_cdc.dox b/ChibiOS_20.3.2/os/hal/dox/hal_usb_cdc.dox new file mode 100644 index 0000000..c480c95 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_usb_cdc.dox @@ -0,0 +1,23 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup USB_CDC USB CDC Header + * @brief USB CDC Support Header + * @details This header contains definitions and types related to USB CDC. + * + * @ingroup HAL_SUPPORT + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_wdg.dox b/ChibiOS_20.3.2/os/hal/dox/hal_wdg.dox new file mode 100644 index 0000000..7529320 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_wdg.dox @@ -0,0 +1,26 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup WDG WDG Driver + * @brief Generic WDG Driver + * @details This module defines an abstract interface for a watchdog + * timer. + * @pre In order to use the WDG driver the @p HAL_USE_WDG option + * must be enabled in @p halconf.h. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/hal_wspi.dox b/ChibiOS_20.3.2/os/hal/dox/hal_wspi.dox new file mode 100755 index 0000000..5cf29d9 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/hal_wspi.dox @@ -0,0 +1,26 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup WSPI WSPI Driver + * @brief Generic WSPI Driver + * @details This module defines an abstract interface for an wide SPI + * communication interface (Quad SPI, Octal SPI and similar). + * @pre In order to use the WSPI driver the @p HAL_USE_WSPI option + * must be enabled in @p halconf.h. + * + * @ingroup HAL_NORMAL_DRIVERS + */ diff --git a/ChibiOS_20.3.2/os/hal/dox/main.dox b/ChibiOS_20.3.2/os/hal/dox/main.dox new file mode 100644 index 0000000..1c543a3 --- /dev/null +++ b/ChibiOS_20.3.2/os/hal/dox/main.dox @@ -0,0 +1,195 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup IO HAL + * @brief Hardware Abstraction Layer. + * @details Under ChibiOS the set of the various device driver interfaces + * is called the HAL subsystem: Hardware Abstraction Layer. The HAL is the + * abstract interface between ChibiOS applications and hardware. + * + * @section hal_device_driver_arch HAL Device Drivers Architecture + * The HAL contains several kind of modules: + * - Normal Device Drivers + * - Complex Device Drivers + * - Interfaces + * - Inner Code + * . + * @section hal_normal_device_drivers HAL Normal Device Drivers + * Normal device are meant to interface the application to the underlying + * hardware through an high level API. Normal Device Drivers are split in two + * layers: + * - High Level Device Driver (HLD). This layer contains the definitions + * of the driver's APIs and the platform independent part of the driver.
+ * An HLD is composed by two files: + * - @p hal_@.c, the HLD implementation file. This file must be + * included in the Makefile in order to use the driver. + * - @p hal_@.h, the HLD header file. This file is implicitly + * included by the HAL header file @p hal.h. + * . + * - Low Level Device Driver (LLD). This layer contains the platform + * dependent part of the driver.
+ * A LLD is composed by two files: + * - @p hal_@_lld.c, the LLD implementation file. This file must be + * included in the Makefile in order to use the driver. + * - @p hal_@_lld.h, the LLD header file. This file is implicitly + * included by the HLD header file. + * . + * . + * @subsection hal_device_driver_diagram Diagram + * @dot + digraph example { + graph [size="5, 7", pad="1.5, 0"]; + node [shape=rectangle, fontname=Helvetica, fontsize=8, + fixedsize="true", width="2.0", height="0.4"]; + edge [fontname=Helvetica, fontsize=8]; + + app [label="Application"]; + hld [label="High Level Driver"]; + lld [label="Low Level Driver"]; + hw [label="Microcontroller Hardware"]; + hal_lld [label="HAL shared low level code"]; + + app->hld; + hld->lld; + lld-> hw; + lld->hal_lld; + hal_lld->hw; + } + * @enddot + * + * @section hal_complex_device_drivers HAL Complex Device Drivers + * It is a class of device drivers that offer an high level API but do not + * use the hardware directly. Complex device drivers use other drivers for + * accessing the machine resources. + * + * @section hal_interfaces HAL Interfaces + * An interface is a binary structure allowing the access to a service + * using virtual functions. This allows to create drivers that can be + * accessed using a common interface. + * The concept of interface is commonly found in object-oriented languages + * like Java or C++, their meaning in ChibiOS/HAL is exactly the same. + * + * @section hal_inner_code HAL Inner Code + * Some modules are shared among multiple device drivers and are not + * necessarily meant to be used by the application layer. + */ + +/** + * @defgroup HAL_CONF Configuration + * @brief HAL Configuration. + * @details The file @p halconf.h contains the high level settings for all + * the drivers supported by the HAL. The low level, platform dependent, + * settings are contained in the @p mcuconf.h file instead and are describe + * in the various platforms reference manuals. + * + * @ingroup IO + */ + +/** + * @defgroup HAL_NORMAL_DRIVERS Normal Drivers + * @brief HAL Normal Drivers. + * + * @ingroup IO + */ + +/** + * @defgroup HAL_COMPLEX_DRIVERS Complex Drivers + * @brief HAL Complex Drivers. + * + * @ingroup IO + */ + +/** + * @defgroup HAL_INTERFACES_CLASSES Interfaces and Classes + * @brief HAL Interfaces and Classes. + * + * @ingroup IO + */ + +/** + * @defgroup HAL_INNER_CODE Inner Code + * @brief HAL Inner Code. + * + * @ingroup IO + */ + +/** + * @defgroup HAL_SUPPORT Support Code + * @brief HAL Support Code. + * + * @ingroup IO + */ + +/** + * @defgroup OSAL OSAL + * @brief Operating System Abstraction Layer. + * @details

The OSAL

+ * The OSAL is the link between ChibiOS/HAL and services + * provided by operating systems like: + * - Critical Zones handling. + * - Interrupts handling. + * - Runtime Errors management. + * - Inter-task synchronization. + * - Task-ISR synchronization. + * - Time management. + * - Events. + * . + * ChibiOS/HAL is designed to tightly integrate with the underlying + * RTOS in order to provide the best experience to developers and + * minimize integration issues.
+ * This section describes the API that OSALs are expected to expose + * to the HAL. + * + *

RTOS Requirements

+ * The OSAL API closely resembles the ChibiOS/RT API, for obvious + * reasons, however an OSAL module can be implemented for any + * reasonably complete RTOS or even a RTOS-less bare metal + * machine, if required.
+ * In order to be able to support an HAL an RTOS should support the + * following minimal set of features: + * - Task-level critical zones API. + * - ISR-level critical zones API, only required on those CPU + * architectures supporting preemptable ISRs like Cortex-Mx + * cores. + * - Ability to invoke API functions from inside a task critical + * zone. Functions that are required to support this feature are + * marked with an "I" or "S" letter at the end of the name. + * - Ability to invoke API functions from inside an ISR critical + * zone. Functions that are required to support this feature are + * marked with an "I" letter at the end of the name. + * - Tasks Queues or Counting Semaphores with Timeout capability. + * - Ability to suspend a task and wakeup it from ISR with Timeout + * capability. + * - Event flags, the mechanism can be simulated using callbacks in + * case the RTOS does not support it. + * - Mutual Exclusion mechanism like Semaphores or Mutexes. + * . + * All the above requirements can be satisfied even on naked HW with + * a very think SW layer. In case that the HAL is required to work + * without an RTOS. + * + *

Supported RTOSes

+ * The RTOSes supported out of the box are: + * - ChibiOS/RT + * - ChibiOS/NIL + * . + * Implementations have also been successfully created on RTOSes not + * belonging to the ChibiOS products family but are not supported + * as a core feature of ChibiOS/HAL. + * + * @ingroup IO + */ -- cgit v1.2.3