diff options
| -rw-r--r-- | docs/src/main.dox | 80 | ||||
| -rw-r--r-- | src/include/ioports.h | 146 |
2 files changed, 211 insertions, 15 deletions
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 @@ -355,6 +355,69 @@ */
/**
+ * @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.<br>
+ * 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.
+ *
+ * <h2>Implementation Rules</h2>
+ * In implementing an I/O port low level driver there are some rules that
+ * should be respected.
+ *
+ * <h3>Write on input pads</h3>
+ * 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.
+ * .
+ * <h3>Read from output pads</h3>
+ * 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.
+ * .
+ * <h3>Writing unused or unimplemented port bits</h3>
+ * The behavior is not specified.
+ *
+ * <h3>Reading from unused or unimplemented port bits</h3>
+ * The behavior is not specified.
+ *
+ * <h3>Reading or writing on pins associated to other functionalities</h3>
+ * 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.<br>
+ * 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.
* @details ChibiOS/RT supports several kinds of queues. The queues are mostly
@@ -373,25 +436,11 @@ * .
* In order to use the I/O queues the @p CH_USE_QUEUES option must
* be specified in @p chconf.h.<br>
+ *
* @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.<br>
- * 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.
* @details This module implements a generic full duplex serial driver. The
@@ -403,6 +452,7 @@ * interrupt service routines much easier.<br>
* 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 <http://www.gnu.org/licenses/>.
+*/
+
+/**
+ * @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_ */
+
+/** @} */
|