[U-Boot] [PATCH v3 1/3] misc: docs: Fix comments in misc.h

[U-Boot] [PATCH v3 1/3] misc: docs: Fix comments in misc.h

[Mario Six]

The comments in misc.h are not in kernel-doc format. Correct the format.

Signed-off-by: Mario Six <mario.six@gdsys.cc>

---

v2 -> v3:
New in v3

---
 include/misc.h | 66 +++++++++++++++++++++++++++++++---------------------------
 1 file changed, 35 insertions(+), 31 deletions(-)

diff --git a/include/misc.h b/include/misc.h
index 68f8e64d61a..0acb4c4df64 100644
--- a/include/misc.h
+++ b/include/misc.h
@@ -6,38 +6,40 @@
 #ifndef _MISC_H_
 #define _MISC_H_

-/*
- * Read the device to buffer, optional.
+/**
+ * misc_read() - Read the device to buffer, optional.
  *
  * @dev: the device
  * @offset: offset to read the device
  * @buf: pointer to data buffer
  * @size: data size in bytes to read the device
- * @return: 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int misc_read(struct udevice *dev, int offset, void *buf, int size);
-/*
- * Write buffer to the device, optional.
+
+/**
+ * misc_write() - Write buffer to the device, optional.
  *
  * @dev: the device
  * @offset: offset to write the device
  * @buf: pointer to data buffer
  * @size: data size in bytes to write the device
- * @return: 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int misc_write(struct udevice *dev, int offset, void *buf, int size);
-/*
- * Assert command to the device, optional.
+
+/**
+ * misc_ioctl() - Assert command to the device, optional.
  *
  * @dev: the device
  * @request: command to be sent to the device
  * @buf: pointer to buffer related to the request
- * @return: 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int misc_ioctl(struct udevice *dev, unsigned long request, void *buf);

-/*
- * Send a message to the device and wait for a response.
+/**
+ * misc_call() - Send a message to the device and wait for a response.
  *
  * The caller provides the message type/ID and payload to be sent.
  * The callee constructs any message header required, transmits it to the
@@ -47,64 +49,66 @@ int misc_ioctl(struct udevice *dev, unsigned long request, void *buf);
  *
  * @dev: the device.
  * @msgid: the message ID/number to send.
- * tx_msg: the request/transmit message payload.
- * tx_size: the size of the buffer pointed at by tx_msg.
- * rx_msg: the buffer to receive the response message payload. May be NULL if
- *         the caller only cares about the error code.
- * rx_size: the size of the buffer pointed at by rx_msg.
- * @return the response message size if OK, -ve on error
+ * @tx_msg: the request/transmit message payload.
+ * @tx_size: the size of the buffer pointed at by tx_msg.
+ * @rx_msg: the buffer to receive the response message payload. May be NULL if
+ *          the caller only cares about the error code.
+ * @rx_size: the size of the buffer pointed at by rx_msg.
+ * Return: the response message size if OK, -ve on error
  */
 int misc_call(struct udevice *dev, int msgid, void *tx_msg, int tx_size,
 	      void *rx_msg, int rx_size);

-/*
+/**
  * struct misc_ops - Driver model Misc operations
  *
  * The uclass interface is implemented by all miscellaneous devices which
  * use driver model.
  */
 struct misc_ops {
-	/*
+	/**
 	 * Read the device to buffer, optional.
 	 *
 	 * @dev: the device
 	 * @offset: offset to read the device
 	 * @buf: pointer to data buffer
 	 * @size: data size in bytes to read the device
-	 * @return: 0 if OK, -ve on error
+	 * Return: 0 if OK, -ve on error
 	 */
 	int (*read)(struct udevice *dev, int offset, void *buf, int size);
-	/*
+
+	/**
 	 * Write buffer to the device, optional.
 	 *
 	 * @dev: the device
 	 * @offset: offset to write the device
 	 * @buf: pointer to data buffer
 	 * @size: data size in bytes to write the device
-	 * @return: 0 if OK, -ve on error
+	 * Return: 0 if OK, -ve on error
 	 */
 	int (*write)(struct udevice *dev, int offset, const void *buf,
 		     int size);
-	/*
+	/**
 	 * Assert command to the device, optional.
 	 *
 	 * @dev: the device
 	 * @request: command to be sent to the device
 	 * @buf: pointer to buffer related to the request
-	 * @return: 0 if OK, -ve on error
+	 * Return: 0 if OK, -ve on error
 	 */
 	int (*ioctl)(struct udevice *dev, unsigned long request, void *buf);
-	/*
+
+	/**
 	 * Send a message to the device and wait for a response.
 	 *
 	 * @dev: the device
 	 * @msgid: the message ID/number to send
-	 * tx_msg: the request/transmit message payload
-	 * tx_size: the size of the buffer pointed at by tx_msg
-	 * rx_msg: the buffer to receive the response message payload. May be
-	 *         NULL if the caller only cares about the error code.
-	 * rx_size: the size of the buffer pointed at by rx_msg
-	 * @return the response message size if OK, -ve on error
+	 * @tx_msg: the request/transmit message payload
+	 * @tx_size: the size of the buffer pointed at by tx_msg
+	 * @rx_msg: the buffer to receive the response message payload. May be
+	 *          NULL if the caller only cares about the error code.
+	 * @rx_size: the size of the buffer pointed at by rx_msg
+	 * Return: the response message size if OK, -ve on error
 	 */
 	int (*call)(struct udevice *dev, int msgid, void *tx_msg, int tx_size,
 		    void *rx_msg, int rx_size);
--
2.11.0

[U-Boot] [PATCH v3 2/3] misc: uclass: Add enable/disable function

[Mario Six]

Add generic enable/disable function to the misc uclass.

Signed-off-by: Mario Six <mario.six@gdsys.cc>

---

v2 -> v3:
* Now return old state from misc_set_enabled

v1 -> v2:
* Merged the two functions into one function
* Explained the semantics of enabling/disabling more throughly

---
 drivers/misc/misc-uclass.c | 10 ++++++++++
 include/misc.h             | 27 +++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/drivers/misc/misc-uclass.c b/drivers/misc/misc-uclass.c
index 0dc62d00344..f240cda5c05 100644
--- a/drivers/misc/misc-uclass.c
+++ b/drivers/misc/misc-uclass.c
@@ -55,6 +55,16 @@ int misc_call(struct udevice *dev, int msgid, void *tx_msg, int tx_size,
 	return ops->call(dev, msgid, tx_msg, tx_size, rx_msg, rx_size);
 }

+int misc_set_enabled(struct udevice *dev, bool val)
+{
+	const struct misc_ops *ops = device_get_ops(dev);
+
+	if (!ops->set_enabled)
+		return -ENOSYS;
+
+	return ops->set_enabled(dev, val);
+}
+
 UCLASS_DRIVER(misc) = {
 	.id		= UCLASS_MISC,
 	.name		= "misc",
diff --git a/include/misc.h b/include/misc.h
index 0acb4c4df64..ffc489ec6b0 100644
--- a/include/misc.h
+++ b/include/misc.h
@@ -60,6 +60,23 @@ int misc_call(struct udevice *dev, int msgid, void *tx_msg, int tx_size,
 	      void *rx_msg, int rx_size);

 /**
+ * misc_set_enabled() - Enable or disable a device.
+ *
+ * The semantics of "disable" and "enable" should be understood here as
+ * activating or deactivating the device's primary function, hence a "disabled"
+ * device should be dormant, but still answer to commands and queries.
+ *
+ * A probed device may start in a disabled or enabled state, depending on the
+ * driver and hardware.
+ *
+ * @dev: the device to enable or disable.
+ * @val: the flag that tells the driver to either enable or disable the device.
+ * Return: -ve on error, 0 if the previous state was "disabled", 1 if the
+ *	   previous state was "enabled"
+ */
+int misc_set_enabled(struct udevice *dev, bool val);
+
+/*
  * struct misc_ops - Driver model Misc operations
  *
  * The uclass interface is implemented by all miscellaneous devices which
@@ -112,6 +129,16 @@ struct misc_ops {
 	 */
 	int (*call)(struct udevice *dev, int msgid, void *tx_msg, int tx_size,
 		    void *rx_msg, int rx_size);
+	/**
+	 * Enable or disable a device, optional.
+	 *
+	 * @dev: the device to enable.
+	 * @val: the flag that tells the driver to either enable or disable the
+	 *	 device.
+	 * Return: -ve on error, 0 if the previous state was "disabled", 1 if
+	 *	   the previous state was "enabled"
+	 */
+	int (*set_enabled)(struct udevice *dev, bool val);
 };

 #endif	/* _MISC_H_ */
--
2.11.0

[U-Boot] [PATCH v3 2/3] misc: uclass: Add enable/disable function

[Simon Glass]

Hi Mario,

On 23 May 2018 at 08:07, Mario Six <mario.six@gdsys.cc> wrote:
> Add generic enable/disable function to the misc uclass.
>
> Signed-off-by: Mario Six <mario.six@gdsys.cc>
>
> ---
>
> v2 -> v3:
> * Now return old state from misc_set_enabled
>
> v1 -> v2:
> * Merged the two functions into one function
> * Explained the semantics of enabling/disabling more throughly
>
> ---
>  drivers/misc/misc-uclass.c | 10 ++++++++++
>  include/misc.h             | 27 +++++++++++++++++++++++++++
>  2 files changed, 37 insertions(+)
>

Reviewed-by: Simon Glass <sjg@chromium.org>

Can you please add a simple dm test for the misc device? Or if
drivers/mailbox/sandbox-mbox-test.c is sufficient, update it?

Regards,
Simon

[U-Boot] [PATCH v3 2/3] misc: uclass: Add enable/disable function

[Mario Six]

Hi Simon,

On Fri, May 25, 2018 at 4:41 AM, Simon Glass <sjg@chromium.org> wrote:
> Hi Mario,
>
> On 23 May 2018 at 08:07, Mario Six <mario.six@gdsys.cc> wrote:
>> Add generic enable/disable function to the misc uclass.
>>
>> Signed-off-by: Mario Six <mario.six@gdsys.cc>
>>
>> ---
>>
>> v2 -> v3:
>> * Now return old state from misc_set_enabled
>>
>> v1 -> v2:
>> * Merged the two functions into one function
>> * Explained the semantics of enabling/disabling more throughly
>>
>> ---
>>  drivers/misc/misc-uclass.c | 10 ++++++++++
>>  include/misc.h             | 27 +++++++++++++++++++++++++++
>>  2 files changed, 37 insertions(+)
>>
>
> Reviewed-by: Simon Glass <sjg@chromium.org>
>
> Can you please add a simple dm test for the misc device? Or if
> drivers/mailbox/sandbox-mbox-test.c is sufficient, update it?
>

OK, will add some tests in v4.

> Regards,
> Simon

Best regards,
Mario

[U-Boot] [PATCH v3 3/3] misc: Add gdsys_ioep driver

[Mario Six]

Add driver for the IHS IO endpoint on IHS FPGAs.

Signed-off-by: Mario Six <mario.six@gdsys.cc>

---

v2 -> v3:
No changes

v1 -> v2:
* Switched to regmap usage (instead of fpgamap)

---
 drivers/misc/Kconfig      |   6 ++
 drivers/misc/Makefile     |   1 +
 drivers/misc/gdsys_ioep.c | 155 ++++++++++++++++++++++++++++++++++++++++++++++
 drivers/misc/gdsys_ioep.h |  73 ++++++++++++++++++++++
 4 files changed, 235 insertions(+)
 create mode 100644 drivers/misc/gdsys_ioep.c
 create mode 100644 drivers/misc/gdsys_ioep.h

diff --git a/drivers/misc/Kconfig b/drivers/misc/Kconfig
index be900cf4d6e..dc4cd4ec110 100644
--- a/drivers/misc/Kconfig
+++ b/drivers/misc/Kconfig
@@ -268,4 +268,10 @@ config GDSYS_RXAUI_CTRL
 	depends on MISC
 	help
 	  Support gdsys FPGA's RXAUI control.
+
+config GDSYS_IOEP
+	bool "Enable gdsys IOEP driver"
+	depends on MISC
+	help
+	  Support gdsys FPGA's IO endpoint driver.
 endmenu
diff --git a/drivers/misc/Makefile b/drivers/misc/Makefile
index e362609d62a..1782dc8be42 100644
--- a/drivers/misc/Makefile
+++ b/drivers/misc/Makefile
@@ -53,3 +53,4 @@ obj-$(CONFIG_ROCKCHIP_EFUSE) += rockchip-efuse.o
 obj-$(CONFIG_STM32_RCC) += stm32_rcc.o
 obj-$(CONFIG_SYS_DPAA_QBMAN) += fsl_portals.o
 obj-$(CONFIG_GDSYS_RXAUI_CTRL) += gdsys_rxaui_ctrl.o
+obj-$(CONFIG_GDSYS_IOEP) += gdsys_ioep.o
diff --git a/drivers/misc/gdsys_ioep.c b/drivers/misc/gdsys_ioep.c
new file mode 100644
index 00000000000..2c29e8c4e8c
--- /dev/null
+++ b/drivers/misc/gdsys_ioep.c
@@ -0,0 +1,155 @@
+/*
+ * (C) Copyright 2017
+ * Mario Six,  Guntermann & Drunck GmbH, mario.six at gdsys.cc
+ *
+ * based on the cmd_ioloop driver/command, which is
+ *
+ * (C) Copyright 2014
+ * Dirk Eibach, Guntermann & Drunck GmbH, dirk.eibach at gdsys.cc
+ *
+ * SPDX-License-Identifier:	GPL-2.0+
+ */
+
+#include <common.h>
+#include <dm.h>
+#include <misc.h>
+#include <regmap.h>
+
+#include "gdsys_ioep.h"
+
+struct gdsys_ioep_priv {
+	struct regmap *map;
+	bool state;
+};
+
+enum last_spec {
+	READ_DATA_IS_LAST,
+	READ_DATA_IS_NOT_LAST,
+};
+
+int gdsys_ioep_set_receive(struct udevice *dev, bool val)
+{
+	struct gdsys_ioep_priv *priv = dev_get_priv(dev);
+	u16 state;
+
+	priv->state = !priv->state;
+
+	if (val)
+		state = CTRL_PROC_RECEIVE_ENABLE;
+	else
+		state = ~CTRL_PROC_RECEIVE_ENABLE;
+
+	gdsys_ioep_set(priv->map, tx_control, state);
+
+	if (val) {
+		/* Set device address to dummy 1*/
+		gdsys_ioep_set(priv->map, device_address, 1);
+	}
+
+	return !priv->state;
+}
+
+int gdsys_ioep_send(struct udevice *dev, int offset, const void *buf, int size)
+{
+	struct gdsys_ioep_priv *priv = dev_get_priv(dev);
+	int k;
+	u16 *p = (u16 *)buf;
+
+	for (k = 0; k < size; ++k)
+		gdsys_ioep_set(priv->map, transmit_data, *(p++));
+
+	gdsys_ioep_set(priv->map, tx_control, CTRL_PROC_RECEIVE_ENABLE |
+					      CTRL_FLUSH_TRANSMIT_BUFFER);
+
+	return 0;
+}
+
+int receive_byte_buffer(struct udevice *dev, uint len, u16 *buffer, enum last_spec last_spec)
+{
+	struct gdsys_ioep_priv *priv = dev_get_priv(dev);
+	int k;
+	int res = -EIO;
+
+	for (k = 0; k < len; ++k) {
+		u16 rx_tx_status;
+
+		gdsys_ioep_get(priv->map, receive_data, buffer++);
+
+		gdsys_ioep_get(priv->map, rx_tx_status, &rx_tx_status);
+		if (k == (len - 1) && (last_spec == READ_DATA_IS_NOT_LAST ||
+				       rx_tx_status & STATE_RX_DATA_LAST))
+			res = 0;
+	}
+
+	return res;
+}
+
+int gdsys_ioep_receive(struct udevice *dev, int offset, void *buf, int size)
+{
+	int res1, res2;
+	struct io_generic_packet header;
+	u16 *p = (u16 *)buf;
+	const int header_words = sizeof(struct io_generic_packet) / 2;
+	uint len;
+
+	res1 = receive_byte_buffer(dev, header_words, p, READ_DATA_IS_NOT_LAST);
+	memcpy(&header, p, 2 * header_words);
+	p += header_words;
+
+	len = (header.packet_length + 1) / 2;
+
+	if (!res1)
+		res2 = receive_byte_buffer(dev, len, p, READ_DATA_IS_LAST);
+
+	return res1 ? res1 : res2;
+}
+
+int gdsys_ioep_get_and_reset_status(struct udevice *dev, int msgid,
+				    void *tx_msg, int tx_size, void *rx_msg,
+				    int rx_size)
+{
+	struct gdsys_ioep_priv *priv = dev_get_priv(dev);
+	const u16 mask = STATE_RX_DIST_ERR | STATE_RX_LENGTH_ERR |
+			 STATE_RX_FRAME_CTR_ERR | STATE_RX_FCS_ERR |
+			 STATE_RX_PACKET_DROPPED | STATE_TX_ERR;
+	u16 *status = rx_msg;
+
+	gdsys_ioep_get(priv->map, rx_tx_status, status);
+
+	gdsys_ioep_set(priv->map, rx_tx_status, *status);
+
+	return (*status & mask) ? 1 : 0;
+}
+
+static const struct misc_ops gdsys_ioep_ops = {
+	.set_enabled = gdsys_ioep_set_receive,
+	.write = gdsys_ioep_send,
+	.read = gdsys_ioep_receive,
+	.call = gdsys_ioep_get_and_reset_status,
+};
+
+int gdsys_ioep_probe(struct udevice *dev)
+{
+	struct gdsys_ioep_priv *priv = dev_get_priv(dev);
+
+	regmap_init_mem(dev_ofnode(dev), &priv->map);
+
+	priv->state = false;
+
+	return 0;
+}
+
+static const struct udevice_id gdsys_ioep_ids[] = {
+	{ .compatible = "gdsys,io-endpoint" },
+	{ }
+};
+
+U_BOOT_DRIVER(gdsys_ioep) = {
+	.name           = "gdsys_ioep",
+	.id             = UCLASS_MISC,
+	.ops		= &gdsys_ioep_ops,
+	.flags		= DM_UC_FLAG_SEQ_ALIAS,
+	.of_match       = gdsys_ioep_ids,
+	.probe          = gdsys_ioep_probe,
+	.priv_auto_alloc_size = sizeof(struct gdsys_ioep_priv),
+};
diff --git a/drivers/misc/gdsys_ioep.h b/drivers/misc/gdsys_ioep.h
new file mode 100644
index 00000000000..cccf5800919
--- /dev/null
+++ b/drivers/misc/gdsys_ioep.h
@@ -0,0 +1,73 @@
+/*
+ * (C) Copyright 2018
+ * Mario Six, Guntermann & Drunck GmbH, mario.six at gdsys.cc
+ *
+ * SPDX-License-Identifier:	GPL-2.0+
+ */
+
+#ifndef __GDSYS_IOEP_H_
+#define __GDSYS_IOEP_H_
+
+/**
+ * struct io_generic_packet - header structure for GDSYS IOEP packets
+ *
+ * @target_address:     Target protocol address of the packet.
+ * @source_address:     Source protocol address of the packet.
+ * @packet_type:        Packet type.
+ * @bc:                 Block counter (filled in by FPGA).
+ * @packet_length:      Length of the packet's payload bytes.
+ */
+struct io_generic_packet {
+        u16 target_address;
+        u16 source_address;
+        u8 packet_type;
+        u8 bc;
+        u16 packet_length;
+} __attribute__((__packed__));
+
+struct gdsys_ioep_regs {
+	u16 transmit_data;
+	u16 tx_control;
+	u16 receive_data;
+	u16 rx_tx_status;
+	u16 device_address;
+	u16 target_address;
+	u16 int_enable;
+};
+
+#define gdsys_ioep_set(map, member, val) \
+	regmap_set(map, struct gdsys_ioep_regs, member, val)
+
+#define gdsys_ioep_get(map, member, valp) \
+	regmap_get(map, struct gdsys_ioep_regs, member, valp)
+enum {
+	STATE_TX_PACKET_BUILDING = BIT(0),
+	STATE_TX_TRANSMITTING = BIT(1),
+	STATE_TX_BUFFER_FULL = BIT(2),
+	STATE_TX_ERR = BIT(3),
+	STATE_RECEIVE_TIMEOUT = BIT(4),
+	STATE_PROC_RX_STORE_TIMEOUT = BIT(5),
+	STATE_PROC_RX_RECEIVE_TIMEOUT = BIT(6),
+	STATE_RX_DIST_ERR = BIT(7),
+	STATE_RX_LENGTH_ERR = BIT(8),
+	STATE_RX_FRAME_CTR_ERR = BIT(9),
+	STATE_RX_FCS_ERR = BIT(10),
+	STATE_RX_PACKET_DROPPED = BIT(11),
+	STATE_RX_DATA_LAST = BIT(12),
+	STATE_RX_DATA_FIRST = BIT(13),
+	STATE_RX_DATA_AVAILABLE = BIT(15),
+};
+
+enum {
+	CTRL_PROC_RECEIVE_ENABLE = BIT(12),
+	CTRL_FLUSH_TRANSMIT_BUFFER = BIT(15),
+};
+
+enum {
+	IRQ_CPU_TRANSMITBUFFER_FREE_STATUS = BIT(5),
+	IRQ_CPU_PACKET_TRANSMITTED_EVENT = BIT(6),
+	IRQ_NEW_CPU_PACKET_RECEIVED_EVENT = BIT(7),
+	IRQ_CPU_RECEIVE_DATA_AVAILABLE_STATUS = BIT(8),
+};
+
+#endif /* __GDSYS_IOEP_H_ */
--
2.11.0

[U-Boot] [PATCH v3 3/3] misc: Add gdsys_ioep driver

[Simon Glass]

On 23 May 2018 at 08:07, Mario Six <mario.six@gdsys.cc> wrote:
> Add driver for the IHS IO endpoint on IHS FPGAs.
>
> Signed-off-by: Mario Six <mario.six@gdsys.cc>
>
> ---
>
> v2 -> v3:
> No changes
>
> v1 -> v2:
> * Switched to regmap usage (instead of fpgamap)
>
> ---
>  drivers/misc/Kconfig      |   6 ++
>  drivers/misc/Makefile     |   1 +
>  drivers/misc/gdsys_ioep.c | 155 ++++++++++++++++++++++++++++++++++++++++++++++
>  drivers/misc/gdsys_ioep.h |  73 ++++++++++++++++++++++
>  4 files changed, 235 insertions(+)
>  create mode 100644 drivers/misc/gdsys_ioep.c
>  create mode 100644 drivers/misc/gdsys_ioep.h
>

Reviewed-by: Simon Glass <sjg@chromium.org>

But you should check the error return value from regmap_init_mem()

[U-Boot] [PATCH v3 3/3] misc: Add gdsys_ioep driver

[Mario Six]

Hi Simon,

On Fri, May 25, 2018 at 4:42 AM, Simon Glass <sjg@chromium.org> wrote:
> On 23 May 2018 at 08:07, Mario Six <mario.six@gdsys.cc> wrote:
>> Add driver for the IHS IO endpoint on IHS FPGAs.
>>
>> Signed-off-by: Mario Six <mario.six@gdsys.cc>
>>
>> ---
>>
>> v2 -> v3:
>> No changes
>>
>> v1 -> v2:
>> * Switched to regmap usage (instead of fpgamap)
>>
>> ---
>>  drivers/misc/Kconfig      |   6 ++
>>  drivers/misc/Makefile     |   1 +
>>  drivers/misc/gdsys_ioep.c | 155 ++++++++++++++++++++++++++++++++++++++++++++++
>>  drivers/misc/gdsys_ioep.h |  73 ++++++++++++++++++++++
>>  4 files changed, 235 insertions(+)
>>  create mode 100644 drivers/misc/gdsys_ioep.c
>>  create mode 100644 drivers/misc/gdsys_ioep.h
>>
>
> Reviewed-by: Simon Glass <sjg@chromium.org>
>
> But you should check the error return value from regmap_init_mem()

True, will be added in v4.

Best regards,
Mario

[U-Boot] [PATCH v3 1/3] misc: docs: Fix comments in misc.h

[Simon Glass]

+Marex

Hi Mario,

On 23 May 2018 at 08:07, Mario Six <mario.six@gdsys.cc> wrote:
> The comments in misc.h are not in kernel-doc format. Correct the format.
>
> Signed-off-by: Mario Six <mario.six@gdsys.cc>
>
> ---
>
> v2 -> v3:
> New in v3
>
> ---
>  include/misc.h | 66 +++++++++++++++++++++++++++++++---------------------------
>  1 file changed, 35 insertions(+), 31 deletions(-)
>

Not another format?! I have been following what I thought was docbook
format as proposed by Marek a few years ago.

Regards,
Simon

[U-Boot] [PATCH v3 1/3] misc: docs: Fix comments in misc.h

[Mario Six]

Hi Simon,

On Fri, May 25, 2018 at 4:41 AM, Simon Glass <sjg@chromium.org> wrote:
> +Marex
>
> Hi Mario,
>
> On 23 May 2018 at 08:07, Mario Six <mario.six@gdsys.cc> wrote:
>> The comments in misc.h are not in kernel-doc format. Correct the format.
>>
>> Signed-off-by: Mario Six <mario.six@gdsys.cc>
>>
>> ---
>>
>> v2 -> v3:
>> New in v3
>>
>> ---
>>  include/misc.h | 66 +++++++++++++++++++++++++++++++---------------------------
>>  1 file changed, 35 insertions(+), 31 deletions(-)
>>
>
> Not another format?! I have been following what I thought was docbook
> format as proposed by Marek a few years ago.
>

Well, others seem to think different. Michal pointed out in [1] that the
comments were very close to kerneldoc, but not quiet, and proposed to change
the format to make them comply. This seems reasonable, since the kerneldoc
utility is in the tree after all.

As for the docbook format: That was imported from the Linux kernel, and the
kernel guys subsequently abandoned the docbook format in favor of Sphinx-based
documentation. So, you could argue that the docbook format is obsolete (also,
from what I see there were only ever two docbook documents written in U-Boot,
so the success was limited).

But that's actually a good question: Is there a preferred or even mandatory doc
format in use? If that's the case, it would certainly be nice if it was
documented somewhere (or even if there was an automated linter akin to
kerneldoc, for example).

[1] http://patchwork.ozlabs.org/patch/905733/#1902178

> Regards,
> Simon

Best regards,
Mario

[U-Boot] [PATCH v3 1/3] misc: docs: Fix comments in misc.h

[Simon Glass]

Hi Mario,

On 28 May 2018 at 07:01, Mario Six <mario.six@gdsys.cc> wrote:
> Hi Simon,
>
> On Fri, May 25, 2018 at 4:41 AM, Simon Glass <sjg@chromium.org> wrote:
>> +Marex
>>
>> Hi Mario,
>>
>> On 23 May 2018 at 08:07, Mario Six <mario.six@gdsys.cc> wrote:
>>> The comments in misc.h are not in kernel-doc format. Correct the format.
>>>
>>> Signed-off-by: Mario Six <mario.six@gdsys.cc>
>>>
>>> ---
>>>
>>> v2 -> v3:
>>> New in v3
>>>
>>> ---
>>>  include/misc.h | 66 +++++++++++++++++++++++++++++++---------------------------
>>>  1 file changed, 35 insertions(+), 31 deletions(-)
>>>
>>
>> Not another format?! I have been following what I thought was docbook
>> format as proposed by Marek a few years ago.
>>
>
> Well, others seem to think different. Michal pointed out in [1] that the
> comments were very close to kerneldoc, but not quiet, and proposed to change
> the format to make them comply. This seems reasonable, since the kerneldoc
> utility is in the tree after all.
>
> As for the docbook format: That was imported from the Linux kernel, and the
> kernel guys subsequently abandoned the docbook format in favor of Sphinx-based
> documentation. So, you could argue that the docbook format is obsolete (also,
> from what I see there were only ever two docbook documents written in U-Boot,
> so the success was limited).
>
> But that's actually a good question: Is there a preferred or even mandatory doc
> format in use? If that's the case, it would certainly be nice if it was
> documented somewhere (or even if there was an automated linter akin to
> kerneldoc, for example).
>
> [1] http://patchwork.ozlabs.org/patch/905733/#1902178

OK how about adding it to the README then? Also the DocBook scripts
need to be updated I think.

Regards,
Simon

[U-Boot] [PATCH v3 1/3] misc: docs: Fix comments in misc.h

[Mario Six]

Hi Simon,

On Wed, May 30, 2018 at 9:18 PM, Simon Glass <sjg@chromium.org> wrote:
> Hi Mario,
>
> On 28 May 2018 at 07:01, Mario Six <mario.six@gdsys.cc> wrote:
>> Hi Simon,
>>
>> On Fri, May 25, 2018 at 4:41 AM, Simon Glass <sjg@chromium.org> wrote:
>>> +Marex
>>>
>>> Hi Mario,
>>>
>>> On 23 May 2018 at 08:07, Mario Six <mario.six@gdsys.cc> wrote:
>>>> The comments in misc.h are not in kernel-doc format. Correct the format.
>>>>
>>>> Signed-off-by: Mario Six <mario.six@gdsys.cc>
>>>>
>>>> ---
>>>>
>>>> v2 -> v3:
>>>> New in v3
>>>>
>>>> ---
>>>>  include/misc.h | 66 +++++++++++++++++++++++++++++++---------------------------
>>>>  1 file changed, 35 insertions(+), 31 deletions(-)
>>>>
>>>
>>> Not another format?! I have been following what I thought was docbook
>>> format as proposed by Marek a few years ago.
>>>
>>
>> Well, others seem to think different. Michal pointed out in [1] that the
>> comments were very close to kerneldoc, but not quiet, and proposed to change
>> the format to make them comply. This seems reasonable, since the kerneldoc
>> utility is in the tree after all.
>>
>> As for the docbook format: That was imported from the Linux kernel, and the
>> kernel guys subsequently abandoned the docbook format in favor of Sphinx-based
>> documentation. So, you could argue that the docbook format is obsolete (also,
>> from what I see there were only ever two docbook documents written in U-Boot,
>> so the success was limited).
>>
>> But that's actually a good question: Is there a preferred or even mandatory doc
>> format in use? If that's the case, it would certainly be nice if it was
>> documented somewhere (or even if there was an automated linter akin to
>> kerneldoc, for example).
>>
>> [1] http://patchwork.ozlabs.org/patch/905733/#1902178
>
> OK how about adding it to the README then? Also the DocBook scripts
> need to be updated I think.
>

The best way to update the DocBook scripts would probably be to pull in the
sphinx-based scripts, and migrate the DocBook files to sphinx. I'll check how
complicated that would be.

> Regards,
> Simon
>

Best regards,
Mario