From 910404bbe44ef7735fe4010d8f042a3b3def219d Mon Sep 17 00:00:00 2001 From: Michael Leonard Date: Tue, 14 May 2024 18:23:59 -0500 Subject: [PATCH] Update README.md with a general introduction --- README.md | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) diff --git a/README.md b/README.md index 521af80..d8be563 100644 --- a/README.md +++ b/README.md @@ -11,3 +11,177 @@ Modules. Supported PMIC Devices are: 1. TPS653860x-Q1: Power Management IC for Safety-Relevant Applications + +## Driver Usage + +This section provides an introduction to how to use this driver within your project. + +### Getting Started + +Start by downloading this repository and placing it within your project +structure as appropriate. To ensure simplified delivery of future changes and +bugfixes, it is recommended to clone this repository into the desired location. + +git repositories can be cloned into a specific folder by specifying the desired +folder name as the last argument to the `git clone` command, as follows: + + git clone git@github.com:TexasInstruments/ti-pmic-lld.git + +To clone the **contents** of this repository into your current directory, use +the `.` folder name, such as: + + git clone git@github.com:TexasInstruments/ti-pmic-lld.git . + +Once the repository has been cloned, check-out the TPS653860x-Q1 support branch +(to track future changes) or check out a relevant release tag (to freeze +changes). The development branch for this device can be checked out with: + + git checkout device/blackbird + +#### Including in a Project + +To include the PMIC driver as part of a larger project, do the following: + +- Update compiler include path with the `include/` directory +- Update the compiler source files to compile all files in the `src/` directory + +To use the PMIC driver throughout the project, the user can then simply include +"pmic.h" and have access to all APIs provided by this driver. + +#### Generating API Documentation + +For more information on how to use each module, the header files are documented +using [Doxygen](https://www.doxygen.nl) syntax. This is fairly readable while +in source format, however Doxygen compiled documentation offers advantages of +better cross-referencing and some organization by topic. + +To generate the compiled Doxygen documentation included with this driver, +install Doxygen so that it is available on your command line and then execute +the following command from the PMIC driver root folder: + + doxygen docs/ti.doxyfile + +Alternatively, if you have Make/GMake installed, run the following command: + + make docs + +This will generate HTML documentation in the `docs/` folder which can be viewed +in a web browser. To view the documentation, open the file at +`docs/html/index.html`. + +#### Driver Initialization + +All APIs provided by this driver expect to receive a `Pmic_CoreHandle_t` in +order to handle communication with the device. This handle should be created +through the use of the `Pmic_CoreCfg_t` structure in `pmic.h` and the +`Pmic_init()` API. + +In order to successfully create a handle, the user will need to provide an +implementation for 4 APIs detailed below which inform the driver how to +operate on the specific platform. + +##### PMIC Handle User Functions: Critical Section Start/Stop + +When constructing `Pmic_CoreCfg_t`, two functions need to be provided in order +for the PMIC to obtain a critical section. These functions are called by the +driver before and after I2C/SPI communications. It is up to the user to +determine what is an appropriate implementation of these APIs as considerations +vary based on platform support and application complexity. + +For very simple microcontroller applications, blocking other interrupts or +claiming a simple global variable may be enough. For more complex applications +and on platforms which support it, a proper shared mutex should be +claimed/released as appropriate to ensure no other device drivers are +attempting to use the I2C/SPI bus at the same time. + +Within the `Pmic_CoreCfg_t` structure, these two functions are: + +```c +{ + .pFnPmicCritSecStart = , + .pFnPmicCritSecStop = , +} +``` + +##### PMIC Handle User Functions: Communications I/O Read/Write + +When constructing `Pmic_CoreCfg_t`, two functions need to be provided in order +for the PMIC to know how to read and write over the desired communications +channel (I2C or SPI, typically). The specific implementation of these functions +is platform dependent, the chosen processor likely has an SDK which provides +functions that match relatively closely. + +Within the `Pmic_CoreCfg_t` structure, these two functions are: + +```c +{ + .pFnPmicCommIoRead = , + .pFnPmicCommIoWrite = , +} +``` + +##### Finalizing Initialization + +Once the `Pmic_CoreCfg_t` structure has been initialized with the necessary +information, the user should call `Pmic_init()` in order to convert the +`Pmic_CoreCfg_t` into a `Pmic_CoreHandle_t` which will be used with the rest of +the driver APIs. + +A full example of what this may look like for TPS65386X-Q1 is shown below: + +```c +int32_t status; + +// The handle should either be declared globally, or stored in a structure that +// can manage access throughout the application, it will need to be re-used +// often. +Pmic_CoreHandle_t PmicHandle; + +Pmic_CoreCfg_t coreCfg = { + .validParams = ( + PMIC_CFG_DEVICE_TYPE_VALID_SHIFT | + PMIC_CFG_COMM_MODE_VALID_SHIFT | + PMIC_CFG_COMM_HANDLE_VALID_SHIFT | + PMIC_CFG_COMM_IO_RD_VALID_SHIFT | + PMIC_CFG_COMM_IO_WR_VALID_SHIFT | + PMIC_CFG_CRITSEC_START_VALID_SHIFT | + PMIC_CFG_CRITSEC_STOP_VALID_SHIFT + ), + .instType = PMIC_MAIN_INST, + .pmicDeviceType = PMIC_DEV_BB_TPS65386X, + .commMode = PMIC_INTF_SPI, + .pCommHandle = &commHandle, + .pFnPmicCommIoRead = PmicCommIoRead, + .pFnPmicCommIoWrite = PmicCommIoWrite, + .pFnPmicCritSecStart = CritSecStart, + .pFnPmicCritSecStop = CritSecStop, +}; + +status = Pmic_init(&PmicHandle, &coreCfg); + +// Check the return code of Pmic_init(), if it is PMIC_ST_SUCCESS, the +// PmicHandle is now valid for use throughout the rest of the application +if (status == PMIC_ST_SUCCESS) { + // other application code... +} +``` + +### CRC Enabled I/O + +This driver provides two APIs (`Pmic_ioRxByte()` and `Pmic_ioTxByte()`) +which are used internally, but may be useful to end-users in cases where driver +feature support does not exist. + +These APIs can be used to read from and write to any PMIC register and will +automatically perform the necessary CRC calculation and frame adjustments in +order to ensure successful communication. + +See `include/pmic_io.h` for more information on these APIs. + +### Watchdog + +The watchdog module for the PMIC driver supports configuration and status +reporting for PMIC watchdog features, and supports calculation and response for +Q&A watchdog mode. + +See `include/pmic_wdg.h` for more information on these APIs.