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-d51de3d6d3f4master
gdisirio
parent
a83063db26
commit
0da4e6e067
|
|
@ -354,6 +354,69 @@
|
||||||
* for the ChibiOS/RT application among very different MCUs.
|
* 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.<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
|
* @defgroup IOQueues I/O Queues
|
||||||
* @brief I/O queues.
|
* @brief I/O queues.
|
||||||
|
|
@ -373,21 +436,7 @@
|
||||||
* .
|
* .
|
||||||
* In order to use the I/O queues the @p CH_USE_QUEUES option must
|
* In order to use the I/O queues the @p CH_USE_QUEUES option must
|
||||||
* be specified in @p chconf.h.<br>
|
* 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
|
* @ingroup IO
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
|
@ -403,6 +452,7 @@
|
||||||
* interrupt service routines much easier.<br>
|
* interrupt service routines much easier.<br>
|
||||||
* In order to use the serial full duplex driver the
|
* In order to use the serial full duplex driver the
|
||||||
* @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h.
|
* @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h.
|
||||||
|
*
|
||||||
* @ingroup IO
|
* @ingroup IO
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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_ */
|
||||||
|
|
||||||
|
/** @} */
|
||||||
Loading…
Reference in New Issue