[ARM] tegra: add nvos/nvrm/nvmap drivers

arch/arm/mach-tegra/nv/include/nvodm_services.h

Index: arch/arm/mach-tegra/nv/include/nvodm_services.h
diff --git a/arch/arm/mach-tegra/nv/include/nvodm_services.h b/arch/arm/mach-tegra/nv/include/nvodm_services.h
new file mode 100644
index 0000000000000000000000000000000000000000..904821ca80490d10ee706ad50499bd9e03ea8276
--- /dev/null
+++ b/arch/arm/mach-tegra/nv/include/nvodm_services.h
@@ -0,0 +1,1694 @@
+/*
+ * Copyright (c) 2007-2009 NVIDIA Corporation.
+ * 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 the NVIDIA Corporation 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 HOLDER 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.
+ *
+ */
+
+/**
+ * @file
+ * <b>NVIDIA Tegra ODM Kit:
+ *         ODM Services API</b>
+ *
+ * @b Description: Defines the abstraction to SOC resources used by
+ *                 external peripherals.
+ */
+
+#ifndef INCLUDED_NVODM_SERVICES_H
+#define INCLUDED_NVODM_SERVICES_H
+
+// Using addtogroup when defgroup resides in another file
+/**
+ * @addtogroup nvodm_services
+ * @{
+ */
+
+#include "nvcommon.h"
+#include "nvodm_modules.h"
+#include "nvassert.h"
+#include "nvcolor.h"
+#include "nvodm_query_pinmux.h"
+#include "nvodm_query.h"
+
+#if defined(__cplusplus)
+extern "C"
+{
+#endif
+
+/*
+ * This header is split into two sections: OS abstraction APIs and basic I/O
+ * driver APIs.
+ */
+
+/** @name OS Abstraction APIs
+ * The Operating System APIs are portable to any NVIDIA-supported operating
+ * system and will appear in all of the engineering sample code.
+ */
+/*@{*/
+
+/**
+ * Outputs a message to the console, if present. Do not use this for
+ * interacting with a user from an application.
+ *
+ * @param format A pointer to the format string. The format string and variable
+ * parameters exactly follow the posix printf standard.
+ */
+void
+NvOdmOsPrintf( const char *format, ...);
+
+/**
+ * Outputs a message to the debugging console, if present. Do not use this for
+ * interacting with a user from an application.
+ *
+ * @param format A pointer to the format string. The format string and variable
+ * parameters exactly follow the posix printf standard.
+ */
+void
+NvOdmOsDebugPrintf( const char *format, ... );
+
+/**
+ * Dynamically allocates memory. Alignment, if desired, must be done by the
+ * caller.
+ *
+ * @param size The size, in bytes, of the allocation request.
+ */
+void *
+NvOdmOsAlloc(size_t size);
+
+/**
+ * Frees a dynamic memory allocation.
+ *
+ * Freeing a NULL value is supported.
+ *
+ * @param ptr A pointer to the memory to free, which should be from NvOdmOsAlloc().
+ */
+void
+NvOdmOsFree(void *ptr);
+
+typedef struct NvOdmOsMutexRec *NvOdmOsMutexHandle;
+typedef struct NvOdmOsSemaphoreRec *NvOdmOsSemaphoreHandle;
+typedef struct NvOdmOsThreadRec *NvOdmOsThreadHandle;
+
+/**
+ * Copies a specified number of bytes from a source memory location to
+ * a destination memory location.
+ *
+ *  @param dest A pointer to the destination of the copy.
+ *  @param src A pointer to the source memory.
+ *  @param size The length of the copy in bytes.
+ */
+void
+NvOdmOsMemcpy(void *dest, const void *src, size_t size);
+
+/**
+ * Sets a region of memory to a value.
+ *
+ *  @param s A pointer to the memory region.
+ *  @param c The value to set.
+ *  @param size The length of the region in bytes.
+ */
+void
+NvOdmOsMemset(void *s, NvU8 c, size_t size);
+
+/**
+ * Create a new mutex.
+ *
+ * @note Mutexes can be locked recursively; if a thread owns the lock,
+ * it can lock it again as long as it unlocks it an equal number of times.
+ *
+ * @return NULL on failure.
+ */
+NvOdmOsMutexHandle
+NvOdmOsMutexCreate( void );
+
+/**
+ * Locks the given unlocked mutex.
+ *
+ * @note This is a recursive lock.
+ *
+ * @param mutex The mutex to lock.
+ */
+void
+NvOdmOsMutexLock( NvOdmOsMutexHandle mutex );
+
+/**
+ * Unlock a locked mutex.
+ *
+ * A mutex must be unlocked exactly as many times as it has been locked.
+ *
+ * @param mutex The mutex to unlock.
+ */
+void
+NvOdmOsMutexUnlock( NvOdmOsMutexHandle mutex );
+
+/**
+ * Frees the resources held by a mutex.
+ *
+ * @param mutex The mutex to destroy. Passing a NULL mutex is supported.
+ */
+void
+NvOdmOsMutexDestroy( NvOdmOsMutexHandle mutex );
+
+/**
+ * Creates a counting semaphore.
+ *
+ * @param value The initial semaphore value.
+ *
+ * @return NULL on failure.
+ */
+NvOdmOsSemaphoreHandle
+NvOdmOsSemaphoreCreate( NvU32 value );
+
+/**
+ * Waits until the semaphore value becomes non-zero.
+ *
+ * @param semaphore The semaphore for which to wait.
+ */
+void
+NvOdmOsSemaphoreWait( NvOdmOsSemaphoreHandle semaphore );
+
+/**
+ * Waits for the given semaphore value to become non-zero with timeout.
+ *
+ * @param semaphore The semaphore for which to wait.
+ * @param msec The timeout value in milliseconds. Use ::NV_WAIT_INFINITE
+ * to wait forever.
+ *
+ * @return NV_FALSE if the wait expires.
+ */
+NvBool
+NvOdmOsSemaphoreWaitTimeout( NvOdmOsSemaphoreHandle semaphore, NvU32 msec );
+
+/**
+ * Increments the semaphore value.
+ *
+ * @param semaphore The semaphore to signal.
+ */
+void
+NvOdmOsSemaphoreSignal( NvOdmOsSemaphoreHandle semaphore );
+
+/**
+ * Frees resources held by the semaphore.
+ *
+ * @param semaphore The semaphore to destroy. Passing in a NULL semaphore
+ * is supported (no op).
+ */
+void
+NvOdmOsSemaphoreDestroy( NvOdmOsSemaphoreHandle semaphore );
+
+/**
+ * Entry point for a thread.
+ */
+typedef void (*NvOdmOsThreadFunction)(void *args);
+
+/**
+ * Creates a thread.
+ *
+ *  @param function The thread entry point.
+ *  @param args The thread arguments.
+ *
+ * @return The thread handle, or NULL on failure.
+ */
+NvOdmOsThreadHandle
+NvOdmOsThreadCreate(
+    NvOdmOsThreadFunction function,
+    void *args);
+
+/**
+ * Waits for the given thread to exit.
+ *
+ *  The joined thread will be destroyed automatically. All OS resources
+ *  will be reclaimed. There is no method for terminating a thread
+ *  before it exits naturally.
+ *
+ *  Passing in a NULL thread ID is ok (no op).
+ *
+ *  @param thread The thread to wait for.
+ */
+void
+NvOdmOsThreadJoin(NvOdmOsThreadHandle thread);
+
+/**
+ *  Unschedules the calling thread for at least the given
+ *      number of milliseconds.
+ *
+ *  Other threads may run during the sleep time.
+ *
+ *  @param msec The number of milliseconds to sleep. This API should not be
+ *  called from an ISR, can be called from the IST though!
+ */
+void
+NvOdmOsSleepMS(NvU32 msec);
+
+
+/**
+ * Stalls the calling thread for at least the given number of
+ * microseconds. The actual time waited might be longer, so you cannot
+ * depend on this function for precise timing.
+ *
+ * @note It is safe to use this function at ISR time.
+ *
+ * @param usec The number of microseconds to wait.
+ */
+void
+NvOdmOsWaitUS(NvU32 usec);
+
+/**
+ * Gets the system time in milliseconds.
+ * The returned values are guaranteed to be monotonically increasing,
+ * but may wrap back to zero (after about 50 days of runtime).
+ *
+ * @return The system time in milliseconds.
+ */
+NvU32
+NvOdmOsGetTimeMS(void);
+
+/// Defines possible operating system types.
+typedef enum
+{
+    NvOdmOsOs_Unknown,
+    NvOdmOsOs_Windows,
+    NvOdmOsOs_Linux,
+    NvOdmOsOs_Aos,
+    NvOdmOsOs_Force32 = 0x7fffffffUL,
+} NvOdmOsOs;
+
+/// Defines possible operating system SKUs.
+typedef enum
+{
+    NvOdmOsSku_Unknown,
+    NvOdmOsSku_CeBase,
+    NvOdmOsSku_Mobile_SmartFon,
+    NvOdmOsSku_Mobile_PocketPC,
+    NvOdmOsSku_Android,
+    NvOdmOsSku_Force32 = 0x7fffffffUL,
+} NvOdmOsSku;
+
+/// Defines the OS information record.
+typedef struct NvOdmOsOsInfoRec
+{
+    NvOdmOsOs  OsType;
+    NvOdmOsSku Sku;
+    NvU16   MajorVersion;
+    NvU16   MinorVersion;
+    NvU32   SubVersion;
+    NvU32   Caps;
+} NvOdmOsOsInfo;
+
+/**
+ * Gets the current OS version.
+ *
+ * @param pOsInfo A pointer to the OS version.
+ * @return NV_TRUE if successful, or NV_FALSE otherwise.
+ */
+NvBool
+NvOdmOsGetOsInformation( NvOdmOsOsInfo *pOsInfo );
+
+/*@}*/
+/** @name Basic I/O Driver APIs
+ * The basic I/O driver APIs are a set of common input/outputs
+ * that can be used to extend the functionality of the software stack
+ * for new devices that aren't explicity handled by the stack.
+ * GPIO, I2C, and SPI are currently supported.
+*/
+/*@{*/
+
+/**
+ * Defines an opaque handle to the ODM Services GPIO rec interface.
+ */
+typedef struct NvOdmServicesGpioRec *NvOdmServicesGpioHandle;
+/**
+ * Defines an opaque handle to the ODM Services GPIO intr interface.
+ */
+typedef struct NvOdmServicesGpioIntrRec *NvOdmServicesGpioIntrHandle;
+/**
+ * Defines an opaque handle to the ODM Services SPI interface.
+ */
+typedef struct NvOdmServicesSpiRec *NvOdmServicesSpiHandle;
+/**
+ * Defines an opaque handle to the ODM Services I2C interface.
+ */
+typedef struct NvOdmServicesI2cRec *NvOdmServicesI2cHandle;
+/**
+ * Defines an opaque handle to the ODM Services PMU interface.
+ */
+typedef struct NvOdmServicesPmuRec *NvOdmServicesPmuHandle;
+/**
+ * Defines an opaque handle to the ODM Services PWM interface.
+ */
+typedef struct NvOdmServicesPwmRec *NvOdmServicesPwmHandle;
+/**
+ * Defines an opaque handle to the ODM Services key list interface.
+ */
+typedef struct NvOdmServicesKeyList *NvOdmServicesKeyListHandle;
+
+/**
+ * Defines an interrupt handler.
+ */
+typedef void (*NvOdmInterruptHandler)(void *args);
+
+/**
+ * @brief Defines the possible GPIO pin modes.
+ */
+typedef enum
+{
+    /// Specifies that that the pin is tristated, which will consume less power.
+    NvOdmGpioPinMode_Tristate = 1,
+
+    /// Specifies input mode with active low interrupt.
+    NvOdmGpioPinMode_InputInterruptLow,
+
+    /// Specifies input mode with active high interrupt.
+    NvOdmGpioPinMode_InputInterruptHigh,
+
+    /// Specifies input mode with no events.
+    NvOdmGpioPinMode_InputData,
+
+    /// Specifies output mode.
+    NvOdmGpioPinMode_Output,
+
+    /// Specifies special function.
+    NvOdmGpioPinMode_Function,
+
+    /// Specifies input and interrupt on any edge.
+    NvOdmGpioPinMode_InputInterruptAny,
+
+    /// Specifies input and interrupt on rising edge.
+    NvOdmGpioPinMode_InputInterruptRisingEdge,
+
+    /// Specifies output and interrupt on falling edge.
+    NvOdmGpioPinMode_InputInterruptFallingEdge,
+
+    /// Ignore -- Forces compilers to make 32-bit enums.
+    NvOdmGpioPinMode_Force32 = 0x7fffffff
+
+} NvOdmGpioPinMode;
+
+/**
+ * Defines the opaque handle to the GPIO pin.
+ */
+typedef struct NvOdmGpioPinRec *NvOdmGpioPinHandle;
+
+/**
+ * Creates and opens a GPIO handle. The handle can then be used to
+ * access GPIO functions.
+ *
+ * @see NvOdmGpioClose
+ *
+ * @return The handle to the GPIO controller, or NULL if an error occurred.
+ */
+NvOdmServicesGpioHandle NvOdmGpioOpen(void);
+
+/**
+ * Closes the GPIO handle. Any pin settings made while this handle is
+ * open will remain. All events enabled by this handle are
+ * disabled.
+ *
+ * @see NvOdmGpioOpen
+ *
+ * @param hOdmGpio The GPIO handle.
+ */
+void NvOdmGpioClose(NvOdmServicesGpioHandle hOdmGpio);
+
+/**
+ * Acquires a pin handle to be used in subsequent calls to
+ * access the pin.
+ *
+ * @see NvOdmGpioClose
+ *
+ * @param hOdmGpio The GPIO handle.
+ * @param port The port.
+ * @param Pin The pin for which to return the handle.
+ *
+ * @return The pin handle, or NULL if an error occurred.
+ */
+NvOdmGpioPinHandle
+NvOdmGpioAcquirePinHandle(NvOdmServicesGpioHandle hOdmGpio,
+        NvU32 port, NvU32 Pin);
+
+/**
+ * Releases the pin handle that was acquired by NvOdmGpioAcquirePinHandle()
+ * and used by the rest of the GPIO ODM APIs.
+ *
+ * @see NvOdmGpioAcquirePinHandle
+ *
+ * @param hOdmGpio The GPIO handle.
+ * @param hPin The pin handle to release.
+ */
+void
+NvOdmGpioReleasePinHandle(NvOdmServicesGpioHandle hOdmGpio,
+        NvOdmGpioPinHandle hPin);
+/**
+ * Sets the output state of a set of GPIO pins.
+ *
+ * @see NvOdmGpioOpen, NvOdmGpioGetState
+ *
+ * @param hOdmGpio The GPIO handle.
+ * @param hGpioPin The pin handle.
+ * @param PinValue The pin state to set. 0 means drive low, 1 means drive high.
+ */
+void
+NvOdmGpioSetState(NvOdmServicesGpioHandle hOdmGpio,
+    NvOdmGpioPinHandle hGpioPin,
+    NvU32 PinValue);
+
+/**
+ * Gets the output state of a specified set of GPIO pins in the port.
+ *
+ * @see NvOdmGpioOpen, NvOdmGpioSetState
+ *
+ * @param hOdmGpio The GPIO handle.
+ * @param hGpioPin The pin handle.
+ * @param pPinStateValue A pointer to the returned current state of the pin.
+ */
+void
+NvOdmGpioGetState(NvOdmServicesGpioHandle hOdmGpio,
+    NvOdmGpioPinHandle hGpioPin,
+    NvU32 *pPinStateValue);
+
+/**
+ * Configures the GPIO to specific mode. Don't use this API to configure the pin
+ * as interrupt pin, instead use the NvOdmGpioInterruptRegister
+ *  and NvOdmGpioInterruptUnregister APIs which internally call this function.
+ *
+ * @param hOdmGpio  The GPIO handle.
+ * @param hGpioPin  The pin handle.
+ * @param Mode      The mode type to configure.
+ */
+void
+NvOdmGpioConfig(NvOdmServicesGpioHandle hOdmGpio,
+    NvOdmGpioPinHandle hGpioPin,
+    NvOdmGpioPinMode Mode);
+
+/**
+ * Registers an interrupt callback function and the mode of interrupt for the
+ * GPIO pin specified.
+ *
+ * Callback uses the interrupt thread and the interrupt stack on Linux
+ * and IST on Windows CE; so, care should be taken on all the APIs used in
+ * the callback function.
+ *
+ * Interrupts are masked when they are triggered. It is up to the caller to
+ * re-enable the interrupts by calling NvOdmGpioInterruptDone().
+ *  
+ * @param hOdmGpio  The GPIO handle.
+ * @param hGpioIntr A pointer to the GPIO interrupt handle. Use this 
+ *  handle while unregistering the interrupt. On failure to hook
+ *  up the interrupt, a NULL handle is returned.
+ * @param hGpioPin  The pin handle.
+ * @param Mode      The mode type to configure. Allowed mode values are:
+ *  - NvOdmGpioPinMode_InputInterruptFallingEdge
+ *  - NvOdmGpioPinMode_InputInterruptRisingEdge
+ *  - NvOdmGpioPinMode_InputInterruptAny
+ *  - NvOdmGpioPinMode_InputInterruptLow
+ *  - NvOdmGpioPinMode_InputInterruptHigh
+ *  
+ * @param Callback The callback function that is called when 
+ *  the interrupt triggers.
+ * @param arg The argument used when the callback is called by the ISR. 
+ * @param DebounceTime The debounce time in milliseconds.
+ *
+ * @return NV_TRUE if successful, or NV_FALSE otherwise.
+ */
+NvBool
+NvOdmGpioInterruptRegister(NvOdmServicesGpioHandle hOdmGpio,
+    NvOdmServicesGpioIntrHandle *hGpioIntr,
+    NvOdmGpioPinHandle hGpioPin,
+    NvOdmGpioPinMode Mode,
+    NvOdmInterruptHandler Callback,
+    void *arg,
+    NvU32 DebounceTime);
+
+/**
+ *  Client of GPIO interrupt to re-enable the interrupt after
+ *  the handling the interrupt.
+ *
+ *  @param handle GPIO interrupt handle returned by a sucessfull call to
+ *  NvOdmGpioInterruptRegister().
+ */
+void NvOdmGpioInterruptDone( NvOdmServicesGpioIntrHandle handle );
+
+/**
+ * Mask/Unmask a gpio interrupt.
+ *
+ * Drivers can use this API to fend off interrupts. Mask means interrupts are
+ * not forwarded to the CPU. Unmask means, interrupts are forwarded to the CPU.
+ * In case of SMP systems, this API masks the interrutps to all the CPU, not
+ * just the calling CPU.
+ *
+ *
+ * @param handle    Interrupt handle returned by NvOdmGpioInterruptRegister API.
+ * @param mask      NV_FALSE to forrward the interrupt to CPU. NV_TRUE to 
+ * mask the interupts to CPU.
+ */
+void
+NvOdmGpioInterruptMask(NvOdmServicesGpioIntrHandle handle, NvBool mask);
+
+/**
+ * Unregisters the GPIO interrupt handler.
+ *
+ * @param hOdmGpio  The GPIO handle.
+ * @param hGpioPin  The pin handle.
+ * @param handle The interrupt handle returned by a successfull call to
+ * NvOdmGpioInterruptRegister().
+ *
+ */
+void
+NvOdmGpioInterruptUnregister(NvOdmServicesGpioHandle hOdmGpio,
+    NvOdmGpioPinHandle hGpioPin,
+    NvOdmServicesGpioIntrHandle handle);
+
+/**
+ * Obtains a handle that can be used to access one of the serial peripheral
+ * interface (SPI) controllers.
+ *
+ * There may be one or more instances of the SPI, depending upon the SOC,
+ * and these instances start from 0.
+ *
+ * @see NvOdmSpiClose
+ *
+ * @param OdmIoModule  The ODM I/O module for the SFLASH, SPI, or SLINK.
+ * @param ControllerId  The SPI controlled ID for which a handle is required.
+ *     Valid SPI channel IDs start from 0.
+ *
+ *
+ * @return The handle to the SPI controller, or NULL if an error occurred.
+ */
+NvOdmServicesSpiHandle NvOdmSpiOpen(NvOdmIoModule OdmIoModule, NvU32 ControllerId);
+
+/**
+ * Obtains a handle that can be used to access one of the serial peripheral
+ * interface (SPI) controllers, for SPI controllers which are multiplexed
+ * between multiple pin mux configurations. The SPI controller's pin mux
+ * will be reset to the specified value every transaction, so that two handles
+ * to the same controller may safely interleave across pin mux configurations.
+ *
+ * The ODM pin mux query for the specified controller must be
+ * NvOdmSpiPinMap_Multiplexed in order to create a handle using this function.
+ *
+ * There may be one or more instances of the SPI, depending upon the SOC,
+ * and these instances start from 0.
+ *
+ * Currently, this function is only supported for OdmIoModule_Spi, instance 2.
+ *
+ * @see NvOdmSpiClose
+ *
+ * @param OdmIoModule  The ODM I/O module for the SFLASH, SPI, or SLINK.
+ * @param ControllerId  The SPI controlled ID for which a handle is required.
+ *     Valid SPI channel IDs start from 0.
+ * @param PinMap The pin mux configuration to use for every transaction.
+ *
+ * @return The handle to the SPI controller, or NULL if an error occurred.
+ */
+NvOdmServicesSpiHandle 
+NvOdmSpiPinMuxOpen(NvOdmIoModule OdmIoModule,
+                   NvU32 ControllerId,
+                   NvOdmSpiPinMap PinMap);
+
+
+/**
+ * Obtains a handle that can be used to access one of the serial peripheral
+ * interface (SPI) controllers in slave mode.
+ *
+ * There may be one or more instances of the SPI, depending upon the SOC,
+ * and these instances start from 0.
+ *
+ * @see NvOdmSpiClose
+ *
+ * @param OdmIoModule  The ODM I/O module for the SFLASH, SPI, or SLINK.
+ * @param ControllerId  The SPI controlled ID for which a handle is required.
+ *     Valid SPI channel IDs start from 0.
+ *
+ *
+ * @return The handle to the SPI controller, or NULL if an error occurred.
+ */
+NvOdmServicesSpiHandle NvOdmSpiSlaveOpen(NvOdmIoModule OdmIoModule, NvU32 ControllerId);
+
+
+/**
+ * Releases a handle to an SPI controller. This API must be called once per
+ * successful call to NvOdmSpiOpen().
+ *
+ * @param hOdmSpi A SPI handle allocated in a call to \c NvOdmSpiOpen.  If \em hOdmSpi
+ *     is NULL, this API has no effect.
+ */
+void NvOdmSpiClose(NvOdmServicesSpiHandle hOdmSpi);
+
+/**
+ * Performs an SPI controller transaction. Every SPI transaction is by
+ * definition a simultaneous read and write transaction, so there are no
+ * separate APIs for read versus write. However, if you only need to do a read or
+ * write, this API allows you to declare that you are not interested in the read
+ * data, or that the write data is not of interest.
+ *
+ * This is a blocking API. When it returns, all of the data has been sent out
+ * over the pins of the SOC (the transaction). This is true even if the read data
+ * is being discarded, as it cannot merely have been queued up.
+ *
+ * Several SPI transactions may be performed in a single call to this API, but
+ * only if all of the transactions are to the same chip select and have the same
+ * packet size.
+ *
+ * Transaction sizes from 1 bit to 32 bits are supported. However, all
+ * of the buffers in memory are byte-aligned. To perform one transaction,
+ * the \em Size argument should be:
+ *
+ * <tt> <!-- typewriter font formats this nicely in the output document -->
+ *   (PacketSize + 7)/8
+ * </tt>
+ *
+ * To perform n transactions, \em Size should be:
+ *
+ * <tt>
+ *   n*((PacketSize + 7)/8)
+ * </tt>
+ *
+ * Within a given
+ * transaction with the packet size larger than 8 bits, the bytes are stored in 
+ * order of the MSB (most significant byte) first.
+ * The Packet is formed with the first Byte will be in MSB and then next byte 
+ * will be in the  next MSB towards the LSB.
+ *
+ * For the example, if One packet need to be send and its size is the 20 bit 
+ * then it will require the 3 bytes in the pWriteBuffer and arrangement of the 
+ * data  are as follows:
+ * The packet is 0x000ABCDE (Packet with length of 20 bit).
+ * pWriteBuff[0] = 0x0A
+ * pWriteBuff[1] = 0xBC
+ * pWtriteBuff[2] = 0xDE
+ *
+ * The most significant bit will be transmitted first i.e. bit20 is transmitted 
+ * first and bit 0 will be transmitted last.
+ *
+ * If the transmitted packet (command + receive data) is more than 32 like 33 and 
+ * want to transfer in the single call (CS should be active) then it can be transmitted
+ * in following way:
+ * The transfer is command(8 bit)+Dummy(1bit)+Read (24 bit) = 33 bit of transfer.
+ * - Send 33 bit as 33 byte and each byte have the 1 valid bit, So packet bit length = 1 and
+ * bytes requested = 33.
+ * NvU8 pSendData[33], pRecData[33];
+ *  pSendData[0] = (Comamnd >>7) & 0x1;
+ *  pSendData[1] = (Command >> 6)& 0x1; 
+ * ::::::::::::::
+ * pSendData[8] = DummyBit;
+ * pSendData[9] to pSendData[32] = 0;
+ * Call NvOdmSpiTransaction(hRmSpi,ChipSelect,ClockSpeedInKHz,pRecData, pSendData, 33,1);
+ * Now You will get the read data from pRecData[9] to pRecData[32] on bit 0 on each byte.
+ *
+ * - The 33 bit transfer can be also done as 11 byte and each byte have the 3 valid bits.
+ * This need to rearrange the command in the pSendData in such a way that each byte have the
+ * 3 valid bits.
+ * NvU8 pSendData[11], pRecData[11];
+ *  pSendData[0] = (Comamnd >>4) & 0x7;
+ *  pSendData[1] = (Command >> 1)& 0x7; 
+ *  pSendData[2] = (((Command)& 0x3) <<1) | DummyBit; 
+ * pSendData[3] to pSendData[10] = 0;
+ * 
+ * Call NvOdmSpiTransaction(hRmSpi, ChipSelect,ClockSpeedInKHz,pRecData, pSendData, 11,3);
+ * Now You will get the read data from pRecData[4] to pRecData[10] on lower 3 bits on each byte.
+ *
+ * Similarly the 33 bit transfer can also be done as 6 byte and each 2 bytes contain the 11 valid bits.
+ * Call NvOdmSpiTransaction(hRmSpi, ChipSelect,ClockSpeedInKHz,pRecData, pSendData, 6,11);
+ *
+ *
+ * \em ReadBuf and \em WriteBuf may be the same pointer, in which case the write
+ * data is destroyed as we read in the read data. Unless they are identical pointers,
+ * however, \em ReadBuf and \em WriteBuf must not overlap.
+ *
+ * @param hOdmSpi The SPI handle allocated in a call to NvOdmSpiOpen().
+ * @param ChipSelect Select with which of the several external devices (attached
+ *     to a single controller) we are communicating. Chip select indices
+ *     start at 0.
+ * @param ClockSpeedInKHz The speed in kHz on which the device can communicate.
+ * @param ReadBuf A pointer to buffer to be filled in with read data. If this
+ *     pointer is NULL, the read data will be discarded.
+ * @param WriteBuf A pointer to a buffer from which to obtain write data. If this
+ *     pointer is NULL, the write data will be all zeros.
+ * @param Size The size of \em ReadBuf and \em WriteBuf buffers in bytes.
+ * @param PacketSize The packet size in bits of each SPI transaction.
+ */
+void
+NvOdmSpiTransaction(
+    NvOdmServicesSpiHandle hOdmSpi,
+    NvU32 ChipSelect,
+    NvU32 ClockSpeedInKHz,
+    NvU8 *ReadBuf,
+    const NvU8 *WriteBuf,
+    NvU32 Size,
+    NvU32 PacketSize);
+
+
+/**
+ * Starts an SPI controller read and write simultaneously in the slave mode.
+ *
+ * This is a nonblocking API, which starts the data transfer and returns
+ * to the caller without waiting for the data transfer completion. 
+ *
+ * @note This API is only supported for the SPI handle, which is opened in
+ * slave mode using NvOdmSpiSlaveOpen(). This API asserts if the opened SPI
+ * handle is the master type.
+ *
+ * @see NvOdmSpiSlaveGetTransactionData
+ *
+ * @par Read or Write Transactions
+ *
+ * Every SPI transaction is by definition a simultaneous read and write 
+ * transaction, so there are no separate APIs for read versus write. 
+ * However, if you only need to start a read or write transaction, this API 
+ * allows you to declare that you are not interested in the read data, 
+ * or that the write data is not of interest. If only read
+ * is required to start, then the client can pass NV_TRUE to the \a IsReadTransfer
+ * parameter and a NULL pointer to \a pWriteBuffer. The state of the data out 
+ * will be set by NvOdmQuerySpiIdleSignalState::IsIdleDataOutHigh  
+ * in nvodm_query.h. Similarly, if the client wants to send data only
+ * then it can pass NV_FALSE to the \a IsReadTransfer parameter.
+ *
+ * @par Transaction Sizes
+ *
+ * Transaction sizes from 1 to 32 bits are supported. However, all of the 
+ * packets are byte-aligned in memory. So, if \a packetBitLength is 12 bits 
+ * then the client needs the 2nd byte for the 1 packet. New packets start from the
+ * new bytes, e.g., byte0 and byte1 contain the first packet and byte2 and byte3
+ * will contain the second packets.
+ *
+ * To perform one transaction, the \a BytesRequested argument should be:
+ * <pre>
+ *   (PacketSizeInBits + 7)/8
+ * </pre>
+ *
+ * To perform \a n transactions, \a BytesRequested should be:
+ * <pre>
+ *   n*((PacketSizeInBits + 7)/8)
+ * </pre>
+ *
+ * Within a given transaction with the packet size larger than 8 bits,
+ * the bytes are stored in the order of the LSB (least significant byte) first.
+ * The packet is formed with the first byte will be in LSB and then next byte 
+ * will be in the next LSB towards the MSB.
+ *  
+ * For example, if one packet needs to be sent and its size is 20 bits, 
+ * then it will require the 3 bytes in the \a pWriteBuffer and arrangement of
+ * the data  are as follows:
+ * - The packet is 0x000ABCDE (Packet with length of 20 bit).
+ * - pWriteBuff[0] = 0xDE
+ * - pWriteBuff[1] = 0xBC
+ * - pWtriteBuff[2] = 0x0A
+ *
+ * The most significant bit will be transmitted first, i.e., bit20 is transmitted 
+ * first and bit0 will be transmitted last.
+ *
+ * @par Transfer Size Limitations
+ *
+ * The limitation on the maximum transfer size of SPI slave communication
+ * depends upon the hardware. The maximum size of byte transfer is 64 K bytes
+ * if the number of packets requested is a multiple of: 
+ * - 4 for 8-bit packet length, or 
+ * - 2 for 16-bit packet length, or 
+ * - any number of packets for 32-bit packet length. 
+ *
+ * For all other cases, the maximum transfer bytes size is limited to 16 K
+ * packets, that is:
+ * <pre>
+ * 16K*((PacketBitLength +7)/8))
+ * </pre>
+ * 
+ * For the example: 
+ * - Non-multiples of 4 for the 8-bit packet length 
+ * - Non multiples of 2 for the 16-bit packet length 
+ * - Any other bit length except for the 32-bit packet length
+ * 
+ * This limitation comes from the:
+ * - Maximum HW DMA transfer of 64 KB
+ * - Maximum packet transfer for HW S-LINK controller of 64 K packets 
+ * - The design of packed/unpacked format of the S-LINK controller
+ *
+ * @par CAIF Use Case
+ * 
+ * The following describes a typical use case for the CAIF interface. The steps
+ * for doing the transfer are:
+ * -# ACPU calls the NvOdmSpiSlaveStartTransaction() to configure the SPI 
+ * controller to set in the receive or transmit mode and make ready for the 
+ * data transfer.
+ * -# ACPU then send the signal to the CCPU to send the SPICLK (by activating 
+ * the SPI_INT) and start the transaction. CCPU get this signal and start sending 
+ * SPICLK.
+ * -# ACPU will call the NvOdmSpiSlaveGetTransactionData() to get the 
+ * data/information about the transaction.
+ * -# After completion of the transfer ACPU inactivate the SPI_INT.
+ *
+ * @param hOdmSpi The SPI handle allocated in a call to NvOdmSpiSlaveOpen().
+ * @param ChipSelectId The chip select ID on which device is connected.
+ * @param ClockSpeedInKHz The clock speed in kHz on which device can communicate.
+ * @param IsReadTransfer Tells that whether or not the read transfer is required.
+ * If it is NV_TRUE then read transfer is required and the read data will be 
+ * available in the local buffer of the driver. The client will get the received
+ * data after calling the \c NvRmSpiGetTransactionData() function.
+ * @param pWriteBuffer A pointer to a buffer from which to obtain write data. 
+ * If this pointer is NULL, the write data will be all zeros.
+ * @param BytesRequested The size of \a pReadBuffer and \a pWriteBuffer buffers
+ * in bytes.
+ * @param PacketSizeInBits The packet size in bits of each SPI transaction.
+ *
+ * @return NV_TRUE if successful, or NV_FALSE otherwise.
+ */
+ NvBool NvOdmSpiSlaveStartTransaction( 
+    NvOdmServicesSpiHandle hOdmSpi,
+    NvU32 ChipSelectId,
+    NvU32 ClockSpeedInKHz,
+    NvBool IsReadTransfer,
+    NvU8 * pWriteBuffer,
+    NvU32 BytesRequested,
+    NvU32 PacketSizeInBits );
+
+/**
+ * Gets the SPI transaction status that is started for the slave mode and waits,
+ * if required, until the transfer completes for a given timeout error.
+ * If a read transaction has been started, then it returns the receive data to 
+ * the client.
+ *
+ * This is a blocking API and waits for the data transfer completion until the
+ * transfer completes or a timeout happens.
+ *
+ * @see NvOdmSpiSlaveStartTransaction
+ *
+ * @param hOdmSpi The SPI handle allocated in a call to NvOdmSpiSlaveOpen().
+ * @param pReadBuffer A pointer to a buffer to be filled in with read data. If this
+ * pointer is NULL, the read data will be discarded.
+ * @param BytesRequested The size of \a pReadBuffer and \a pWriteBuffer buffers
+ * in bytes.
+ * @param pBytesTransfererd A pointer to the number of bytes transferred.
+ * @param WaitTimeout The timeout in millisecond to wait for the transaction to be 
+ * completed.
+ *
+ * @return NV_TRUE if successful, or NV_FALSE otherwise.
+ *
+ */
+  NvBool NvOdmSpiSlaveGetTransactionData( 
+    NvOdmServicesSpiHandle hOdmSpi,
+    NvU8 * pReadBuffer,
+    NvU32 BytesRequested,
+    NvU32 * pBytesTransfererd,
+    NvU32 WaitTimeout );
+
+/**
+ * Sets the signal mode for the SPI communication for a given chip select.
+ * After calling this API, further communication happens with the newly 
+ * configured signal modes.
+ * The default value of the signal mode is taken from ODM Query, and this
+ * API overrides the signal mode that is read from the query.
+ *
+ * @param hOdmSpi The SPI handle allocated in a call to NvOdmSpiOpen().
+ * @param ChipSelectId The chip select ID to which the device is connected.
+ * @param SpiSignalMode The ODM signal mode to be set.
+ *
+ */
+void
+NvOdmSpiSetSignalMode(
+    NvOdmServicesSpiHandle hOdmSpi,
+    NvU32 ChipSelectId,
+    NvOdmQuerySpiSignalMode SpiSignalMode);
+
+/// Contains the error flags for the I2C transaction.
+typedef enum
+{
+    NvOdmI2cStatus_Success = 0,
+    NvOdmI2cStatus_Timeout,
+    NvOdmI2cStatus_SlaveNotFound,
+    NvOdmI2cStatus_InvalidTransferSize,
+    NvOdmI2cStatus_ReadFailed,
+    NvOdmI2cStatus_WriteFailed,
+    NvOdmI2cStatus_InternalError,
+    NvOdmI2cStatus_ArbitrationFailed,
+    NvOdmI2cStatus_Force32 = 0x7FFFFFFF
+} NvOdmI2cStatus;
+
+/// Flag to indicate the I2C write/read operation.
+#define NVODM_I2C_IS_WRITE            0x00000001
+/// Flag to indicate the I2C slave address type as 10-bit or 7-bit.
+#define NVODM_I2C_IS_10_BIT_ADDRESS   0x00000002
+/// Flag to indicate the I2C transaction with repeat start.
+#define NVODM_I2C_USE_REPEATED_START  0x00000004
+/// Flag to indicate that the I2C slave will not generate ACK.
+#define NVODM_I2C_NO_ACK              0x00000008
+/// Flag to indicate software I2C using GPIO.
+#define NVODM_I2C_SOFTWARE_CONTROLLER 0x00000010
+
+
+/// Contians the I2C transaction details.
+typedef struct
+{
+    /// Flags to indicate the transaction details, like write/read operation,
+    /// slave address type 10-bit or 7-bit and the transaction uses repeat
+    /// start or a normal transaction.
+    NvU32 Flags;
+    /// I2C slave device address.
+    NvU32 Address;
+    /// Number of bytes to be transferred.
+    NvU32 NumBytes;
+    /// Send/receive buffer. For I2C send operation this buffer should be
+    /// filled with the data to be sent to the slave device. For I2C receive
+    /// operation this buffer is filled with the data received from the slave device.
+    NvU8 *Buf;
+} NvOdmI2cTransactionInfo;
+
+/**
+ * Initializes and opens the I2C channel. This function allocates the
+ * handle for the I2C channel and provides it to the client.
+ *
+ * @see NvOdmI2cClose
+ *
+ * @param OdmIoModuleId  The ODM I/O module for I2C.
+ * @param instance The instance of the I2C driver to be opened.
+ *
+ * @return The handle to the I2C controller, or NULL if an error occurred.
+ */
+NvOdmServicesI2cHandle
+NvOdmI2cOpen(
+    NvOdmIoModule OdmIoModuleId,
+    NvU32 instance);
+
+/**
+ * Obtains a handle that can be used to access one of the I2C controllers, 
+ * for I2C controllers which are multiplexed between multiple pin mux 
+ * configurations. The I2C controller's pin mux will be reset to the specified 
+ * value every transaction, so that two handles to the same controller may 
+ * safely interleave across pin mux configurations.
+ *
+ * The ODM pin mux query for the specified controller must be
+ * NvOdmI2cPinMap_Multiplexed in order to create a handle using this function.
+ *
+ * There may be one or more instances of the I2C, depending upon the SOC,
+ * and these instances start from 0.
+ *
+ * Currently, this function is only supported for OdmIoModule_I2C, instance 1.
+ *
+ * @see NvOdmI2cClose
+ *
+ * @param OdmIoModule  The ODM I/O module for the I2C.
+ * @param ControllerId  The I2C controlled ID for which a handle is required.
+ *     Valid I2C controller IDs start from 0.
+ * @param PinMap The pin mux configuration to use for every transaction.
+ *
+ * @return The handle to the I2C controller, or NULL if an error occurred.
+ */
+NvOdmServicesI2cHandle 
+NvOdmI2cPinMuxOpen(NvOdmIoModule OdmIoModule,
+                   NvU32 ControllerId,
+                   NvOdmI2cPinMap PinMap);
+
+/**
+ * Closes the I2C channel. This function frees the memory allocated for
+ * the I2C handle and de-initializes the I2C ODM channel.
+ *
+ * @see NvOdmI2cOpen
+ *
+ * @param hOdmI2c The handle to the I2C channel.
+ */
+void NvOdmI2cClose(NvOdmServicesI2cHandle hOdmI2c);
+
+/**
+ * Does the I2C send or receive transactions with the slave deivces. This is a
+ * blocking call (with timeout). This API works for both the normal I2C transactions
+ * or I2C transactions in repeat start mode.
+ *
+ * For the I2C transactions with slave devices, a pointer to the list of required
+ * transactions must be passed and the corresponding number of transactions must
+ * be passed.
+ *
+ * The transaction information structure contains the flags (to indicate the
+ * transaction information, such as read or write transaction, transaction is with
+ * repeat-start or normal transaction and the slave device address type is 7-bit or
+ * 10-bit), slave deivce address, buffer to be transferred and number of bytes
+ * to be transferred.
+ *
+ * @param hOdmI2c The handle to the I2C channel.
+ * @param TransactionInfo A pointer to the array of I2C transaction structures.
+ * @param NumberOfTransactions The number of I2C transactions.
+ * @param ClockSpeedKHz Specifies the clock speed for the I2C transactions.
+ * @param WaitTimeoutInMilliSeconds The timeout in milliseconds.
+ *  ::NV_WAIT_INFINITE specifies to wait forever.
+ *
+ * @retval NvOdmI2cStatus_Success If successful, or the appropriate error code.
+ */
+NvOdmI2cStatus
+NvOdmI2cTransaction(
+    NvOdmServicesI2cHandle hOdmI2c,
+    NvOdmI2cTransactionInfo *TransactionInfo,
+    NvU32 NumberOfTransactions,
+    NvU32 ClockSpeedKHz,
+    NvU32 WaitTimeoutInMilliSeconds);
+
+/**
+ *  Defines the PMU VDD rail capabilities.
+ */
+typedef struct NvOdmServicesPmuVddRailCapabilitiesRec
+{
+    /// Specifies ODM protection attribute; if \c NV_TRUE PMU hardware
+    ///  or ODM Kit would protect this voltage from being changed by NvDdk client.
+    NvBool RmProtected;
+
+    /// Specifies the minimum voltage level in mV.
+    NvU32 MinMilliVolts;
+
+    /// Specifies the step voltage level in mV.
+    NvU32 StepMilliVolts;
+
+    /// Specifies the maximum voltage level in mV.
+    NvU32 MaxMilliVolts;
+
+    /// Specifies the request voltage level in mV.
+    NvU32 requestMilliVolts;
+
+} NvOdmServicesPmuVddRailCapabilities;
+
+/// Special level to indicate voltage plane is disabled.
+#define NVODM_VOLTAGE_OFF (0UL)
+
+/**
+ * Initializes and opens the PMU driver. The handle that is returned by this
+ * driver is used for all the other PMU operations.
+ *
+ * @see NvOdmPmuClose
+ *
+ * @return The handle to the PMU driver, or NULL if an error occurred.
+ */
+NvOdmServicesPmuHandle NvOdmServicesPmuOpen(void);
+
+/**
+ * Closes the PMU handle.
+ *
+ * @see NvOdmServicesPmuOpen
+ *
+ * @param handle The handle to the PMU driver.
+ */
+void NvOdmServicesPmuClose(NvOdmServicesPmuHandle handle);
+
+/**
+ * Gets capabilities for the specified PMU rail.
+ *
+ * @param handle The handle to the PMU driver.
+ * @param vddId The ODM-defined PMU rail ID.
+ * @param pCapabilities A pointer to the targeted
+ *  capabilities returned by the ODM.
+ *
+ */
+void NvOdmServicesPmuGetCapabilities(
+        NvOdmServicesPmuHandle handle,
+        NvU32 vddId,
+        NvOdmServicesPmuVddRailCapabilities * pCapabilities );
+
+/**
+ * Gets current voltage level for the specified PMU rail.
+ *
+ * @param handle The handle to the PMU driver.
+ * @param vddId The ODM-defined PMU rail ID.
+ * @param pMilliVolts A pointer to the voltage level returned
+ *  by the ODM.
+ */
+void NvOdmServicesPmuGetVoltage(
+        NvOdmServicesPmuHandle handle,
+        NvU32 vddId,
+        NvU32 * pMilliVolts );
+
+/**
+ * Sets new voltage level for the specified PMU rail.
+ *
+ * @param handle The handle to the PMU driver.
+ * @param vddId The ODM-defined PMU rail ID.
+ * @param MilliVolts The new voltage level to be set in millivolts (mV).
+ *  Set to ::NVODM_VOLTAGE_OFF to turn off the target voltage.
+ * @param pSettleMicroSeconds A pointer to the settling time in microseconds (uS),
+ *  which is the time for supply voltage to settle after this function
+ *  returns; this may or may not include PMU control interface transaction time,
+ *  depending on the ODM implementation. If NULL this parameter is ignored.
+ */
+void NvOdmServicesPmuSetVoltage(
+        NvOdmServicesPmuHandle handle,
+        NvU32 vddId,
+        NvU32 MilliVolts,
+        NvU32 * pSettleMicroSeconds );
+
+/**
+ * Configures SoC power rail controls for the upcoming PMU voltage transition.
+ *
+ * @note Should be called just before PMU rail On/Off, or Off/On transition.
+ *  Should not be called if rail voltage level is changing within On range.
+ * 
+ * @param handle The handle to the PMU driver.
+ * @param vddId The ODM-defined PMU rail ID.
+ * @param Enable Set NV_TRUE if target voltage is about to be turned On, or
+ *  NV_FALSE if target voltage is about to be turned Off.
+ */
+void NvOdmServicesPmuSetSocRailPowerState(
+        NvOdmServicesPmuHandle handle,
+        NvU32 vddId, 
+        NvBool Enable );
+
+/**
+ * Defines battery instances.
+ */
+typedef enum
+{
+    /// Specifies main battery.
+    NvOdmServicesPmuBatteryInst_Main,
+
+    /// Specifies backup battery.
+    NvOdmServicesPmuBatteryInst_Backup,
+
+    /// Ignore -- Forces compilers to make 32-bit enums.
+    NvOdmServicesPmuBatteryInstance_Force32 = 0x7FFFFFFF
+} NvOdmServicesPmuBatteryInstance;
+
+/**
+ * Gets the battery status.
+ *
+ * @param handle The handle to the PMU driver.
+ * @param batteryInst The battery type.
+ * @param pStatus A pointer to the battery
+ *  status returned by the ODM.
+ * 
+ * @return NV_TRUE if successful, or NV_FALSE otherwise.
+ */
+NvBool 
+NvOdmServicesPmuGetBatteryStatus(
+    NvOdmServicesPmuHandle handle,
+    NvOdmServicesPmuBatteryInstance batteryInst,
+    NvU8 * pStatus);
+
+/**
+ * Defines battery data.
+ */
+typedef struct NvOdmServicesPmuBatteryDataRec
+{
+    /// Specifies battery life percent.
+    NvU32 batteryLifePercent;
+
+    /// Specifies battery life time.
+    NvU32 batteryLifeTime;
+
+    /// Specifies voltage.
+    NvU32 batteryVoltage;
+    
+    /// Specifies battery current.
+    NvS32 batteryCurrent;
+
+    /// Specifies battery average current.
+    NvS32 batteryAverageCurrent;
+
+    /// Specifies battery interval.
+    NvU32 batteryAverageInterval;
+
+    /// Specifies the mAH consumed.
+    NvU32 batteryMahConsumed;
+
+    /// Specifies battery temperature.
+    NvU32 batteryTemperature;
+} NvOdmServicesPmuBatteryData;
+
+/**
+ * Gets the battery data.
+ *
+ * @param handle The handle to the PMU driver.
+ * @param batteryInst The battery type.
+ * @param pData A pointer to the battery
+ *  data returned by the ODM.
+ * 
+ * @return NV_TRUE if successful, or NV_FALSE otherwise.
+ */
+NvBool
+NvOdmServicesPmuGetBatteryData(
+    NvOdmServicesPmuHandle handle,
+    NvOdmServicesPmuBatteryInstance batteryInst,
+    NvOdmServicesPmuBatteryData * pData);
+
+/**
+ * Gets the battery full lifetime.
+ *
+ * @param handle The handle to the PMU driver.
+ * @param batteryInst The battery type.
+ * @param pLifeTime A pointer to the battery
+ *  full lifetime returned by the ODM.
+ */
+void
+NvOdmServicesPmuGetBatteryFullLifeTime(
+    NvOdmServicesPmuHandle handle,
+    NvOdmServicesPmuBatteryInstance batteryInst,
+    NvU32 * pLifeTime);
+
+/**
+ * Defines battery chemistry.
+ */
+typedef enum
+{
+    /// Specifies an alkaline battery.
+    NvOdmServicesPmuBatteryChemistry_Alkaline,
+
+    /// Specifies a nickel-cadmium (NiCd) battery.
+    NvOdmServicesPmuBatteryChemistry_NICD,
+
+    /// Specifies a nickel-metal hydride (NiMH) battery.
+    NvOdmServicesPmuBatteryChemistry_NIMH,
+
+    /// Specifies a lithium-ion (Li-ion) battery.
+    NvOdmServicesPmuBatteryChemistry_LION,
+
+    /// Specifies a lithium-ion polymer (Li-poly) battery.
+    NvOdmServicesPmuBatteryChemistry_LIPOLY,
+
+    /// Specifies a zinc-air battery.
+    NvOdmServicesPmuBatteryChemistry_XINCAIR,
+
+    /// Ignore -- Forces compilers to make 32-bit enums.
+    NvOdmServicesPmuBatteryChemistry_Force32 = 0x7FFFFFFF
+} NvOdmServicesPmuBatteryChemistry;
+
+/**
+ * Gets the battery chemistry.
+ *
+ * @param handle The handle to the PMU driver.
+ * @param batteryInst The battery type.
+ * @param pChemistry A pointer to the battery
+ *  chemistry returned by the ODM.
+ */
+void
+NvOdmServicesPmuGetBatteryChemistry(
+    NvOdmServicesPmuHandle handle,
+    NvOdmServicesPmuBatteryInstance batteryInst,
+    NvOdmServicesPmuBatteryChemistry * pChemistry);
+
+/**
+ * Defines the charging path.
+ */
+typedef enum
+{
+    /// Specifies external wall plug charger.
+    NvOdmServicesPmuChargingPath_MainPlug, 
+
+    /// Specifies external USB bus charger.
+    NvOdmServicesPmuChargingPath_UsbBus,
+
+    /// Ignore -- Forces compilers to make 32-bit enums.
+    NvOdmServicesPmuChargingPath_Force32 = 0x7FFFFFFF
+} NvOdmServicesPmuChargingPath;
+
+/** 
+* Sets the charging current limit. 
+* 
+* @param handle The Rm device handle.
+* @param ChargingPath The charging path. 
+* @param ChargingCurrentLimitMa The charging current limit in mA. 
+* @param ChargerType The charger type.
+*/
+void 
+NvOdmServicesPmuSetChargingCurrentLimit( 
+    NvOdmServicesPmuHandle handle,
+    NvOdmServicesPmuChargingPath ChargingPath,
+    NvU32 ChargingCurrentLimitMa,
+    NvOdmUsbChargerType ChargerType);
+
+/**
+ * Obtains a handle to set or get state of keys, for example, the state of the
+ * hold switch.
+ *
+ * @see NvOdmServicesKeyListClose()
+ *
+ * @return A handle to the key-list, or NULL if this open call fails.
+ */
+NvOdmServicesKeyListHandle
+NvOdmServicesKeyListOpen(void);
+
+/**
+ * Releases the handle obtained during the NvOdmServicesKeyListOpen() call and
+ * any other resources allocated.
+ *
+ * @param handle The handle returned from the \c NvOdmServicesKeyListOpen call.
+ */
+void NvOdmServicesKeyListClose(NvOdmServicesKeyListHandle handle);
+
+/**
+ * Searches the list of keys present and returns the value of the appropriate
+ * key.
+ * @param handle The handle obtained from NvOdmServicesKeyListOpen().
+ * @param KeyID The ID of the key whose value is required.
+ *
+ * @return The value of the corresponding key, or 0 if the key is not
+ * present in the list.
+ */
+NvU32
+NvOdmServicesGetKeyValue(
+            NvOdmServicesKeyListHandle handle,
+            NvU32 KeyID);
+
+/**
+ * Searches the list of keys present and sets the value of the key to the value
+ * given. If the key is not present, it adds the key to the list and sets the
+ * value.
+ * @param handle The handle obtained from NvOdmServicesKeyListOpen().
+ * @param Key The ID of the key whose value is to be set.
+ * @param Value The value to be set for the corresponding key.
+ *
+ * @return NV_TRUE if successful, or NV_FALSE otherwise.
+ */
+NvBool
+NvOdmServicesSetKeyValuePair(
+            NvOdmServicesKeyListHandle handle,
+            NvU32 Key,
+            NvU32 Value);
+
+/**
+ * @brief Defines the possible PWM modes.
+ */
+
+typedef enum
+{
+    /// Specifies Pwm disabled mode.
+    NvOdmPwmMode_Disable = 1,
+
+    /// Specifies Pwm enabled mode.
+    NvOdmPwmMode_Enable,
+
+    /// Specifies Blink LED enabled mode
+    NvOdmPwmMode_Blink_LED,
+
+    /// Specifies Blink output 32KHz clock enable mode
+    NvOdmPwmMode_Blink_32KHzClockOutput,
+
+    /// Specifies Blink disabled mode
+    NvOdmPwmMode_Blink_Disable,
+
+    NvOdmPwmMode_Force32 = 0x7fffffffUL
+
+} NvOdmPwmMode;
+
+/**
+ * @brief Defines the possible PWM output pin.
+ */
+
+typedef enum
+{
+    /// Specifies PWM Output-0.
+    NvOdmPwmOutputId_PWM0 = 1,
+
+    /// Specifies PWM Output-1.
+    NvOdmPwmOutputId_PWM1,
+
+    /// Specifies PWM Output-2.
+    NvOdmPwmOutputId_PWM2,
+
+    /// Specifies PWM Output-3.
+    NvOdmPwmOutputId_PWM3,
+
+    /// Specifies PMC Blink LED.
+    NvOdmPwmOutputId_Blink, 
+
+    NvOdmPwmOutputId_Force32 = 0x7fffffffUL
+
+} NvOdmPwmOutputId;
+
+/**
+ * Creates and opens a PWM handle. The handle can be used to
+ * access PWM functions.
+ *
+ * @note Only the service client knows when the service can go idle,
+ * like in the case of vibrator, so the client suspend entry code
+ * must call NvOdmPwmClose() to close the PWM service.
+ *
+ * @return The handle to the PWM controller, or NULL if an error occurred.
+ */
+NvOdmServicesPwmHandle NvOdmPwmOpen(void);
+
+/**
+ * Releases a handle to a PWM controller. This API must be called once per
+ * successful call to NvOdmPwmOpen().
+ *
+ * @param hOdmPwm The handle to the PWM controller.
+ */
+void NvOdmPwmClose(NvOdmServicesPwmHandle hOdmPwm);
+
+/**
+ *  @brief Configures PWM module as disable/enable. This API is also
+ *  used to set the PWM duty cycle and frequency. Beside that, it is 
+ *  used to configure PMC' blinking LED if OutputId is 
+ *  NvOdmPwmOutputId_Blink
+ *
+ *  @param hOdmPwm The PWM handle obtained from NvOdmPwmOpen().
+ *  @param OutputId The PWM output pin to configure. Allowed values are
+ *   defined in ::NvOdmPwmOutputId.
+ *  @param Mode The mode type to configure. Allowed values are
+ *   defined in ::NvOdmPwmMode.
+ *  @param DutyCycle The duty cycle is an unsigned 15.16 fixed point
+ *   value that represents the PWM duty cycle in percentage range from
+ *   0.00 to 100.00. For example, 10.5 percentage duty cycle would be
+ *   represented as 0x000A8000. This parameter is ignored if NvOdmPwmMode
+ *   is NvOdmMode_Blink_32KHzClockOutput or NvOdmMode_Blink_Disable
+ *  @param pRequestedFreqHzOrPeriod A pointer to the request frequency in Hz
+ *   or period in second
+ *   A requested frequency value beyond the maximum supported value will be
+ *   clamped to the maximum supported value. If \em pRequestedFreqHzOrPeriod 
+ *   is NULL, it returns the maximum supported frequency. This parameter is 
+ *   ignored if NvOdmPwmMode is NvOdmMode_Blink_32KHzClockOutput or
+ *   NvOdmMode_Blink_Disable
+ *  @param pCurrentFreqHzOrPeriod A pointer to the returned frequency of 
+ *   that mode. If PMC Blink LED is used then it is the pointer to the returns 
+ *   period time. This parameter is ignored if NvOdmPwmMode is
+ *   NvOdmMode_Blink_32KHzClockOutput or NvOdmMode_Blink_Disable
+ */
+void
+NvOdmPwmConfig(NvOdmServicesPwmHandle hOdmPwm,
+    NvOdmPwmOutputId OutputId, 
+    NvOdmPwmMode Mode,            
+    NvU32 DutyCycle,
+    NvU32 *pRequestedFreqHzOrPeriod,
+    NvU32 *pCurrentFreqHzOrPeriod);
+
+/**
+ * Enables and disables external clock interfaces (e.g., CDEV and CSUS pins)
+ * for the specified peripheral. External clock sources should be enabled
+ * prior to programming peripherals reliant on them. If multiple peripherals use
+ * the same external clock source, it is safe to call this API multiple times.
+ *
+ * @param Guid The ODM-defined GUID of the peripheral to be configured. The
+ *             peripheral should have an @see NvOdmIoAddress entry for the
+ *             NvOdmIoModule_ExternalClock device interface. If multiple
+ *             external clock interfaces are specified, all will be
+ *             enabled (disabled).
+ *
+ * @param EnableTristate NV_TRUE will tristate the specified clock sources,
+ *             NV_FALSE will drive them.
+ *  
+ * @param pInstances Returns the list of clocks that were enabled.
+ *  
+ * @param pFrequencies Returns the frequency, in kHz, that is 
+ *                     being output on each clock pin
+ *  
+ * @param pNum Returns the number of clocks that were enabled.
+ *
+ * @return NV_TRUE if successful, or NV_FALSE otherwise.
+ */
+NvBool
+NvOdmExternalClockConfig(
+    NvU64 Guid,
+    NvBool EnableTristate,
+    NvU32 *pInstances,
+    NvU32 *pFrequencies,
+    NvU32 *pNum);
+
+/**
+ *  Defines SoC strap groups.
+ */
+typedef enum
+{
+    /// Specifies the ram_code strap group.
+    NvOdmStrapGroup_RamCode = 1,
+
+    NvOdmStrapGroup_Num,
+    NvOdmStrapGroup_Force32 = 0x7FFFFFFF
+} NvOdmStrapGroup;
+
+/**
+ * Gets SoC strap value for the given strap group.
+ * 
+ * @note The strap assignment on each platform must be consistent with SoC
+ *  bootrom specifications and platform-specific BCT contents. The strap
+ *  value usage in ODM queries, however, is not limited to bootrom defined
+ *  functionality. The mapping between strap values and platforms is the ODM's
+ *  responsibility. ODMs should also ensure that they are using strap groups
+ *  that match the SOC in their product.
+ * 
+ * @param StrapGroup The strap group to be read.
+ * @param pStrapValue A pointer to the returned strap group value.
+ *  This value can be used by ODM queries to identify ODM platforms and to
+ *  provide the respective configuration settings.
+ *  
+ * @return NV_TRUE if successful, or NV_FALSE otherwise.
+ */
+NvBool NvOdmGetStraps(NvOdmStrapGroup StrapGroup, NvU32* pStrapValue);
+
+/**
+ * File input/output.
+ */
+typedef void* NvOdmOsFileHandle;
+
+/**
+ *  Defines the OS file types.
+ */
+typedef enum
+{
+    NvOdmOsFileType_Unknown = 0,
+    NvOdmOsFileType_File,
+    NvOdmOsFileType_Directory,
+    NvOdmOsFileType_Fifo,
+
+    NvOdmOsFileType_Force32 = 0x7FFFFFFF
+} NvOdmOsFileType;
+
+/**
+ *  Defines the OS status type.
+ */
+typedef struct NvOdmOsStatTypeRec
+{
+    NvU64 size;
+    NvOdmOsFileType type;
+} NvOdmOsStatType;
+
+/** Open a file with read permissions. */
+#define NVODMOS_OPEN_READ    0x1
+
+/** Open a file with write persmissions. */
+#define NVODMOS_OPEN_WRITE   0x2
+
+/** Create a file if is not present on the file system. */
+#define NVODMOS_OPEN_CREATE  0x4
+
+/**
+ *  Opens a file stream.
+ *
+ *  If the ::NVODMOS_OPEN_CREATE flag is specified, ::NVODMOS_OPEN_WRITE must also
+ *  be specified.
+ *
+ *  If ::NVODMOS_OPEN_WRITE is specified the file will be opened for write and
+ *  will be truncated if it was previously existing.
+ *
+ *  If ::NVODMOS_OPEN_WRITE and ::NVODMOS_OPEN_READ is specified the file will not
+ *  be truncated.
+ *
+ *  @param path A pointer to the path to the file.
+ *  @param flags ORed flags for the open operation (NVODMOS_OPEN_*).
+ *  @param file [out] A pointer to the file that will be opened, if successful.
+ *
+ *  @return NV_TRUE if successful, or NV_FALSE otherwise.
+ */
+NvBool
+NvOdmOsFopen(const char *path, NvU32 flags, NvOdmOsFileHandle *file);
+
+/**
+ *  Closes a file stream.
+ *  Passing in a NULL handle is okay.
+ *
+ *  @param stream The file stream to close.
+ */
+void NvOdmOsFclose(NvOdmOsFileHandle stream);
+
+/**
+ *  Writes to a file stream.
+ *
+ *  @param stream The file stream.
+ *  @param ptr A pointer to the data to write.
+ *  @param size The length of the write.
+ *
+ *  @return NV_TRUE if successful, or NV_FALSE otherwise.
+ */
+NvBool
+NvOdmOsFwrite(NvOdmOsFileHandle stream, const void *ptr, size_t size);
+
+/**
+ *  Reads a file stream.
+ *
+ *  To detect short reads (less that specified amount), pass in \a bytes
+ *  and check its value to the expected value. The \a bytes parameter may
+ *  be NULL.
+ *
+ *  @param stream The file stream.
+ *  @param ptr A pointer to the buffer for the read data.
+ *  @param size The length of the read.
+ *  @param bytes [out] A pointer to the number of bytes read -- may be NULL.
+ *
+ *  @return NV_TRUE if successful, or NV_FALSE otherwise.
+ */
+NvBool
+NvOdmOsFread(NvOdmOsFileHandle stream, void *ptr, size_t size, size_t *bytes);
+
+/**
+ *  Gets file information.
+ *
+ *  @param filename A pointer to the file to get information about.
+ *  @param stat [out] A pointer to the information structure.
+ *
+ *  @return NV_TRUE if successful, or NV_FALSE otherwise.
+ */
+NvBool
+NvOdmOsStat(const char *filename, NvOdmOsStatType *stat);
+
+/**
+ * Enables or disables USB OTG circuitry.
+ *
+ * @param Enable NV_TRUE to enable, or NV_FALSE to disable.
+ */
+void NvOdmEnableOtgCircuitry(NvBool Enable);
+
+/**
+ * Checks whether or not USB is connected.
+ *
+ * @pre The USB circuit is enabled by calling NvOdmEnableOtgCircuitry().
+ * To reduce power consumption, disable the USB circuit when not connected
+ * by calling \c NvOdmEnableOtgCircuitry(NV_FALSE).
+ *
+ * @return NV_TRUE if USB is successfully connected, otherwise NV_FALSE.
+ */
+NvBool NvOdmUsbIsConnected(void);
+
+/**
+ * Checks the current charging type.
+ *
+ * @pre The USB circuit is enabled by calling NvOdmEnableOtgCircuitry().
+ * To reduce power consumption, disable the USB circuit when not connected
+ * by calling \c NvOdmEnableOtgCircuitry(NV_FALSE).
+ *
+ * @param Instance Set to 0 by default.
+ * @return The current charging type.
+ */
+NvOdmUsbChargerType NvOdmUsbChargingType(NvU32 Instance);
+
+#if defined(__cplusplus)
+}
+#endif
+
+/*@}*/
+/** @} */
+
+#endif // INCLUDED_NVODM_SERVICES_H