diff options
Diffstat (limited to 'Documentation/driver-api')
| -rw-r--r-- | Documentation/driver-api/dma-buf.rst | 6 | ||||
| -rw-r--r-- | Documentation/driver-api/driver-model/devres.rst | 1 | ||||
| -rw-r--r-- | Documentation/driver-api/generic-counter.rst | 363 | ||||
| -rw-r--r-- | Documentation/driver-api/ipmi.rst | 64 | ||||
| -rw-r--r-- | Documentation/driver-api/media/drivers/rkisp1.rst | 43 | ||||
| -rw-r--r-- | Documentation/driver-api/media/maintainer-entry-profile.rst | 2 | ||||
| -rw-r--r-- | Documentation/driver-api/media/v4l2-subdev.rst | 14 | ||||
| -rw-r--r-- | Documentation/driver-api/mmc/mmc-tools.rst | 4 | ||||
| -rw-r--r-- | Documentation/driver-api/serial/n_gsm.rst | 71 | ||||
| -rw-r--r-- | Documentation/driver-api/serial/tty.rst | 2 | ||||
| -rw-r--r-- | Documentation/driver-api/thermal/sysfs-api.rst | 225 | ||||
| -rw-r--r-- | Documentation/driver-api/usb/writing_usb_driver.rst | 13 |
12 files changed, 476 insertions, 332 deletions
diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index f5ac4c90b237..2cd7db82d9fe 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -176,12 +176,6 @@ DMA Fences Functions Reference .. kernel-doc:: include/linux/dma-fence.h :internal: -Seqno Hardware Fences -~~~~~~~~~~~~~~~~~~~~~ - -.. kernel-doc:: include/linux/seqno-fence.h - :internal: - DMA Fence Array ~~~~~~~~~~~~~~~ diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index 650096523f4f..148e19381b79 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -287,6 +287,7 @@ IIO devm_iio_device_register() devm_iio_dmaengine_buffer_setup() devm_iio_kfifo_buffer_setup() + devm_iio_map_array_register() devm_iio_triggered_buffer_setup() devm_iio_trigger_alloc() devm_iio_trigger_register() diff --git a/Documentation/driver-api/generic-counter.rst b/Documentation/driver-api/generic-counter.rst index 64fe7db080e5..1b487a331467 100644 --- a/Documentation/driver-api/generic-counter.rst +++ b/Documentation/driver-api/generic-counter.rst @@ -223,19 +223,6 @@ whether an input line is differential or single-ended) and instead focus on the core idea of what the data and process represent (e.g. position as interpreted from quadrature encoding data). -Userspace Interface -=================== - -Several sysfs attributes are generated by the Generic Counter interface, -and reside under the /sys/bus/counter/devices/counterX directory, where -counterX refers to the respective counter device. Please see -Documentation/ABI/testing/sysfs-bus-counter for detailed -information on each Generic Counter interface sysfs attribute. - -Through these sysfs attributes, programs and scripts may interact with -the Generic Counter paradigm Counts, Signals, and Synapses of respective -counter devices. - Driver API ========== @@ -247,11 +234,14 @@ for defining a counter device. .. kernel-doc:: include/linux/counter.h :internal: -.. kernel-doc:: drivers/counter/counter.c +.. kernel-doc:: drivers/counter/counter-core.c + :export: + +.. kernel-doc:: drivers/counter/counter-chrdev.c :export: -Implementation -============== +Driver Implementation +===================== To support a counter device, a driver must first allocate the available Counter Signals via counter_signal structures. These Signals should @@ -267,25 +257,61 @@ respective counter_count structure. These counter_count structures are set to the counts array member of an allocated counter_device structure before the Counter is registered to the system. -Driver callbacks should be provided to the counter_device structure via -a constant counter_ops structure in order to communicate with the -device: to read and write various Signals and Counts, and to set and get -the "action mode" and "function mode" for various Synapses and Counts -respectively. +Driver callbacks must be provided to the counter_device structure in +order to communicate with the device: to read and write various Signals +and Counts, and to set and get the "action mode" and "function mode" for +various Synapses and Counts respectively. A defined counter_device structure may be registered to the system by passing it to the counter_register function, and unregistered by passing it to the counter_unregister function. Similarly, the -devm_counter_register and devm_counter_unregister functions may be used -if device memory-managed registration is desired. - -Extension sysfs attributes can be created for auxiliary functionality -and data by passing in defined counter_device_ext, counter_count_ext, -and counter_signal_ext structures. In these cases, the -counter_device_ext structure is used for global/miscellaneous exposure -and configuration of the respective Counter device, while the -counter_count_ext and counter_signal_ext structures allow for auxiliary -exposure and configuration of a specific Count or Signal respectively. +devm_counter_register function may be used if device memory-managed +registration is desired. + +The struct counter_comp structure is used to define counter extensions +for Signals, Synapses, and Counts. + +The "type" member specifies the type of high-level data (e.g. BOOL, +COUNT_DIRECTION, etc.) handled by this extension. The "``*_read``" and +"``*_write``" members can then be set by the counter device driver with +callbacks to handle that data using native C data types (i.e. u8, u64, +etc.). + +Convenience macros such as ``COUNTER_COMP_COUNT_U64`` are provided for +use by driver authors. In particular, driver authors are expected to use +the provided macros for standard Counter subsystem attributes in order +to maintain a consistent interface for userspace. For example, a counter +device driver may define several standard attributes like so:: + + struct counter_comp count_ext[] = { + COUNTER_COMP_DIRECTION(count_direction_read), + COUNTER_COMP_ENABLE(count_enable_read, count_enable_write), + COUNTER_COMP_CEILING(count_ceiling_read, count_ceiling_write), + }; + +This makes it simple to see, add, and modify the attributes that are +supported by this driver ("direction", "enable", and "ceiling") and to +maintain this code without getting lost in a web of struct braces. + +Callbacks must match the function type expected for the respective +component or extension. These function types are defined in the struct +counter_comp structure as the "``*_read``" and "``*_write``" union +members. + +The corresponding callback prototypes for the extensions mentioned in +the previous example above would be:: + + int count_direction_read(struct counter_device *counter, + struct counter_count *count, + enum counter_count_direction *direction); + int count_enable_read(struct counter_device *counter, + struct counter_count *count, u8 *enable); + int count_enable_write(struct counter_device *counter, + struct counter_count *count, u8 enable); + int count_ceiling_read(struct counter_device *counter, + struct counter_count *count, u64 *ceiling); + int count_ceiling_write(struct counter_device *counter, + struct counter_count *count, u64 ceiling); Determining the type of extension to create is a matter of scope. @@ -313,52 +339,235 @@ Determining the type of extension to create is a matter of scope. chip overheated via a device extension called "error_overtemp": /sys/bus/counter/devices/counterX/error_overtemp -Architecture -============ - -When the Generic Counter interface counter module is loaded, the -counter_init function is called which registers a bus_type named -"counter" to the system. Subsequently, when the module is unloaded, the -counter_exit function is called which unregisters the bus_type named -"counter" from the system. +Subsystem Architecture +====================== + +Counter drivers pass and take data natively (i.e. ``u8``, ``u64``, etc.) +and the shared counter module handles the translation between the sysfs +interface. This guarantees a standard userspace interface for all +counter drivers, and enables a Generic Counter chrdev interface via a +generalized device driver ABI. + +A high-level view of how a count value is passed down from a counter +driver is exemplified by the following. The driver callbacks are first +registered to the Counter core component for use by the Counter +userspace interface components:: + + Driver callbacks registration: + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +----------------------------+ + | Counter device driver | + +----------------------------+ + | Processes data from device | + +----------------------------+ + | + ------------------- + / driver callbacks / + ------------------- + | + V + +----------------------+ + | Counter core | + +----------------------+ + | Routes device driver | + | callbacks to the | + | userspace interfaces | + +----------------------+ + | + ------------------- + / driver callbacks / + ------------------- + | + +---------------+---------------+ + | | + V V + +--------------------+ +---------------------+ + | Counter sysfs | | Counter chrdev | + +--------------------+ +---------------------+ + | Translates to the | | Translates to the | + | standard Counter | | standard Counter | + | sysfs output | | character device | + +--------------------+ +---------------------+ + +Thereafter, data can be transferred directly between the Counter device +driver and Counter userspace interface:: + + Count data request: + ~~~~~~~~~~~~~~~~~~~ + ---------------------- + / Counter device \ + +----------------------+ + | Count register: 0x28 | + +----------------------+ + | + ----------------- + / raw count data / + ----------------- + | + V + +----------------------------+ + | Counter device driver | + +----------------------------+ + | Processes data from device | + |----------------------------| + | Type: u64 | + | Value: 42 | + +----------------------------+ + | + ---------- + / u64 / + ---------- + | + +---------------+---------------+ + | | + V V + +--------------------+ +---------------------+ + | Counter sysfs | | Counter chrdev | + +--------------------+ +---------------------+ + | Translates to the | | Translates to the | + | standard Counter | | standard Counter | + | sysfs output | | character device | + |--------------------| |---------------------| + | Type: const char * | | Type: u64 | + | Value: "42" | | Value: 42 | + +--------------------+ +---------------------+ + | | + --------------- ----------------------- + / const char * / / struct counter_event / + --------------- ----------------------- + | | + | V + | +-----------+ + | | read | + | +-----------+ + | \ Count: 42 / + | ----------- + | + V + +--------------------------------------------------+ + | `/sys/bus/counter/devices/counterX/countY/count` | + +--------------------------------------------------+ + \ Count: "42" / + -------------------------------------------------- + +There are four primary components involved: + +Counter device driver +--------------------- +Communicates with the hardware device to read/write data; e.g. counter +drivers for quadrature encoders, timers, etc. + +Counter core +------------ +Registers the counter device driver to the system so that the respective +callbacks are called during userspace interaction. + +Counter sysfs +------------- +Translates counter data to the standard Counter sysfs interface format +and vice versa. + +Please refer to the ``Documentation/ABI/testing/sysfs-bus-counter`` file +for a detailed breakdown of the available Generic Counter interface +sysfs attributes. + +Counter chrdev +-------------- +Translates Counter events to the standard Counter character device; data +is transferred via standard character device read calls, while Counter +events are configured via ioctl calls. + +Sysfs Interface +=============== -Counter devices are registered to the system via the counter_register -function, and later removed via the counter_unregister function. The -counter_register function establishes a unique ID for the Counter -device and creates a respective sysfs directory, where X is the -mentioned unique ID: - - /sys/bus/counter/devices/counterX - -Sysfs attributes are created within the counterX directory to expose -functionality, configurations, and data relating to the Counts, Signals, -and Synapses of the Counter device, as well as options and information -for the Counter device itself. - -Each Signal has a directory created to house its relevant sysfs -attributes, where Y is the unique ID of the respective Signal: - - /sys/bus/counter/devices/counterX/signalY - -Similarly, each Count has a directory created to house its relevant -sysfs attributes, where Y is the unique ID of the respective Count: - - /sys/bus/counter/devices/counterX/countY - -For a more detailed breakdown of the available Generic Counter interface -sysfs attributes, please refer to the -Documentation/ABI/testing/sysfs-bus-counter file. +Several sysfs attributes are generated by the Generic Counter interface, +and reside under the ``/sys/bus/counter/devices/counterX`` directory, +where ``X`` is to the respective counter device id. Please see +``Documentation/ABI/testing/sysfs-bus-counter`` for detailed information +on each Generic Counter interface sysfs attribute. -The Signals and Counts associated with the Counter device are registered -to the system as well by the counter_register function. The -signal_read/signal_write driver callbacks are associated with their -respective Signal attributes, while the count_read/count_write and -function_get/function_set driver callbacks are associated with their -respective Count attributes; similarly, the same is true for the -action_get/action_set driver callbacks and their respective Synapse -attributes. If a driver callback is left undefined, then the respective -read/write permission is left disabled for the relevant attributes. +Through these sysfs attributes, programs and scripts may interact with +the Generic Counter paradigm Counts, Signals, and Synapses of respective +counter devices. -Similarly, extension sysfs attributes are created for the defined -counter_device_ext, counter_count_ext, and counter_signal_ext -structures that are passed in. +Counter Character Device +======================== + +Counter character device nodes are created under the ``/dev`` directory +as ``counterX``, where ``X`` is the respective counter device id. +Defines for the standard Counter data types are exposed via the +userspace ``include/uapi/linux/counter.h`` file. + +Counter events +-------------- +Counter device drivers can support Counter events by utilizing the +``counter_push_event`` function:: + + void counter_push_event(struct counter_device *const counter, const u8 event, + const u8 channel); + +The event id is specified by the ``event`` parameter; the event channel +id is specified by the ``channel`` parameter. When this function is +called, the Counter data associated with the respective event is +gathered, and a ``struct counter_event`` is generated for each datum and +pushed to userspace. + +Counter events can be configured by users to report various Counter +data of interest. This can be conceptualized as a list of Counter +component read calls to perform. For example: + + +------------------------+------------------------+ + | COUNTER_EVENT_OVERFLOW | COUNTER_EVENT_INDEX | + +========================+========================+ + | Channel 0 | Channel 0 | + +------------------------+------------------------+ + | * Count 0 | * Signal 0 | + | * Count 1 | * Signal 0 Extension 0 | + | * Signal 3 | * Extension 4 | + | * Count 4 Extension 2 +------------------------+ + | * Signal 5 Extension 0 | Channel 1 | + | +------------------------+ + | | * Signal 4 | + | | * Signal 4 Extension 0 | + | | * Count 7 | + +------------------------+------------------------+ + +When ``counter_push_event(counter, COUNTER_EVENT_INDEX, 1)`` is called +for example, it will go down the list for the ``COUNTER_EVENT_INDEX`` +event channel 1 and execute the read callbacks for Signal 4, Signal 4 +Extension 0, and Count 7 -- the data returned for each is pushed to a +kfifo as a ``struct counter_event``, which userspace can retrieve via a +standard read operation on the respective character device node. + +Userspace +--------- +Userspace applications can configure Counter events via ioctl operations +on the Counter character device node. There following ioctl codes are +supported and provided by the ``linux/counter.h`` userspace header file: + +* :c:macro:`COUNTER_ADD_WATCH_IOCTL` + +* :c:macro:`COUNTER_ENABLE_EVENTS_IOCTL` + +* :c:macro:`COUNTER_DISABLE_EVENTS_IOCTL` + +To configure events to gather Counter data, users first populate a +``struct counter_watch`` with the relevant event id, event channel id, +and the information for the desired Counter component from which to +read, and then pass it via the ``COUNTER_ADD_WATCH_IOCTL`` ioctl +command. + +Note that an event can be watched without gathering Counter data by +setting the ``component.type`` member equal to +``COUNTER_COMPONENT_NONE``. With this configuration the Counter +character device will simply populate the event timestamps for those +respective ``struct counter_event`` elements and ignore the component +value. + +The ``COUNTER_ADD_WATCH_IOCTL`` command will buffer these Counter +watches. When ready, the ``COUNTER_ENABLE_EVENTS_IOCTL`` ioctl command +may be used to activate these Counter watches. + +Userspace applications can then execute a ``read`` operation (optionally +calling ``poll`` first) on the Counter character device node to retrieve +``struct counter_event`` elements with the desired data. diff --git a/Documentation/driver-api/ipmi.rst b/Documentation/driver-api/ipmi.rst index bc281f10ce4b..e224e47b6b09 100644 --- a/Documentation/driver-api/ipmi.rst +++ b/Documentation/driver-api/ipmi.rst @@ -166,8 +166,8 @@ and the type is IPMI_SYSTEM_INTERFACE_ADDR_TYPE. This is used for talking straight to the BMC on the current card. The channel must be IPMI_BMC_CHANNEL. -Messages that are destined to go out on the IPMB bus use the -IPMI_IPMB_ADDR_TYPE address type. The format is:: +Messages that are destined to go out on the IPMB bus going through the +BMC use the IPMI_IPMB_ADDR_TYPE address type. The format is:: struct ipmi_ipmb_addr { @@ -181,6 +181,23 @@ The "channel" here is generally zero, but some devices support more than one channel, it corresponds to the channel as defined in the IPMI spec. +There is also an IPMB direct address for a situation where the sender +is directly on an IPMB bus and doesn't have to go through the BMC. +You can send messages to a specific management controller (MC) on the +IPMB using the IPMI_IPMB_DIRECT_ADDR_TYPE with the following format:: + + struct ipmi_ipmb_direct_addr + { + int addr_type; + short channel; + unsigned char slave_addr; + unsigned char rq_lun; + unsigned char rs_lun; + }; + +The channel is always zero. You can also receive commands from other +MCs that you have registered to handle and respond to them, so you can +use this to implement a management controller on a bus.. Messages -------- @@ -348,6 +365,10 @@ user may be registered for each netfn/cmd/channel, but different users may register for different commands, or the same command if the channel bitmasks do not overlap. +To respond to a received command, set the response bit in the returned +netfn, use the address from the received message, and use the same +msgid that you got in the receive message. + From userland, equivalent IOCTLs are provided to do these functions. @@ -570,6 +591,45 @@ web page. The driver supports a hot add and remove of interfaces through the I2C sysfs interface. +The IPMI IPMB Driver +-------------------- + +This driver is for supporting a system that sits on an IPMB bus; it +allows the interface to look like a normal IPMI interface. Sending +system interface addressed messages to it will cause the message to go +to the registered BMC on the system (default at IPMI address 0x20). + +It also allows you to directly address other MCs on the bus using the +ipmb direct addressing. You can receive commands from other MCs on +the bus and they will be handled through the normal received command +mechanism described above. + +Parameters are:: + + ipmi_ipmb.bmcaddr=<address to use for system interface addresses messages> + ipmi_ipmb.retry_time_ms=<Time between retries on IPMB> + ipmi_ipmb.max_retries=<Number of times to retry a message> + +Loading the module will not result in the driver automatcially +starting unless there is device tree information setting it up. If +you want to instantiate one of these by hand, do:: + + echo ipmi-ipmb <addr> > /sys/class/i2c-dev/i2c-<n>/device/new_device + +Note that the address you give here is the I2C address, not the IPMI +address. So if you want your MC address to be 0x60, you put 0x30 +here. See the I2C driver info for more details. + +Command bridging to other IPMB busses through this interface does not +work. The receive message queue is not implemented, by design. There +is only one receive message queue on a BMC, and that is meant for the +host drivers, not something on the IPMB bus. + +A BMC may have multiple IPMB busses, which bus your device sits on +depends on how the system is wired. You can fetch the channels with +"ipmitool channel info <n>" where <n> is the channel, with the +channels being 0-7 and try the IPMB channels. + Other Pieces ------------ diff --git a/Documentation/driver-api/media/drivers/rkisp1.rst b/Documentation/driver-api/media/drivers/rkisp1.rst new file mode 100644 index 000000000000..ea336958a3af --- /dev/null +++ b/Documentation/driver-api/media/drivers/rkisp1.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The Rockchip Image Signal Processor Driver (rkisp1) +=================================================== + +Versions and their differences +------------------------------ + +The rkisp1 block underwent some changes between SoC implementations. +The vendor designates them as: + +- V10: used at least in rk3288 and rk3399 +- V11: declared in the original vendor code, but not used +- V12: used at least in rk3326 and px30 +- V13: used at least in rk1808 +- V20: used in rk3568 and beyond + +Right now the kernel supports rkisp1 implementations based +on V10 and V12 variants. V11 does not seem to be actually used +and V13 will need some more additions but isn't researched yet, +especially as it seems to be limited to the rk1808 which hasn't +reached much market spread. + +V20 on the other hand will probably be used in future SoCs and +has seen really big changes in the vendor kernel, so will need +quite a bit of research. + +Changes from V10 to V12 +----------------------- + +- V12 supports a new CSI-host implementation but can still + also use the same implementation from V10 +- The module for lens shading correction got changed + from 12bit to 13bit width +- The AWB and AEC modules got replaced to support finer + grained data collection + +Changes from V12 to V13 +----------------------- + +The list for V13 is incomplete and needs further investigation. + +- V13 does not support the old CSI-host implementation anymore diff --git a/Documentation/driver-api/media/maintainer-entry-profile.rst b/Documentation/driver-api/media/maintainer-entry-profile.rst index eb1cdfd280ba..ffc712a5f632 100644 --- a/Documentation/driver-api/media/maintainer-entry-profile.rst +++ b/Documentation/driver-api/media/maintainer-entry-profile.rst @@ -71,7 +71,7 @@ media maintainers do the review. The media maintainers that work on specific areas of the subsystem are: -- Digital TV and remote controllers: +- Remote Controllers (infrared): Sean Young <[email protected]> - HDMI CEC: diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index 7736da077fb8..08ea2673b19e 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -191,21 +191,21 @@ registered this way are stored in a global list of subdevices, ready to be picked up by bridge drivers. Bridge drivers in turn have to register a notifier object. This is -performed using the :c:func:`v4l2_async_notifier_register` call. To +performed using the :c:func:`v4l2_async_nf_register` call. To unregister the notifier the driver has to call -:c:func:`v4l2_async_notifier_unregister`. The former of the two functions +:c:func:`v4l2_async_nf_unregister`. The former of the two functions takes two arguments: a pointer to struct :c:type:`v4l2_device` and a pointer to struct :c:type:`v4l2_async_notifier`. Before registering the notifier, bridge drivers must do two things: first, the -notifier must be initialized using the :c:func:`v4l2_async_notifier_init`. +notifier must be initialized using the :c:func:`v4l2_async_nf_init`. Second, bridge drivers can then begin to form a list of subdevice descriptors that the bridge device needs for its operation. Several functions are available to add subdevice descriptors to a notifier, depending on the type of device and the needs of the driver. -:c:func:`v4l2_async_notifier_add_fwnode_remote_subdev` and -:c:func:`v4l2_async_notifier_add_i2c_subdev` are for bridge and ISP drivers for +:c:func:`v4l2_async_nf_add_fwnode_remote` and +:c:func:`v4l2_async_nf_add_i2c` are for bridge and ISP drivers for registering their async sub-devices with the notifier. :c:func:`v4l2_async_register_subdev_sensor` is a helper function for @@ -230,8 +230,8 @@ These functions allocate an async sub-device descriptor which is of type struct ... - my_asd = v4l2_async_notifier_add_fwnode_remote_subdev(¬ifier, ep, - struct my_async_subdev); + my_asd = v4l2_async_nf_add_fwnode_remote(¬ifier, ep, + struct my_async_subdev); fwnode_handle_put(ep); if (IS_ERR(asd)) diff --git a/Documentation/driver-api/mmc/mmc-tools.rst b/Documentation/driver-api/mmc/mmc-tools.rst index a231e9644351..eee1c2ccfa8f 100644 --- a/Documentation/driver-api/mmc/mmc-tools.rst +++ b/Documentation/driver-api/mmc/mmc-tools.rst @@ -2,10 +2,10 @@ MMC tools introduction ====================== -There is one MMC test tools called mmc-utils, which is maintained by Chris Ball, +There is one MMC test tools called mmc-utils, which is maintained by Ulf Hansson, you can find it at the below public git repository: - https://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/ + https://git.kernel.org/pub/scm/utils/mmc/mmc-utils.git Functions ========= diff --git a/Documentation/driver-api/serial/n_gsm.rst b/Documentation/driver-api/serial/n_gsm.rst index 87dfcd54a96b..8fe723ab9c67 100644 --- a/Documentation/driver-api/serial/n_gsm.rst +++ b/Documentation/driver-api/serial/n_gsm.rst @@ -12,13 +12,16 @@ modems connected to a physical serial port. How to use it ------------- -1. initialize the modem in 0710 mux mode (usually AT+CMUX= command) through - its serial port. Depending on the modem used, you can pass more or less - parameters to this command, -2. switch the serial line to using the n_gsm line discipline by using - TIOCSETD ioctl, -3. configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl, -4. obtain base gsmtty number for the used serial port, +1. config initiator +^^^^^^^^^^^^^^^^^^^^^ + +1.1 initialize the modem in 0710 mux mode (usually AT+CMUX= command) through + its serial port. Depending on the modem used, you can pass more or less + parameters to this command. +1.2 switch the serial line to using the n_gsm line discipline by using + TIOCSETD ioctl. +1.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl. +1.4 obtain base gsmtty number for the used serial port. Major parts of the initialization program : (a good starting point is util-linux-ng/sys-utils/ldattach.c):: @@ -70,14 +73,14 @@ Major parts of the initialization program : daemon(0,0); pause(); -5. use these devices as plain serial ports. +1.5 use these devices as plain serial ports. for example, it's possible: - and to use gnokii to send / receive SMS on ttygsm1 - to use ppp to establish a datalink on ttygsm2 -6. first close all virtual ports before closing the physical port. +1.6 first close all virtual ports before closing the physical port. Note that after closing the physical port the modem is still in multiplexing mode. This may prevent a successful re-opening of the port later. To avoid @@ -87,6 +90,56 @@ Major parts of the initialization program : 0xf9, 0x03, 0xef, 0x03, 0xc3, 0x16, 0xf9. +2. config requester +^^^^^^^^^^^^^^^^^^^^^ + +2.1 receive string "AT+CMUX= command" through its serial port,initialize + mux mode config +2.2 switch the serial line to using the n_gsm line discipline by using + TIOCSETD ioctl. +2.3 configure the mux using GSMIOC_GETCONF / GSMIOC_SETCONF ioctl. +2.4 obtain base gsmtty number for the used serial port, + + #include <stdio.h> + #include <stdint.h> + #include <linux/gsmmux.h> + #include <linux/tty.h> + #define DEFAULT_SPEED B115200 + #define SERIAL_PORT /dev/ttyS0 + + int ldisc = N_GSM0710; + struct gsm_config c; + struct termios configuration; + uint32_t first; + + /* open the serial port */ + fd = open(SERIAL_PORT, O_RDWR | O_NOCTTY | O_NDELAY); + + /* configure the serial port : speed, flow control ... */ + + /* get serial data and check "AT+CMUX=command" parameter ... */ + + /* use n_gsm line discipline */ + ioctl(fd, TIOCSETD, &ldisc); + + /* get n_gsm configuration */ + ioctl(fd, GSMIOC_GETCONF, &c); + /* we are requester and need encoding 0 (basic) */ + c.initiator = 0; + c.encapsulation = 0; + /* our modem defaults to a maximum size of 127 bytes */ + c.mru = 127; + c.mtu = 127; + /* set the new configuration */ + ioctl(fd, GSMIOC_SETCONF, &c); + /* get first gsmtty device node */ + ioctl(fd, GSMIOC_GETFIRST, &first); + printf("first muxed line: /dev/gsmtty%i\n", first); + + /* and wait for ever to keep the line discipline enabled */ + daemon(0,0); + pause(); + Additional Documentation ------------------------ More practical details on the protocol and how it's supported by industrial diff --git a/Documentation/driver-api/serial/tty.rst b/Documentation/driver-api/serial/tty.rst index dd972caacf3e..4b709f392713 100644 --- a/Documentation/driver-api/serial/tty.rst +++ b/Documentation/driver-api/serial/tty.rst @@ -58,7 +58,7 @@ close() This is called on a terminal when the line hangup() Called when the tty line is hung up. The line discipline should cease I/O to the tty. No further calls into the ldisc code will occur. - The return value is ignored. Can sleep. + Can sleep. read() (optional) A process requests reading data from the line. Multiple read calls may occur in parallel diff --git a/Documentation/driver-api/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst index c93fa5e961a0..2e0f79a9e2ee 100644 --- a/Documentation/driver-api/thermal/sysfs-api.rst +++ b/Documentation/driver-api/thermal/sysfs-api.rst @@ -428,6 +428,9 @@ of thermal zone device. E.g. the generic thermal driver registers one hwmon class device and build the associated hwmon sysfs I/F for all the registered ACPI thermal zones. +Please read Documentation/ABI/testing/sysfs-class-thermal for thermal +zone and cooling device attribute details. + :: /sys/class/hwmon/hwmon[0-*]: @@ -437,228 +440,6 @@ ACPI thermal zones. Please read Documentation/hwmon/sysfs-interface.rst for additional information. -Thermal zone attributes ------------------------ - -type - Strings which represent the thermal zone type. - This is given by thermal zone driver as part of registration. - E.g: "acpitz" indicates it's an ACPI thermal device. - In order to keep it consistent with hwmon sys attribute; this should - be a short, lowercase string, not containing spaces nor dashes. - RO, Required - -temp - Current temperature as reported by thermal zone (sensor). - Unit: millidegree Celsius - RO, Required - -mode - One of the predefined values in [enabled, disabled]. - This file gives information about the algorithm that is currently - managing the thermal zone. It can be either default kernel based - algorithm or user space application. - - enabled - enable Kernel Thermal management. - disabled - Preventing kernel thermal zone driver actions upon - trip points so that user application can take full - charge of the thermal management. - - RW, Optional - -policy - One of the various thermal governors used for a particular zone. - - RW, Required - -available_policies - Available thermal governors which can be used for a particular zone. - - RO, Required - -`trip_point_[0-*]_temp` - The temperature above which trip point will be fired. - - Unit: millidegree Celsius - - RO, Optional - -`trip_point_[0-*]_type` - Strings which indicate the type of the trip point. - - E.g. it can be one of critical, hot, passive, `active[0-*]` for ACPI - thermal zone. - - RO, Optional - -`trip_point_[0-*]_hyst` - The hysteresis value for a trip point, represented as an integer - Unit: Celsius - RW, Optional - -`cdev[0-*]` - Sysfs link to the thermal cooling device node where the sys I/F - for cooling device throttling control represents. - - RO, Optional - -`cdev[0-*]_trip_point` - The trip point in this thermal zone which `cdev[0-*]` is associated - with; -1 means the cooling device is not associated with any trip - point. - - RO, Optional - -`cdev[0-*]_weight` - The influence of `cdev[0-*]` in this thermal zone. This value - is relative to the rest of cooling devices in the thermal - zone. For example, if a cooling device has a weight double - than that of other, it's twice as effective in cooling the - thermal zone. - - RW, Optional - -emul_temp - Interface to set the emulated temperature method in thermal zone - (sensor). After setting this temperature, the thermal zone may pass - this temperature to platform emulation function if registered or - cache it locally. This is useful in debugging different temperature - threshold and its associated cooling action. This is write only node - and writing 0 on this node should disable emulation. - Unit: millidegree Celsius - - WO, Optional - - WARNING: - Be careful while enabling this option on production systems, - because userland can easily disable the thermal policy by simply - flooding this sysfs node with low temperature values. - -sustainable_power - An estimate of the sustained power that can be dissipated by - the thermal zone. Used by the power allocator governor. For - more information see Documentation/driver-api/thermal/power_allocator.rst - - Unit: milliwatts - - RW, Optional - -k_po - The proportional term of the power allocator governor's PID - controller during temperature overshoot. Temperature overshoot - is when the current temperature is above the "desired - temperature" trip point. For more information see - Documentation/driver-api/thermal/power_allocator.rst - - RW, Optional - -k_pu - The proportional term of the power allocator governor's PID - controller during temperature undershoot. Temperature undershoot - is when the current temperature is below the "desired - temperature" trip point. For more information see - Documentation/driver-api/thermal/power_allocator.rst - - RW, Optional - -k_i - The integral term of the power allocator governor's PID - controller. This term allows the PID controller to compensate - for long term drift. For more information see - Documentation/driver-api/thermal/power_allocator.rst - - RW, Optional - -k_d - The derivative term of the power allocator governor's PID - controller. For more information see - Documentation/driver-api/thermal/power_allocator.rst - - RW, Optional - -integral_cutoff - Temperature offset from the desired temperature trip point - above which the integral term of the power allocator - governor's PID controller starts accumulating errors. For - example, if integral_cutoff is 0, then the integral term only - accumulates error when temperature is above the desired - temperature trip point. For more information see - Documentation/driver-api/thermal/power_allocator.rst - - Unit: millidegree Celsius - - RW, Optional - -slope - The slope constant used in a linear extrapolation model - to determine a hotspot temperature based off the sensor's - raw readings. It is up to the device driver to determine - the usage of these values. - - RW, Optional - -offset - The offset constant used in a linear extrapolation model - to determine a hotspot temperature based off the sensor's - raw readings. It is up to the device driver to determine - the usage of these values. - - RW, Optional - -Cooling device attributes -------------------------- - -type - String which represents the type of device, e.g: - - - for generic ACPI: should be "Fan", "Processor" or "LCD" - - for memory controller device on intel_menlow platform: - should be "Memory controller". - - RO, Required - -max_state - The maximum permissible cooling state of this cooling device. - - RO, Required - -cur_state - The current cooling state of this cooling device. - The value can any integer numbers between 0 and max_state: - - - cur_state == 0 means no cooling - - cur_state == max_state means the maximum cooling. - - RW, Required - -stats/reset - Writing any value resets the cooling device's statistics. - WO, Required - -stats/time_in_state_ms: - The amount of time spent by the cooling device in various cooling - states. The output will have "<state> <time>" pair in each line, which - will mean this cooling device spent <time> msec of time at <state>. - Output will have one line for each of the supported states. - RO, Required - - -stats/total_trans: - A single positive value showing the total number of times the state of a - cooling device is changed. - - RO, Required - -stats/trans_table: - This gives fine grained information about all the cooling state - transitions. The cat output here is a two dimensional matrix, where an - entry <i,j> (row i, column j) represents the number of transitions from - State_i to State_j. If the transition table is bigger than PAGE_SIZE, - reading this will return an -EFBIG error. - RO, Required - 3. A simple implementation ========================== diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index 2176297e5765..b43e1ce49f0e 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -57,9 +57,12 @@ structure. The skeleton driver declares a :c:type:`usb_driver` as:: .name = "skeleton", .probe = skel_probe, .disconnect = skel_disconnect, - .fops = &skel_fops, - .minor = USB_SKEL_MINOR_BASE, + .suspend = skel_suspend, + .resume = skel_resume, + .pre_reset = skel_pre_reset, + .post_reset = skel_post_reset, .id_table = skel_table, + .supports_autosuspend = 1, }; @@ -81,7 +84,7 @@ this user-space interaction. The skeleton driver needs this kind of interface, so it provides a minor starting number and a pointer to its :c:type:`file_operations` functions. -The USB driver is then registered with a call to :c:func:`usb_register`, +The USB driver is then registered with a call to usb_register(), usually in the driver's init function, as shown here:: static int __init usb_skel_init(void) @@ -102,7 +105,7 @@ usually in the driver's init function, as shown here:: When the driver is unloaded from the system, it needs to deregister -itself with the USB subsystem. This is done with the :c:func:`usb_deregister` +itself with the USB subsystem. This is done with usb_deregister() function:: static void __exit usb_skel_exit(void) @@ -231,7 +234,7 @@ error message. This can be shown with the following code:: skel->bulk_in_endpointAddr), skel->bulk_in_buffer, skel->bulk_in_size, - &count, HZ*10); + &count, 5000); /* if the read was successful, copy the data to user space */ if (!retval) { if (copy_to_user (buffer, skel->bulk_in_buffer, count)) |