diff options
Diffstat (limited to 'bsp-howto')
| -rw-r--r-- | bsp-howto/discrete.rst | 190 | ||||
| -rw-r--r-- | bsp-howto/index.rst | 1 |
2 files changed, 0 insertions, 191 deletions
diff --git a/bsp-howto/discrete.rst b/bsp-howto/discrete.rst deleted file mode 100644 index 6607882..0000000 --- a/bsp-howto/discrete.rst +++ /dev/null @@ -1,190 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -Discrete Driver -*************** - -The Discrete driver is responsible for providing an interface to Discrete -Input/Outputs. The capabilities provided by this class of device driver are: - -- Initialize a Discrete I/O Board - -- Open a Particular Discrete Bitfield - -- Close a Particular Discrete Bitfield - -- Read from a Particular Discrete Bitfield - -- Write to a Particular Discrete Bitfield - -- Reset DACs - -- Reinitialize DACS - -Most discrete I/O devices are found on I/O cards that support many bits of -discrete I/O on a single card. This driver model is centered on the notion of -reading bitfields from the card. - -There are currently no discrete I/O device drivers included in the RTEMS source -tree. The information provided in this chapter is based on drivers developed -for applications using RTEMS. It is hoped that this driver model information -can form the discrete I/O driver model that can be supported in future RTEMS -distribution. - -Major and Minor Numbers -======================= - -The ``major`` number of a device driver is its index in the RTEMS Device -Address Table. - -A ``minor`` number is associated with each device instance managed by a -particular device driver. An RTEMS minor number is an ``unsigned32`` entity. -Convention calls for dividing the bits in the minor number down into categories -that specify a particular bitfield. This results in categories like the -following: - -- ``board`` - indicates the board a particular bitfield is located on - -- ``word`` - indicates the particular word of discrete bits the bitfield is - located within - -- ``start`` - indicates the starting bit of the bitfield - -- ``width`` - indicates the width of the bitfield - -From the above, it should be clear that a single device driver can support -multiple copies of the same board in a single system. The minor number is used -to distinguish the devices. - -By providing a way to easily access a particular bitfield from the device -driver, the application is insulated with knowing how to mask fields in and out -of a discrete I/O. - -Discrete I/O Driver Configuration -================================= - -There is not a standard discrete I/O driver configuration table but some fields -are common across different drivers. The discrete I/O driver configuration -table is typically an array of structures with each structure containing the -information for a particular board. The following is a list of the type of -information normally required to configure an discrete I/O board: - -``board_offset`` - is the base address of a board. - -``relay_initial_values`` - is an array of the values that should be written to each output word on the - board during initialization. This allows the driver to start with the - board's output in a known state. - -Initialize a Discrete I/O Board -=============================== - -At system initialization, the discrete I/O driver's initialization entry point -will be invoked. As part of initialization, the driver will perform whatever -board initializatin is required and then set all outputs to their configured -initial state. - -The discrete I/O driver may register a device name for bitfields of particular -interest to the system. Normally this will be restricted to the names of each -word and, if the driver supports it, an "all words". - -Open a Particular Discrete Bitfield -=================================== - -This is the driver open call. Usually this call does nothing other than -validate the minor number. - -With some drivers, it may be necessary to allocate memory when a particular -device is opened. If that is the case, then this is often the place to do this -operation. - -Close a Particular Discrete Bitfield -==================================== - -This is the driver close call. Usually this call does nothing. - -With some drivers, it may be necessary to allocate memory when a particular -device is opened. If that is the case, then this is the place where that -memory should be deallocated. - -Read from a Particular Discrete Bitfield -======================================== - -This corresponds to the driver read call. After validating the minor number -and arguments, this call reads the indicated bitfield. A discrete I/O devices -may have to store the last value written to a discrete output. If the bitfield -is output only, saving the last written value gives the appearance that it can -be read from also. If the bitfield is input, then it is sampled. - -.. note:: - - Many discrete inputs have a tendency to bounce. The application may have to - take account for bounces. - -The value returned is an ``unsigned32`` number representing the bitfield read. -This value is stored in the ``argument_block`` passed in to the call. - -.. note:: - - Some discrete I/O drivers have a special minor number used to access all - discrete I/O bits on the board. If this special minor is used, then the - area pointed to by ``argument_block`` must be the correct size. - -Write to a Particular Discrete Bitfield -======================================= - -This corresponds to the driver write call. After validating the minor number -and arguments, this call writes the indicated device. If the specified device -is an ADC, then an error is usually returned. - -The value written is an ``unsigned32`` number representing the value to be -written to the specified bitfield. This value is stored in the -``argument_block`` passed in to the call. - -.. note:: - - Some discrete I/O drivers have a special minor number used to access all - discrete I/O bits on the board. If this special minor is used, then the - area pointed to by ``argument_block`` must be the correct size. - -Disable Discrete Outputs -======================== - -This is one of the IOCTL functions supported by the I/O control device driver -entry point. When this IOCTL function is invoked, the discrete outputs are -disabled. - -.. note:: - - It may not be possible to disable/enable discrete output on all discrete I/O - boards. - -Enable Discrete Outputs -======================= - -This is one of the IOCTL functions supported by the I/O control device driver -entry point. When this IOCTL function is invoked, the discrete outputs are -enabled. - -.. note:: - - It may not be possible to disable/enable discrete output on all discrete - I/O boards. - -Reinitialize Outputs -==================== - -This is one of the IOCTL functions supported by the I/O control device driver -entry point. When this IOCTL function is invoked, the discrete outputs are -rewritten with the configured initial output values. - -Get Last Written Values -======================= - -This is one of the IOCTL functions supported by the I/O control device driver -entry point. When this IOCTL function is invoked, the following information is -returned to the caller: - -- last value written to the specified output word - -- timestamp of when the last write was performed diff --git a/bsp-howto/index.rst b/bsp-howto/index.rst index 31cc0fa..f99118d 100644 --- a/bsp-howto/index.rst +++ b/bsp-howto/index.rst @@ -57,7 +57,6 @@ to the Community Project hosted at http://www.rtems.org. networking shared_memory_support frame_buffer - discrete command * :ref:`genindex` |