PMICDRV-157: Support initial release for Coach

Support the following features: - Basic I/O communications (w/ CRC support) - Register lock and unlock - Scratchpad register read and write - Watchdog configuration and control Signed-off-by: Michael Leonard <[email protected]>
TexasInstruments · Jun 13, 2024 · ec9255b · ec9255b
1 parent 6e34b3d
commit ec9255b
Show file tree

Hide file tree

Showing 15 changed files with 6,047 additions and 22 deletions.
diff --git a/Makefile b/Makefile
@@ -0,0 +1,107 @@
+# Copyright (c) 2024, Texas Instruments Incorporated
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# *  Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#
+# *  Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# *  Neither the name of Texas Instruments Incorporated nor the names of
+#    its contributors may be used to endorse or promote products derived
+#    from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+# OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+# WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+# OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+# EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+ifdef OS
+RM = rm
+RMDIR = rmdir
+MKDIR = mkdir
+unix_to_dos = $(subst /,\,$1)
+OSP = windows
+else
+ifeq ($(shell uname), Linux)
+RM = rm -f
+RMDIR = rm -rf
+MKDIR = mkdir -p
+OSP = unix
+else
+RM = rm -f
+RMDIR = rm -rf
+MKDIR = mkdir -p
+OSP = macos
+ifeq ($(CC),)
+CC := clang
+endif
+endif
+endif
+
+ifeq ($(CC),)
+CC := gcc
+endif
+
+INC	= -I./include
+
+CFLAGS = -fPIC $(INC) -Weverything \
+				 -Wno-documentation \
+				 -Wno-padded \
+				 -Wno-poison-system-directories
+LDFLAGS = -shared
+LIB_DIR = lib
+
+DEBUGFLAGS = -O0 -g -D _DEBUG
+RELEASEFLAGS = -O2 -D NDEBUG
+build ?= release
+
+ifeq ($(build), debug)
+    CFLAGS += $(DEBUGFLAGS)
+    TARGET = $(LIB_DIR)/libpmic.so
+endif
+
+ifeq ($(build), release)
+    CFLAGS += $(RELEASEFLAGS)
+    TARGET = $(LIB_DIR)/libpmic.so
+endif
+
+SOURCES = \
+	src/pmic.c \
+	src/pmic_common.c \
+	src/pmic_core.c \
+	src/pmic_wdg.c \
+	src/pmic_io.c
+
+OBJECTS = $(SOURCES:.c=.o)
+
+.PHONY: docs clean
+
+all: $(TARGET)
+
+$(TARGET): $(OBJECTS)
+	$(MKDIR) $(LIB_DIR)
+	$(call $(CC) $(CFLAGS) $(LDFLAGS) -o $(TARGET) $(OBJECTS))
+	$(CC) $(CFLAGS) $(LDFLAGS) -o $(TARGET) $(OBJECTS)
+	$(RM) $(OBJECTS)
+
+docs:
+	doxygen docs/ti.doxyfile
+
+clean:
+	$(RM) $(TARGET)
+	$(RM) $(OBJECTS)
+	$(RMDIR) docs/html/
+	$(RMDIR) $(LIB_DIR)
diff --git a/README.md b/README.md
@@ -1,31 +1,192 @@
-# Texas Instruments PMIC Low-Level Drivers (pmic-lld)
+# Texas Instruments PMIC Low-Level Driver (LLD) for Coach / LP8772X-Q1
 
-PMIC LLD is designed to support the control and configuration of various Texas
-Instruments power management ICs (PMICs) in a platform, processor, and OS
-agnostic manner.
+This is an API guide for PMIC (Power Management Integrated Circuit) Driver. PMIC
+Driver is designed to power up different components on the embedded boards or
+provide supply to MCU (Micro Controller Unit) or SoC (System on chip) using
+APIs provided in the guide.
 
-PMICs supported by this driver are intended for automotive and industrial
-applications and this driver is designed in compliance with the ISO 26262
-functional safety standard.
+The PMIC Driver supports below mentioned PMIC devices and their features or
+Modules.
 
-Architecturally, PMIC LLD provides a well-defined API that abstracts low-level
-details of the PMIC, allowing users to configure and control device features
-without the need to worry about register and bit-field level details.
+Supported PMIC Devices are:
 
-## Device Support Branches
+1. LP8772X-Q1: Three Buck Converters, one Linear Regulator and one Load Switch
+   for AWR and IWR Radar Sensors
 
-Device support is subdivided based on feature set:
+## Driver Usage
 
-| Part Number | Friendly Name | Support Branch           |
-| ----------- | ------------- | ------------------------ |
-| TPS6594x    | Leo           | `device/leo-hera-burton` |
-| LP8764x     | Hera          | `device/leo-hera-burton` |
-| TPS6522x    | Burton        | `device/leo-hera-burton` |
-| TPS653860xx | Blackbird     | `device/blackbird`       |
+This section provides an introduction to how to use this driver within your project.
 
-## Contributing
+### Getting Started
 
-Contributions are accepted through GitHub pull requests, Texas Instruments
-reserves the right to modify or reject contributions for any reason.
+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.
 
-See CODE_OF_CONDUCT.md and CONTRIBUTING.md for more information.
+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 [email protected]:TexasInstruments/ti-pmic-lld.git <DESIRED FOLDER NAME>
+
+To clone the **contents** of this repository into your current directory, use
+the `.` folder name, such as:
+
+    git clone [email protected]:TexasInstruments/ti-pmic-lld.git .
+
+Once the repository has been cloned, check-out the LP8772X-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/coach
+
+#### 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 = <your CS start function>,
+    .pFnPmicCritSecStop = <your CS stop function>,
+}
+```
+
+##### 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 = <your I/O read function>,
+    .pFnPmicCommIoWrite = <your I/O write function>,
+}
+```
+
+##### 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 LP8772X-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_CRC_ENABLE_VALID_SHIFT    |
+        PMIC_CFG_SLAVEADDR_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_COACH_LP8772X,
+    .commMode = PMIC_INTF_I2C_SINGLE,
+    .crcEnable = PMIC_ENABLE,
+    .slaveAddr = <Device I2C Address>,
+    .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.