From 0da4e6e067db019f455b43a3391a1510f517d2cf Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 1 Jun 2009 17:52:34 +0000 Subject: [PATCH] Added abstract I/O ports driver header file and documentation. Implementations are missing. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1003 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/main.dox | 80 ++++++++++++++++++----- src/include/ioports.h | 146 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 211 insertions(+), 15 deletions(-) create mode 100644 src/include/ioports.h diff --git a/docs/src/main.dox b/docs/src/main.dox index 0bcd4969f..a969854f4 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -354,6 +354,69 @@ * for the ChibiOS/RT application among very different MCUs. */ +/** + * @defgroup IOPorts Abstract I/O Ports + * @brief Abstract digital I/O ports. + * @details This module defines an abstract interface for digital I/O ports. + * Note that no code is present, I/O ports are just a set of macros that must + * be implemented by a low level I/O port driver.
+ * Currently the I/O ports interface does not handle physical port programming + * like direction, pull up/down resistors etc. The interface only allows input + * and output operations but this may change in future releases. + * This system has the advantage to make the access to I/O ports platform + * independent from the implementation logic. + * + *

Implementation Rules

+ * In implementing an I/O port low level driver there are some rules that + * should be respected. + * + *

Write 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. + * . + *

Read 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. + * . + *

Writing unused or unimplemented port bits

+ * The behavior is not specified. + * + *

Reading from unused or unimplemented port bits

+ * The behavior is not specified. + * + *

Reading or writing on pins associated to other functionalities

+ * The behavior is not specified. + * + * @ingroup IO + */ + +/** + * @defgroup Channels Abstract I/O Channels + * @brief Abstract I/O Channels. + * @details This module defines an abstract interface for I/O channels. Note + * that no code is present, I/O channels are just abstract classes-like + * structures, you should look at the systems as to a set of abstract C++ + * classes (even if written in C). Specific device drivers can use/extend + * the interfaces and implement them.
+ * This system has the advantage to make the access to channels + * independent from the implementation logic. As example, an I/O channel + * interface can hide the access to a serial driver, to a networking socket + * and so on. + * + * @ingroup IO + */ + /** * @defgroup IOQueues I/O Queues * @brief I/O queues. @@ -373,24 +436,10 @@ * . * In order to use the I/O queues the @p CH_USE_QUEUES option must * be specified in @p chconf.h.
+ * * @ingroup IO */ -/** - * @defgroup Channels Abstract I/O Channels - * @brief Abstract I/O Channels. - * @details This module defines an abstract interface for I/O channels. Note - * that no code is present, I/O channels are just abstract classes-like - * structures, you should look at the systems as to a set of abstract C++ - * classes (even if written in C). Specific device drivers can use/extend - * the interfaces and implement them.
- * This system has the advantage to make the access to channels - * independent from the implementation logic. As example, an I/O channel - * interface can hide the access to a serial driver, to a networking socket - * and so on. - * @ingroup IO - */ - /** * @defgroup Serial Serial Drivers * @brief Generic Serial Drivers. @@ -403,6 +452,7 @@ * interrupt service routines much easier.
* In order to use the serial full duplex driver the * @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h. + * * @ingroup IO */ diff --git a/src/include/ioports.h b/src/include/ioports.h new file mode 100644 index 000000000..15792aa3d --- /dev/null +++ b/src/include/ioports.h @@ -0,0 +1,146 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @file ioports.h + * @brief I/O ports + * @addtogroup IOPorts + * @{ + */ + +#ifndef _IOPORTS_H_ +#define _IOPORTS_H_ + +#ifndef _IOPORTS_LLD_H_ +#include "ioports_lld.h" +#endif + +/** + * @brief Port bit helper macro. + * @details This macro calculates the mask of a bit within a port. + */ +#define IOPORT_BIT(n) ((ioportmask_t)(1 << (n))) + +/** + * @brief Port bus mask helper macro. + * @details This macro calculates the proper bus mask starting from the width + * and the offset. + * + * @param[in] width the width, in bits, of the I/O bus + * @param[in] offset the offset, within the port, of the I/O bus. The offset + * must be specified as offset from the least significant bit. + */ +#define IOPORT_BUS_MASK(width, offset) \ + ((ioportmask_t)(((1 << (width)) - 1) << (offset))) + +/** + * @brief I/O bus descriptor. + * @details This structure describes a group of contiguous digital I/O lines + * that have to be handled as bus. + * @note I/O operations on a bus do not affect I/O lines on the same port but + * not belonging to the bus. + */ +typedef struct { + /** Port identifier. */ + ioportid_t bus_portid; + /** Mask of the I/O lines that form the bus. The lines must be contiguous. + * The mask must be pre-shifted and also defines the bus size. */ + ioportmask_t bus_mask; + /** Offset, within the port, of the least significant bit of the bus. */ + uint_fast8_t bus_offset; +} IOBus; + +/** + * @brief Writes a bits mask on a I/O port. + * + * @param[in] port the port identifier + * @param[in] mask the mask to be written on the specified port + */ +#define chPortWrite(port, value) ioport_write_lld(port, value) + +/** + * @brief Reads an I/O port. + * + * @param[in] port the port identifier + */ +#define chPortRead(port) ioport_read_lld(port) + +/** + * @brief Sets a bits mask on a I/O port. + * + * @param[in] port the port identifier + * @param[in] mask the mask to be ORed on the specified port + * + * @note The operation is not guaranteed to be atomic on all the architectures, + * for atomicity and/or portability reasons you may need to enclose port + * I/O operations between @p chSysLock() and @p chSysUnlock(). + */ +#define chPortSet(port, mask) ioport_set_lld(port, mask) + +/** + * @brief Clears a bits mask on a I/O port. + * + * @param[in] port the port identifier + * @param[in] mask the mask to be cleared on the specified port + * + * @note The operation is not guaranteed to be atomic on all the architectures, + * for atomicity and/or portability reasons you may need to enclose port + * I/O operations between @p chSysLock() and @p chSysUnlock(). + */ +#define chPortClear(port, mask) ioport_clear_lld(port mask) + +/** + * @brief Toggles a bits mask on a I/O port. + * + * @param[in] port the port identifier + * @param[in] mask the mask to be XORed on the specified port + * + * @note The operation is not guaranteed to be atomic on all the architectures, + * for atomicity and/or portability reasons you may need to enclose port + * I/O operations between @p chSysLock() and @p chSysUnlock(). + */ +#define chPortToggle(port, mask) ioport_clear_lld(port mask) + +/** + * @brief Writes a value on an I/O bus. + * + * @param[in] bus the I/O bus + * @param[in] value the value to be written on the I/O bus. Values exceeding + * the bus width are masked so most significant bits may be lost. + * + * @note The operation is not guaranteed to be atomic on all the architectures, + * for atomicity and/or portability reasons you may need to enclose port + * I/O operations between @p chSysLock() and @p chSysUnlock(). + */ +#define chPortWriteBus(bus, value) ioport_writebus_lld(bus, value) + +/** + * @brief Reads a value from an I/O bus. + * + * @param[in] bus the I/O bus + * + * @note The operation is not guaranteed to be atomic on all the architectures, + * for atomicity and/or portability reasons you may need to enclose port + * I/O operations between @p chSysLock() and @p chSysUnlock(). + */ +#define chPortReadBus(bus) ioport_readbus_lld(bus) + +#endif /* _IOPORTS_H_ */ + +/** @} */