Re: [RFC PATCH v2 1/3] add mikrobus descriptors to greybus_manifest

[Vaishnav M A]

Hi,

Trying to add more information regarding the newly added
descriptors and describe how they are used now within the
mikroBUS driver.

On Tue, Aug 18, 2020 at 6:18 PM Vaishnav M A <vaishnav@xxxxxxxxxxxxxxx> wrote:
>
> This patch adds new descriptors used in the manifest parsing inside
> the mikrobus driver, the device descriptor help to describe the
> devices on a mikroBUS port, mikrobus descriptor is used to set up
> the mikrobus port pinmux and GPIO states and property descriptor
> to pass named properties to device drivers through the Unified
> Properties API under linux/property.h
>
> The corresponding pull request for manifesto is updated
> at : https://github.com/projectara/manifesto/pull/2
>
> Signed-off-by: Vaishnav M A <vaishnav@xxxxxxxxxxxxxxx>
> ---
>  include/linux/greybus/greybus_manifest.h | 47 ++++++++++++++++++++++++
>  1 file changed, 47 insertions(+)
>
> diff --git a/include/linux/greybus/greybus_manifest.h b/include/linux/greybus/greybus_manifest.h
> index 6e62fe478712..821661ea7f01 100644
> --- a/include/linux/greybus/greybus_manifest.h
> +++ b/include/linux/greybus/greybus_manifest.h
> @@ -23,6 +23,9 @@ enum greybus_descriptor_type {
>         GREYBUS_TYPE_STRING             = 0x02,
>         GREYBUS_TYPE_BUNDLE             = 0x03,
>         GREYBUS_TYPE_CPORT              = 0x04,
> +       GREYBUS_TYPE_MIKROBUS           = 0x05,

The mikrobus descriptor is used to pass information about
the specific pinmux settings and the default GPIO states on
the mikrobus port to be set up for the add-on board to work
correctly, this descriptor has 12 u8 fields(corresponding  to the
12 pins on the mikrobus port) which includes information
about the prior setup required on the mikroBUS port for the
device(s) on the add-on board to work correctly. The mikrobus
descriptor is a fixed-length descriptor and there will be only a
single instance of mikrobus descriptor per add-on board manifest.

> +       GREYBUS_TYPE_PROPERTY           = 0x06,

The property descriptors are used to pass named properties
to the device drivers through the Unified device property interface
under linux/property.h , so that device drivers using the
device_property_read_* call can get the named properties,
the mikrobus driver fetches the information from the manifest
binary and forms a corresponding `struct property_entry` which
will be attached to the `struct device`.
The property descriptor is a variable-length descriptor similar
to the string descriptor and there can be multiple instances of
property descriptor per add-on board manifest.

> +       GREYBUS_TYPE_DEVICE             = 0x07,

The device descriptor is used to describe a device on the
mikrobus port and has necessary fields from `struct i2c_board_info`
and `struct spi_board_info` to describe a device on these buses
in a mikrobus port, even though  SPI/I2C device info structs are used
this descriptor has enough information to describe other kinds of
devices relevant to mikrobus as well.(serdev/platform devices).
The device descriptor is a fixed-length descriptor and there can be
multiple instances of device descriptors in an add-on board manifest
in cases where the add-on board presents more than one device
to the host.

>  };
>
>  enum greybus_protocol {
> @@ -151,6 +154,47 @@ struct greybus_descriptor_cport {
>         __u8    protocol_id;    /* enum greybus_protocol */
>  } __packed;
>
> +/*
> + * A mikrobus descriptor is used to describe the details
> + * about the bus ocnfiguration for the add-on board
> + * connected to the mikrobus port.
> + */
> +struct greybus_descriptor_mikrobus {
> +       __u8 pin_state[12];
> +} __packed;
> +

These 12 u8 fields describe the state of the pins in the
mikrobus port(in clock wise order starting from the PWM
pin)
mikrobus v2 standard specification :
https://download.mikroe.com/documents/standards/mikrobus/mikrobus-standard-specification-v200.pdf
This struct is filled from the mikrobus-descriptor
in the manifest and can have one of the values
for each pin group:
MIKROBUS_STATE_INPUT = 0x01,
MIKROBUS_STATE_OUTPUT_HIGH = 0x02,
MIKROBUS_STATE_OUTPUT_LOW = 0x03,
MIKROBUS_STATE_PWM = 0x04,  ( applicable only to  PWM pin)
MIKROBUS_STATE_SPI = 0x05, ( applicable only to
the group of MOSI, MISO, SCK , CS pins on mikroBUS port)
MIKROBUS_STATE_I2C = 0x06, (applicable only to the SCL, SDA
pins on the mikrobus port)
MIKROBUS_STATE_UART = 0x07,(applicable only to the RX, TX
pins on the mikrobus port)
There are two purposes for adding this descriptor,
1) for some add-on boards some of the pins might need to
be configured as GPIOs deviating from their reserved purposes
An example for this case is an SHT15 Click (https://www.mikroe.com/sht1x-click),
where the SCL and SDA Pins need to be configured as GPIOs
for the driver (drivers/hwmon/sht15.c) to work. The mikrobus
descriptor for this case would look like this :
[mikrobus-descriptor]
pwm-state = 4 (default, pwm)
int-state = 1 (default, input)
rx-state = 7 (default, uart)
tx-state = 7 (default, uart)
scl-state = 3 (note the SCL Pin configured as GPIO)
sda-state = 3 (note the SCL Pin configured as GPIO)
mosi-state = 5 (default, spi)
miso-state = 5 (default, spi)
sck-state = 5 (default, spi)
cs-state = 5 (default, spi)
rst-state = 2 (default, GPIO)
an-state = 1 (default, input)
2) for some add-on boards the driver may not take care
of some additional signals like reset/wake-up/other thus
the mikrobus driver can set-up these GPIOs to a required
default state from the information from the manifest, a good
example for this is the  ENC28J60 click (https://www.mikroe.com/eth-click)
where the reset line(RST pin on the mikrobus port) needs to be
pulled high. The manifest example for this add-on board can
be found here :
https://github.com/vaishnav98/manifesto/blob/mikrobusv3/manifests/ETH-CLICK.mnfs

> +/*
> + * A property descriptor is used to pass named properties
> + * to device drivers through the unified device properties
> + * interface under linux/property.h
> + */
> +struct greybus_descriptor_property {
> +       __u8 length;
> +       __u8 id;
> +       __u8 propname_stringid;
> +       __u8 type;
> +       __u8 value[0];
> +} __packed;
> +

This descriptor is used to fill in `struct property_entry`
(linux/property.h), the propname_stringid
field is used to map to the corresponding string descriptor
which has the property name, the type field has the types
under dev_prop_type (linux/property.h) and there are
some new types which are used within the mikrobus
driver, these are the new types :
MIKROBUS_PROPERTY_TYPE_LINK = 0x01
MIKROBUS_PROPERTY_TYPE_GPIO = 0x02

The property-link type is used to attach an array of properties
to the corresponding device, for example, consider an SPI
EEPROM device which works with the AT25 driver(
drivers/misc/eeprom/at25.c), The device and property
descriptor parts of the manifest will look like this.

[device-descriptor 1]
driver-string-id = 3
prop-link = 1 (The ID of the property-descriptor which
contains the list of IDs of the actual properties to attach with
the device)
protocol = 0xb
reg = 0
mode = 0x3
max-speed-hz = 5000000
[string-descriptor 3]
string = at25 (driver string)

[property-descriptor 1]
name-string-id = 4
type = 0x01 (type is property-link)
value = <2 3 4>(attach properties with id 2,3,4 to the device)
[string-descriptor 4]
string = prop-link

[property-descriptor 2]
name-string-id = 5 (string id for the property name string)
type = 0x05 (U32, driver uses device_property_read_u32 call
to read the value)
value = <262144>
[string-descriptor 5]
string = size (property name string)

[property-descriptor 3]
name-string-id = 6
type = 0x05
value = <256>
[string-descriptor 6]
string = pagesize

[property-descriptor 4]
name-string-id = 7
type = 0x05
value = <24>
[string-descriptor 7]
string = address-width

The gpio-link type is very similar to property descriptor and is used to
pass an array of named gpios to the device driver through GPIO lookup tables,
consider an example for a SHT15 device (drivers/hwmon/sht15.c),
the device and the property(gpio) descriptors are as follows :

[device-descriptor 1]
driver-string-id = 3
protocol = 0xfe
reg = 0
gpio-link = 1 (The ID of the property-descriptor which
contains the list of IDs of the named gpio properties to attach with
the device)

[string-descriptor 3]
string = sht11 (device_id string)

[property-descriptor 1]
name-string-id = 4
type = 0x02 (gpio-link)
value = <2 3> (attach properties with id 2,3 as named gpios to the device)
[string-descriptor 4]
string = gpio-link

[property-descriptor 2]
name-string-id = 5
type = 0x03
value = <4>
[string-descriptor 5]
string = clk (name of the GPIO, the driver uses
devm_gpiod_get or similar calls to get the GPIO)

[property-descriptor 3]
name-string-id = 6
type = 0x03
value = <5>
[string-descriptor 6]
string = data

Note that the values here 4 and 5 for the GPIOs are
the offset numbers(clockwise starting from PWM pin)
within a mikrobus port, the mikrobus drivers translates this
offset information to the actual GPIO while creating the GPIO
lookup table, this ensures that the manifest doesn't have any
port-specific information and a single manifest can be used for
an add-on board over different platforms/sockets.

> +/*
> + * A device descriptor is used to describe the
> + * details required by a add-on board device
> + * driver.
> + */
> +struct greybus_descriptor_device {
> +       __u8 id;
> +       __u8 driver_stringid;
> +       __u8 protocol;
> +       __u8 reg;
> +       __le32 max_speed_hz;
> +       __u8 irq;
> +       __u8 irq_type;
> +       __u8 mode;
> +       __u8 prop_link;
> +       __u8 gpio_link;
> +       __u8 pad[3];
> +} __packed;
> +

The device descriptor is used to describe a device on the
mikrobus port and has necessary fields from `struct i2c_board_info`
and `struct spi_board_info`, of these fields, the irq field is similar to
the gpio descriptor value above in that the value under irq is also
the pin offset within the mikrobus port which will be translated to the
actual GPIO within the mikrobus driver and the irq-type takes types
defined under linux/interrupt.h . For a device with a
IRQF_TRIGGER_RISING interrupt on the INT pin on the mikrobus port
the fields will be :
irq = 1 (offset of INT pin)
irq_type = 1 ( IRQF_TRIGGER_RISING)

>  struct greybus_descriptor_header {
>         __le16  size;
>         __u8    type;           /* enum greybus_descriptor_type */
> @@ -164,6 +208,9 @@ struct greybus_descriptor {
>                 struct greybus_descriptor_interface     interface;
>                 struct greybus_descriptor_bundle        bundle;
>                 struct greybus_descriptor_cport         cport;
> +               struct greybus_descriptor_mikrobus      mikrobus;
> +               struct greybus_descriptor_property      property;
> +               struct greybus_descriptor_device        device;
>         };
>  } __packed;
>
> --
> 2.25.1
>
Thanks and Regards,
Vaishnav